Kubo
Montar stack
CLI

Fluxos de agente

Fluxos JSON-first e orientados a schema para agentes, scripts e automação

Visão geral

O kubojs agora suporta um fluxo totalmente JSON-first para agentes e automação:

  • Criação de projeto via JSON bruto com create-json
  • Instalação de addons via JSON bruto com add-json
  • Introspecção de schema em runtime com schema
  • Servidor MCP local via stdio com mcp
  • Configuração estruturada de addons com addonOptions
  • Configuração estruturada de setup de banco com dbSetupOptions
  • Planejamento seguro com --dry-run

Se você está automatizando a CLI a partir de um LLM, job de CI ou outra ferramenta, comece por aqui em vez do fluxo interativo de prompts.

create-json

Cria um projeto a partir de um único payload JSON em vez de muitas flags.

kubojs create-json --input '{
  "projectName": "my-app",
  "frontend": ["tanstack-router"],
  "backend": "hono",
  "runtime": "bun",
  "database": "postgres",
  "orm": "drizzle",
  "api": "trpc",
  "auth": "none",
  "addons": ["wxt", "mcp"],
  "addonOptions": {
    "wxt": { "template": "react", "devPort": 5555 },
    "mcp": {
      "scope": "project",
      "servers": ["context7"],
      "agents": ["cursor"]
    }
  },
  "install": false
}'

Este é o melhor caminho quando:

  • Sua entrada já existe como dados estruturados
  • Você quer evitar problemas de expansão de flags no shell
  • Precisa de opções aninhadas de addon ou de setup de banco

add-json

Adiciona addons a um projeto existente com um único payload JSON.

kubojs add-json --input '{
  "projectDir": "./my-app",
  "addons": ["skills", "ultracite"],
  "addonOptions": {
    "skills": {
      "scope": "project",
      "agents": ["cursor", "codex"],
      "selections": [
        {
          "source": "vercel-labs/agent-skills",
          "skills": ["web-design-guidelines"]
        },
        {
          "source": "https://www.evlog.dev",
          "skills": ["review-logging-patterns", "analyze-logs"]
        }
      ]
    },
    "ultracite": {
      "linter": "biome",
      "editors": ["vscode", "cursor"],
      "agents": ["claude", "codex"]
    }
  },
  "dryRun": true
}'

Introspecção de schema em runtime

Use a própria CLI como fonte da verdade para os shapes de input atuais.

kubojs schema --name all
kubojs schema --name cli
kubojs schema --name createInput
kubojs schema --name addInput
kubojs schema --name addonOptions
kubojs schema --name dbSetupOptions

Padrões úteis:

  • schema --name cli: inspeciona os comandos disponíveis
  • schema --name createInput: inspeciona o payload completo de create
  • schema --name addonOptions: inspeciona a configuração aninhada de addons
  • schema --name dbSetupOptions: inspeciona o comportamento estruturado de setup de banco

mcp

Rode o próprio kubojs como servidor MCP local via stdio:

npx kubojs@latest mcp

Instale-o nas configs de agente suportadas com add-mcp:

npx -y add-mcp@latest "npx -y kubojs@latest mcp"

Tools expostas:

  • bts_get_stack_guidance
  • bts_get_schema
  • bts_plan_project
  • bts_create_project
  • bts_plan_addons
  • bts_add_addons

Este é o melhor caminho quando um cliente com MCP deve gerar scaffold ou modificar projetos kubojs sem recorrer a um fluxo de CLI orientado por prompts.

Fluxo MCP recomendado:

  1. Chame bts_get_stack_guidance se o pedido do usuário for ambíguo.
  2. Chame bts_get_schema para o shape de input exato de que precisa.
  3. Monte uma config de stack completa e explícita.
  4. Chame bts_plan_project antes de bts_create_project.
  5. Na execução via MCP, use install: false ao criar projetos.
  6. Chame bts_plan_addons antes de bts_add_addons.

Para criação de projeto, as tools MCP agora esperam uma config completa e explícita, não um payload parcial. Isso significa que o agente deve fornecer todas as escolhas principais da stack, como:

  • frontend
  • backend
  • runtime
  • database
  • orm
  • api
  • auth
  • payments
  • addons
  • examples
  • dbSetup
  • webDeploy
  • serverDeploy
  • git
  • packageManager
  • install

Regras importantes de campos:

  • frontend significa superfícies de app, não escolhas de estilo.
  • addons deve ser um array explícito. Use [] quando nenhum for pedido.
  • examples deve ser um array explícito. Use [] quando nenhum for pedido.
  • dbSetup, webDeploy e serverDeploy devem ser explícitos mesmo quando a resposta for none.
  • git, install e packageManager devem sempre ser definidos explicitamente.
  • install costuma ser false em bts_create_project, porque a instalação de dependências pode ultrapassar timeouts comuns de clientes MCP. Rode npm install, pnpm install ou bun install separadamente após o scaffold.
  • Se o pedido ainda for ambíguo depois de ler a orientação, o agente deve resolver essa ambiguidade antes de chamar bts_plan_project.

Se você gerar um projeto com o addon mcp, o próprio kubojs passa a ser um dos servidores MCP recomendados. O addon o instala via add-mcp com um comando de package runner, para que a config gerada não dependa de uma CLI instalada globalmente:

npx -y add-mcp@latest "npx -y kubojs@latest mcp"

Em projetos Bun, a config gerada usa o comando de servidor equivalente bunx kubojs@latest mcp dentro do add-mcp. Assim, agentes com MCP dentro do projeto gerado podem falar de volta com o kubojs sem instalação global extra, junto com outros servidores MCP recomendados de docs, frameworks e banco de dados.

Usar dentro do seu agente de IA

Instale o plugin kubojs e seu assistente gera scaffold e estende projetos por você — basta pedir em linguagem natural, como "create a fullstack app with Next, Hono, Postgres and Better Auth", e ele monta uma stack válida em vez de escrever boilerplate na mão.

Claude Code

Adicione o marketplace e instale o plugin:

/plugin marketplace add albuquerquesz/kubo
/plugin install kubojs@kubojs

Depois peça um projeto no chat, ou use os atalhos:

  • /kubojs:new <description> — scaffold de um novo projeto
  • /kubojs:add <addons> — adiciona addons a um existente

Codex

Adicione o mesmo marketplace na tela de plugins do Codex e instale kubojs, depois peça um projeto no chat.

Prefere só as tools sem o plugin? Conecte o servidor MCP no Codex com add-mcp:

npx -y add-mcp@latest "npx -y kubojs@latest mcp"   # choose "codex"

Ou adicione em ~/.codex/config.toml diretamente:

[mcp_servers.kubojs]
command = "npx"
args = ["-y", "kubojs@latest", "mcp"]

opencode

Adicione o servidor MCP e peça um projeto no chat:

npx -y add-mcp@latest "npx -y kubojs@latest mcp"   # choose "opencode"

Outros agentes

Qualquer outro agente também funciona, porque por baixo o kubojs é uma CLI:

  • Agentes com MCP (Cursor, VS Code, Gemini CLI, Zed e mais) — conecte o servidor com npx -y add-mcp@latest "npx -y kubojs@latest mcp" e escolha seu agente.
  • Agentes CLI-first como pi — peça para gerar scaffold com kubojs e ele roda a CLI kubojs diretamente.

Opções estruturadas de addon

Addons orientados por prompts podem ser configurados de antemão via addonOptions.

Superfícies estruturadas de addon suportadas incluem:

  • wxt
  • fumadocs
  • opentui
  • mcp
  • skills
  • ultracite

Quando skills é usado com o addon evlog, o kubojs recomenda as agent skills do Evlog em https://www.evlog.dev: review-logging-patterns e analyze-logs.

Exemplo:

{
  "addons": ["wxt"],
  "addonOptions": {
    "wxt": {
      "template": "react",
      "devPort": 5555
    }
  }
}

Opções estruturadas de addon ainda são persistidas em bts.jsonc, mas o comando reproduzível impresso agora fica em flags normais da CLI por consistência. Isso significa que opções profundamente aninhadas de addon ou de setup específico de provider não ficam totalmente codificadas no comando de replay de uma linha.

Opções estruturadas de setup de banco

dbSetupOptions controla como o provisionamento de banco se comporta na automação.

Exemplo:

kubojs create-json --input '{
  "projectName": "db-app",
  "database": "postgres",
  "orm": "drizzle",
  "backend": "hono",
  "runtime": "bun",
  "api": "trpc",
  "frontend": ["tanstack-router"],
  "dbSetup": "neon",
  "dbSetupOptions": {
    "mode": "manual"
  }
}'

Comportamento atual:

  • Providers com provisionamento automático na nuvem usam manual por padrão em fluxos silenciosos/agente:
    • turso
    • neon
    • prisma-postgres
    • supabase
    • mongodb-atlas
  • Providers que hoje só gravam config local/manual não são forçados a manual:
    • d1
    • docker
    • planetscale

Isso evita que agentes criem recursos na nuvem por acidente, a menos que a automação opte explicitamente por auto, deixando setups locais ou só manuais inalterados.

Opções específicas de provider são intencionalmente pequenas hoje:

  • neon.method, neon.projectName, neon.regionId
  • prismaPostgres.regionId
  • turso.databaseName, turso.groupName, turso.installCli

Dry runs

Use --dry-run para validar inputs e diretórios de destino sem gravar arquivos.

kubojs --yes --dry-run
kubojs create-json --input '{"projectName":"my-app","yes":true,"dryRun":true}'
kubojs add-json --input '{"projectDir":"./my-app","addons":["mcp"],"dryRun":true}'

Isso é especialmente útil para:

  • Planejar ações antes de mutar
  • Validação em CI
  • Loops de raciocínio de agentes

API programática

As APIs exportadas create() e add() rodam em modo silencioso por padrão, então se beneficiam do mesmo comportamento agent-safe dos comandos JSON.

Veja API programática para exemplos em TypeScript.

Armazenado em bts.jsonc

O kubojs persiste configuração estruturada em bts.jsonc, incluindo:

  • reproducibleCommand
  • addonOptions
  • dbSetupOptions

Veja bts.jsonc para o formato do arquivo.

Comandos

Referência completa de todos os comandos da CLI

API programática

Use o kubojs de forma programática em aplicações Node.js

Nesta página

Visão geralcreate-jsonadd-jsonIntrospecção de schema em runtimemcpUsar dentro do seu agente de IAClaude CodeCodexopencodeOutros agentesOpções estruturadas de addonOpções estruturadas de setup de bancoDry runsAPI programáticaArmazenado em bts.jsonc