@seedgrid/ai-toolkit 0.0.0-stage → 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SeedGrid
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,152 @@
-# Temporary Holding Version
+# SeedGrid AI Toolkit
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Fonte versionada de **agentes (papéis), skills, regras, templates, referências e a base de conhecimento SeedGrid (KB)** para assistentes de código, independente de provedor, e um CLI (`seedgrid-ai`) que instala esse conteúdo em projetos locais para o **Claude Code** e o **Codex**, pelos mecanismos nativos de cada ferramenta.
+
+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.
+
+## O que é instalado
+
+Cada pasta de `.ai/` (`rules`, `agents`, `skills`, `templates`, `references`) tem um `index.md` **gerado** a partir do frontmatter dos arquivos. O bloco do `AGENTS.md` aponta para as pastas e manda começar pelo `index.md`; ele não lista arquivos, então não cresce quando entram novas rules, skills ou templates.
+
+| Destino | Conteúdo |
+| --- | --- |
+| `.ai/agents/` | Papéis (`arquiteto`, `backend-java`, `backend-rust`, `frontend-react`, `qa`, `revisor`) e `index.md` gerado |
+| `.ai/rules/` | Coordenação, formato de entrega, personalização local e os **padrões SeedGrid obrigatórios** (`frontend-seedgrid`, `backend-java-seedgrid`) |
+| `.ai/templates/` | Especificação de tarefa, decisão de arquitetura, relatório de validação |
+| `.ai/references/` | Modos shared/native e glossário |
+| `.ai/skills/index.md` | Índice gerado das skills (o que faz e quando usar) |
+| `.ai/brain/SeedGrid/` | **Base de conhecimento SeedGrid** (extensions Quarkus, componentes React, propriedades, enums): ~157 notas Markdown, somente leitura |
+| `.ai/toolkit-lock.json` | Versões, opções e hashes SHA-256 dos arquivos e blocos gerenciados |
+| `.ai/backups/` | Backups locais por operação (ignorados pelo Git via `.ai/backups/.gitignore`) |
+| `.claude/skills/<nome>/` | Skills para o Claude Code |
+| `.agents/skills/<nome>/` | Skills para o Codex |
+| `AGENTS.md` | Bloco gerenciado que referencia o toolkit (lido pelo Codex) |
+| `CLAUDE.md` | Bloco gerenciado com `@AGENTS.md` (o Claude Code lê CLAUDE.md, não AGENTS.md) |
+| `.claude/agents/<id>.md` | Somente `--mode native`: subagentes do Claude Code |
+| `.codex/agents/<id>.toml` | Somente `--mode native`: agentes personalizados do Codex |
+
+Skills: `planejar-mudanca`, `revisar-codigo`, `validar-mudanca` (genéricas) e `seedgrid-crud`, `seedgrid-new-screen`, `seedgrid-review` (padrões SeedGrid). Toda instalação recebe todas as skills.
+
+## A base de conhecimento (seedgridKB)
+
+O repositório é, ao mesmo tempo, um **vault do Obsidian**: abra a pasta `seedgridKB/` no Obsidian para navegar, buscar e editar tudo (KB, skills, agentes e regras) com grafo e backlinks. O mesmo vault é a fonte do que o CLI distribui:
+
+- `seedgridKB/SeedGrid/` (documentação das extensions e dos componentes) vira `.ai/brain/SeedGrid/` nos projetos;
+- `seedgridKB/SeedGrid/Toolkit/` (agents, rules, templates, references, skills) vira `.ai/`, `.claude/skills/` e `.agents/skills/`.
+
+O bloco que o CLI grava no `AGENTS.md` do projeto manda o Claude/Codex consultar a KB pelos índices antes de usar ou configurar qualquer extension ou componente SeedGrid, e não inventar o que a KB não traz. Veja [docs/formato.md](docs/formato.md#o-vault).
+
+Em `AGENTS.md` e `CLAUDE.md`, o toolkit altera **somente** o trecho entre `<!-- BEGIN SEEDGRID AI TOOLKIT -->` e `<!-- END SEEDGRID AI TOOLKIT -->`. Personalizações do projeto ficam em `.ai/local/`, que o toolkit nunca toca.
+
+## Uso local (sem npm público)
+
+Requisitos: Node.js 22.12 ou superior (LTS).
+
+```bash
+# na pasta do toolkit
+npm install
+npm run build
+npm test            # opcional: 34 testes em diretórios temporários
+
+# executar o JavaScript compilado contra um projeto
+node dist/cli.js init --project "C:/caminho/do/projeto" --target both --mode shared
+```
+
+Opcionalmente, registre o comando `seedgrid-ai` globalmente via link (aponta para esta pasta; recompile após mudanças):
+
+```bash
+npm link
+cd /caminho/do/projeto
+seedgrid-ai init --target both --mode shared
+# para desfazer: npm unlink -g @seedgrid/ai-toolkit
+```
+
+## Comandos
+
+```bash
+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
+seedgrid-ai status                               # versões, opções e divergências
+seedgrid-ai doctor                               # diagnóstico de sintaxe, consistência e limitações
+seedgrid-ai doctor --probe                       # + confirma descoberta real no Codex (sem chamar o modelo)
+seedgrid-ai update --dry-run                     # plano da atualização
+seedgrid-ai update                               # aplica o conteúdo empacotado no CLI em execução
+seedgrid-ai remove --dry-run
+seedgrid-ai remove
+seedgrid-ai validate --source ./seedgridKB          # valida uma fonte de conteúdo
+seedgrid-ai review                               # confere o código contra os padrões SeedGrid (front e back, só os arquivos alterados)
+seedgrid-ai review front --full                  # só o front-end, projeto inteiro
+seedgrid-ai review back --tool codex             # só o back-end, usando o Codex
+```
+
+- `--target`: `claude`, `codex` ou `both` (padrão `both`). `--mode`: `shared` (padrão) ou `native`.
+- `--project <caminho>`: projeto alvo (padrão: pasta atual). Caminhos com espaços e Unicode são suportados.
+- `--source <pasta>`: fonte de conteúdo local, relativa à pasta atual. Sem ela, usa o conteúdo empacotado no CLI.
+- `--dry-run`: gera o plano e não escreve nenhum arquivo. `--json`: saída para scripts.
+- Códigos de saída: `0` sucesso, `1` erro, `2` conflito (nada foi alterado), `3` (`review`) revisão concluída com violações.
+
+### `seedgrid-ai review`
+
+Executa a skill `seedgrid-review` na ferramenta de IA instalada, em modo não interativo e somente leitura (Claude Code: `claude -p` com ferramentas de leitura; Codex: `codex exec --sandbox read-only`). A skill confere o código contra as regras `FE-nn` e `BE-nn` (`.ai/rules/frontend-seedgrid.md` e `backend-java-seedgrid.md`) e o CLI mostra o relatório e devolve o código de saída.
+
+- **Escopo:** `front`, `back` ou nenhum (os dois). Por padrão revisa os arquivos alterados (diff); `--full` revisa o projeto inteiro.
+- **Ferramenta:** `--tool claude|codex`. Sem a opção, usa a primeira disponível nesta ordem: Claude Code, Codex. Considera só os targets instalados no projeto que tenham a skill e o executável no `PATH`. O CLI não detecta em qual ferramenta você está trabalhando.
+- **Custo e login:** chama o modelo com o seu login na ferramenta e **consome tokens**. É o único comando que faz isso. Nenhum token é lido nem gravado pelo CLI.
+- **Resultado não determinístico:** a revisão é feita por um modelo; execuções repetidas podem apontar itens um pouco diferentes (nos testes, as duas ferramentas acharam as violações óbvias e divergiram nos itens de julgamento). Trate o resultado como revisão, não como prova.
+- **Saída estruturada:** a skill termina com um bloco `seedgrid-review-json`. Se a ferramenta falhar, esgotar o tempo (15 min) ou responder sem o bloco, o comando sai com `1` e mostra o texto bruto; nunca conta como "sem violações".
+- Exige o toolkit instalado (`init`) com a skill `seedgrid-review` (`update` leva as skills novas a projetos já instalados).
+
+Depois de instalar ou atualizar, **abra uma nova sessão** do Claude Code ou do Codex. Não há recarga garantida em todas as ferramentas.
+
+## Conflitos e segurança
+
+- Arquivo gerenciado modificado localmente, arquivo preexistente diferente ou bloco editado → **conflito**: a operação inteira é abortada antes de qualquer escrita. Não existe opção que force sobrescrita de customizações.
+- Antes de alterar ou apagar arquivos existentes, o CLI guarda cópias em `.ai/backups/<operação>/`. Se uma escrita falhar, tenta desfazer tudo e informa se o rollback foi incompleto.
+- `remove` apaga apenas arquivos gerenciados intactos e blocos intactos; pastas com conteúdo de terceiros permanecem.
+- O lock é tratado como entrada não confiável: caminhos fora das áreas gerenciadas, absolutos ou com `..` são rejeitados, assim como destinos que passem por links simbólicos para fora do projeto.
+- Scripts de skills nunca são executados na instalação. Nenhum token é gravado e nenhuma permissão das ferramentas de IA é alterada.
+
+## shared x native
+
+- **shared** (padrão): catálogo e papéis em `.ai/`. A sessão principal lê o catálogo, escolhe papéis e delega pelo mecanismo disponível; sem subagentes, aplica o papel na própria sessão e informa isso.
+- **native**: além do shared, gera `.claude/agents/` e `.codex/agents/` a partir dos mesmos papéis (sem duplicar autoria). Validado no Claude Code 2.1.299 e no Codex 0.160.1 (veja [docs/compatibilidade.md](docs/compatibilidade.md)). No Codex, os agentes de projeto **só carregam se o projeto for confiável** (trusted).
+
+Seleção de papéis e delegação são comportamentos orientados por instruções, não garantias do instalador.
+
+## Uso via npm
+
+Depois que a versão for publicada:
+
+```bash
+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
+```
+
+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.
+
+## Repositório e publicação
+
+O código-fonte fica no GitHub; usuários não precisam cloná-lo. Para criar o repositório:
+
+```bash
+git init
+git add .
+git commit -m "SeedGrid AI Toolkit 0.2.0"
+git branch -M main
+git remote add origin git@github.com:SeedGrid/seedgrid-ai.git
+git push -u origin main
+```
+
+O `.gitignore` já exclui `node_modules/`, `dist/`, `build-test/`, `*.tgz` e arquivos `.env`. O CI (`.github/workflows/ci.yml`) testa cada push e pull request; o workflow `release.yml` publica no npm a cada tag `vX.Y.Z`. Passo a passo da primeira publicação e do lançamento de versões: [docs/manutencao.md](docs/manutencao.md#publicação-no-npm).
+
+## Documentação
+
+- [docs/arquitetura.md](docs/arquitetura.md) — módulos, fluxo de planejamento e escrita, lock.
+- [docs/instalacao.md](docs/instalacao.md) — instalação, atualização, remoção e recuperação em projetos.
+- [docs/formato.md](docs/formato.md) — autoria de conteúdo: manifesto, papéis, skills, templates.
+- [docs/manutencao.md](docs/manutencao.md) — versões, testes, empacotamento, publicação e smoke test.
+- [docs/compatibilidade.md](docs/compatibilidade.md) — versões testadas, caminhos validados e limitações reais.

package/dist/adapters/claude.js

@@ -0,0 +1,114 @@
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { parseFrontmatter, renderFrontmatter } from '../core/frontmatter.js';
+import { scanBlock } from '../core/blocks.js';
+import { GENERATED_NOTICE } from './types.js';
+/**
+ * Tradução de capacidades portáveis para ferramentas do Claude Code.
+ * Restringir "tools" limita o subagente, mas não é um mecanismo de segurança do projeto.
+ */
+const TOOLS_BY_CAPABILITY = {
+    'read-files': ['Read', 'Grep', 'Glob'],
+    'edit-files': ['Edit', 'Write'],
+    'run-checks': ['Bash'],
+};
+export function claudeTools(agent) {
+    if (agent.capabilities.length === 0)
+        return null; // herda as ferramentas da sessão
+    const tools = new Set();
+    for (const c of agent.capabilities)
+        for (const t of TOOLS_BY_CAPABILITY[c])
+            tools.add(t);
+    if (agent.preferredSkills.length > 0)
+        tools.add('Skill');
+    return [...tools];
+}
+export function renderClaudeAgent(agent, contentVersion) {
+    const data = { name: agent.id, description: agent.description };
+    const tools = claudeTools(agent);
+    if (tools)
+        data.tools = tools.join(', ');
+    const skills = agent.preferredSkills.length > 0 ? `Skills preferidas: ${agent.preferredSkills.join(', ')}.\n\n` : '';
+    const body = [
+        `<!-- ${GENERATED_NOTICE} a partir de .ai/agents/${agent.id}.md (conteúdo ${contentVersion}). Não edite; personalize em .ai/local/. -->`,
+        '',
+        `Você atua no papel \`${agent.id}\` do SeedGrid AI Toolkit. Siga AGENTS.md, .ai/rules/formato-entrega.md e, se existir, .ai/local/.`,
+        '',
+        `${skills}${agent.body.trim()}`,
+        '',
+    ].join('\n');
+    return renderFrontmatter(data, body);
+}
+export const claudeAdapter = {
+    target: 'claude',
+    displayName: 'Claude Code',
+    skillsDir: '.claude/skills',
+    nativeAgentsDir: '.claude/agents',
+    nativeAgentExtension: '.md',
+    versionCommand: 'claude --version',
+    validatedVersions: ['2.1.299'],
+    reviewCommand: (prompt) => `claude -p "${prompt}" --allowedTools "Read,Grep,Glob,Bash(git diff:*),Bash(git status:*),Bash(git log:*),Bash(git ls-files:*)"`,
+    probeCommand: null, // não há comando que liste skills/agentes sem abrir uma sessão com o modelo
+    skillFiles(bundle) {
+        return bundle.skills.flatMap((s) => s.files.map((f) => ({ path: `.claude/skills/${s.name}/${f.path}`, content: f.content, component: `skill:${s.name}` })));
+    },
+    nativeAgentFiles(bundle) {
+        return bundle.agents.map((a) => ({
+            path: `.claude/agents/${a.id}.md`,
+            content: renderClaudeAgent(a, bundle.contentVersion),
+            component: 'native:claude',
+        }));
+    },
+    blocks() {
+        return [
+            {
+                file: 'CLAUDE.md',
+                inner: [
+                    '## SeedGrid AI Toolkit',
+                    '',
+                    '@AGENTS.md',
+                    '',
+                    'Bloco gerenciado pelo `seedgrid-ai`. As instruções do projeto estão em `AGENTS.md` (importado acima) e as regras compartilhadas em `.ai/rules/`. Siga-as também no Claude Code. Não edite entre os marcadores.',
+                ].join('\n'),
+            },
+        ];
+    },
+    checkNativeAgent(relPath, content) {
+        const fm = parseFrontmatter(content);
+        if ('error' in fm)
+            return [{ level: 'erro', message: `${relPath}: ${fm.error}` }];
+        const issues = [];
+        const name = fm.data.name;
+        if (typeof name !== 'string' || name.length === 0 || name.length > 256 || name.includes(':') || name.startsWith('-')) {
+            issues.push({ level: 'erro', message: `${relPath}: name ausente ou inválido; o Claude Code ignora o arquivo` });
+        }
+        if (typeof fm.data.description !== 'string' || fm.data.description.trim() === '') {
+            issues.push({ level: 'erro', message: `${relPath}: description ausente; o Claude Code ignora o arquivo` });
+        }
+        return issues;
+    },
+    async projectChecks(projectRoot) {
+        const issues = [];
+        try {
+            const text = await readFile(path.join(projectRoot, 'CLAUDE.md'), 'utf8');
+            const scan = scanBlock(text);
+            if (scan.status === 'one' && !/^@AGENTS\.md\s*$/m.test(scan.inner)) {
+                issues.push({ level: 'erro', message: 'CLAUDE.md: o bloco gerenciado não importa @AGENTS.md' });
+            }
+        }
+        catch {
+            issues.push({ level: 'erro', message: 'CLAUDE.md ausente: o Claude Code não lê AGENTS.md diretamente' });
+        }
+        return issues;
+    },
+    limitations(mode) {
+        const out = [
+            'O Claude Code lê CLAUDE.md, não AGENTS.md; o bloco em CLAUDE.md importa AGENTS.md com @AGENTS.md.',
+            'Skills e agentes de projeto só são carregados em sessões abertas na pasta do projeto (ou subpastas até a raiz do repositório).',
+        ];
+        if (mode === 'native') {
+            out.push('Se .claude/agents/ não existia quando a sessão começou, reinicie a sessão para o Claude Code observar a pasta.', 'O campo tools limita as ferramentas do subagente, mas não substitui permissões nem sandbox.');
+        }
+        return out;
+    },
+};

package/dist/adapters/codex.js

@@ -0,0 +1,108 @@
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { parse as parseToml } from 'smol-toml';
+import { GENERATED_NOTICE } from './types.js';
+function tomlBasicString(value) {
+    return JSON.stringify(value); // strings JSON simples são strings básicas TOML válidas
+}
+/** String multilinha legível; usa literal ''' quando possível. */
+export function tomlMultiline(value) {
+    const text = value.replace(/\r\n/g, '\n');
+    if (!text.includes("'''") && !/[\x00-\x08\x0b-\x1f\x7f]/.test(text)) {
+        return `'''\n${text}'''`;
+    }
+    const escaped = text
+        .replace(/\\/g, '\\\\')
+        .replace(/"""/g, '""\\"')
+        .replace(/[\x00-\x08\x0b-\x1f\x7f]/g, (c) => `\\u${c.charCodeAt(0).toString(16).padStart(4, '0')}`);
+    return `"""\n${escaped}"""`;
+}
+export function renderCodexAgent(agent, contentVersion) {
+    const skills = agent.preferredSkills.length > 0 ? `Skills preferidas: ${agent.preferredSkills.join(', ')}.\n\n` : '';
+    const instructions = [
+        `Você atua no papel \`${agent.id}\` do SeedGrid AI Toolkit. Siga AGENTS.md, .ai/rules/formato-entrega.md e, se existir, .ai/local/.`,
+        '',
+        `${skills}${agent.body.trim()}`,
+        '',
+    ].join('\n');
+    return [
+        `# ${GENERATED_NOTICE} a partir de .ai/agents/${agent.id}.md (conteúdo ${contentVersion}).`,
+        '# Não edite; personalize em .ai/local/.',
+        `name = ${tomlBasicString(agent.id)}`,
+        `description = ${tomlBasicString(agent.description)}`,
+        `developer_instructions = ${tomlMultiline(instructions)}`,
+        '',
+    ].join('\n');
+}
+export const codexAdapter = {
+    target: 'codex',
+    displayName: 'Codex',
+    skillsDir: '.agents/skills',
+    nativeAgentsDir: '.codex/agents',
+    nativeAgentExtension: '.toml',
+    versionCommand: 'codex --version',
+    validatedVersions: ['0.160.1'],
+    // Renderiza o prompt visível ao modelo (AGENTS.md e lista de skills) sem chamar o modelo.
+    reviewCommand: (prompt) => `codex exec --sandbox read-only "${prompt}"`,
+    probeCommand: 'codex debug prompt-input "seedgrid-ai doctor --probe"',
+    skillFiles(bundle) {
+        return bundle.skills.flatMap((s) => s.files.map((f) => ({ path: `.agents/skills/${s.name}/${f.path}`, content: f.content, component: `skill:${s.name}` })));
+    },
+    nativeAgentFiles(bundle) {
+        // Um arquivo por agente em .codex/agents/; .codex/config.toml não é alterado.
+        return bundle.agents.map((a) => ({
+            path: `.codex/agents/${a.id}.toml`,
+            content: renderCodexAgent(a, bundle.contentVersion),
+            component: 'native:codex',
+        }));
+    },
+    blocks() {
+        return []; // o Codex lê AGENTS.md nativamente
+    },
+    checkNativeAgent(relPath, content) {
+        let data;
+        try {
+            data = parseToml(content);
+        }
+        catch (err) {
+            return [{ level: 'erro', message: `${relPath}: TOML inválido: ${err.message.split('\n')[0]}` }];
+        }
+        const issues = [];
+        for (const key of ['name', 'description', 'developer_instructions']) {
+            if (typeof data[key] !== 'string' || data[key].trim() === '') {
+                issues.push({ level: 'erro', message: `${relPath}: campo obrigatório "${key}" ausente` });
+            }
+        }
+        return issues;
+    },
+    async projectChecks(projectRoot, mode) {
+        const issues = [];
+        if (mode !== 'native')
+            return issues;
+        let raw = null;
+        try {
+            raw = await readFile(path.join(projectRoot, '.codex', 'config.toml'), 'utf8');
+        }
+        catch {
+            return issues;
+        }
+        try {
+            const cfg = parseToml(raw);
+            const agents = cfg.agents;
+            if (agents && agents.enabled === false) {
+                issues.push({ level: 'aviso', message: '.codex/config.toml define [agents] enabled = false; subagentes estão desativados' });
+            }
+        }
+        catch (err) {
+            issues.push({ level: 'erro', message: `.codex/config.toml inválido: ${err.message.split('\n')[0]}` });
+        }
+        return issues;
+    },
+    limitations(mode) {
+        const out = ['O Codex lê AGENTS.md e .agents/skills/ a partir da pasta atual até a raiz do repositório.'];
+        if (mode === 'native') {
+            out.push('O Codex só carrega camadas .codex/ do projeto (inclusive .codex/agents/) quando o projeto é confiável (trusted).', 'capabilities não são traduzidas para o Codex: a leitura de arquivos usa o shell, e sandbox_mode/approval_policy em arquivos de agente não sobrescrevem a sessão principal.');
+        }
+        return out;
+    },
+};

package/dist/adapters/index.js

@@ -0,0 +1,17 @@
+import { claudeAdapter } from './claude.js';
+import { codexAdapter } from './codex.js';
+import { agentsMdBlock, sharedFiles } from './shared.js';
+export const ADAPTERS = { claude: claudeAdapter, codex: codexAdapter };
+/** Estado completo desejado no projeto para os targets e o modo escolhidos. */
+export function buildDesiredState(bundle, targets, mode) {
+    const files = sharedFiles(bundle, targets);
+    const blocks = [agentsMdBlock(bundle, targets, mode)];
+    for (const t of targets) {
+        const a = ADAPTERS[t];
+        files.push(...a.skillFiles(bundle));
+        if (mode === 'native')
+            files.push(...a.nativeAgentFiles(bundle));
+        blocks.push(...a.blocks(bundle));
+    }
+    return { files, blocks };
+}

package/dist/adapters/shared.js

@@ -0,0 +1,142 @@
+import { GENERATED_NOTICE } from './types.js';
+export const SHARED_ROOT = '.ai';
+/** Destino instalado de um arquivo compartilhado (ex.: rules/x.md -> .ai/rules/x.md). */
+export function sharedDest(contentPath) {
+    return `${SHARED_ROOT}/${contentPath}`;
+}
+function escapeCell(text) {
+    return text.replace(/\|/g, '\\|').replace(/\s*\n\s*/g, ' ');
+}
+/** Catálogo curto, gerado do frontmatter dos papéis para não duplicar autoria. */
+export function renderCatalog(bundle) {
+    const lines = [
+        '# Índice de papéis',
+        '',
+        `<!-- ${GENERATED_NOTICE} a partir do frontmatter de agents/*.md (conteúdo ${bundle.contentVersion}). Não edite. -->`,
+        '',
+        'Escolha papéis por esta tabela. Leia a definição completa apenas dos papéis selecionados.',
+        '',
+        '| Papel | Quando usar | Capacidades | Skills preferidas | Definição |',
+        '| --- | --- | --- | --- | --- |',
+        ...bundle.agents.map((a) => `| ${a.id} | ${escapeCell(a.description)} | ${a.capabilities.join(', ') || '-'} | ${a.preferredSkills.join(', ') || '-'} | [${a.id}.md](${a.id}.md) |`),
+        '',
+    ];
+    return lines.join('\n');
+}
+const FOLDER_INDEX = {
+    rules: { title: 'Índice de regras', intro: 'Leia a regra quando a descrição combinar com a tarefa.' },
+    templates: {
+        title: 'Índice de templates',
+        intro: 'Copie o modelo para o local de documentação do projeto antes de preencher; não edite o modelo.',
+    },
+    references: { title: 'Índice de referências', intro: 'Conhecimento estático do toolkit. Leia só o que a tarefa pedir.' },
+};
+/** Índice de rules, templates ou references, gerado do frontmatter para o AGENTS.md não listar arquivos. */
+export function renderFolderIndex(bundle, type) {
+    const files = bundle.shared.filter((s) => s.type === type).sort((a, b) => a.path.localeCompare(b.path));
+    const { title, intro } = FOLDER_INDEX[type];
+    return [
+        `# ${title}`,
+        '',
+        `<!-- ${GENERATED_NOTICE} a partir do frontmatter de ${type}/*.md (conteúdo ${bundle.contentVersion}). Não edite. -->`,
+        '',
+        intro,
+        '',
+        '| Arquivo | O que é e quando usar |',
+        '| --- | --- |',
+        ...files.map((f) => {
+            const name = f.path.slice(type.length + 1);
+            return `| [${name}](${name}) | ${escapeCell(f.description ?? '')} |`;
+        }),
+        '',
+    ].join('\n');
+}
+export const SKILLS_INDEX_FILE = '.ai/skills/index.md';
+/** Índice das skills do toolkit, gerado das descrições para o AGENTS.md não crescer a cada skill nova. */
+export function renderSkillsIndex(bundle, targets) {
+    const cell = (t) => t.replace(/\|/g, '\\|').replace(/\s*\n\s*/g, ' ').trim();
+    const dirs = [targets.includes('claude') ? '.claude/skills' : null, targets.includes('codex') ? '.agents/skills' : null].filter((d) => d !== null);
+    const lines = [
+        '# Índice de skills',
+        '',
+        `<!-- ${GENERATED_NOTICE} a partir do frontmatter de cada SKILL.md (conteúdo ${bundle.contentVersion}). Não edite. -->`,
+        '',
+        'Skills instaladas pelo SeedGrid AI Toolkit. Antes de uma tarefa que combine com a descrição, leia o `SKILL.md` indicado e siga-o. Skills do próprio projeto que não são do toolkit não aparecem aqui.',
+        '',
+        '| Skill | O que faz e quando usar | Arquivo |',
+        '| --- | --- | --- |',
+        ...bundle.skills.map((k) => `| \`${k.name}\` | ${cell(k.description)} | ${dirs.map((d) => `\`${d}/${k.name}/SKILL.md\``).join(' ou ')} |`),
+        '',
+    ];
+    return lines.join('\n');
+}
+export function sharedFiles(bundle, targets) {
+    const files = bundle.shared.map((s) => ({
+        path: sharedDest(s.path),
+        content: s.content,
+        component: s.component,
+    }));
+    files.push({ path: sharedDest('agents/index.md'), content: renderCatalog(bundle), component: 'agents' });
+    for (const type of ['rules', 'templates', 'references']) {
+        files.push({ path: sharedDest(`${type}/index.md`), content: renderFolderIndex(bundle, type), component: type });
+    }
+    files.push({ path: SKILLS_INDEX_FILE, content: renderSkillsIndex(bundle, targets), component: 'skills-index' });
+    return files;
+}
+/** Instruções de consulta à base de conhecimento SeedGrid (.ai/brain/), quando o conteúdo a inclui. */
+function brainLines(bundle) {
+    if (!bundle.brain)
+        return [];
+    const entries = bundle.brain.entrypoints.map((e) => `\`${e}\``).join(', ');
+    return [
+        `- **Base de conhecimento SeedGrid** (extensions Quarkus, componentes React, propriedades e enums): \`.ai/brain/\` (${bundle.brain.notes} notas, somente leitura). Consulte-a antes de usar ou configurar qualquer extension ou componente SeedGrid.`,
+        `  - Comece pelos índices, sem varrer a pasta inteira: ${entries}.`,
+        '  - Links `[[SeedGrid/...]]` nas notas são caminhos a partir de `.ai/brain/` (acrescente `.md`).',
+        '  - O frontmatter (`commit`, `analisado-em`) diz a que versão do código a nota se refere. Se a versão usada no projeto puder diferir, confirme no código-fonte, no jar ou no pacote e avise o usuário.',
+        '  - Não invente propriedades, valores padrão ou enums que não estejam nas notas; diga que não encontrou.',
+        '  - Não edite `.ai/brain/`: ela é atualizada por `seedgrid-ai update`.',
+    ];
+}
+const STANDARD_RULES = [
+    ['rules/frontend-seedgrid.md', 'front-end'],
+    ['rules/backend-java-seedgrid.md', 'back-end Java'],
+];
+/** Padrões SeedGrid obrigatórios (front e back), quando o conteúdo os inclui. */
+function standardsLines(bundle) {
+    const present = STANDARD_RULES.filter(([p]) => bundle.shared.some((s) => s.path === p));
+    if (present.length === 0)
+        return [];
+    const review = bundle.skills.some((k) => k.name === 'seedgrid-review')
+        ? ' Para conferir se o código segue o padrão, use a skill `seedgrid-review`.'
+        : '';
+    const list = present.map(([p, label]) => `\`.ai/${p}\` (${label})`).join(' e ');
+    return [`- **Padrões SeedGrid obrigatórios:** ao implementar ou alterar código, siga ${list}.${review}`];
+}
+export function agentsMdBlock(bundle, targets, mode) {
+    const nativeDirs = [
+        targets.includes('claude') ? '`.claude/agents/`' : null,
+        targets.includes('codex') ? '`.codex/agents/`' : null,
+    ]
+        .filter(Boolean)
+        .join(' e ');
+    const delegation = mode === 'native'
+        ? `- Modo \`native\`: os papéis do catálogo também estão registrados como subagentes em ${nativeDirs}, com os mesmos ids. Use-os quando a ferramenta os reconhecer; caso contrário, siga o modo shared e informe a indisponibilidade.`
+        : '- Modo `shared`: para delegar, use o mecanismo de subagentes disponível na ferramenta e passe a definição do papel. Sem subagentes, aplique o papel na sessão principal e informe isso.';
+    const inner = [
+        '## SeedGrid AI Toolkit',
+        '',
+        `Bloco gerenciado pelo \`seedgrid-ai\` (conteúdo ${bundle.contentVersion}, modo \`${mode}\`). Não edite entre os marcadores; personalize em \`.ai/local/\`.`,
+        '',
+        'Cada pasta de `.ai/` tem um `index.md` com o que há nela: comece por ele e leia só o que a tarefa pedir.',
+        '',
+        '- Regras: `.ai/rules/`. Antes de tarefas não triviais, leia `coordenacao.md`.',
+        ...standardsLines(bundle),
+        '- Papéis: `.ai/agents/`.',
+        `- Skills: \`.ai/skills/\` (${bundle.skills.length}). Antes de uma tarefa que combine com a descrição, leia o \`SKILL.md\` indicado no índice.`,
+        '- Templates: `.ai/templates/`. Referências: `.ai/references/`.',
+        ...brainLines(bundle),
+        '- Personalizações do projeto ficam em `.ai/local/` (se existir) e prevalecem sobre as regras compartilhadas; veja `.ai/rules/personalizacao-local.md`.',
+        delegation,
+    ].join('\n');
+    return { file: 'AGENTS.md', inner };
+}

package/dist/adapters/types.js

@@ -0,0 +1 @@
+export const GENERATED_NOTICE = 'Gerado por seedgrid-ai';