@kuyper/harness 0.1.0

package/dist/cli.js

@@ -0,0 +1,165 @@
+#!/usr/bin/env node
+import { readFileSync, realpathSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { KuyperRefusal } from './errors.js';
+import { requireProject } from './project.js';
+import { generate } from './generate.js';
+import { validate } from './validate.js';
+import { init } from './init.js';
+import { integrate } from './integrate.js';
+import { publish } from './publish.js';
+import { update, continueUpdate } from './update.js';
+import { runCapabilityCommand } from './capabilityCommands.js';
+import { runPreCommitHook, runPrePushHook } from './hookBehavior.js';
+const moduleDir = dirname(fileURLToPath(import.meta.url));
+const pkg = JSON.parse(readFileSync(join(moduleDir, '..', 'package.json'), 'utf8'));
+/** As oito interfaces públicas (PRD §1). Nada além disso. */
+export const COMMANDS = [
+    'init',
+    'generate',
+    'validate',
+    'integrate',
+    'publish',
+    'update',
+    'rule',
+    'skill',
+];
+function isCommand(value) {
+    return COMMANDS.includes(value);
+}
+function printCommandList() {
+    console.log('kuyper — copiloto de desenvolvimento\n');
+    console.log('Comandos:');
+    for (const cmd of COMMANDS)
+        console.log(`  kuyper ${cmd}`);
+}
+/**
+ * Todos os comandos, menos `init`, herdam a checagem comum (R1) — mesmo
+ * antes de ter lógica própria (prova do B1). No B10, as oito interfaces
+ * públicas passam a ter lógica real.
+ */
+const HANDLERS = {
+    init: async () => init(),
+    generate: async (rest) => {
+        await requireProject();
+        await generate({ force: rest.includes('--force') });
+        return 0;
+    },
+    validate: async () => {
+        await requireProject();
+        const report = await validate();
+        return report.code;
+    },
+    integrate: async () => {
+        await requireProject();
+        const report = await integrate();
+        return report.code;
+    },
+    publish: async () => {
+        await requireProject();
+        const report = await publish();
+        return report.code;
+    },
+    update: async () => {
+        await requireProject();
+        return update();
+    },
+    rule: async (rest) => {
+        await requireProject();
+        return runCapabilityCommand('rule', rest, { readStdin: () => readStdin(process.stdin) });
+    },
+    skill: async (rest) => {
+        await requireProject();
+        return runCapabilityCommand('skill', rest, { readStdin: () => readStdin(process.stdin) });
+    },
+};
+async function readStdin(stream) {
+    const chunks = [];
+    for await (const chunk of stream) {
+        chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk)));
+    }
+    return Buffer.concat(chunks).toString('utf8');
+}
+/**
+ * `__hook` e `__update-continue` são maquinaria declarada, não a nona
+ * interface: fora de `COMMANDS`, da ajuda e da lista de comandos. `__hook`
+ * (PRD §3.8) é o ponto de entrada que o script de hook gerado chama;
+ * `__update-continue` (PRD §3.6, passos 5–9) é o que `update()` (Fase 1,
+ * `update.ts`) invoca relançando o binário recém-instalado — nunca algo
+ * que um humano ou uma LLM digita.
+ */
+async function runHook(rest) {
+    const [name] = rest;
+    if (name === 'pre-commit')
+        return runPreCommitHook(process.cwd());
+    if (name === 'pre-push')
+        return runPrePushHook(process.cwd(), await readStdin(process.stdin));
+    console.error(`✗  __hook desconhecido: ${String(name)}`);
+    return 1;
+}
+export async function main(argv) {
+    const [maybeCmd, ...rest] = argv;
+    if (maybeCmd === '--version' || maybeCmd === '-v') {
+        console.log(pkg.version);
+        return 0;
+    }
+    if (maybeCmd === undefined) {
+        printCommandList();
+        return 0;
+    }
+    try {
+        if (maybeCmd === '__hook') {
+            return await runHook(rest);
+        }
+        if (maybeCmd === '__update-continue') {
+            return await continueUpdate({ projectRoot: process.cwd() });
+        }
+        if (!isCommand(maybeCmd)) {
+            console.error(`✗  Comando desconhecido: ${maybeCmd}\n`);
+            printCommandList();
+            return 1;
+        }
+        return await HANDLERS[maybeCmd](rest);
+    }
+    catch (err) {
+        if (err instanceof KuyperRefusal) {
+            console.error(err.format());
+            return 1;
+        }
+        throw err;
+    }
+}
+/**
+ * Comparar `process.argv[1]` direto com `fileURLToPath(import.meta.url)`
+ * quebra em qualquer invocação com um symlink no meio do caminho — que é
+ * exatamente como o binário é invocado de verdade: `node_modules/.bin/kuyper`
+ * (o que `pnpm add -D` cria) É um symlink, e macOS já resolve `/tmp` para
+ * `/private/tmp` por conta própria. Sem `realpathSync` dos dois lados,
+ * `isMain` dá falso sempre que a instalação real acontece, e o binário
+ * inteiro não faz nada — silenciosamente, saindo com 0. Achado testando o
+ * hook materializado de verdade via `node_modules/.bin/`, não em uso comum
+ * (B6) — nenhum teste anterior invocava por aí.
+ */
+function isMainModule() {
+    const invoked = process.argv[1];
+    if (invoked === undefined)
+        return false;
+    try {
+        return realpathSync(invoked) === realpathSync(fileURLToPath(import.meta.url));
+    }
+    catch {
+        return false;
+    }
+}
+const isMain = isMainModule();
+if (isMain) {
+    main(process.argv.slice(2))
+        .then((code) => {
+        process.exitCode = code;
+    })
+        .catch((err) => {
+        console.error(err instanceof Error ? err.message : String(err));
+        process.exitCode = 1;
+    });
+}

package/dist/config.js

@@ -0,0 +1,159 @@
+import { readFile } from 'node:fs/promises';
+import { parse as parseYaml } from 'yaml';
+/**
+ * Schema inválido recusa (R25): campo obrigatório ausente, gate duplicado,
+ * estágio desconhecido, comando vazio, ou campo que o produto já declarou
+ * morto (`mainBranch`, `workBranch`, `remote` — PRD §4.1).
+ */
+export class ConfigSchemaError extends Error {
+    issues;
+    constructor(issues) {
+        super(`.kuyper/config.yaml inválido:\n${issues.map((i) => `  - ${i}`).join('\n')}`);
+        this.issues = issues;
+        this.name = 'ConfigSchemaError';
+    }
+}
+const KNOWN_PROVIDERS = new Set(['claude', 'codex']);
+const KNOWN_STAGES = new Set(['pre-commit', 'publish']);
+const TOP_LEVEL_KEYS = new Set(['schemaVersion', 'providers', 'gates']);
+const PROVIDERS_KEYS = new Set(['enabled']);
+const GATE_KEYS = new Set(['id', 'command', 'stages']);
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/**
+ * Puro: recebe o texto do YAML, devolve a config validada ou lança
+ * `ConfigSchemaError` com todos os achados — não só o primeiro.
+ */
+export function parseConfig(text) {
+    const issues = [];
+    let data;
+    try {
+        data = parseYaml(text);
+    }
+    catch (err) {
+        throw new ConfigSchemaError([`YAML malformado: ${err.message}`]);
+    }
+    if (!isPlainObject(data)) {
+        throw new ConfigSchemaError(['o arquivo não é um mapa YAML']);
+    }
+    for (const key of Object.keys(data)) {
+        if (!TOP_LEVEL_KEYS.has(key))
+            issues.push(`campo desconhecido: ${key}`);
+    }
+    if (data['schemaVersion'] !== 1) {
+        issues.push(`schemaVersion deve ser 1 (encontrado: ${JSON.stringify(data['schemaVersion'])})`);
+    }
+    const enabled = [];
+    const providers = data['providers'];
+    if (!isPlainObject(providers)) {
+        issues.push('providers ausente ou inválido');
+    }
+    else {
+        for (const key of Object.keys(providers)) {
+            if (!PROVIDERS_KEYS.has(key))
+                issues.push(`providers: campo desconhecido: ${key}`);
+        }
+        const enabledRaw = providers['enabled'];
+        if (!Array.isArray(enabledRaw)) {
+            issues.push('providers.enabled ausente ou não é uma lista');
+        }
+        else {
+            for (const p of enabledRaw) {
+                if (typeof p === 'string' && KNOWN_PROVIDERS.has(p)) {
+                    enabled.push(p);
+                }
+                else {
+                    issues.push(`provider desconhecido: ${JSON.stringify(p)}`);
+                }
+            }
+        }
+    }
+    const gates = [];
+    const gatesRaw = data['gates'];
+    const seenIds = new Set();
+    if (!Array.isArray(gatesRaw)) {
+        issues.push('gates ausente ou não é uma lista');
+    }
+    else {
+        gatesRaw.forEach((gateRaw, i) => {
+            if (!isPlainObject(gateRaw)) {
+                issues.push(`gates[${i}]: não é um mapa`);
+                return;
+            }
+            for (const key of Object.keys(gateRaw)) {
+                if (!GATE_KEYS.has(key))
+                    issues.push(`gates[${i}]: campo desconhecido: ${key}`);
+            }
+            const id = gateRaw['id'];
+            const command = gateRaw['command'];
+            const stagesRaw = gateRaw['stages'];
+            let idOk = false;
+            if (typeof id !== 'string' || id.length === 0) {
+                issues.push(`gates[${i}]: id ausente ou vazio`);
+            }
+            else if (seenIds.has(id)) {
+                issues.push(`gate duplicado: ${id}`);
+            }
+            else {
+                seenIds.add(id);
+                idOk = true;
+            }
+            const commandOk = typeof command === 'string' && command.trim().length > 0;
+            if (!commandOk)
+                issues.push(`gates[${i}]: comando vazio`);
+            const stages = [];
+            if (!Array.isArray(stagesRaw)) {
+                issues.push(`gates[${i}]: stages ausente ou não é uma lista`);
+            }
+            else {
+                for (const s of stagesRaw) {
+                    if (typeof s === 'string' && KNOWN_STAGES.has(s)) {
+                        stages.push(s);
+                    }
+                    else {
+                        issues.push(`gates[${i}]: estágio desconhecido: ${JSON.stringify(s)}`);
+                    }
+                }
+            }
+            if (idOk && commandOk) {
+                gates.push({ id: id, command: command, stages });
+            }
+        });
+    }
+    if (issues.length > 0) {
+        throw new ConfigSchemaError(issues);
+    }
+    return { schemaVersion: 1, providers: { enabled }, gates };
+}
+export async function readConfig(configPath) {
+    const text = await readFile(configPath, 'utf8');
+    return parseConfig(text);
+}
+/**
+ * "Um gate que não pode ser executado não é gate vermelho: é configuração
+ * quebrada, e o Harness acusa o config.yaml, não o código" (PRD §4.1).
+ *
+ * Só confere gates cujo comando é `pnpm <script>` — é a convenção que o
+ * corpus inteiro usa, e a checagem aponta o config.yaml, não tenta validar
+ * comando arbitrário. Devolve os gates cujo script não existe no
+ * `package.json` do projeto.
+ */
+export function findGatesWithMissingScript(gates, packageJsonScripts) {
+    const missing = [];
+    for (const gate of gates) {
+        const match = /^pnpm\s+([\w:-]+)/.exec(gate.command);
+        if (!match)
+            continue;
+        const scriptName = match[1];
+        if (!(scriptName in packageJsonScripts)) {
+            missing.push(gate);
+        }
+    }
+    return missing;
+}
+export async function readPackageScripts(packageJsonPath) {
+    const text = await readFile(packageJsonPath, 'utf8');
+    const data = JSON.parse(text);
+    return data.scripts ?? {};
+}

package/dist/coreClassification.js

@@ -0,0 +1,76 @@
+import { readFile, readdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { isTempPath } from './atomicWrite.js';
+import { computeChecksum } from './lock.js';
+/**
+ * Chaves relativas (com `/`) → checksum, de todo arquivo regular sob
+ * `rootDir`. Leitores ignoram `.kuyper-tmp` e não-regulares (symlink etc.) —
+ * "o mesmo conjunto de arquivos regulares" da SPEC protocolo-core-lock §4.
+ */
+export async function checksumTree(rootDir) {
+    const result = new Map();
+    await walk(rootDir, '');
+    return result;
+    async function walk(absDir, relPrefix) {
+        let entries;
+        try {
+            entries = await readdir(absDir, { withFileTypes: true });
+        }
+        catch (err) {
+            if (err.code === 'ENOENT')
+                return;
+            throw err;
+        }
+        for (const entry of entries) {
+            if (isTempPath(entry.name))
+                continue;
+            const relPath = relPrefix ? `${relPrefix}/${entry.name}` : entry.name;
+            const absPath = join(absDir, entry.name);
+            if (entry.isDirectory()) {
+                await walk(absPath, relPath);
+            }
+            else if (entry.isFile()) {
+                const content = await readFile(absPath);
+                result.set(relPath, computeChecksum(content));
+            }
+            // symlinks e outros tipos: fora de "arquivo regular", ignorados.
+        }
+    }
+}
+export function mapsEqual(a, b) {
+    if (a.size !== b.size)
+        return false;
+    for (const [k, v] of a) {
+        if (b.get(k) !== v)
+            return false;
+    }
+    return true;
+}
+/**
+ * `.kuyper/core/**` do lock anterior, com o prefixo removido — o candidato
+ * `L` da SPEC protocolo-core-lock §4.
+ */
+export function coreEntriesFromLock(lockEntries) {
+    const prefix = '.kuyper/core/';
+    const out = new Map();
+    for (const [key, value] of Object.entries(lockEntries)) {
+        if (key.startsWith(prefix))
+            out.set(key.slice(prefix.length), value);
+    }
+    return out;
+}
+/**
+ * A classificação agregada (SPEC protocolo-core-lock §4). A unidade de
+ * autorização é a árvore inteira, nunca um arquivo — não existe aceitação
+ * independente por caminho.
+ */
+export function classifyCore(L, P, D) {
+    const unknown = [...D.keys()].filter((k) => !L.has(k) && !P.has(k));
+    if (unknown.length > 0)
+        return { state: 'unknown-path', paths: unknown.sort() };
+    if (mapsEqual(D, L))
+        return { state: 'anterior-intact' };
+    if (mapsEqual(D, P))
+        return { state: 'transition-complete' };
+    return { state: 'mismatch' };
+}

package/dist/errors.js

@@ -0,0 +1,38 @@
+const LINE_WIDTH = 68;
+function withCodeTag(headline, code) {
+    const prefix = `✗  ${headline}`;
+    const tag = `(${code})`;
+    const gap = LINE_WIDTH - prefix.length - tag.length;
+    return gap > 1 ? `${prefix}${' '.repeat(gap)}${tag}` : `${prefix}   ${tag}`;
+}
+function indentBlock(lines, indent) {
+    return lines.map((line) => (line === '' ? '' : `${indent}${line}`));
+}
+export function formatRefusal(opts) {
+    const out = [];
+    out.push(opts.code ? withCodeTag(opts.headline, opts.code) : `✗  ${opts.headline}`);
+    if (opts.details && opts.details.length > 0) {
+        out.push('');
+        out.push(...indentBlock(opts.details, '   '));
+    }
+    if (opts.route && opts.route.length > 0) {
+        out.push('');
+        out.push(...indentBlock(opts.route, '   '));
+    }
+    return out.join('\n');
+}
+/**
+ * Uma recusa do produto. `format()` produz o texto exatamente na forma do
+ * PRD §3 — quem lança isto no dispatcher só precisa imprimir e sair com 1.
+ */
+export class KuyperRefusal extends Error {
+    opts;
+    constructor(opts) {
+        super(opts.headline);
+        this.opts = opts;
+        this.name = 'KuyperRefusal';
+    }
+    format() {
+        return formatRefusal(this.opts);
+    }
+}

package/dist/gateRunner.js

@@ -0,0 +1,109 @@
+import { exec } from 'node:child_process';
+import { promisify } from 'node:util';
+import { addPaths, dirtyPaths, hashFiles, unstagedAndUntrackedPaths } from './gitPlumbing.js';
+const execAsync = promisify(exec);
+export function gatesForStage(gates, stage) {
+    return gates.filter((g) => g.stages.includes(stage));
+}
+/**
+ * Roda o comando do gate via shell (`sh -c`) — o mesmo tanto faz `pnpm
+ * typecheck` quanto algo com pipe ou aspas. Um gate que não pode ser
+ * executado (comando inexistente) e um gate que roda e falha caem no mesmo
+ * `ok: false` — a distinção entre "configuração quebrada" e "código
+ * quebrado" não é deste módulo (PRD §4.1); ele só relata.
+ */
+export async function runGateCommand(command, cwd) {
+    try {
+        const { stdout, stderr } = await execAsync(command, { cwd, maxBuffer: 16 * 1024 * 1024 });
+        return { ok: true, output: `${stdout}${stderr}` };
+    }
+    catch (err) {
+        const e = err;
+        const output = `${e.stdout ?? ''}${e.stderr ?? ''}`;
+        return { ok: false, output: output.length > 0 ? output : e.message };
+    }
+}
+/**
+ * O laço do `pre-commit` (PRD §4.1, ADR gates-que-escrevem). Até
+ * `maxRounds` voltas, cada volta rodando **todos** os gates do estágio em
+ * ordem — se o lint conserta um arquivo, o typecheck da mesma volta já
+ * rodou sobre a versão de antes, então uma volta que mudou algo sempre
+ * repete a lista inteira, nunca só o gate seguinte.
+ *
+ * A fotografia (diff + não rastreados) é tirada **por gate**, não por
+ * volta — é o que permite o relatório final dizer qual gate corrigiu o
+ * quê (§3.8: *"lint corrigiu 2 arquivos"*), sem mudar a regra de quando
+ * repetir a volta.
+ *
+ * Um arquivo que já estava sujo antes de um gate rodar e teve o
+ * **conteúdo** mudado por ele (não só a categoria do `status` — daí o
+ * hash) nunca é readicionado: é recusa, a limitação do staging parcial
+ * declarada no §3.8.
+ */
+export async function runConverging(gates, cwd, options = {}) {
+    const maxRounds = options.maxRounds ?? 3;
+    const fixedByGate = new Map();
+    let lastTouched = [];
+    for (let round = 0; round < maxRounds; round++) {
+        let touchedThisRound = false;
+        for (const gate of gates) {
+            const before = await unstagedAndUntrackedPaths(cwd);
+            const beforeHashes = await hashFiles(cwd, before);
+            const result = await runGateCommand(gate.command, cwd);
+            if (!result.ok) {
+                return { kind: 'gate-failed', gate: gate.id, output: result.output };
+            }
+            const after = await unstagedAndUntrackedPaths(cwd);
+            const touchedNew = [...after].filter((p) => !before.has(p)).sort();
+            const stillDirty = [...before].filter((p) => after.has(p));
+            const afterHashesForStillDirty = await hashFiles(cwd, stillDirty);
+            const touchedPreexisting = stillDirty.filter((p) => afterHashesForStillDirty.get(p) !== beforeHashes.get(p)).sort();
+            if (touchedPreexisting.length > 0) {
+                return { kind: 'edited-unstaged', gate: gate.id, paths: touchedPreexisting };
+            }
+            if (touchedNew.length === 0)
+                continue;
+            touchedThisRound = true;
+            lastTouched = touchedNew;
+            await addPaths(cwd, touchedNew);
+            const existing = fixedByGate.get(gate.id) ?? new Set();
+            for (const p of touchedNew)
+                existing.add(p);
+            fixedByGate.set(gate.id, existing);
+        }
+        if (!touchedThisRound) {
+            const fixed = [...fixedByGate.entries()].map(([id, paths]) => ({ gate: id, paths: [...paths].sort() }));
+            return { kind: 'ok', fixed };
+        }
+    }
+    return { kind: 'no-converge', paths: lastTouched };
+}
+/**
+ * O modo `integrate`/`publish`/`pre-push` (PRD §4.1, ADR gates-que-escrevem,
+ * decisão 4): sem conserto. Quem chama garante a árvore limpa **antes** de
+ * entrar aqui — a R14 nos comandos, a precondição do §3.8 no `pre-push`;
+ * este runner não reconfere isso, só detecta se algum gate sujou o que
+ * devia continuar limpo. `git status --porcelain` basta (não precisa de
+ * `write-tree`): a árvore começou limpa, então qualquer entrada nova já é
+ * a resposta — diferente do `pre-commit`, onde ela é suja por natureza.
+ *
+ * A duração por gate (`results`) é o que o `integrate` (§3.4) e o `publish`
+ * (§3.5) imprimem no relatório de sucesso — medida aqui porque é aqui que
+ * cada gate roda, não recalculada por quem chama.
+ */
+export async function runExact(gates, cwd) {
+    const results = [];
+    for (const gate of gates) {
+        const start = Date.now();
+        const result = await runGateCommand(gate.command, cwd);
+        if (!result.ok) {
+            return { kind: 'gate-failed', gate: gate.id, output: result.output };
+        }
+        results.push({ gate: gate.id, durationMs: Date.now() - start });
+    }
+    const paths = await dirtyPaths(cwd);
+    if (paths.length > 0) {
+        return { kind: 'wrote', paths };
+    }
+    return { kind: 'ok', results };
+}