@kuyper/harness 0.1.0

package/dist/generate.js

@@ -0,0 +1,467 @@
+import { access, readFile, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+import { discoverRules, discoverSkills, compileInstructionFile, compileSkillRoutingSection, } from './capabilities.js';
+import { readConfig, ConfigSchemaError } from './config.js';
+import { KuyperRefusal } from './errors.js';
+import { checksumTree, classifyCore, coreEntriesFromLock, mapsEqual, } from './coreClassification.js';
+import { readLock, writeLock, computeChecksum } from './lock.js';
+import { writeFileAtomic, sweepTempFiles } from './atomicWrite.js';
+import { decideOutput, decideOrphan, computeOrphanPaths, removeOrphanFile, outputPath, } from './outputPlan.js';
+import { packageCorePath, packageRoot } from './paths.js';
+import { HOOK_NAMES, HOOKS_PATH, HOOK_MODE, hookScript, getCoreHooksPath, setCoreHooksPath, classifyHooksPath, } from './hooks.js';
+function controlledRoots(projectRoot) {
+    return [join(projectRoot, '.kuyper'), join(projectRoot, '.claude'), join(projectRoot, '.agents')];
+}
+export async function loadCapabilities(projectRoot) {
+    const issues = [];
+    const coreRulesR = await discoverRules(join(projectRoot, '.kuyper', 'core', 'rules'), 'core');
+    const projectRulesR = await discoverRules(join(projectRoot, '.kuyper', 'project', 'rules'), 'project');
+    const coreSkillsR = await discoverSkills(join(projectRoot, '.kuyper', 'core', 'skills'), 'core');
+    const projectSkillsR = await discoverSkills(join(projectRoot, '.kuyper', 'project', 'skills'), 'project');
+    issues.push(...coreRulesR.issues, ...projectRulesR.issues, ...coreSkillsR.issues, ...projectSkillsR.issues);
+    return {
+        set: {
+            coreRules: coreRulesR.items,
+            projectRules: projectRulesR.items,
+            coreSkills: coreSkillsR.items,
+            projectSkills: projectSkillsR.items,
+        },
+        issues,
+    };
+}
+/**
+ * Colisão de nome, referência que não resolve, `replaces:` para regra
+ * inexistente (R9) e duas rules substituindo a mesma regra do core (R10).
+ * Roda contra o inventário ativo — precisa passar antes de qualquer saída
+ * ou lock ser alterado (SPEC protocolo-core-lock §4).
+ *
+ * Tagueado com o próprio código — R9 e R10 são fechados separadamente de
+ * R25 (BUILD.md B2, "Fecha"), não é achado de schema.
+ */
+export function checkReferences(set) {
+    const issues = [];
+    const coreRuleNames = new Set(set.coreRules.map((r) => r.name));
+    const replacesTargets = new Map();
+    for (const rule of set.projectRules) {
+        if (rule.replaces === undefined)
+            continue;
+        const target = rule.replaces.slice('core:'.length);
+        if (!coreRuleNames.has(target)) {
+            issues.push({ code: 'R9', path: rule.sourcePath, message: `replaces aponta para regra inexistente: core:${target}` });
+            continue;
+        }
+        const existing = replacesTargets.get(target) ?? [];
+        existing.push(rule.name);
+        replacesTargets.set(target, existing);
+    }
+    for (const [target, names] of replacesTargets) {
+        if (names.length > 1) {
+            issues.push({
+                code: 'R10',
+                path: names.join(', '),
+                message: `duas rules do projeto substituem core:${target}`,
+            });
+        }
+    }
+    const coreSkillNames = new Set(set.coreSkills.map((s) => s.name));
+    const skillReplacesTargets = new Map();
+    for (const skill of set.projectSkills) {
+        if (coreSkillNames.has(skill.name)) {
+            issues.push({ code: 'R9', path: skill.sourceDir, message: `colide com a skill core:${skill.name}` });
+        }
+        if (skill.replaces === undefined)
+            continue;
+        if (!coreSkillNames.has(skill.replaces)) {
+            issues.push({ code: 'R9', path: skill.sourceDir, message: `replaces aponta para skill inexistente: ${skill.replaces}` });
+            continue;
+        }
+        const existing = skillReplacesTargets.get(skill.replaces) ?? [];
+        existing.push(skill.name);
+        skillReplacesTargets.set(skill.replaces, existing);
+    }
+    for (const [target, names] of skillReplacesTargets) {
+        if (names.length > 1) {
+            issues.push({
+                code: 'R10',
+                path: names.join(', '),
+                message: `duas skills do projeto substituem ${target} na lista de roteamento`,
+            });
+        }
+    }
+    return issues;
+}
+export function buildDesiredOutputs(set, config) {
+    const outputs = [];
+    const rulesSection = compileInstructionFile(set.coreRules, set.projectRules);
+    const routingSection = compileSkillRoutingSection(set.coreSkills, set.projectSkills);
+    const instructionContent = `${rulesSection}\n${routingSection}`;
+    const claudeEnabled = config.providers.enabled.includes('claude');
+    const codexEnabled = config.providers.enabled.includes('codex');
+    if (claudeEnabled)
+        outputs.push({ path: 'CLAUDE.md', content: instructionContent });
+    outputs.push({ path: 'AGENTS.md', content: instructionContent });
+    const allSkills = [...set.coreSkills, ...set.projectSkills];
+    for (const skill of allSkills) {
+        if (claudeEnabled) {
+            outputs.push({ path: `.claude/skills/${skill.name}/SKILL.md`, content: skill.normalizedSkillMd });
+            for (const script of skill.scripts) {
+                outputs.push({
+                    path: `.claude/skills/${skill.name}/${script.relPath}`,
+                    content: script.content.toString('utf8'),
+                    mode: script.mode,
+                });
+            }
+        }
+        if (codexEnabled) {
+            outputs.push({ path: `.agents/skills/${skill.name}/SKILL.md`, content: skill.normalizedSkillMd });
+            for (const script of skill.scripts) {
+                outputs.push({
+                    path: `.agents/skills/${skill.name}/${script.relPath}`,
+                    content: script.content.toString('utf8'),
+                    mode: script.mode,
+                });
+            }
+        }
+    }
+    for (const name of HOOK_NAMES) {
+        outputs.push({ path: `${HOOKS_PATH}/${name}`, content: hookScript(name), mode: HOOK_MODE });
+    }
+    return outputs;
+}
+export async function diskChecksumOf(projectRoot, relPath) {
+    try {
+        const content = await readFile(outputPath(projectRoot, relPath));
+        return computeChecksum(content);
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return undefined;
+        throw err;
+    }
+}
+/**
+ * O modo continua fora do checksum (PRD §3.3) — um hook com conteúdo correto
+ * mas sem bit de execução passaria pela comparação de conteúdo sem ser
+ * notado. `false` também quando o caminho não existe (quem chama já sabe,
+ * via `diskChecksumOf`).
+ */
+export async function diskIsExecutable(projectRoot, relPath) {
+    try {
+        const info = await stat(outputPath(projectRoot, relPath));
+        return (info.mode & 0o111) !== 0;
+    }
+    catch {
+        return false;
+    }
+}
+function refuseR8(paths) {
+    throw new KuyperRefusal({
+        code: 'R8',
+        headline: paths.length === 1
+            ? `${paths[0]} existe e não foi gerado pelo Harness.`
+            : 'Caminhos existem e não foram gerados pelo Harness.',
+        details: [...paths, '', 'Não estão rastreados pelo Git — não há backup.'],
+        route: ['Confira o conteúdo, remova o arquivo se não precisar dele, e rode de novo.'],
+    });
+}
+function refuseR7(paths) {
+    const first = paths[0];
+    throw new KuyperRefusal({
+        code: 'R7',
+        headline: paths.length === 1
+            ? `${first} não corresponde ao que foi gerado antes nem ao que a fonte produz agora.`
+            : 'Saídas não correspondem ao que foi gerado antes nem ao que a fonte produz agora.',
+        details: ['Foi(ram) editado(s) à mão.', '', ...paths],
+        route: [
+            'Para descartar a edição:      git restore <arquivo>',
+            'Ou, se não estiver commitado: pnpm exec kuyper generate --force',
+        ],
+    });
+}
+function refuseCoreR7() {
+    throw new KuyperRefusal({
+        code: 'R7',
+        headline: '.kuyper/core/ não coincide integralmente com o lock anterior nem com o pacote em execução.',
+        details: ['Edição manual, remoção ou transição incompleta.'],
+        route: ['git restore .kuyper/core/', '', 'Ou conclua a igualação ao pacote instalado antes de rodar generate.'],
+    });
+}
+function refuseCoreR8(paths) {
+    throw new KuyperRefusal({
+        code: 'R8',
+        headline: 'Conteúdo desconhecido no namespace do core.',
+        details: paths,
+        route: ['Remova o(s) caminho(s) acima de .kuyper/core/, ou restaure a árvore com Git.'],
+    });
+}
+function refuseR24(current) {
+    throw new KuyperRefusal({
+        code: 'R24',
+        headline: 'O core.hooksPath já aponta para fora de .kuyper/hooks.',
+        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 generate'],
+    });
+}
+function refuseIssues(issues) {
+    throw new KuyperRefusal({
+        code: 'R25',
+        headline: issues.length === 1 ? 'A fonte canônica é inválida.' : `A fonte canônica é inválida (${issues.length} achados).`,
+        details: issues.map((i) => `${i.path}: ${i.message}`),
+        route: ['Corrija a fonte e rode pnpm exec kuyper generate de novo.'],
+    });
+}
+function refuseReferenceIssues(issues) {
+    // um lote pode misturar R9 e R10; a etiqueta segue a maioria dos achados,
+    // e cada linha do detalhe já nomeia o próprio código.
+    const r10Count = issues.filter((i) => i.code === 'R10').length;
+    const code = r10Count > issues.length / 2 ? 'R10' : 'R9';
+    throw new KuyperRefusal({
+        code,
+        headline: issues.length === 1 ? 'Referência de capacidade inválida.' : `Referências de capacidade inválidas (${issues.length} achados).`,
+        details: issues.map((i) => `[${i.code}] ${i.path}: ${i.message}`),
+        route: ['Corrija a fonte e rode pnpm exec kuyper generate de novo.'],
+    });
+}
+function formatSuccessReport(written, alreadyCorrect) {
+    const lines = [`✓  ${written.length} saídas atualizadas, ${alreadyCorrect} já estavam corretas.`];
+    if (written.length > 0) {
+        lines.push('');
+        for (const p of written)
+            lines.push(`   ${p}`);
+    }
+    return lines.join('\n');
+}
+/**
+ * SPEC protocolo-core-lock §3.1.1 — `.kuyper/` sem lock. Bootstrap e
+ * interrupção são o mesmo estado; a base só converge se for estruturalmente
+ * completa E a árvore core inteira já coincidir com o pacote.
+ */
+async function bootstrapGenerate(projectRoot, P, options) {
+    const missing = [];
+    let config;
+    try {
+        config = await readConfig(join(projectRoot, '.kuyper', 'config.yaml'));
+    }
+    catch (err) {
+        if (err instanceof ConfigSchemaError)
+            missing.push(`.kuyper/config.yaml inválido: ${err.issues.join('; ')}`);
+        else
+            missing.push('.kuyper/config.yaml ausente');
+    }
+    const D = await checksumTree(join(projectRoot, '.kuyper', 'core'));
+    if (D.size === 0 || !mapsEqual(D, P)) {
+        missing.push('.kuyper/core/ ausente, ou não coincide inteiramente com o core/ do pacote instalado');
+    }
+    try {
+        await access(join(projectRoot, '.kuyper', 'STATE.md'));
+    }
+    catch {
+        missing.push('.kuyper/STATE.md ausente');
+    }
+    // O conflito de core.hooksPath é ortogonal à completude da base e tem rota
+    // própria e não destrutiva — não deve virar "apague .kuyper/ e reinicie".
+    const hooksPathCurrent = await getCoreHooksPath(projectRoot);
+    const hooksPathState = classifyHooksPath(hooksPathCurrent);
+    if (hooksPathState === 'other') {
+        refuseR24(hooksPathCurrent);
+    }
+    if (missing.length > 0) {
+        throw new KuyperRefusal({
+            headline: 'A base em .kuyper/ está incompleta.',
+            details: missing,
+            route: ['Apague .kuyper/ e execute pnpm exec kuyper init novamente.'],
+        });
+    }
+    const { set, issues } = await loadCapabilities(projectRoot);
+    if (issues.length > 0)
+        refuseIssues(issues);
+    const refIssues = checkReferences(set);
+    if (refIssues.length > 0)
+        refuseReferenceIssues(refIssues);
+    const config2 = config;
+    const desired = buildDesiredOutputs(set, config2);
+    const decisions = new Map();
+    const foreignPaths = [];
+    for (const output of desired) {
+        const disk = await diskChecksumOf(projectRoot, output.path);
+        const newChecksum = computeChecksum(output.content);
+        if (disk !== undefined && disk !== newChecksum) {
+            foreignPaths.push(output.path);
+            continue;
+        }
+        let decision = disk === undefined ? { action: 'write' } : { action: 'already-correct' };
+        if (decision.action === 'already-correct' && output.mode !== undefined && !(await diskIsExecutable(projectRoot, output.path))) {
+            decision = { action: 'write' };
+        }
+        decisions.set(output.path, {
+            decision,
+            newChecksum,
+            content: output.content,
+            mode: output.mode,
+        });
+    }
+    if (foreignPaths.length > 0) {
+        throw new KuyperRefusal({
+            headline: 'A base em .kuyper/ está incompleta.',
+            details: [
+                'Estes caminhos de saída já existem com conteúdo diferente do desejado:',
+                ...foreignPaths,
+            ],
+            route: ['Apague .kuyper/ e execute pnpm exec kuyper init novamente.'],
+        });
+    }
+    const written = [];
+    let alreadyCorrect = 0;
+    for (const [path, entry] of decisions) {
+        if (entry.decision.action === 'write') {
+            await writeFileAtomic(outputPath(projectRoot, path), entry.content, entry.mode !== undefined ? { mode: entry.mode } : {});
+            written.push(path);
+        }
+        else {
+            alreadyCorrect++;
+        }
+    }
+    if (hooksPathState === 'absent') {
+        await setCoreHooksPath(projectRoot, HOOKS_PATH);
+    }
+    const lockEntries = {};
+    for (const [key, checksum] of D)
+        lockEntries[`.kuyper/core/${key}`] = checksum;
+    for (const [path, entry] of decisions)
+        lockEntries[path] = entry.newChecksum;
+    await writeLock(join(projectRoot, '.kuyper', 'generated.lock'), {
+        schemaVersion: 1,
+        harness: await harnessVersion(),
+        entries: lockEntries,
+    });
+    await sweepTempFiles(controlledRoots(projectRoot));
+    if (!options.silent)
+        console.log(formatSuccessReport(written, alreadyCorrect));
+    return { written, removed: [], alreadyCorrect };
+}
+let cachedVersion;
+export async function harnessVersion() {
+    if (cachedVersion)
+        return cachedVersion;
+    const raw = await readFile(join(packageRoot(), 'package.json'), 'utf8');
+    const pkg = JSON.parse(raw);
+    cachedVersion = pkg.version;
+    return cachedVersion;
+}
+async function normalGenerate(projectRoot, lock, P, options) {
+    const L = coreEntriesFromLock(lock.entries);
+    const D = await checksumTree(join(projectRoot, '.kuyper', 'core'));
+    const classification = classifyCore(L, P, D);
+    if (classification.state === 'unknown-path') {
+        refuseCoreR8(classification.paths);
+    }
+    if (classification.state === 'mismatch') {
+        refuseCoreR7();
+    }
+    const coreTransitioned = classification.state === 'transition-complete';
+    const config = await readConfig(join(projectRoot, '.kuyper', 'config.yaml'));
+    const { set, issues } = await loadCapabilities(projectRoot);
+    if (issues.length > 0)
+        refuseIssues(issues);
+    const refIssues = checkReferences(set);
+    if (refIssues.length > 0)
+        refuseReferenceIssues(refIssues);
+    const hooksPathCurrent = await getCoreHooksPath(projectRoot);
+    const hooksPathState = classifyHooksPath(hooksPathCurrent);
+    if (hooksPathState === 'other')
+        refuseR24(hooksPathCurrent);
+    const desired = buildDesiredOutputs(set, config);
+    const desiredPaths = new Set(desired.map((o) => o.path));
+    const editedRefused = [];
+    const foreignRefused = [];
+    const toWrite = [];
+    const alreadyCorrectPaths = [];
+    const newChecksums = {};
+    for (const output of desired) {
+        const disk = await diskChecksumOf(projectRoot, output.path);
+        const newChecksum = computeChecksum(output.content);
+        newChecksums[output.path] = newChecksum;
+        const lockChecksum = lock.entries[output.path];
+        const decision = decideOutput(disk, lockChecksum, newChecksum);
+        if (decision.action === 'refuse-foreign') {
+            foreignRefused.push(output.path);
+        }
+        else if (decision.action === 'refuse-edited') {
+            if (options.force)
+                toWrite.push(output);
+            else
+                editedRefused.push(output.path);
+        }
+        else if (decision.action === 'write') {
+            toWrite.push(output);
+        }
+        else if (output.mode !== undefined && !(await diskIsExecutable(projectRoot, output.path))) {
+            toWrite.push(output);
+        }
+        else {
+            alreadyCorrectPaths.push(output.path);
+        }
+    }
+    const orphanPaths = computeOrphanPaths(lock.entries, desiredPaths);
+    const orphansToRemove = [];
+    for (const path of orphanPaths) {
+        const disk = await diskChecksumOf(projectRoot, path);
+        const decision = decideOrphan(disk, lock.entries[path]);
+        if (decision.action === 'refuse-edited') {
+            if (options.force)
+                orphansToRemove.push(path);
+            else
+                editedRefused.push(path);
+        }
+        else if (decision.action === 'remove') {
+            orphansToRemove.push(path);
+        }
+    }
+    if (foreignRefused.length > 0)
+        refuseR8(foreignRefused);
+    if (editedRefused.length > 0)
+        refuseR7(editedRefused);
+    if (hooksPathState === 'absent') {
+        await setCoreHooksPath(projectRoot, HOOKS_PATH);
+    }
+    const written = [];
+    for (const output of toWrite) {
+        await writeFileAtomic(outputPath(projectRoot, output.path), output.content, output.mode !== undefined ? { mode: output.mode } : {});
+        written.push(output.path);
+    }
+    for (const path of orphansToRemove) {
+        await removeOrphanFile(projectRoot, path);
+    }
+    const coreLockEntries = {};
+    if (coreTransitioned) {
+        for (const [key, checksum] of D)
+            coreLockEntries[`.kuyper/core/${key}`] = checksum;
+    }
+    else {
+        for (const [key, checksum] of L)
+            coreLockEntries[`.kuyper/core/${key}`] = checksum;
+    }
+    const outputLockEntries = {};
+    for (const path of desiredPaths)
+        outputLockEntries[path] = newChecksums[path];
+    await writeLock(join(projectRoot, '.kuyper', 'generated.lock'), {
+        schemaVersion: 1,
+        harness: await harnessVersion(),
+        entries: { ...coreLockEntries, ...outputLockEntries },
+    });
+    await sweepTempFiles(controlledRoots(projectRoot));
+    const alreadyCorrect = alreadyCorrectPaths.length;
+    if (!options.silent)
+        console.log(formatSuccessReport(written, alreadyCorrect));
+    return { written, removed: orphansToRemove, alreadyCorrect };
+}
+export async function generate(options = {}) {
+    const projectRoot = options.projectRoot ?? process.cwd();
+    const lockPath = join(projectRoot, '.kuyper', 'generated.lock');
+    const P = await checksumTree(options.packageCoreDir ?? packageCorePath());
+    const lock = await readLock(lockPath);
+    if (lock === undefined) {
+        return bootstrapGenerate(projectRoot, P, options);
+    }
+    return normalGenerate(projectRoot, lock, P, options);
+}

package/dist/gitPlumbing.js

@@ -0,0 +1,213 @@
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+const execFileAsync = promisify(execFile);
+/**
+ * Wrappers finos do Git — nenhuma função aqui decide nada, mesmo as que
+ * escrevem (`addPaths`, `switchBranch`, os dois `merge*`). As decisões (o
+ * que fazer com o que foi lido, quando mudar de branch) pertencem a quem
+ * chama: `gateRunner.ts`, `hookBehavior.ts`, `init.ts`, `integrate.ts`.
+ */
+export async function isGitRepo(cwd) {
+    try {
+        await execFileAsync('git', ['rev-parse', '--is-inside-work-tree'], { cwd });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * `symbolic-ref`, não `rev-parse --abbrev-ref HEAD`: o segundo falha num
+ * repositório sem nenhum commit ainda, porque HEAD não resolve pra revisão
+ * nenhuma — o estado normal logo depois de um `git init` (achado do B5).
+ */
+export async function currentBranch(cwd) {
+    try {
+        const { stdout } = await execFileAsync('git', ['symbolic-ref', '--short', 'HEAD'], { cwd });
+        return stdout.trim();
+    }
+    catch {
+        return undefined;
+    }
+}
+/** `undefined` quando HEAD não resolve (repositório sem nenhum commit). */
+export async function headSha(cwd) {
+    try {
+        const { stdout } = await execFileAsync('git', ['rev-parse', 'HEAD'], { cwd });
+        return stdout.trim();
+    }
+    catch {
+        return undefined;
+    }
+}
+export async function statusPorcelain(cwd) {
+    const { stdout } = await execFileAsync('git', ['status', '--porcelain'], { cwd });
+    return stdout;
+}
+function splitLines(text) {
+    return text.split('\n').filter((l) => l.trim().length > 0);
+}
+/**
+ * Os caminhos de `git status --porcelain` — staged, não staged e não
+ * rastreados juntos, sem distinguir categoria. "Árvore suja" pra um comando
+ * como `integrate` é qualquer coisa não commitada; diferente da "fotografia
+ * dupla" de `unstagedAndUntrackedPaths`, que existe só pra saber o que **um
+ * gate** tocou durante a convergência do `pre-commit`.
+ */
+export async function dirtyPaths(cwd) {
+    const status = await statusPorcelain(cwd);
+    return splitLines(status).map((line) => line.slice(3).trim());
+}
+/** `git merge-base --is-ancestor` — `ancestor` alcança `descendant`? Verdadeiro também quando são o mesmo commit. */
+export async function isAncestor(cwd, ancestor, descendant) {
+    try {
+        await execFileAsync('git', ['merge-base', '--is-ancestor', ancestor, descendant], { cwd });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** O SHA que uma branch **local** aponta agora, independente de qual está em checkout. `undefined` se a branch não existe. */
+export async function branchSha(cwd, branch) {
+    return resolveRef(cwd, `refs/heads/${branch}`);
+}
+/**
+ * `git rev-parse <ref>` cru, sem assumir `refs/heads/` — o que `branchSha`
+ * assume, e por isso não serve pra um ref de tracking remoto como
+ * `origin/main` (vive em `refs/remotes/`, não em `refs/heads/`).
+ * `undefined` se `ref` não resolve.
+ */
+export async function resolveRef(cwd, ref) {
+    try {
+        const { stdout } = await execFileAsync('git', ['rev-parse', ref], { cwd });
+        return stdout.trim();
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Quantos commits `descendant` tem à frente de `ancestor` — `git rev-list --count`. */
+export async function commitsAhead(cwd, ancestor, descendant) {
+    return totalCommits(cwd, `${ancestor}..${descendant}`);
+}
+/**
+ * `git rev-list --count <rangeOrRef>` cru — aceita tanto um único ref (conta
+ * tudo alcançável dali, o caso da primeira publicação, sem `origin/main`
+ * pra formar um intervalo) quanto um intervalo `A..B`. Diferente de
+ * `diffShortstat`/`diffNameStatus`/`readFileAtRef`, que aceitam objetos de
+ * árvore direto, `rev-list` exige commit-ish — por isso a árvore vazia
+ * nunca entra aqui como extremidade de intervalo.
+ */
+export async function totalCommits(cwd, rangeOrRef) {
+    const { stdout } = await execFileAsync('git', ['rev-list', '--count', rangeOrRef], { cwd });
+    return Number(stdout.trim());
+}
+/** Caminhos que mudaram entre duas referências, restritos a `pathspecs`. */
+export async function changedPaths(cwd, refA, refB, pathspecs) {
+    const { stdout } = await execFileAsync('git', ['diff', '--name-only', refA, refB, '--', ...pathspecs], { cwd });
+    return splitLines(stdout);
+}
+export async function switchBranch(cwd, branch) {
+    await execFileAsync('git', ['switch', branch], { cwd });
+}
+/** `git merge --no-ff` — sempre cria um commit de merge, mesmo quando um fast-forward bastaria. */
+export async function mergeNoFF(cwd, branch) {
+    await execFileAsync('git', ['merge', '--no-ff', branch, '-m', `Merge branch '${branch}'`], { cwd });
+}
+/** `git merge --ff-only` — falha (lança) se não for um fast-forward puro. */
+export async function mergeFastForward(cwd, branch) {
+    await execFileAsync('git', ['merge', '--ff-only', branch], { cwd });
+}
+/**
+ * A "fotografia dupla" do PRD §4.1: `git diff` da árvore de trabalho contra
+ * o índice (não staged) mais a lista de não rastreados. É contra isto que
+ * `gateRunner.ts` compara antes/depois de rodar os gates, pra saber
+ * exatamente o que cada volta tocou — nunca `git status`, que descreve
+ * categoria, não conteúdo.
+ */
+export async function unstagedAndUntrackedPaths(cwd) {
+    const [diffResult, untrackedResult] = await Promise.all([
+        execFileAsync('git', ['diff', '--name-only'], { cwd }),
+        execFileAsync('git', ['ls-files', '--others', '--exclude-standard'], { cwd }),
+    ]);
+    return new Set([...splitLines(diffResult.stdout), ...splitLines(untrackedResult.stdout)]);
+}
+/** `git add --`, nunca `-A` — só os caminhos exatos que o gate tocou (PRD §4.1). */
+export async function addPaths(cwd, paths) {
+    if (paths.length === 0)
+        return;
+    await execFileAsync('git', ['add', '--', ...paths], { cwd });
+}
+/**
+ * O hash de conteúdo (blob) de um arquivo no disco, sem precisar dele estar
+ * staged. `undefined` quando o caminho não existe mais — um gate pode
+ * apagar um arquivo, e ausência também conta como "mudou" pra quem compara.
+ */
+export async function hashFile(cwd, path) {
+    try {
+        const { stdout } = await execFileAsync('git', ['hash-object', path], { cwd });
+        return stdout.trim();
+    }
+    catch {
+        return undefined;
+    }
+}
+/** `hashFile` para vários caminhos de uma vez, em paralelo. */
+export async function hashFiles(cwd, paths) {
+    const list = [...paths];
+    const hashes = await Promise.all(list.map((p) => hashFile(cwd, p)));
+    return new Map(list.map((p, i) => [p, hashes[i]]));
+}
+/** `true` se `ref` resolve pra algo — usado pra "origin/main existe?" sem lançar. */
+export async function refExists(cwd, ref) {
+    try {
+        await execFileAsync('git', ['rev-parse', '--verify', '--quiet', ref], { cwd });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** O conteúdo de um arquivo num ref específico (`git show <ref>:<path>`). `undefined` se não existe ali. */
+export async function readFileAtRef(cwd, ref, path) {
+    try {
+        const { stdout } = await execFileAsync('git', ['show', `${ref}:${path}`], { cwd });
+        return stdout;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** `git diff --shortstat` entre duas árvores, parseado. Zeros quando não há diferença. */
+export async function diffShortstat(cwd, from, to) {
+    const { stdout } = await execFileAsync('git', ['diff', '--shortstat', from, to], { cwd });
+    const files = /(\d+) files? changed/.exec(stdout);
+    const insertions = /(\d+) insertions?\(\+\)/.exec(stdout);
+    const deletions = /(\d+) deletions?\(-\)/.exec(stdout);
+    return {
+        files: files ? Number(files[1]) : 0,
+        insertions: insertions ? Number(insertions[1]) : 0,
+        deletions: deletions ? Number(deletions[1]) : 0,
+    };
+}
+/** `git diff --name-status` entre duas árvores. Renomes/cópias (`R*`/`C*`) contam como `M` — não há decisão de renome neste nível. */
+export async function diffNameStatus(cwd, from, to) {
+    const { stdout } = await execFileAsync('git', ['diff', '--name-status', from, to], { cwd });
+    return splitLines(stdout).map((line) => {
+        const [rawStatus, ...rest] = line.split('\t');
+        const status = (rawStatus ?? '').charAt(0);
+        const normalized = status === 'A' ? 'A' : status === 'D' ? 'D' : 'M';
+        return { status: normalized, path: rest[rest.length - 1] ?? '' };
+    });
+}
+/** A data (AAAA-MM-DD) do commit mais antigo em `range` — o "desde quando" do resumo do `publish`. `undefined` se `range` não tem commit nenhum. */
+export async function oldestCommitDate(cwd, range) {
+    const { stdout } = await execFileAsync('git', ['log', '--format=%ad', '--date=short', range], { cwd });
+    const lines = splitLines(stdout);
+    return lines.length > 0 ? lines[lines.length - 1] : undefined;
+}
+/** `git push -u <remote> <branch>` — o único ponto do produto que fala com a rede. */
+export async function push(cwd, remote, branch) {
+    await execFileAsync('git', ['push', '-u', remote, branch], { cwd });
+}