@fontdata/ai-harness 2.0.0

package/src/init.js

@@ -0,0 +1,317 @@
+import { existsSync, readdirSync, statSync } from 'node:fs';
+import { resolve } from 'node:path';
+import * as p from '@clack/prompts';
+import { loadCatalog, allCommands, recommendedCommands } from './catalog.js';
+import { installCommand, installClaudeMd, installMaster, installSkill } from './installer.js';
+
+/** Encerra o fluxo com mensagem amigável quando o usuário cancela (Ctrl+C). */
+function bail(value) {
+  if (p.isCancel(value)) {
+    p.cancel('Operação cancelada.');
+    process.exit(0);
+  }
+  return value;
+}
+
+/**
+ * Quantos itens a lista pode mostrar de uma vez sem estourar a altura do terminal.
+ * Calcula a partir das linhas reais do terminal (process.stdout.rows), deixando
+ * margem para a mensagem e os indicadores de rolagem do clack. Sem isso, em um
+ * terminal baixo a lista sobrepõe as renderizações ("itens duplicados").
+ */
+function viewportItems(min = 3, reserve = 6) {
+  const rows = process.stdout.rows || 20;
+  return Math.max(min, rows - reserve);
+}
+
+/**
+ * Manifestos de stack: se algum existir na raiz, é um projeto já existente.
+ */
+const PROJECT_MANIFESTS = [
+  'package.json', 'pyproject.toml', 'requirements.txt', 'go.mod',
+  'Cargo.toml', 'pom.xml', 'build.gradle', 'build.gradle.kts',
+  'composer.json', 'Gemfile', 'Makefile', 'CMakeLists.txt',
+  'tsconfig.json', 'pubspec.yaml', 'mix.exs',
+];
+
+/** Pastas de código-fonte que, se tiverem conteúdo, indicam projeto existente. */
+const SOURCE_DIRS = ['src', 'app', 'lib', 'source'];
+
+/**
+ * Detecta se a pasta alvo já é um projeto com código ('existing') ou está
+ * essencialmente vazia/recém-criada ('new'). Ignora .git e .claude — a presença
+ * deles sozinha não caracteriza um projeto existente.
+ */
+function detectProjectKind(repoPath) {
+  // 1. Manifesto de stack na raiz.
+  if (PROJECT_MANIFESTS.some((f) => existsSync(resolve(repoPath, f)))) return 'existing';
+
+  // 2. Arquivo de solução/projeto .NET na raiz.
+  let rootEntries = [];
+  try {
+    rootEntries = readdirSync(repoPath);
+  } catch {
+    return 'new';
+  }
+  if (rootEntries.some((f) => /\.(sln|csproj|fsproj|vbproj)$/i.test(f))) return 'existing';
+
+  // 3. Pasta de código-fonte com algum conteúdo.
+  for (const dir of SOURCE_DIRS) {
+    const dirPath = resolve(repoPath, dir);
+    try {
+      if (statSync(dirPath).isDirectory() && readdirSync(dirPath).length) return 'existing';
+    } catch {
+      // pasta não existe — segue.
+    }
+  }
+
+  return 'new';
+}
+
+/**
+ * Seleção interativa em dois níveis: menu de grupos → submenu de itens do grupo
+ * → volta ao menu de grupos. Mantém cada lista pequena (cabe em terminais baixos)
+ * e mostra o quanto já foi marcado em cada grupo. Retorna os comandos escolhidos.
+ *
+ * `initialIds` define os comandos já marcados ao abrir (ex.: recomendados em
+ * projeto novo). Em projeto existente vem vazio — o usuário marca só os avulsos.
+ */
+async function selectByGroups(catalog, initialIds = new Set()) {
+  const selectedIds = new Set(initialIds);
+  const DONE = '__done__';
+
+  for (;;) {
+    const groupOptions = catalog.groups.map((g) => {
+      const chosen = g.commands.filter((c) => selectedIds.has(c.id)).length;
+      return {
+        value: g.id,
+        label: `${g.title}  (${chosen}/${g.commands.length})`,
+        hint: chosen ? `${chosen} marcado(s)` : undefined,
+      };
+    });
+    groupOptions.push({
+      value: DONE,
+      label: `✓ Concluir e instalar  (${selectedIds.size} comando(s) marcado(s))`,
+    });
+
+    const groupChoice = bail(
+      await p.select({
+        message: 'Escolha um grupo para marcar comandos — ou Concluir:',
+        options: groupOptions,
+        maxItems: viewportItems(),
+      })
+    );
+
+    if (groupChoice === DONE) break;
+
+    const group = catalog.groups.find((g) => g.id === groupChoice);
+    const picked = bail(
+      await p.multiselect({
+        message: `${group.title} — espaço marca, enter volta ao menu de grupos:`,
+        options: group.commands.map((c) => ({ value: c.id, label: c.title, hint: c.description })),
+        initialValues: group.commands.filter((c) => selectedIds.has(c.id)).map((c) => c.id),
+        required: false,
+        maxItems: viewportItems(),
+      })
+    );
+
+    // Reconcilia só este grupo: limpa os ids dele e re-adiciona os que ficaram marcados.
+    for (const c of group.commands) selectedIds.delete(c.id);
+    for (const id of picked) selectedIds.add(id);
+  }
+
+  return allCommands(catalog).filter((c) => selectedIds.has(c.id));
+}
+
+export async function runInit(initialPath) {
+  const catalog = loadCatalog();
+
+  p.intro('Fontdata · ai-harness — instalador do harness para Claude Code');
+
+  // 1. Diretório alvo
+  const repoInput = bail(
+    await p.text({
+      message: 'Em qual pasta do projeto deseja instalar?',
+      placeholder: '. (pasta atual)',
+      initialValue: initialPath || '.',
+    })
+  );
+  const repoPath = resolve(process.cwd(), repoInput.trim() || '.');
+
+  if (!existsSync(repoPath)) {
+    p.cancel(`Pasta não encontrada: ${repoPath}`);
+    process.exit(1);
+  }
+
+  // Detecta o tipo de projeto: muda como a seleção "Manual" começa.
+  const projectKind = detectProjectKind(repoPath);
+  p.note(
+    projectKind === 'existing'
+      ? 'Projeto existente detectado. Na opção "Escolher manualmente" nada vem marcado — ideal para cadastrar comandos avulsos.'
+      : 'Projeto novo detectado. Na opção "Escolher manualmente" os comandos recomendados já vêm marcados.',
+    projectKind === 'existing' ? 'Projeto existente' : 'Projeto novo'
+  );
+
+  // 2. O que instalar
+  const scope = bail(
+    await p.select({
+      message: 'O que deseja instalar?',
+      options: [
+        { value: 'recommended', label: 'Conjunto recomendado', hint: 'núcleo de setup + dia a dia' },
+        { value: 'all', label: 'Tudo', hint: `${allCommands(catalog).length} comandos` },
+        {
+          value: 'manual',
+          label: 'Escolher manualmente',
+          hint: projectKind === 'existing' ? 'seleção por categoria (nada marcado)' : 'seleção por categoria (recomendados marcados)',
+        },
+      ],
+    })
+  );
+
+  let selected;
+  if (scope === 'all') {
+    selected = allCommands(catalog);
+  } else if (scope === 'recommended') {
+    selected = recommendedCommands(catalog);
+  } else {
+    // Projeto novo começa com os recomendados marcados; existente começa vazio.
+    const initialIds =
+      projectKind === 'new'
+        ? new Set(recommendedCommands(catalog).map((c) => c.id))
+        : new Set();
+    selected = await selectByGroups(catalog, initialIds);
+  }
+
+  // 3. Comando-mestre /harness
+  const wantMaster = bail(
+    await p.confirm({
+      message: 'Incluir também o comando-mestre /harness (conduz a sequência de setup em ordem)?',
+      initialValue: true,
+    })
+  );
+
+  // Se o /harness foi escolhido, garante que os comandos que ele invoca também sejam instalados.
+  let autoAdded = [];
+  if (wantMaster) {
+    const required = catalog.master.requires || [];
+    const selectedIds = new Set(selected.map((c) => c.id));
+    const missing = allCommands(catalog).filter(
+      (c) => required.includes(c.id) && !selectedIds.has(c.id)
+    );
+    if (missing.length) {
+      selected = [...selected, ...missing];
+      autoAdded = missing.map((c) => c.title);
+    }
+  }
+
+  // Resolve dependências por comando (campo `requires`): se um comando selecionado
+  // depende de outro, o dependente entra junto, mesmo que não tenha sido marcado —
+  // como acontece com o /harness.
+  {
+    const selectedIds = new Set(selected.map((c) => c.id));
+    const deps = allCommands(catalog).filter(
+      (c) =>
+        !selectedIds.has(c.id) &&
+        selected.some((sel) => (sel.requires || []).includes(c.id))
+    );
+    if (deps.length) {
+      selected = [...selected, ...deps];
+      autoAdded = [...autoAdded, ...deps.map((c) => c.title)];
+    }
+  }
+
+  // 4. CLAUDE.md base
+  const claudeExists = existsSync(resolve(repoPath, catalog.claudeMd.target));
+  let claudeMode = 'create';
+  const wantClaude = bail(
+    await p.confirm({
+      message: claudeExists
+        ? 'Já existe um CLAUDE.md na raiz. Deseja tratá-lo?'
+        : 'Criar o CLAUDE.md base na raiz (filosofia de orquestração/TDD)?',
+      initialValue: !claudeExists,
+    })
+  );
+  if (wantClaude && claudeExists) {
+    claudeMode = bail(
+      await p.select({
+        message: 'O que fazer com o CLAUDE.md existente?',
+        options: [
+          { value: 'backup', label: 'Sobrescrever criando .bak', hint: 'recomendado' },
+          { value: 'overwrite', label: 'Sobrescrever sem backup' },
+          { value: 'skip', label: 'Manter o existente' },
+        ],
+      })
+    );
+  }
+
+  // 5. Confirmação final
+  if (selected.length === 0 && !wantMaster && !wantClaude) {
+    p.outro('Nada selecionado. Nenhuma alteração feita.');
+    return;
+  }
+
+  // Skills exigidas pelos comandos selecionados (campo `requiresSkills`).
+  const skillCatalog = catalog.skills || [];
+  const neededSkillIds = new Set(selected.flatMap((c) => c.requiresSkills || []));
+  const neededSkills = skillCatalog.filter((sk) => neededSkillIds.has(sk.id));
+
+  // Política global de conflito: perguntamos UMA vez se houver risco de sobrescrever.
+  const anyConflict =
+    selected.some((c) => existsSync(resolve(repoPath, '.claude', 'commands', `${c.id}.md`))) ||
+    (wantMaster && existsSync(resolve(repoPath, '.claude', 'commands', `${catalog.master.id}.md`))) ||
+    neededSkills.some((sk) => existsSync(resolve(repoPath, '.claude', 'skills', sk.id)));
+
+  let conflictPolicy = 'overwrite';
+  if (anyConflict) {
+    conflictPolicy = bail(
+      await p.select({
+        message: 'Alguns itens já existem no destino. O que fazer com os conflitos?',
+        options: [
+          { value: 'overwrite', label: 'Sobrescrever os existentes' },
+          { value: 'skip', label: 'Pular os que já existem' },
+        ],
+      })
+    );
+  }
+
+  // Execução
+  const s = p.spinner();
+  s.start('Instalando...');
+
+  const results = { created: [], overwritten: [], skipped: [] };
+  for (const cmd of selected) {
+    const status = installCommand(cmd, repoPath, () => conflictPolicy);
+    results[status].push(cmd.title);
+  }
+  if (wantMaster) {
+    const status = installMaster(catalog, repoPath, () => conflictPolicy);
+    results[status].push(catalog.master.title);
+  }
+
+  const skillResults = { created: [], overwritten: [], skipped: [] };
+  for (const skill of neededSkills) {
+    const status = installSkill(skill, repoPath, () => conflictPolicy);
+    skillResults[status].push(skill.title);
+  }
+
+  let claudeResult = null;
+  if (wantClaude) {
+    claudeResult = installClaudeMd(catalog, repoPath, claudeExists ? claudeMode : 'create');
+  }
+
+  s.stop('Instalação concluída.');
+
+  // Resumo
+  const lines = [];
+  if (results.created.length) lines.push(`Criados (${results.created.length}): ${results.created.join(', ')}`);
+  if (results.overwritten.length) lines.push(`Sobrescritos (${results.overwritten.length}): ${results.overwritten.join(', ')}`);
+  if (results.skipped.length) lines.push(`Pulados (${results.skipped.length}): ${results.skipped.join(', ')}`);
+  const skillsInstalled = [...skillResults.created, ...skillResults.overwritten];
+  if (skillsInstalled.length) lines.push(`Skills (${skillsInstalled.length}): ${skillsInstalled.join(', ')}`);
+  if (skillResults.skipped.length) lines.push(`Skills puladas (${skillResults.skipped.length}): ${skillResults.skipped.join(', ')}`);
+  if (autoAdded.length) lines.push(`Adicionados como dependência (${autoAdded.length}): ${autoAdded.join(', ')}`);
+  if (claudeResult) lines.push(`CLAUDE.md: ${claudeResult}`);
+  p.note(lines.join('\n') || 'Nada a instalar.', `Resumo · ${repoPath}`);
+
+  p.outro('Abra o projeto no Claude Code e digite "/" para ver os comandos instalados.');
+}

package/src/installer.js

@@ -0,0 +1,92 @@
+import { cpSync, copyFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { templatesDir } from './catalog.js';
+
+/** Garante que o diretório de um arquivo exista. */
+function ensureDir(filePath) {
+  mkdirSync(dirname(filePath), { recursive: true });
+}
+
+/**
+ * Copia um comando (template) para <repo>/.claude/commands/<id>.md.
+ * Retorna o status da operação: 'created' | 'overwritten' | 'skipped'.
+ *
+ * @param {object} cmd           Item do catálogo (precisa de id e file).
+ * @param {string} repoPath      Raiz do repositório alvo.
+ * @param {function} resolveConflict  (destPath) => 'overwrite' | 'skip'. Chamado só se o destino existir.
+ */
+export function installCommand(cmd, repoPath, resolveConflict) {
+  const source = join(templatesDir, cmd.file);
+  const dest = join(repoPath, '.claude', 'commands', `${cmd.id}.md`);
+
+  if (existsSync(dest)) {
+    const decision = resolveConflict ? resolveConflict(dest) : 'overwrite';
+    if (decision === 'skip') return 'skipped';
+    ensureDir(dest);
+    copyFileSync(source, dest);
+    return 'overwritten';
+  }
+
+  ensureDir(dest);
+  copyFileSync(source, dest);
+  return 'created';
+}
+
+/**
+ * Instala/atualiza o CLAUDE.md base na raiz do repositório.
+ * mode: 'overwrite' | 'skip' | 'backup' (cria CLAUDE.md.bak antes de sobrescrever).
+ * Retorna 'created' | 'overwritten' | 'skipped' | 'backed-up'.
+ */
+export function installClaudeMd(catalog, repoPath, mode = 'overwrite') {
+  const source = join(templatesDir, catalog.claudeMd.file);
+  const dest = join(repoPath, catalog.claudeMd.target);
+
+  if (!existsSync(dest)) {
+    writeFileSync(dest, readFileSync(source, 'utf8'));
+    return 'created';
+  }
+
+  if (mode === 'skip') return 'skipped';
+
+  if (mode === 'backup') {
+    copyFileSync(dest, `${dest}.bak`);
+    writeFileSync(dest, readFileSync(source, 'utf8'));
+    return 'backed-up';
+  }
+
+  writeFileSync(dest, readFileSync(source, 'utf8'));
+  return 'overwritten';
+}
+
+/**
+ * Copia uma skill (pasta com SKILL.md e references/) para
+ * <repo>/.claude/skills/<id>/. Retorna 'created' | 'overwritten' | 'skipped'.
+ *
+ * @param {object} skill         Item do catálogo (precisa de id e dir).
+ * @param {string} repoPath      Raiz do repositório alvo.
+ * @param {function} resolveConflict  (destPath) => 'overwrite' | 'skip'. Chamado só se o destino existir.
+ */
+export function installSkill(skill, repoPath, resolveConflict) {
+  const source = join(templatesDir, skill.dir);
+  const dest = join(repoPath, '.claude', 'skills', skill.id);
+
+  if (existsSync(dest)) {
+    const decision = resolveConflict ? resolveConflict(dest) : 'overwrite';
+    if (decision === 'skip') return 'skipped';
+    cpSync(source, dest, { recursive: true });
+    return 'overwritten';
+  }
+
+  mkdirSync(dirname(dest), { recursive: true });
+  cpSync(source, dest, { recursive: true });
+  return 'created';
+}
+
+/** Instala o comando-mestre /harness (mesmo mecanismo de installCommand). */
+export function installMaster(catalog, repoPath, resolveConflict) {
+  return installCommand(
+    { id: catalog.master.id, file: catalog.master.file },
+    repoPath,
+    resolveConflict
+  );
+}

package/src/run.js

@@ -0,0 +1,99 @@
+import { spawnSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+import { loadCatalog, allCommands } from './catalog.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+/** Raiz do pacote — é ela que vira o plugin carregado via `claude --plugin-dir`. */
+export const pluginRoot = join(__dirname, '..');
+
+/** Nome do plugin, lido do manifesto para não duplicar a string. */
+export function pluginName() {
+  const manifest = JSON.parse(
+    readFileSync(join(pluginRoot, '.claude-plugin', 'plugin.json'), 'utf8')
+  );
+  return manifest.name;
+}
+
+/**
+ * Ids executáveis: os comandos dos grupos mais o comando-mestre, que fica fora
+ * de `groups` no catálogo.
+ */
+export function runnableIds(catalog = loadCatalog()) {
+  const ids = allCommands(catalog).map((cmd) => cmd.id);
+  if (catalog.master?.id) ids.unshift(catalog.master.id);
+  return [...new Set(ids)];
+}
+
+/** Ids mais parecidos com o que foi digitado, para sugerir em caso de erro. */
+export function suggestIds(input, ids) {
+  const needle = input.toLowerCase();
+  return ids
+    .filter((id) => id.includes(needle) || needle.includes(id) || id.startsWith(needle.slice(0, 4)))
+    .slice(0, 5);
+}
+
+const SYSTEM_NOTE =
+  'Os slash commands do harness Fontdata estão disponíveis nesta sessão com o prefixo ' +
+  '`/PLUGIN:` (ex.: `/PLUGIN:gerar-spec`). Quando uma instrução referenciar um comando ' +
+  'como `/nome`, entenda que se trata de `/PLUGIN:nome`.';
+
+/**
+ * Executa um comando do catálogo abrindo o Claude Code na pasta atual, com o
+ * pacote carregado como plugin da sessão — sem instalar nada no projeto.
+ */
+export function runCommand(id, args = [], claudeFlags = []) {
+  const catalog = loadCatalog();
+  const ids = runnableIds(catalog);
+  const wanted = id.replace(/^\//, '');
+
+  if (!ids.includes(wanted)) {
+    const near = suggestIds(wanted, ids);
+    console.error(`Comando desconhecido: ${wanted}`);
+    if (near.length) console.error(`\nVocê quis dizer: ${near.join(', ')}`);
+    console.error('\nRode `npx @fontdata/ai-harness list` para ver o catálogo completo.');
+    return 1;
+  }
+
+  const name = pluginName();
+  const prompt = [`/${name}:${wanted}`, ...args].join(' ').trim();
+  const argv = [
+    '--plugin-dir',
+    pluginRoot,
+    '--append-system-prompt',
+    SYSTEM_NOTE.replaceAll('PLUGIN', name),
+    ...claudeFlags,
+    '--',
+    prompt,
+  ];
+
+  const result = spawn(argv);
+
+  if (result.error?.code === 'ENOENT') {
+    console.error(
+      'Claude Code não encontrado no PATH.\n' +
+        'Instale com: npm install -g @anthropic-ai/claude-code'
+    );
+    return 127;
+  }
+  if (result.error) {
+    console.error('Erro ao executar o Claude Code:', result.error.message);
+    return 1;
+  }
+  return result.status ?? 0;
+}
+
+/**
+ * No Windows o `claude` costuma ser um `.cmd`, que o spawn sem shell não
+ * resolve; nesse caso repetimos a chamada pelo shell, com os argumentos citados.
+ */
+function spawn(argv) {
+  const direct = spawnSync('claude', argv, { stdio: 'inherit', cwd: process.cwd() });
+  if (direct.error?.code === 'ENOENT' && process.platform === 'win32') {
+    const quoted = argv.map((arg) => `"${String(arg).replaceAll('"', '\\"')}"`).join(' ');
+    return spawnSync(`claude ${quoted}`, { stdio: 'inherit', cwd: process.cwd(), shell: true });
+  }
+  return direct;
+}

package/templates/CLAUDE.md

@@ -0,0 +1,49 @@
+# [NOME DO PROJETO]
+> Substitua esta seção rodando `/gerar-claude-md` depois de gerar o `SPEC.md`.
+
+Este projeto usa o **harness de engenharia com IA da Fontdata** para Claude Code.
+Os slash commands ficam em `.claude/commands/`. Comece por `/validar-ideia` (ou `/harness`).
+
+## Filosofia de trabalho
+
+- **Documentação como contrato.** `SPEC.md` (raiz), `CLAUDE.md` (raiz) e os planos em `docs/plans/`
+  são a fonte da verdade. Agents não os reescrevem por conta própria.
+- **TDD obrigatório.** Toda task escreve os testes primeiro (RED), confirma que falham, e só então
+  implementa o mínimo para passar (GREEN). Mínimo de 2 testes críticos por task.
+- **Orquestração com sub-agents.** Tasks independentes da mesma fase rodam em paralelo. O orquestrador
+  delega, não implementa. Gates entre fases: só avança quando os testes da fase passam.
+- **Sempre relatar qual agent está ativo** no chat, principalmente nos gates entre agents.
+
+## Modelo de arquivos
+
+| Arquivo | Local | Papel |
+|--------|-------|-------|
+| `SPEC.md` | raiz | Definição **principal** e completa do projeto (única). |
+| `CLAUDE.md` | raiz | Este context file, lido em toda sessão. |
+| `docs/specs/AAAA-MM-DD-*.md` | `docs/specs/` | Specs **complementares**: o start inicial e cada nova tarefa. |
+| `docs/plans/AAAA-MM-DD-*.md` | `docs/plans/` | Plano de implementação correspondente a cada spec complementar. |
+| `docs/bugs/AAAA-MM-DD-*.md` | `docs/bugs/` | Correção de defeito: sintoma, causa-raiz e fix (via `/resolver-bug`). |
+| `docs/investigacoes/AAAA-MM-DD-*.md` | `docs/investigacoes/` | Investigação, medição, auditoria, paridade e comparação (via `/auditar-*`, `/codigo-morto`). |
+
+## Fluxo recomendado (projeto novo)
+
+1. `/validar-ideia` — confere se cabe em ~4h com multi-agents
+2. `/gerar-spec` — gera o `SPEC.md` principal na raiz
+3. `/gerar-claude-md` — gera/atualiza este arquivo
+4. `/gerar-ignore` — `.claudeignore` e `.gitignore`
+5. `/nova-tarefa` — spec do start (derivada do SPEC) + plano em `docs/`
+6. `/scaffold` — estrutura inicial + `/health` + testes de smoke
+7. `/criar-agents`, `/criar-code-reviewer`, `/criar-rules`, `/criar-hooks` — monta o harness
+8. `/executar-plan` — orquestra a implementação
+
+No dia a dia: `/nova-tarefa`, `/resolver-bug`, `/git-commit-push`.
+
+## Nunca fazer
+
+- Nunca implementar sem teste escrito antes.
+- Nunca avançar de fase com gate (testes) falhando.
+- Nunca reescrever `SPEC.md`/`CLAUDE.md`/planos sem pedido explícito.
+- Nunca usar `git push --force` ou comandos destrutivos sem confirmação.
+- Nunca comentar o passo a passo do código, decorar arquivo com banner de seção, nem escrever
+  task/fase/plano/data/hash de commit dentro de comentário — isso vai na mensagem de commit e em `docs/`.
+  Rode `/configurar-comentarios` para instalar a rule, o hook e a catraca.