@kuyper/harness 0.1.0

package/dist/hookBehavior.js

@@ -0,0 +1,212 @@
+import { execFile } from 'node:child_process';
+import { join } from 'node:path';
+import { promisify } from 'node:util';
+import { readConfig } from './config.js';
+import { KuyperRefusal } from './errors.js';
+import { gatesForStage, runConverging, runExact } from './gateRunner.js';
+import { currentBranch, headSha, statusPorcelain } from './gitPlumbing.js';
+import { validate } from './validate.js';
+const execFileAsync = promisify(execFile);
+async function devBranchExists(cwd) {
+    try {
+        await execFileAsync('git', ['show-ref', '--verify', '--quiet', 'refs/heads/dev'], { cwd });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function switchToDevRoute(cwd) {
+    return (await devBranchExists(cwd)) ? 'git switch dev' : 'git switch -c dev';
+}
+// ---------------------------------------------------------------------------
+// pre-commit (PRD §3.8, §4.1)
+// ---------------------------------------------------------------------------
+function refuseR22(route) {
+    throw new KuyperRefusal({
+        code: 'R22',
+        headline: 'Commit direto na main não é permitido.',
+        details: ['A main recebe merges, não commits diretos.'],
+        route: [route],
+    });
+}
+function refuseGateFailed(gate, output) {
+    throw new KuyperRefusal({
+        code: 'R19',
+        headline: `O gate ${gate} falhou.`,
+        details: output.split('\n').filter((l) => l.length > 0),
+        route: ['Corrija o que o gate acusou e commite de novo.'],
+    });
+}
+function refuseNoConverge(paths) {
+    throw new KuyperRefusal({
+        code: 'R20',
+        headline: 'Um gate não converge — continua alterando arquivos depois de três voltas.',
+        details: ['Isto é configuração quebrada, não código quebrado.', '', ...paths],
+        route: ['Corrija o gate (ele não pode reescrever a cada execução) e commite de novo.'],
+    });
+}
+function refuseEditedUnstaged(gate, paths) {
+    throw new KuyperRefusal({
+        code: 'R20',
+        headline: paths.length === 1 ? `${gate} alterou um arquivo que já tinha edição não staged.` : `${gate} alterou arquivos que já tinham edição não staged.`,
+        details: [
+            'Não foi readicionado — isso incluiria conteúdo que você deixou de fora',
+            'do commit de propósito (staging parcial).',
+            '',
+            ...paths,
+        ],
+        route: ['Revise os arquivos acima, decida o que fica no commit, e rode git add você mesmo antes de commitar de novo.'],
+    });
+}
+function formatFixedReport(fixed) {
+    const lines = ['✓  gates concluídos.'];
+    for (const f of fixed) {
+        const n = f.paths.length;
+        lines.push(`   ${f.gate} corrigiu ${n} arquivo${n === 1 ? '' : 's'}, incluíd${n === 1 ? 'o' : 'os'} no commit.`);
+    }
+    return lines.join('\n');
+}
+/**
+ * O comportamento do `pre-commit` (PRD §3.8): recusa commit direto na
+ * `main`, sem rodar gate nenhum — ali não existe pergunta de qualidade a
+ * fazer. Senão, roda o laço de convergência dos gates do estágio
+ * `pre-commit` e traduz o resultado. Termina **antes** de o Git criar o
+ * commit — nunca diz "commit criado".
+ */
+export async function runPreCommitHook(cwd) {
+    const branch = await currentBranch(cwd);
+    if (branch === 'main') {
+        refuseR22(await switchToDevRoute(cwd));
+    }
+    const config = await readConfig(join(cwd, '.kuyper', 'config.yaml'));
+    const outcome = await runConverging(gatesForStage(config.gates, 'pre-commit'), cwd);
+    if (outcome.kind === 'gate-failed')
+        refuseGateFailed(outcome.gate, outcome.output);
+    if (outcome.kind === 'no-converge')
+        refuseNoConverge(outcome.paths);
+    if (outcome.kind === 'edited-unstaged')
+        refuseEditedUnstaged(outcome.gate, outcome.paths);
+    console.log(formatFixedReport(outcome.fixed));
+    return 0;
+}
+const ZERO_SHA = '0'.repeat(40);
+/** O `stdin` do Git: uma linha por atualização, `local_ref local_sha remote_ref remote_sha`. */
+function parseRefUpdates(stdin) {
+    const updates = [];
+    for (const raw of stdin.split('\n')) {
+        const line = raw.trim();
+        if (line.length === 0)
+            continue;
+        const [localRef, localSha, remoteRef, remoteSha] = line.split(/\s+/u);
+        if (localRef === undefined || localSha === undefined || remoteRef === undefined || remoteSha === undefined)
+            continue;
+        updates.push({ localRef, localSha, remoteRef, remoteSha });
+    }
+    return updates;
+}
+function refuseDirtyTreeForPush(route) {
+    throw new KuyperRefusal({
+        headline: 'A árvore de trabalho está suja — o push para a main foi recusado.',
+        details: ['O que seria testado não é necessariamente o que está sendo enviado.'],
+        route: [route],
+    });
+}
+function refuseWrongBranchForPush(route) {
+    throw new KuyperRefusal({
+        headline: 'A branch atual não é a main, mas o push tem a main como destino.',
+        route: [route],
+    });
+}
+function refuseShaMismatchForPush() {
+    throw new KuyperRefusal({
+        headline: 'O commit sendo enviado não é o HEAD local.',
+        details: ['O candidato testado precisa ser exatamente o candidato enviado.'],
+        route: ['git switch main', 'Confira que o HEAD é o commit que você quer publicar, e empurre de novo.'],
+    });
+}
+function refuseValidateDiverged(report) {
+    const details = report.code === 2 ? report.findings : [];
+    throw new KuyperRefusal({
+        code: 'R23',
+        headline: report.code === 1 ? 'kuyper validate ficou inconclusivo — o push para a main foi recusado.' : 'kuyper validate está divergente — o push para a main foi recusado.',
+        details,
+        route: ['pnpm exec kuyper generate', 'Revise, commite na dev, integre, e publique de novo.'],
+    });
+}
+function refuseGateFailedPush(gate, output) {
+    throw new KuyperRefusal({
+        code: 'R19',
+        headline: `O gate ${gate} falhou no publish.`,
+        details: output.split('\n').filter((l) => l.length > 0),
+        route: ['Corrija o que o gate acusou, leve para a dev, commite, integre, e publique de novo.'],
+    });
+}
+/**
+ * R23 — tanto para "um gate escreveu durante os gates" quanto para "a
+ * árvore ou o HEAD mudaram depois dos gates" (checagem final, §3.8). A
+ * mensagem nunca sugere `push --no-verify`: ele enviaria exatamente a
+ * versão sem a correção (§3.8).
+ */
+function refuseWroteDuringPush(paths) {
+    throw new KuyperRefusal({
+        code: 'R23',
+        headline: 'Um gate alterou arquivos durante a execução — o push para a main foi recusado.',
+        details: ['O que foi testado não é o que seria enviado. A correção está na sua árvore.', '', ...paths],
+        route: [
+            'Leve a correção para a dev, commite lá, e integre:',
+            '    git stash && git switch dev && git stash pop',
+            '    git add -- <arquivos acima> && git commit',
+            '    pnpm exec kuyper integrate && pnpm exec kuyper publish',
+        ],
+    });
+}
+function refuseHeadMovedDuringPush() {
+    throw new KuyperRefusal({
+        code: 'R23',
+        headline: 'O HEAD mudou durante a execução dos gates — o push para a main foi recusado.',
+        details: ['O candidato testado não é mais o candidato enviado.'],
+        route: ['git switch main', 'Confira o estado do repositório antes de empurrar de novo.'],
+    });
+}
+/**
+ * O comportamento do `pre-push` (PRD §3.8). Só age nas atualizações
+ * destinadas a `refs/heads/main` — push de outra branch não dispara nada
+ * daqui. Três preconições antes de qualquer gate (árvore limpa, branch
+ * atual `main`, SHA enviado igual ao `HEAD`), depois `validate()`, depois
+ * os gates do estágio `publish` em modo exato, depois a checagem final
+ * (árvore continua limpa, `HEAD` não se moveu).
+ */
+export async function runPrePushHook(cwd, stdin) {
+    const updates = parseRefUpdates(stdin);
+    const mainUpdate = updates.find((u) => u.remoteRef === 'refs/heads/main' && u.localSha !== ZERO_SHA);
+    if (mainUpdate === undefined)
+        return 0;
+    const status = await statusPorcelain(cwd);
+    if (status.trim().length > 0) {
+        refuseDirtyTreeForPush(await switchToDevRoute(cwd));
+    }
+    const branch = await currentBranch(cwd);
+    if (branch !== 'main') {
+        refuseWrongBranchForPush('git switch main');
+    }
+    const headBefore = await headSha(cwd);
+    if (headBefore !== mainUpdate.localSha) {
+        refuseShaMismatchForPush();
+    }
+    const validateReport = await validate({ projectRoot: cwd, silent: true });
+    if (validateReport.code !== 0) {
+        refuseValidateDiverged(validateReport);
+    }
+    const config = await readConfig(join(cwd, '.kuyper', 'config.yaml'));
+    const outcome = await runExact(gatesForStage(config.gates, 'publish'), cwd);
+    if (outcome.kind === 'gate-failed')
+        refuseGateFailedPush(outcome.gate, outcome.output);
+    if (outcome.kind === 'wrote')
+        refuseWroteDuringPush(outcome.paths);
+    const headAfter = await headSha(cwd);
+    if (headAfter !== headBefore) {
+        refuseHeadMovedDuringPush();
+    }
+    return 0;
+}

package/dist/hooks.js

@@ -0,0 +1,49 @@
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+const execFileAsync = promisify(execFile);
+export const HOOK_NAMES = ['pre-commit', 'pre-push'];
+export const HOOKS_PATH = '.kuyper/hooks';
+export const HOOK_MODE = 0o755;
+/**
+ * O conteúdo dos dois hooks (PRD §3.8) — idêntico, salvo o estágio na última
+ * linha. Resolve o binário em `node_modules/.bin/`, nunca por `pnpm exec` nem
+ * pelo `PATH` (mesma regra do relançamento no `update`).
+ */
+export function hookScript(name) {
+    return `#!/bin/sh
+# gerado por @kuyper/harness — não editar
+set -e
+root=$(git rev-parse --show-toplevel)
+bin="$root/node_modules/.bin/kuyper"
+if [ ! -x "$bin" ]; then
+  echo "✗  O Harness não está instalado neste clone." >&2
+  echo "   pnpm install" >&2
+  exit 1
+fi
+exec "$bin" __hook ${name} "$@"
+`;
+}
+/** `undefined` quando `core.hooksPath` não está configurado. */
+export async function getCoreHooksPath(cwd) {
+    try {
+        const { stdout } = await execFileAsync('git', ['config', '--get', 'core.hooksPath'], { cwd });
+        const value = stdout.trim();
+        return value.length > 0 ? value : undefined;
+    }
+    catch (err) {
+        // git config --get sai com 1 quando a chave não está definida — não é erro.
+        if (err.code === 1)
+            return undefined;
+        throw err;
+    }
+}
+export async function setCoreHooksPath(cwd, value) {
+    await execFileAsync('git', ['config', 'core.hooksPath', value], { cwd });
+}
+export function classifyHooksPath(current) {
+    if (current === undefined)
+        return 'absent';
+    // git normaliza separador e pode devolver com ou sem barra final.
+    const normalized = current.replace(/\/+$/u, '');
+    return normalized === HOOKS_PATH ? 'correct' : 'other';
+}

package/dist/init.js

@@ -0,0 +1,265 @@
+import { access, readFile, readdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { createInterface } from 'node:readline/promises';
+import { readPackageScripts, findGatesWithMissingScript } from './config.js';
+import { KuyperRefusal } from './errors.js';
+import { getCoreHooksPath, classifyHooksPath } from './hooks.js';
+import { packageCorePath } from './paths.js';
+import { writeFileAtomic } from './atomicWrite.js';
+import { generate, loadCapabilities } from './generate.js';
+import { isGitRepo, currentBranch } from './gitPlumbing.js';
+/** A lista fixa de gates que o Harness exige — não é escolha do usuário (PRD §4.1). */
+const DEFAULT_GATES = [
+    { id: 'typecheck', command: 'pnpm typecheck', stages: ['pre-commit', 'publish'] },
+    { id: 'lint', command: 'pnpm lint', stages: ['pre-commit', 'publish'] },
+    { id: 'test', command: 'pnpm test', stages: ['publish'] },
+    { id: 'build', command: 'pnpm build', stages: ['publish'] },
+];
+const GATE_SUGGESTIONS = {
+    typecheck: { install: 'pnpm add -D typescript', scriptLine: '"typecheck": "tsc --noEmit"' },
+    lint: { install: 'pnpm add -D eslint', scriptLine: '"lint": "eslint ."' },
+    test: { install: 'pnpm add -D vitest  (sugestão — qualquer test runner serve)', scriptLine: '"test": "vitest run"' },
+    build: { scriptLine: '"build": "<o comando que produz sua saída publicável>"' },
+};
+const PREPARE_SCRIPT = 'pnpm exec kuyper generate';
+const FIXED_PROVIDER_ORDER = ['claude', 'codex'];
+const SOBRE_O_PROJETO_TITLE = 'Sobre este projeto';
+function configYaml(providers) {
+    const gateBlocks = DEFAULT_GATES.map((g) => `  - id: ${g.id}\n    command: ${g.command}\n    stages: [${g.stages.join(', ')}]`).join('\n');
+    return `schemaVersion: 1\nproviders:\n  enabled: [${providers.join(', ')}]\ngates:\n${gateBlocks}\n`;
+}
+function stateMd(today) {
+    return `Atualizado por: init — ${today}\n\n## Onde parei\n## O que descobri que não estava óbvio\n## Próximo passo concreto\n## Cuidado\n`;
+}
+function sobreOProjetoBody(name, description) {
+    const trimmed = description.trim();
+    return trimmed.length > 0 ? `\`${name}\` — ${trimmed}.\n` : `\`${name}\`.\n`;
+}
+function todayIso() {
+    const d = new Date();
+    const pad = (n) => String(n).padStart(2, '0');
+    return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}`;
+}
+async function pathExists(p) {
+    try {
+        await access(p);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function refuseNoTty() {
+    throw new KuyperRefusal({
+        headline: 'O init precisa de um terminal interativo.',
+        details: [
+            'Ele faz três perguntas e espera a sua aprovação antes de criar a base.',
+            'Sem terminal não há como respondê-las, e o Harness não inventa as respostas por você.',
+        ],
+        route: ['Rode num terminal interativo — é o único comando do Harness que exige um.'],
+    });
+}
+function refuseR2() {
+    throw new KuyperRefusal({ code: 'R2', headline: 'Isto não é um repositório Git.', route: ['git init'] });
+}
+function refuseR3() {
+    throw new KuyperRefusal({ code: 'R3', headline: 'Não existe package.json.', route: ['pnpm init'] });
+}
+function refuseR4() {
+    throw new KuyperRefusal({
+        code: 'R4',
+        headline: 'Já existe .kuyper/ neste projeto.',
+        details: ['O init não volta.'],
+        route: ['Para regenerar as saídas:', '    pnpm exec kuyper generate'],
+    });
+}
+function refuseR5() {
+    throw new KuyperRefusal({
+        code: 'R5',
+        headline: 'Nenhum provider escolhido.',
+        details: ['Sem provider não há saída a materializar.'],
+        route: ['Rode de novo e escolha ao menos um: claude, codex.'],
+    });
+}
+function refuseR6(missing) {
+    const details = [];
+    for (const gate of missing) {
+        const suggestion = GATE_SUGGESTIONS[gate.id];
+        if (suggestion?.install)
+            details.push(`${gate.id}    ${suggestion.install}`);
+        else
+            details.push(gate.id);
+        details.push(`${' '.repeat(gate.id.length)}    package.json → ${suggestion?.scriptLine ?? gate.command}`);
+        details.push('');
+    }
+    details.pop();
+    throw new KuyperRefusal({
+        headline: missing.length === 1
+            ? 'Falta o script de um gate que o Harness usa.'
+            : `Faltam scripts para ${missing.length} gates que o Harness usa.`,
+        details,
+        route: ['Instale, declare os scripts, e rode pnpm exec kuyper init de novo.'],
+    });
+}
+function refuseR24(current) {
+    throw new KuyperRefusal({
+        code: 'R24',
+        headline: 'O core.hooksPath já aponta para outro lugar.',
+        details: [`atual:  ${current}`, '', 'Outro gerenciador de hooks controla este repositório. O Harness não', 'assume esse controle por conta própria — a decisão é sua.'],
+        route: ['Para entregar os hooks ao Harness:', '    git config --unset core.hooksPath', '    pnpm exec kuyper init'],
+    });
+}
+function parseProviders(raw) {
+    const trimmed = raw.trim();
+    if (trimmed.length === 0)
+        return [...FIXED_PROVIDER_ORDER];
+    const tokens = new Set(trimmed.toLowerCase().split(/[\s,]+/u).filter((t) => t.length > 0));
+    return FIXED_PROVIDER_ORDER.filter((p) => tokens.has(p));
+}
+function parseYesNo(raw, defaultYes) {
+    const trimmed = raw.trim().toLowerCase();
+    if (trimmed.length === 0)
+        return defaultYes;
+    return trimmed[0] !== 'n';
+}
+async function copyCoreTree(fromDir, toDir) {
+    let entries;
+    try {
+        entries = await readdir(fromDir, { withFileTypes: true });
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return;
+        throw err;
+    }
+    for (const entry of entries) {
+        const from = join(fromDir, entry.name);
+        const to = join(toDir, entry.name);
+        if (entry.isDirectory()) {
+            await copyCoreTree(from, to);
+        }
+        else if (entry.isFile()) {
+            const content = await readFile(from);
+            await writeFileAtomic(to, content);
+        }
+    }
+}
+async function readPackageJson(path) {
+    const text = await readFile(path, 'utf8');
+    return JSON.parse(text);
+}
+/**
+ * Do repositório cru à base pronta para revisão (PRD §3.1). Único comando
+ * que exige terminal interativo — três perguntas, uma confirmação, depois
+ * cria `.kuyper/` inteiro e chama `generate`. Não commita, não empurra.
+ */
+export async function init(options = {}) {
+    const projectRoot = options.projectRoot ?? process.cwd();
+    // Preflight primeiro, TTY depois — de propósito. Nenhuma das checagens
+    // abaixo precisa de interação, e rodar assim faz um init sem terminal
+    // (ex.: dentro de um script de CI, num repositório que nem é Git ainda)
+    // ver o motivo de verdade em vez de só "precisa de terminal", que não
+    // ajudaria a consertar o problema real. Cada uma sua própria recusa,
+    // nada é criado antes daqui.
+    if (!(await isGitRepo(projectRoot)))
+        refuseR2();
+    const packageJsonPath = join(projectRoot, 'package.json');
+    if (!(await pathExists(packageJsonPath)))
+        refuseR3();
+    if (await pathExists(join(projectRoot, '.kuyper')))
+        refuseR4();
+    const scripts = await readPackageScripts(packageJsonPath);
+    const missingGates = findGatesWithMissingScript([...DEFAULT_GATES], scripts);
+    if (missingGates.length > 0)
+        refuseR6(missingGates);
+    const hooksPathCurrent = await getCoreHooksPath(projectRoot);
+    const hooksPathState = classifyHooksPath(hooksPathCurrent);
+    if (hooksPathState === 'other')
+        refuseR24(hooksPathCurrent);
+    const interactive = options.input !== undefined || options.output !== undefined;
+    if (!interactive && process.stdin.isTTY !== true) {
+        refuseNoTty();
+    }
+    const input = options.input ?? process.stdin;
+    const output = options.output ?? process.stdout;
+    const print = (line) => {
+        output.write(`${line}\n`);
+    };
+    const pkg = await readPackageJson(packageJsonPath);
+    const rl = createInterface({ input: input, output });
+    let name;
+    let description;
+    let providers;
+    try {
+        const defaultName = pkg.name ?? '';
+        const nameAnswer = (await rl.question(`Nome do projeto [${defaultName}]: `)).trim();
+        name = nameAnswer.length > 0 ? nameAnswer : defaultName;
+        const defaultDescription = pkg.description ?? '';
+        const descriptionAnswer = (await rl.question(`Descrição [${defaultDescription || '(nenhuma)'}]: `)).trim();
+        description = descriptionAnswer.length > 0 ? descriptionAnswer : defaultDescription;
+        const providersAnswer = await rl.question('Providers a habilitar — claude, codex [ambos]: ');
+        providers = parseProviders(providersAnswer);
+        if (providers.length === 0)
+            refuseR5();
+        print('');
+        print('Vou criar:');
+        print('');
+        print(`   nome:         ${name}`);
+        print(`   descrição:    ${description.length > 0 ? description : '(nenhuma)'}`);
+        print(`   providers:    ${providers.join(', ')}`);
+        print('');
+        print('   .kuyper/config.yaml');
+        print('   .kuyper/project/rules/sobre-o-projeto.md');
+        print('   .kuyper/STATE.md');
+        print('   .kuyper/core/         (6 rules, 4 skills)');
+        print('   arquivo(s) de instrução, skills e hooks dos providers escolhidos');
+        print('');
+        const confirmAnswer = await rl.question('Confirma? [S/n] ');
+        if (!parseYesNo(confirmAnswer, true)) {
+            print('Cancelado. Nada foi criado.');
+            return 0;
+        }
+    }
+    finally {
+        rl.close();
+    }
+    const kuyperDir = join(projectRoot, '.kuyper');
+    await writeFileAtomic(join(kuyperDir, 'config.yaml'), configYaml(providers));
+    const projectRuleContent = `---\ntitle: ${SOBRE_O_PROJETO_TITLE}\n---\n\n${sobreOProjetoBody(name, description)}`;
+    await writeFileAtomic(join(kuyperDir, 'project', 'rules', 'sobre-o-projeto.md'), projectRuleContent);
+    await writeFileAtomic(join(kuyperDir, 'STATE.md'), stateMd(todayIso()));
+    await copyCoreTree(options.packageCoreDir ?? packageCorePath(), join(kuyperDir, 'core'));
+    await generate(options.packageCoreDir === undefined ? { projectRoot } : { projectRoot, packageCoreDir: options.packageCoreDir });
+    const pkgWithPrepare = { ...pkg, scripts: { ...pkg.scripts, prepare: PREPARE_SCRIPT } };
+    await writeFileAtomic(packageJsonPath, `${JSON.stringify(pkgWithPrepare, null, 2)}\n`);
+    const claudeEnabled = providers.includes('claude');
+    const codexEnabled = providers.includes('codex');
+    const outputs = [
+        claudeEnabled ? 'CLAUDE.md' : undefined,
+        'AGENTS.md',
+        claudeEnabled ? '.claude/skills/' : undefined,
+        codexEnabled ? '.agents/skills/' : undefined,
+    ].filter((v) => v !== undefined);
+    // Contado de verdade, não cravado — o número de rules/skills do core não é
+    // uma constante do produto, é o que o pacote em execução realmente trouxe.
+    const { set } = await loadCapabilities(projectRoot);
+    print('');
+    print('✓  Base criada em .kuyper/');
+    print('');
+    print(`   core:      ${set.coreRules.length} rules, ${set.coreSkills.length} skills`);
+    print(`   projeto:   ${set.projectRules.length} rule${set.projectRules.length === 1 ? '' : 's'}`);
+    print(`   saídas:    ${outputs.join(', ')}`);
+    print('   hooks:     pre-commit, pre-push  (ativos)');
+    print('');
+    print('   Revise e commite:');
+    print('       git add -A && git commit');
+    const branch = await currentBranch(projectRoot);
+    if (branch === 'main') {
+        print('');
+        print('⚠  você está na main; crie a dev antes de commitar, senão o pre-commit');
+        print('   que acabou de ser instalado vai recusar:');
+        print('');
+        print('       git switch -c dev');
+    }
+    return 0;
+}