@seedgrid/ai-toolkit 0.3.0 → 0.3.1

package/README.md

@@ -4,7 +4,17 @@ Fonte versionada de **agentes (papéis), skills, regras, templates, referências
 
 O toolkit **não** é um orquestrador de modelos: não chama APIs da OpenAI ou da Anthropic, não guarda credenciais e não escolhe fornecedores. Ele instala instruções e configurações; a ferramenta de IA executa e coordena o trabalho.
 
-> Estado: versão 0.3.0 (pacote e conteúdo), pronta para publicar no npm como `@seedgrid/ai-toolkit`. Licença MIT. O pacote ainda **não foi publicado** no npm e o repositório GitHub ainda não existe.
+> Pacote público no npm como `@seedgrid/ai-toolkit` (licença MIT); código em https://github.com/SeedGrid/seedgrid-ai. A versão do pacote e a do conteúdo instalado são a mesma.
+
+## Instalação rápida
+
+```bash
+npx @seedgrid/ai-toolkit@latest install   # uma vez por máquina: instala o comando seedgrid-ai (npm install -g)
+cd /caminho/do/projeto
+seedgrid-ai init                          # instala o toolkit no projeto
+```
+
+Depois é só `seedgrid-ai update`, `seedgrid-ai status`, `seedgrid-ai doctor`, `seedgrid-ai review` etc. (`seedgrid-ai --help` lista tudo). Sem instalar o comando, qualquer comando também funciona com `npx @seedgrid/ai-toolkit <comando>`. Abra uma **sessão nova** do Claude Code ou do Codex depois de instalar no projeto.
 
 ## O que é instalado
 
@@ -66,6 +76,7 @@ seedgrid-ai init --target both --mode shared
 ## Comandos
 
 ```bash
+seedgrid-ai install                              # instala o comando seedgrid-ai na máquina (npm install -g)
 seedgrid-ai init --target both --mode shared     # padrão; idempotente
 seedgrid-ai init --target both --mode native     # também registra subagentes nativos
 seedgrid-ai init --source ./seedgridKB --dry-run    # fonte local (desenvolvimento), só o plano
@@ -118,15 +129,15 @@ Seleção de papéis e delegação são comportamentos orientados por instruçõ
 
 ## Uso via npm
 
-Depois que a versão for publicada:
-
 ```bash
+npx @seedgrid/ai-toolkit@latest install     # instala o comando seedgrid-ai nesta máquina (uma vez; repita para atualizar o comando)
 cd /caminho/do/projeto
-npx @seedgrid/ai-toolkit@0.2.0 init --target both     # primeira instalação
-npx @seedgrid/ai-toolkit@latest update                # traz o conteúdo da versão mais recente
+seedgrid-ai init --target both              # primeira instalação no projeto
+seedgrid-ai update                          # leva o projeto ao conteúdo da versão do comando instalado
+npx @seedgrid/ai-toolkit@latest update      # ou: usa a versão mais recente sem instalar nada
 ```
 
-Ou instale o comando globalmente: `npm i -g @seedgrid/ai-toolkit` e use `seedgrid-ai`. Se houver versão mais nova publicada, `init`, `update` e `status` avisam e, no terminal, perguntam se devem usá-la (`[Y/n]`); desative com `--no-update-check`. Detalhes em [docs/instalacao.md](docs/instalacao.md#aviso-de-versão-nova). O pacote leva o CLI compilado e o conteúdo; a versão do pacote identifica o conteúdo instalado, e `update` nunca baixa conteúdo por conta própria. Faça commit do resultado no projeto: o restante da equipe recebe tudo pelo Git, sem rodar o CLI.
+`install` executa `npm install -g @seedgrid/ai-toolkit@<versão deste CLI>` e confere se `seedgrid-ai` ficou no PATH; não toca em nenhum projeto (`--dry-run` mostra o comando). Se der erro de permissão, configure um prefixo global do npm para o seu usuário ou continue usando `npx`. Se houver versão mais nova publicada, `init`, `update` e `status` avisam e, no terminal, perguntam se devem usá-la (`[Y/n]`); desative com `--no-update-check`. Detalhes em [docs/instalacao.md](docs/instalacao.md#aviso-de-versão-nova). O pacote leva o CLI compilado e o conteúdo; a versão do pacote identifica o conteúdo instalado, e `update` nunca baixa conteúdo por conta própria. Faça commit do resultado no projeto: o restante da equipe recebe tudo pelo Git, sem rodar o CLI.
 
 ## Repositório e publicação
 

package/dist/cli.js

@@ -7,15 +7,18 @@ import { doctorCommand } from './commands/doctor.js';
 import { initCommand } from './commands/init.js';
 import { removeCommand } from './commands/remove.js';
 import { reviewCommand } from './commands/review.js';
+import { selfInstallCommand } from './commands/selfinstall.js';
 import { statusCommand } from './commands/status.js';
 import { updateCommand } from './commands/update.js';
 import { validateCommand } from './commands/validate.js';
 import { cliVersion } from './core/env.js';
+import { TOOL_NAME } from './core/lock.js';
 import { ToolkitError } from './core/types.js';
 import { checkLatest, confirm, isInteractive, npxCommandLine, runPublishedVersion, } from './core/updates.js';
 const HELP = `seedgrid-ai — instala o SeedGrid AI Toolkit em projetos locais (Claude Code e Codex)
 
 Comandos:
+  install   Instala o comando seedgrid-ai nesta máquina (npm install -g), para usar sem npx; não altera nenhum projeto
   init      Instala o toolkit (regras, papéis, skills, base de conhecimento) no projeto; idempotente
   update    Leva o projeto ao conteúdo da versão do CLI em execução (use npx @seedgrid/ai-toolkit@latest para a mais nova)
   status    Mostra versões, opções e divergências da instalação
@@ -26,6 +29,7 @@ Comandos:
   help      Mostra esta ajuda
 
 Uso:
+  seedgrid-ai install  [--dry-run]
   seedgrid-ai init     [--target claude|codex|both] [--mode shared|native] [--source <pasta>] [--dry-run]
   seedgrid-ai update   [--target ...] [--mode ...] [--source <pasta>] [--dry-run]
   seedgrid-ai status
@@ -46,10 +50,12 @@ Opções comuns:
   --no-update-check    Não consulta o npm por versões mais novas (também: SEEDGRID_AI_NO_UPDATE_CHECK=1)
   --version, --help
 
+Primeira vez: npx @seedgrid/ai-toolkit@latest install  (depois use seedgrid-ai init, update, ... sem npx)
 Padrões do init: --target both --mode shared (ou as opções do lock existente).
 Em terminal interativo, init/update/status perguntam se devem usar uma versão mais nova publicada no npm.
 Conflitos abortam a operação inteira (código de saída 2); nada é sobrescrito.`;
 const COMMANDS = {
+    install: { handler: selfInstallCommand, allowed: ['dry-run'] },
     init: { handler: initCommand, allowed: ['target', 'mode', 'source', 'dry-run'] },
     update: { handler: updateCommand, allowed: ['target', 'mode', 'source', 'dry-run'] },
     status: { handler: statusCommand, allowed: [] },
@@ -174,7 +180,7 @@ export async function main(argv) {
     }
 }
 function updateNotice(info, args) {
-    return `Aviso: versão ${info.latest} disponível no npm (este CLI: ${info.current}). Para usá-la: ${npxCommandLine(info.latest, args)}`;
+    return `Aviso: versão ${info.latest} disponível no npm (este CLI: ${info.current}). Para usá-la: ${npxCommandLine(info.latest, args)}. Para atualizar o comando seedgrid-ai instalado na máquina: npx ${TOOL_NAME}@latest install`;
 }
 /** Repassa o comando para a versão publicada mais nova. */
 async function delegate(info, args) {

package/dist/commands/selfinstall.js

@@ -0,0 +1,63 @@
+import { exec } from 'node:child_process';
+import { cliVersion } from '../core/env.js';
+import { TOOL_NAME } from '../core/lock.js';
+import { EXIT_ERROR, EXIT_OK } from './common.js';
+/** Executa um comando fixo (sem entrada do usuário) e devolve o resultado. shell é necessário para npm.cmd no Windows. */
+function runFixed(command, timeoutMs) {
+    return new Promise((resolve) => {
+        const child = exec(command, { timeout: timeoutMs, windowsHide: true, maxBuffer: 16 * 1024 * 1024 }, (err, stdout, stderr) => {
+            const e = err;
+            resolve({ code: e ? (typeof e.code === 'number' ? e.code : null) : 0, stdout: stdout.toString(), stderr: stderr.toString() });
+        });
+        child.stdin?.end();
+    });
+}
+/**
+ * Instala o comando `seedgrid-ai` na máquina (npm install -g), na versão deste CLI.
+ * Depois, os demais comandos ficam disponíveis sem npx. Não toca em nenhum projeto.
+ */
+export async function selfInstallCommand(opts) {
+    const version = cliVersion();
+    const command = `npm install -g ${TOOL_NAME}@${version}`;
+    const base = { command: 'install', version, npmCommand: command };
+    if (opts.dryRun) {
+        return {
+            exitCode: EXIT_OK,
+            report: { ...base, dryRun: true },
+            lines: [`Executaria: ${command}`, 'Nada foi instalado (--dry-run).'],
+        };
+    }
+    const run = opts.npmRunner ?? runFixed;
+    const result = await run(command, 5 * 60 * 1000);
+    if (result.code !== 0) {
+        const detail = (result.stderr.trim() || result.stdout.trim() || '(sem saída)').split('\n').slice(-8).join('\n');
+        return {
+            exitCode: EXIT_ERROR,
+            report: { ...base, ok: false, code: result.code, stderr: result.stderr },
+            lines: [
+                `Não foi possível instalar com "${command}" (código ${result.code ?? 'desconhecido'}).`,
+                detail,
+                '',
+                'Se for permissão, configure um prefixo global do npm para o seu usuário ou rode o terminal com a permissão necessária.',
+                'Sem instalar, você ainda pode usar: npx @seedgrid/ai-toolkit <comando>',
+            ],
+        };
+    }
+    const check = await run('seedgrid-ai --version', 30 * 1000);
+    const found = check.code === 0 && check.stdout.trim() === version;
+    return {
+        exitCode: EXIT_OK,
+        report: { ...base, ok: true, onPath: found },
+        lines: [
+            `Instalado: ${TOOL_NAME}@${version} (comando seedgrid-ai).`,
+            found
+                ? 'O comando já está disponível neste terminal.'
+                : 'Se "seedgrid-ai" não for reconhecido, abra um novo terminal ou confira se a pasta global do npm (npm prefix -g) está no PATH.',
+            '',
+            'Próximos passos, na pasta do projeto:',
+            '  seedgrid-ai init       # instala o toolkit no projeto',
+            '  seedgrid-ai --help     # lista todos os comandos',
+            `Para atualizar o próprio comando no futuro: npx ${TOOL_NAME}@latest install`,
+        ],
+    };
+}

package/docs/formato.md

@@ -57,7 +57,7 @@ Arquivos e pastas que começam com ponto são ignorados.
 ```json
 {
   "schemaVersion": 2,
-  "contentVersion": "0.3.0",
+  "contentVersion": "0.3.1",
   "toolkitBase": "SeedGrid/Toolkit",
   "components": [
     { "id": "agents", "type": "agents", "files": ["agents/arquiteto.md"] },

package/docs/instalacao.md

@@ -1,6 +1,6 @@
 # Instalação em projetos
 
-Os exemplos usam `seedgrid-ai`. Sem `npm link`, troque por `node <pasta-do-toolkit>/dist/cli.js`.
+Os exemplos usam o comando `seedgrid-ai`. Para tê-lo na máquina: `npx @seedgrid/ai-toolkit@latest install` (executa `npm install -g`, uma vez; repita para atualizar o comando). Sem instalar, troque `seedgrid-ai` por `npx @seedgrid/ai-toolkit`; em desenvolvimento do toolkit, por `node <pasta-do-toolkit>/dist/cli.js`.
 
 ## Primeira instalação
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@seedgrid/ai-toolkit",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "Instala agentes, skills, regras, templates e referências versionados em projetos locais para Claude Code e Codex.",
   "type": "module",
   "license": "MIT",