@fontdata/ai-harness 2.0.0 → 2.2.0

package/dist/init.js

@@ -0,0 +1,240 @@
+import { existsSync } from 'node:fs';
+import { EOL } from 'node:os';
+import { join, resolve } from 'node:path';
+import * as p from '@clack/prompts';
+import { allCommands, loadCatalog, recommendedCommands } from './catalog.js';
+import { readConfig, syncGitignore, writeDefaultConfig } from './config/config.js';
+import { parseInitArgs } from './install/flags.js';
+import { isHarnessPluginEnabled } from './install/hooks.js';
+import { readLock } from './install/lock.js';
+import { describePlan, executePlan, packageInfo, planInstall, resolveInstallOptions, } from './install/plan.js';
+import { detectProjectKind } from './install/selection.js';
+export { detectProjectKind, neededSkillsFor, resolveSelection } from './install/selection.js';
+const PLUGIN_HOOKS_NOTE = 'O plugin fontdata@ai-harness está habilitado: os hooks já rodam por ele e não foram instalados no projeto, para não rodarem duas vezes.';
+/** 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);
+}
+/**
+ * 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})`,
+                ...(chosen ? { hint: `${chosen} marcado(s)` } : {}),
+            };
+        });
+        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);
+        if (!group)
+            continue;
+        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,
+        }));
+        // 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));
+}
+/** Config com os padrões (sem sobrescrever a existente) e o bloco gerenciado do .gitignore. */
+function prepareProjectFiles(repoPath) {
+    writeDefaultConfig(repoPath);
+    syncGitignore(repoPath, readConfig(repoPath).config);
+}
+/**
+ * Sem terminal interativo, ou com escopo dado por flag, o init não pergunta nada.
+ * Sem `--yes` ele só mostra o que faria — o que protege execuções em CI.
+ */
+function runNonInteractive(args) {
+    const catalog = loadCatalog();
+    const repoPath = resolve(process.cwd(), args.path ?? '.');
+    if (!existsSync(repoPath))
+        throw new Error(`Pasta não encontrada: ${repoPath}`);
+    readLock(repoPath);
+    const options = resolveInstallOptions(args);
+    const skippedForPlugin = options.hooks && isHarnessPluginEnabled(repoPath);
+    if (skippedForPlugin)
+        options.hooks = false;
+    const plan = planInstall(catalog, repoPath, options);
+    const summary = [describePlan(plan), ...(skippedForPlugin ? [PLUGIN_HOOKS_NOTE] : [])].join(EOL + EOL);
+    if (!args.yes) {
+        console.log(`Simulação — nada foi gravado em ${repoPath}.\n\n${summary}\n\nRode de novo com --yes para aplicar.`);
+        return;
+    }
+    const lock = executePlan(repoPath, plan, packageInfo());
+    prepareProjectFiles(repoPath);
+    console.log(`Instalação concluída em ${repoPath}.\n\n${summary}\n\nLock: .ai-harness/lock.json (${lock.itens.length} itens).`);
+}
+async function runWizard(args) {
+    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: args.path || '.',
+    }));
+    const repoPath = resolve(process.cwd(), repoInput.trim() || '.');
+    if (!existsSync(repoPath)) {
+        p.cancel(`Pasta não encontrada: ${repoPath}`);
+        process.exit(1);
+    }
+    readLock(repoPath);
+    // 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 commands = [];
+    if (scope === 'manual') {
+        // 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();
+        commands = (await selectByGroups(catalog, initialIds)).map((c) => c.id);
+    }
+    // 3. Comando-mestre /harness
+    const includeMaster = bail(await p.confirm({
+        message: 'Incluir também o comando-mestre /harness (conduz a sequência de setup em ordem)?',
+        initialValue: true,
+    }));
+    // 4. CLAUDE.md base
+    const claudeExists = existsSync(resolve(repoPath, catalog.claudeMd.target));
+    let claudeMd = 'keep';
+    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) {
+        claudeMd = claudeExists
+            ? 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: 'keep', label: 'Manter o existente' },
+                ],
+            }))
+            : 'create';
+    }
+    // 5. Hooks: pelo plugin habilitado eles já rodam; no projeto, perguntamos.
+    let hooks = false;
+    if (isHarnessPluginEnabled(repoPath)) {
+        p.note(PLUGIN_HOOKS_NOTE, 'Hooks');
+    }
+    else {
+        hooks = bail(await p.confirm({
+            message: 'Instalar os hooks do harness (lembrete de fluxos, bloqueio de segredos no commit e avisos de método)?',
+            initialValue: true,
+        }));
+    }
+    const agents = bail(await p.confirm({
+        message: 'Instalar os agents somente leitura do harness (revisor-testes, qa, investigador, auditor-plano)?',
+        initialValue: true,
+    }));
+    const comments = bail(await p.confirm({
+        message: 'Instalar o padrão de comentários (rule, hook que bloqueia a violação e catraca do legado)?',
+        initialValue: true,
+    }));
+    const options = {
+        scope: scope === 'all' ? 'all' : scope === 'manual' ? 'manual' : 'recommended',
+        commands,
+        includeMaster,
+        claudeMd,
+        conflict: 'overwrite',
+        hooks,
+        agents,
+        comments,
+    };
+    let plan = planInstall(catalog, repoPath, options);
+    // 6. Confirmação final
+    if (plan.files.length === 0) {
+        p.outro('Nada selecionado. Nenhuma alteração feita.');
+        return;
+    }
+    // Política global de conflito: perguntamos UMA vez se houver risco de sobrescrever.
+    const anyConflict = plan.files.some((file) => file.path !== catalog.claudeMd.target && existsSync(join(repoPath, file.path)));
+    if (anyConflict) {
+        const conflict = 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' },
+            ],
+        }));
+        if (conflict === 'skip')
+            plan = planInstall(catalog, repoPath, { ...options, conflict });
+    }
+    // Execução
+    const s = p.spinner();
+    s.start('Instalando...');
+    executePlan(repoPath, plan, packageInfo());
+    prepareProjectFiles(repoPath);
+    s.stop('Instalação concluída.');
+    p.note(describePlan(plan), `Resumo · ${repoPath}`);
+    p.outro('Abra o projeto no Claude Code e digite "/" para ver os comandos instalados.');
+}
+export async function runInit(argv = []) {
+    const args = parseInitArgs(argv);
+    const interactive = Boolean(process.stdin.isTTY) && !args.hasSelectionFlags && !args.yes;
+    if (interactive)
+        await runWizard(args);
+    else
+        runNonInteractive(args);
+}

package/dist/install/atomic.js

@@ -0,0 +1,51 @@
+import { mkdirSync, readdirSync, renameSync, rmdirSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+/** Resolve um caminho relativo à raiz do projeto, recusando o que escapar dela. */
+export function resolveInside(root, relPath) {
+    const target = resolve(root, relPath);
+    const rel = relative(root, target);
+    if (isAbsolute(relPath) || rel === '' || rel === '..' || rel.startsWith(`..${sep}`)) {
+        throw new Error(`Caminho fora da raiz do projeto: ${relPath}`);
+    }
+    return target;
+}
+/**
+ * Grava um conjunto de arquivos no projeto de forma que uma falha não deixe a
+ * instalação pela metade: tudo é montado antes numa pasta temporária dentro do
+ * próprio projeto (mesmo sistema de arquivos) e só então movido com `rename`.
+ * Arquivos do projeto fora do conjunto não são tocados.
+ */
+export function applyAtomically(root, files) {
+    const planned = files.map((file) => ({
+        target: resolveInside(root, file.path),
+        rel: relative(root, resolve(root, file.path)),
+        content: file.content,
+    }));
+    const harnessDir = join(root, '.ai-harness');
+    const stage = join(harnessDir, `.tmp-${process.pid}-${Date.now()}`);
+    try {
+        for (const file of planned) {
+            const staged = join(stage, file.rel);
+            mkdirSync(dirname(staged), { recursive: true });
+            writeFileSync(staged, file.content);
+        }
+        for (const file of planned) {
+            mkdirSync(dirname(file.target), { recursive: true });
+            renameSync(join(stage, file.rel), file.target);
+        }
+    }
+    finally {
+        rmSync(stage, { recursive: true, force: true });
+        removeIfEmpty(harnessDir);
+    }
+}
+/** A pasta .ai-harness criada só para a montagem não deve sobrar num projeto sem lock nem config. */
+function removeIfEmpty(dir) {
+    try {
+        if (readdirSync(dir).length === 0)
+            rmdirSync(dir);
+    }
+    catch {
+        // não existe ou não pôde ser lida — nada a limpar.
+    }
+}

package/dist/install/flags.js

@@ -0,0 +1,99 @@
+const SCOPES = { recomendado: 'recommended', tudo: 'all' };
+const CLAUDE_MD = {
+    criar: 'create',
+    manter: 'keep',
+    backup: 'backup',
+    sobrescrever: 'overwrite',
+};
+const CONFLICTS = { sobrescrever: 'overwrite', pular: 'skip' };
+const VALUE_FLAGS = ['--escopo', '--comandos', '--claude-md', '--conflito'];
+const BOOLEAN_FLAGS = ['--sem-harness', '--sem-hooks', '--sem-agents', '--sem-comentarios', '--yes', '-y', '--sim'];
+function pick(flag, value, options) {
+    const chosen = options[value];
+    if (chosen === undefined) {
+        throw new Error(`Valor inválido para ${flag}: ${value}. Use: ${Object.keys(options).join(', ')}.`);
+    }
+    return chosen;
+}
+function distance(a, b) {
+    const row = Array.from({ length: b.length + 1 }, (_, j) => j);
+    for (let i = 1; i <= a.length; i++) {
+        let diagonal = row[0] ?? 0;
+        row[0] = i;
+        for (let j = 1; j <= b.length; j++) {
+            const above = row[j] ?? 0;
+            row[j] = Math.min(above + 1, (row[j - 1] ?? 0) + 1, diagonal + (a[i - 1] === b[j - 1] ? 0 : 1));
+            diagonal = above;
+        }
+    }
+    return row[b.length] ?? 0;
+}
+/** Flag conhecida mais parecida com a digitada, para sugerir em mensagens de erro. */
+export function suggestFlag(token, flags) {
+    const [best] = flags
+        .map((flag) => ({ flag, d: distance(token, flag) }))
+        .filter(({ d }) => d <= 2)
+        .sort((x, y) => x.d - y.d);
+    return best?.flag;
+}
+/** Lê os argumentos do `init`; valores e flags inválidos viram erro com orientação. */
+export function parseInitArgs(argv) {
+    const args = {
+        path: undefined,
+        scope: undefined,
+        commands: [],
+        includeMaster: undefined,
+        claudeMd: undefined,
+        conflict: undefined,
+        hooks: undefined,
+        agents: undefined,
+        comments: undefined,
+        yes: false,
+        hasSelectionFlags: false,
+    };
+    for (let i = 0; i < argv.length; i++) {
+        const token = argv[i] ?? '';
+        if (!token.startsWith('-')) {
+            if (args.path !== undefined)
+                throw new Error(`Argumento inesperado: ${token}`);
+            args.path = token;
+            continue;
+        }
+        if (BOOLEAN_FLAGS.includes(token)) {
+            if (token === '--sem-harness')
+                args.includeMaster = false;
+            else if (token === '--sem-hooks')
+                args.hooks = false;
+            else if (token === '--sem-agents')
+                args.agents = false;
+            else if (token === '--sem-comentarios')
+                args.comments = false;
+            else
+                args.yes = true;
+            continue;
+        }
+        if (!VALUE_FLAGS.includes(token)) {
+            const suggestion = suggestFlag(token, [...VALUE_FLAGS, ...BOOLEAN_FLAGS]);
+            throw new Error(`Flag desconhecida: ${token}.${suggestion ? ` Você quis dizer ${suggestion}?` : ''}`);
+        }
+        const value = argv[i + 1];
+        if (value === undefined || value.startsWith('-'))
+            throw new Error(`${token} precisa de um valor.`);
+        i++;
+        if (token === '--escopo')
+            args.scope = pick(token, value, SCOPES);
+        else if (token === '--claude-md')
+            args.claudeMd = pick(token, value, CLAUDE_MD);
+        else if (token === '--conflito')
+            args.conflict = pick(token, value, CONFLICTS);
+        else {
+            args.commands = value.split(',').map((id) => id.trim()).filter(Boolean);
+            args.scope = 'manual';
+        }
+    }
+    if (argv.includes('--escopo') && argv.includes('--comandos')) {
+        throw new Error('Use --escopo ou --comandos, não os dois.');
+    }
+    args.hasSelectionFlags = args.scope !== undefined;
+    return args;
+}

package/dist/install/hooks.js

@@ -0,0 +1,47 @@
+import { readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { templatesDir } from '../catalog.js';
+/** Id do item do lock que agrupa os scripts de hook copiados para o projeto. */
+export const HOOKS_ITEM_ID = 'ai-harness';
+export const PROJECT_HOOKS_DIR = '.claude/hooks/ai-harness';
+export const PLUGIN_ID = 'fontdata@ai-harness';
+const PLUGIN_PREFIX = '${CLAUDE_PLUGIN_ROOT}/templates/hooks/';
+const PROJECT_PREFIX = `$CLAUDE_PROJECT_DIR/${PROJECT_HOOKS_DIR}/`;
+/** Hooks do plugin (templates/hooks/hooks.json), fonte única também para a instalação no projeto. */
+export function pluginHooksConfig() {
+    const file = JSON.parse(readFileSync(join(templatesDir, 'hooks', 'hooks.json'), 'utf8'));
+    return file.hooks;
+}
+/** Os mesmos hooks, apontando para os scripts copiados em .claude/hooks/ai-harness/. */
+export function projectHooksConfig() {
+    return Object.fromEntries(Object.entries(pluginHooksConfig()).map(([event, groups]) => [
+        event,
+        groups.map((group) => ({
+            ...group,
+            hooks: group.hooks.map((hook) => ({ ...hook, command: hook.command.replaceAll(PLUGIN_PREFIX, PROJECT_PREFIX) })),
+        })),
+    ]));
+}
+/**
+ * O plugin está habilitado no projeto ou para o usuário? Nesse caso os hooks já rodam
+ * pelo plugin, e instalá-los também no projeto faria cada um rodar duas vezes (D-24).
+ */
+export function isHarnessPluginEnabled(root, home = homedir()) {
+    const files = [
+        join(root, '.claude', 'settings.json'),
+        join(root, '.claude', 'settings.local.json'),
+        join(home, '.claude', 'settings.json'),
+    ];
+    return files.some((file) => {
+        try {
+            const plugins = JSON.parse(readFileSync(file, 'utf8')).enabledPlugins;
+            if (Array.isArray(plugins))
+                return plugins.includes(PLUGIN_ID);
+            return typeof plugins === 'object' && plugins !== null && plugins[PLUGIN_ID] === true;
+        }
+        catch {
+            return false;
+        }
+    });
+}

package/dist/install/lock.js

@@ -0,0 +1,39 @@
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+/** Versão do formato do lock; o CLI recusa ler um lock de formato mais novo que o seu. */
+export const LOCK_VERSION = 1;
+export const LOCK_PATH = join('.ai-harness', 'lock.json');
+export function hashContent(content) {
+    return createHash('sha256').update(content).digest('hex');
+}
+/** Monta o item do lock com o hash de cada arquivo já instalado, em ordem estável. */
+export function buildLockItem(root, tipo, id, relPaths) {
+    const arquivos = [...relPaths]
+        .sort()
+        .map((caminho) => ({ caminho, sha256: hashContent(readFileSync(join(root, caminho))) }));
+    return { tipo, id, arquivos };
+}
+export function readLock(root) {
+    const file = join(root, LOCK_PATH);
+    if (!existsSync(file))
+        return null;
+    let lock;
+    try {
+        lock = JSON.parse(readFileSync(file, 'utf8'));
+    }
+    catch (error) {
+        const reason = error instanceof Error ? error.message : String(error);
+        throw new Error(`O ${LOCK_PATH} está com JSON inválido (${reason}).`);
+    }
+    if (lock.lock_versao > LOCK_VERSION) {
+        throw new Error(`O ${LOCK_PATH} foi gerado por uma versão mais nova do ai-harness (lock_versao ${lock.lock_versao}). ` +
+            'Atualize o pacote antes de continuar.');
+    }
+    return lock;
+}
+export function writeLock(root, lock) {
+    const file = join(root, LOCK_PATH);
+    mkdirSync(dirname(file), { recursive: true });
+    writeFileSync(file, `${JSON.stringify(lock, null, 2)}\n`);
+}