@kuyper/harness 0.1.0

package/dist/integrate.js

@@ -0,0 +1,192 @@
+import { join } from 'node:path';
+import { readConfig } from './config.js';
+import { KuyperRefusal } from './errors.js';
+import { gatesForStage, runExact } from './gateRunner.js';
+import { branchSha, changedPaths, commitsAhead, currentBranch, dirtyPaths, headSha, isAncestor, isGitRepo, mergeFastForward, mergeNoFF, switchBranch, } from './gitPlumbing.js';
+import { validate } from './validate.js';
+/**
+ * Onde procurar "a fonte que mudou" pra R18 (PRD §3.4). Não é o lock — a
+ * ADR `generated-lock` decide, de propósito, não guardar checksum de fonte
+ * (`.kuyper/project/**` fica fora por natureza). `integrate` já compara
+ * `dev` contra `main`; é essa comparação, via Git, que nomeia a fonte, sem
+ * estado novo nenhum.
+ */
+const SOURCE_PATHS = ['.kuyper/core', '.kuyper/project', '.kuyper/config.yaml'];
+/**
+ * Sem código: R2 ("não é repositório Git") é escopo do `init` na tabela do
+ * §5. `.kuyper/` existir sem `.git` não deveria acontecer em uso normal (só
+ * o `init` cria `.kuyper/`, e exige um repositório Git pra isso) — mas sem
+ * esta checagem, o primeiro comando Git de `integrate` (`git status
+ * --porcelain`) falha cru, com stack trace de Git, não uma recusa do
+ * produto.
+ */
+function refuseNotGitRepo() {
+    throw new KuyperRefusal({
+        headline: 'Este diretório não é um repositório Git.',
+        details: ['.kuyper/ existe, mas não há um repositório Git aqui — o integrate precisa de um pra funcionar.'],
+    });
+}
+function refuseR15() {
+    throw new KuyperRefusal({
+        code: 'R15',
+        headline: 'Você está na main.',
+        details: ['O integrate leva a dev para a main; rodando dele mesmo não há o que levar.'],
+        route: ['git switch dev'],
+    });
+}
+/**
+ * Sem código: a PRD só nomeia a R15 pra "você está na main" — uma terceira
+ * branch (ou nenhuma, HEAD destacada) não tem recusa numerada. Mesmo padrão
+ * do B6 pras precondições do `pre-push` que a R23 não cobre.
+ */
+function refuseNotOnDev(branch) {
+    throw new KuyperRefusal({
+        headline: branch === undefined ? 'Não foi possível determinar a branch atual.' : `A branch atual é "${branch}", não a dev.`,
+        details: ['O integrate opera a partir da dev — é de lá que ele leva o trabalho para a main.'],
+        route: ['git switch dev'],
+    });
+}
+function refuseR14(paths) {
+    throw new KuyperRefusal({
+        code: 'R14',
+        headline: 'A árvore de trabalho está suja.',
+        details: [...paths, '', 'Os gates precisam rodar sobre o que será integrado, e não sobre alterações que ficariam de fora.'],
+        route: ['git add -A && git commit'],
+    });
+}
+function refuseR16() {
+    throw new KuyperRefusal({
+        code: 'R16',
+        headline: 'A main tem commits que a dev não tem.',
+        details: ['Integrar agora criaria um merge com conflito no meio do seu fluxo.'],
+        route: ['git switch dev && git merge main'],
+    });
+}
+/** Sem rota: a PRD mostra este exemplo sem bloco de rota — não há o que consertar, só nada a fazer. */
+function refuseR26() {
+    throw new KuyperRefusal({
+        code: 'R26',
+        headline: 'Não há nada novo para integrar.',
+        details: ['dev e main apontam para o mesmo commit — não existe merge a criar.'],
+    });
+}
+function refuseR18(report, changedSources) {
+    if (report.code === 1) {
+        throw new KuyperRefusal({
+            code: 'R18',
+            headline: 'kuyper validate ficou inconclusivo.',
+            details: [report.reason],
+            // §3.4: "a rota não é regenerar — regenerar sobre um estado ilegível
+            // não conserta nada." A rota ainda é obrigatória (§3) — aponta pra
+            // como confirmar a correção, não pra qual correção fazer.
+            route: ['Corrija o que o motivo acima descreve.', 'pnpm exec kuyper validate', 'pnpm exec kuyper integrate'],
+        });
+    }
+    const details = [...report.findings];
+    if (changedSources.length > 0) {
+        details.push('', `fonte alterada: ${changedSources.join(', ')}`);
+    }
+    details.push('', 'Faltou regenerar. A main não foi tocada.');
+    throw new KuyperRefusal({
+        code: 'R18',
+        headline: 'A geração está divergente.',
+        details,
+        route: ['pnpm exec kuyper generate', 'git add -A && git commit', 'pnpm exec kuyper integrate'],
+    });
+}
+function refuseGateFailed(gate, output) {
+    throw new KuyperRefusal({
+        code: 'R19',
+        headline: `O gate ${gate} falhou.`,
+        details: [...output.split('\n').filter((l) => l.length > 0), '', 'Conserte na dev e rode de novo. A main não foi tocada.'],
+        route: ['Corrija o que o gate acusou e rode pnpm exec kuyper integrate de novo.'],
+    });
+}
+function refuseGateWrote(paths) {
+    throw new KuyperRefusal({
+        code: 'R20',
+        headline: paths.length === 1 ? 'Um gate alterou um arquivo durante a execução.' : 'Um gate alterou arquivos durante a execução.',
+        details: [...paths, '', 'Em integrate a árvore precisa continuar limpa. Commite a correção na dev e rode de novo.'],
+        route: ['git add -- <arquivos acima> && git commit', 'pnpm exec kuyper integrate'],
+    });
+}
+function formatSuccess(mergeSha, commitCount, gates) {
+    const lines = [commitCount === 1 ? '✓  1 commit integrado na main.' : `✓  ${commitCount} commits integrados na main.`, ''];
+    if (gates.length > 0) {
+        lines.push(`   ${gates.map((g) => `${g.gate}  ${(g.durationMs / 1000).toFixed(1)}s`).join('     ')}`, '');
+    }
+    lines.push(`   merge  ${mergeSha.slice(0, 7)}  "Merge branch 'dev'"`);
+    lines.push('   dev    avançada até a main');
+    return lines.join('\n');
+}
+/**
+ * Sucesso parcial declarado, nunca sucesso (§3.4): o merge na main já
+ * aconteceu quando isto imprime — só o fast-forward de volta pra dev falhou,
+ * quase sempre porque a dev avançou durante os gates. Marcador `⚠`, não `✗`:
+ * não é recusa, é aviso — o trabalho não se perdeu.
+ */
+function formatPartial(mergeSha, devSha) {
+    return [
+        '⚠  O merge foi criado, mas a dev não avançou.',
+        '',
+        `   main  ${mergeSha.slice(0, 7)}   ← correta, com o seu trabalho integrado`,
+        `   dev   ${devSha.slice(0, 7)}   ← uma posição atrás`,
+        '',
+        '   Nada se perdeu. Para concluir:',
+        '',
+        '       git switch dev && git merge --ff-only main',
+    ].join('\n');
+}
+/**
+ * `kuyper integrate` (PRD §3.4). Reaproveita `runExact` (B6) inteiro — mesmo
+ * padrão do `validate` reaproveitando o `generate` no B3. As quatro
+ * primeiras recusas são de precondição, antes de qualquer gate rodar; a
+ * main só é tocada depois de R14/R15(ou branch)/R16/R26/R18/R19/R20 todas
+ * passarem.
+ */
+export async function integrate(options = {}) {
+    const projectRoot = options.projectRoot ?? process.cwd();
+    if (!(await isGitRepo(projectRoot)))
+        refuseNotGitRepo();
+    const dirty = await dirtyPaths(projectRoot);
+    if (dirty.length > 0)
+        refuseR14(dirty);
+    const branch = await currentBranch(projectRoot);
+    if (branch === 'main')
+        refuseR15();
+    if (branch !== 'dev')
+        refuseNotOnDev(branch);
+    const mainIsAncestorOfDev = await isAncestor(projectRoot, 'main', 'dev');
+    if (!mainIsAncestorOfDev)
+        refuseR16();
+    const mainSha = await branchSha(projectRoot, 'main');
+    const devSha = await branchSha(projectRoot, 'dev');
+    if (mainSha === devSha)
+        refuseR26();
+    const report = await validate({ projectRoot, silent: true });
+    if (report.code !== 0) {
+        const changedSources = report.code === 2 ? await changedPaths(projectRoot, 'main', 'dev', SOURCE_PATHS) : [];
+        refuseR18(report, changedSources);
+    }
+    const config = await readConfig(join(projectRoot, '.kuyper', 'config.yaml'));
+    const outcome = await runExact(gatesForStage(config.gates, 'publish'), projectRoot);
+    if (outcome.kind === 'gate-failed')
+        refuseGateFailed(outcome.gate, outcome.output);
+    if (outcome.kind === 'wrote')
+        refuseGateWrote(outcome.paths);
+    const commitCount = await commitsAhead(projectRoot, 'main', 'dev');
+    await switchBranch(projectRoot, 'main');
+    await mergeNoFF(projectRoot, 'dev');
+    const mergeSha = (await headSha(projectRoot));
+    try {
+        await switchBranch(projectRoot, 'dev');
+        await mergeFastForward(projectRoot, 'main');
+    }
+    catch {
+        const currentDevSha = (await branchSha(projectRoot, 'dev'));
+        console.log(formatPartial(mergeSha, currentDevSha));
+        return { code: 1, mergeSha, devSha: currentDevSha };
+    }
+    console.log(formatSuccess(mergeSha, commitCount, outcome.results));
+    return { code: 0, mergeSha, gates: outcome.results };
+}

package/dist/lock.js

@@ -0,0 +1,108 @@
+import { createHash } from 'node:crypto';
+import { readFile } from 'node:fs/promises';
+import { writeFileAtomic } from './atomicWrite.js';
+/**
+ * Um lock corrompido ou adulterado não pode fazer o Harness tocar em nada
+ * fora das raízes gerenciadas (PRD §4.1). Caminho fora delas é recusa, não
+ * aviso — checado na leitura, antes de qualquer entrada virar candidato a
+ * escrita.
+ */
+const MANAGED_ROOT_PREFIXES = ['.kuyper/', '.claude/', '.agents/'];
+const MANAGED_ROOT_FILES = new Set(['CLAUDE.md', 'AGENTS.md']);
+export function isManagedLockPath(path) {
+    if (MANAGED_ROOT_FILES.has(path))
+        return true;
+    return MANAGED_ROOT_PREFIXES.some((prefix) => path.startsWith(prefix));
+}
+/** Nome de capacidade: minúsculas, dígitos e hífen, sem hífen inicial/final/duplicado. */
+export const CAPABILITY_NAME_PATTERN = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+export function isValidCapabilityName(name) {
+    return CAPABILITY_NAME_PATTERN.test(name);
+}
+/** Só `\r\n` → `\n`. É a única normalização que o produto decidiu (ADR generated-lock, decisão 3). */
+export function normalizeLineEndings(text) {
+    return text.replace(/\r\n/g, '\n');
+}
+export function computeChecksum(content) {
+    const text = typeof content === 'string' ? content : content.toString('utf8');
+    const normalized = normalizeLineEndings(text);
+    const hex = createHash('sha256').update(normalized, 'utf8').digest('hex');
+    return `sha256:${hex}`;
+}
+/**
+ * Serializa o lock: chaves ordenadas por caminho, indentação de dois espaços,
+ * uma entrada por linha, newline final. Duas execuções sobre a mesma fonte
+ * produzem bytes idênticos (A4c) — não depende da ordem de inserção.
+ */
+export function serializeLock(lock) {
+    const sortedEntries = {};
+    for (const key of Object.keys(lock.entries).sort()) {
+        sortedEntries[key] = lock.entries[key];
+    }
+    const ordered = {
+        schemaVersion: lock.schemaVersion,
+        harness: lock.harness,
+        entries: sortedEntries,
+    };
+    return `${JSON.stringify(ordered, null, 2)}\n`;
+}
+export class LockParseError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'LockParseError';
+    }
+}
+export function parseLock(text) {
+    let data;
+    try {
+        data = JSON.parse(text);
+    }
+    catch (err) {
+        throw new LockParseError(`generated.lock não é JSON válido: ${err.message}`);
+    }
+    if (typeof data !== 'object' || data === null || Array.isArray(data)) {
+        throw new LockParseError('generated.lock não é um objeto');
+    }
+    const obj = data;
+    if (obj['schemaVersion'] !== 1) {
+        throw new LockParseError(`generated.lock: schemaVersion inesperado (${JSON.stringify(obj['schemaVersion'])})`);
+    }
+    if (typeof obj['harness'] !== 'string') {
+        throw new LockParseError('generated.lock: campo harness ausente ou inválido');
+    }
+    const entriesRaw = obj['entries'];
+    if (typeof entriesRaw !== 'object' || entriesRaw === null || Array.isArray(entriesRaw)) {
+        throw new LockParseError('generated.lock: campo entries ausente ou inválido');
+    }
+    const entries = {};
+    const unmanaged = [];
+    for (const [key, value] of Object.entries(entriesRaw)) {
+        if (typeof value !== 'string') {
+            throw new LockParseError(`generated.lock: entrada inválida para ${key}`);
+        }
+        if (!isManagedLockPath(key))
+            unmanaged.push(key);
+        entries[key] = value;
+    }
+    if (unmanaged.length > 0) {
+        throw new LockParseError(`generated.lock: caminho fora das raízes gerenciadas: ${unmanaged.join(', ')}`);
+    }
+    return { schemaVersion: 1, harness: obj['harness'], entries };
+}
+/** `undefined` quando o lock não existe — o estado de bootstrap da SPEC §3.1.1. */
+export async function readLock(lockPath) {
+    let raw;
+    try {
+        raw = await readFile(lockPath, 'utf8');
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return undefined;
+        throw err;
+    }
+    return parseLock(raw);
+}
+/** Grava o lock pelo mesmo escritor atômico das demais saídas — ele também é `.kuyper-tmp` + rename. */
+export async function writeLock(lockPath, lock) {
+    await writeFileAtomic(lockPath, serializeLock(lock));
+}

package/dist/outputPlan.js

@@ -0,0 +1,61 @@
+import { dirname, join, resolve } from 'node:path';
+import { readdir, rm, rmdir } from 'node:fs/promises';
+export function decideOutput(diskChecksum, lockChecksum, newChecksum) {
+    if (diskChecksum === undefined) {
+        return { action: 'write' };
+    }
+    if (diskChecksum === lockChecksum) {
+        return newChecksum === diskChecksum ? { action: 'already-correct' } : { action: 'write' };
+    }
+    if (diskChecksum === newChecksum) {
+        return { action: 'already-correct' };
+    }
+    if (lockChecksum === undefined) {
+        return { action: 'refuse-foreign' };
+    }
+    return { action: 'refuse-edited' };
+}
+/**
+ * saídas órfãs = entradas de saída do lock anterior − caminhos de saída
+ * desejados (PRD §3.2). Entradas `.kuyper/core/**` nunca participam — sua
+ * remoção pertence só ao `update`.
+ */
+export function computeOrphanPaths(lockEntries, desiredPaths) {
+    return Object.keys(lockEntries)
+        .filter((p) => !p.startsWith('.kuyper/core/'))
+        .filter((p) => !desiredPaths.has(p));
+}
+export function decideOrphan(diskChecksum, lockChecksum) {
+    if (diskChecksum === undefined)
+        return { action: 'already-gone' };
+    if (diskChecksum === lockChecksum)
+        return { action: 'remove' };
+    return { action: 'refuse-edited' };
+}
+/**
+ * Remove o arquivo e sobe removendo diretórios vazios até o primeiro
+ * não-vazio ou até a raiz do projeto — "não é `rm -rf`" (PRD §3.2). Um
+ * arquivo alheio deixado numa pasta de skill impede a subida naquele ponto.
+ */
+export async function removeOrphanFile(projectRoot, relPath) {
+    const root = resolve(projectRoot);
+    const absPath = resolve(root, relPath);
+    await rm(absPath, { force: true });
+    let dir = dirname(absPath);
+    while (dir !== root && dir.startsWith(`${root}/`)) {
+        let entries;
+        try {
+            entries = await readdir(dir);
+        }
+        catch {
+            break;
+        }
+        if (entries.length > 0)
+            break;
+        await rmdir(dir);
+        dir = dirname(dir);
+    }
+}
+export function outputPath(projectRoot, relPath) {
+    return join(projectRoot, relPath);
+}

package/dist/paths.js

@@ -0,0 +1,22 @@
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+/**
+ * Resolvido a partir DESTE módulo — nunca por `process.cwd()`, nunca
+ * procurando `@kuyper/harness` a partir do projeto. É a mesma regra do
+ * relançamento do binário no `update`: a instalação que responde é sempre a
+ * que está rodando, nunca a que for encontrada (ADR empacotamento-do-core,
+ * decisão 2).
+ *
+ * Isto vale tanto compilado (`dist/paths.js`, um nível abaixo da raiz do
+ * pacote) quanto em desenvolvimento (`src/paths.ts`, um nível abaixo da raiz
+ * do repositório) — a mesma profundidade nos dois layouts.
+ */
+const moduleDir = dirname(fileURLToPath(import.meta.url));
+/** Raiz do pacote em execução: onde ficam `package.json`, `dist/` e `core/`. */
+export function packageRoot() {
+    return join(moduleDir, '..');
+}
+/** `core/` do pacote em execução — a origem de distribuição do `core:` (§4.2). */
+export function packageCorePath() {
+    return join(packageRoot(), 'core');
+}

package/dist/project.js

@@ -0,0 +1,29 @@
+import { access } from 'node:fs/promises';
+import { join } from 'node:path';
+import { KuyperRefusal } from './errors.js';
+/**
+ * A checagem comum a "todos, menos init" (R1). Todo comando que a chama
+ * herda a mesma recusa — é o que o BUILD B1 chama de "uma rota já
+ * implementada prova a recusa comum".
+ */
+export async function requireProject(cwd = process.cwd()) {
+    const kuyperDir = join(cwd, '.kuyper');
+    try {
+        await access(kuyperDir);
+    }
+    catch {
+        throw new KuyperRefusal({
+            code: 'R1',
+            headline: 'Este diretório não é um projeto Kuyper.',
+            details: ['Não existe .kuyper/ aqui.'],
+            route: [
+                'Se for iniciar um projeto novo:',
+                '    pnpm exec kuyper init',
+                '',
+                'Se .kuyper/ deveria existir, confira se você está na raiz do',
+                'repositório.',
+            ],
+        });
+    }
+    return kuyperDir;
+}

package/dist/publish.js

@@ -0,0 +1,207 @@
+import { join } from 'node:path';
+import { parseConfig, readConfig } from './config.js';
+import { KuyperRefusal } from './errors.js';
+import { gatesForStage, runExact } from './gateRunner.js';
+import { commitsAhead, currentBranch, diffNameStatus, diffShortstat, dirtyPaths, headSha, isGitRepo, oldestCommitDate, push, readFileAtRef, refExists, resolveRef, switchBranch, totalCommits, } from './gitPlumbing.js';
+import { buildDesiredOutputs, loadCapabilities } from './generate.js';
+import { validate } from './validate.js';
+/** O hash universal da árvore vazia — o "antes" da primeira publicação, sem nenhum estado novo. */
+const EMPTY_TREE = '4b825dc642cb6eb9a060e54bf8d69288fbee4904';
+const TEST_PATH_PATTERN = /(\.test\.|\.spec\.|\/tests?\/|\/__tests__\/)/;
+function refuseR14(paths) {
+    throw new KuyperRefusal({
+        code: 'R14',
+        headline: 'A árvore de trabalho está suja.',
+        details: [...paths, '', 'Os gates precisam rodar sobre o que será publicado, e não sobre alterações que ficariam de fora.'],
+        route: ['git add -A && git commit'],
+    });
+}
+/** Sem rota: o exemplo da PRD mostra este caso sem bloco de rota — não há o que consertar. */
+function refuseR17(remoteSha) {
+    throw new KuyperRefusal({
+        code: 'R17',
+        headline: 'Não há nada novo para publicar.',
+        details: [`origin/main já está em ${remoteSha.slice(0, 7)}.`],
+    });
+}
+function refuseR18(report) {
+    if (report.code === 1) {
+        throw new KuyperRefusal({
+            code: 'R18',
+            headline: 'kuyper validate ficou inconclusivo.',
+            details: [report.reason],
+            route: ['Corrija o que o motivo acima descreve.', 'pnpm exec kuyper validate', 'pnpm exec kuyper publish'],
+        });
+    }
+    throw new KuyperRefusal({
+        code: 'R18',
+        headline: 'A geração está divergente.',
+        details: [...report.findings, '', 'Faltou regenerar.'],
+        route: ['pnpm exec kuyper generate', 'git add -A && git commit', 'pnpm exec kuyper publish'],
+    });
+}
+/**
+ * O gate roda de novo sobre a `main` porque código commitado à mão nunca
+ * passou por um `integrate` — a mensagem diz isso (§3.5), não é
+ * redundância burocrática.
+ */
+function refuseGateFailed(gate, output) {
+    throw new KuyperRefusal({
+        code: 'R19',
+        headline: `O gate ${gate} falhou.`,
+        details: [
+            ...output.split('\n').filter((l) => l.length > 0),
+            '',
+            'Este código nunca passou por um integrate — foi commitado direto na main.',
+            'É a única checagem antes de sair da máquina, e ela reprovou.',
+        ],
+        route: ['Conserte, e rode de novo. Nada saiu daqui.'],
+    });
+}
+function refuseGateWrote(paths) {
+    throw new KuyperRefusal({
+        code: 'R20',
+        headline: paths.length === 1 ? 'Um gate alterou um arquivo durante a execução.' : 'Um gate alterou arquivos durante a execução.',
+        details: [...paths, '', 'Em publish a árvore precisa continuar limpa. Nada saiu daqui.'],
+        route: ['git add -- <arquivos acima> && git commit', 'pnpm exec kuyper publish'],
+    });
+}
+function parsePackageDependencyKeys(text) {
+    if (text === undefined)
+        return new Set();
+    try {
+        const data = JSON.parse(text);
+        return new Set([...Object.keys(data.dependencies ?? {}), ...Object.keys(data.devDependencies ?? {})]);
+    }
+    catch {
+        return new Set();
+    }
+}
+function gateSignature(gate) {
+    return `${gate.command}\n${gate.stages.slice().sort().join(',')}`;
+}
+function changedGateIds(oldGates, newGates) {
+    const oldById = new Map(oldGates.map((g) => [g.id, g]));
+    const newById = new Map(newGates.map((g) => [g.id, g]));
+    const ids = new Set([...oldById.keys(), ...newById.keys()]);
+    const changed = [];
+    for (const id of ids) {
+        const before = oldById.get(id);
+        const after = newById.get(id);
+        if (before === undefined || after === undefined || gateSignature(before) !== gateSignature(after)) {
+            changed.push(id);
+        }
+    }
+    return changed.sort();
+}
+/**
+ * Os quatro "sinais que merecem atenção" do §3.5 — nenhum tem código A/R,
+ * mecanismo de detecção é decisão de implementação (ver o plano do B8).
+ * `fromRef` é `undefined` na primeira publicação: "dependência nova" e
+ * "gate alterado" ficam sem "antes" pra comparar e não são calculados;
+ * "saída gerada" e "testes removidos" não precisam de um "antes".
+ */
+async function collectSignals(projectRoot, fromRef, toRef, config) {
+    const diffFrom = fromRef ?? EMPTY_TREE;
+    const entries = await diffNameStatus(projectRoot, diffFrom, toRef);
+    const { set } = await loadCapabilities(projectRoot);
+    const desired = buildDesiredOutputs(set, config);
+    const desiredPaths = new Set(desired.map((o) => o.path));
+    const generatedOutputs = entries.filter((e) => desiredPaths.has(e.path)).map((e) => e.path);
+    const removedTests = entries.filter((e) => e.status === 'D' && TEST_PATH_PATTERN.test(e.path)).map((e) => e.path);
+    let newDependencies = [];
+    let changedGates = [];
+    if (fromRef !== undefined) {
+        const [oldPkg, newPkg] = await Promise.all([
+            readFileAtRef(projectRoot, fromRef, 'package.json'),
+            readFileAtRef(projectRoot, toRef, 'package.json'),
+        ]);
+        const oldDeps = parsePackageDependencyKeys(oldPkg);
+        const newDeps = parsePackageDependencyKeys(newPkg);
+        newDependencies = [...newDeps].filter((d) => !oldDeps.has(d)).sort();
+        const oldConfigText = await readFileAtRef(projectRoot, fromRef, '.kuyper/config.yaml');
+        if (oldConfigText !== undefined) {
+            try {
+                const oldConfig = parseConfig(oldConfigText);
+                changedGates = changedGateIds(oldConfig.gates, config.gates);
+            }
+            catch {
+                // config antigo malformado: sinal best-effort, não bloqueia o publish.
+            }
+        }
+    }
+    return { generatedOutputs, newDependencies, removedTests, changedGates };
+}
+function formatSummary(commitCount, since, stat, gates, signals) {
+    const lines = [
+        `✓  Pronto para publicar: ${commitCount} commit${commitCount === 1 ? '' : 's'}${since !== undefined ? ` desde ${since}` : ''}.`,
+        '',
+        `   ${stat.files} arquivo${stat.files === 1 ? '' : 's'}   +${stat.insertions}  −${stat.deletions}`,
+    ];
+    if (gates.length > 0) {
+        lines.push('', `   ${gates.map((g) => `${g.gate}  ${(g.durationMs / 1000).toFixed(1)}s`).join('     ')}`);
+    }
+    const warnings = [];
+    if (signals.removedTests.length > 0)
+        warnings.push(`   ⚠  testes removidos: ${signals.removedTests.join(', ')}`);
+    if (signals.changedGates.length > 0)
+        warnings.push(`   ⚠  gate alterado: ${signals.changedGates.join(', ')}`);
+    if (signals.generatedOutputs.length > 0)
+        warnings.push(`   ⚠  saída gerada no conjunto: ${signals.generatedOutputs.join(', ')}`);
+    if (signals.newDependencies.length > 0)
+        warnings.push(`   ⚠  dependência nova: ${signals.newDependencies.join(', ')}`);
+    if (warnings.length > 0)
+        lines.push('', ...warnings);
+    lines.push('', '   → origin/main');
+    return lines.join('\n');
+}
+/**
+ * `kuyper publish` (PRD §3.5). O único comando que fala com o remoto.
+ * Guarda a branch de origem e só volta pra ela no sucesso completo —
+ * R14/R17 (precondição, passo 1) nunca trocam de branch; R18/R19/R20
+ * acontecem já na `main` e não restauram, do mesmo jeito que o
+ * equivalente manual pararia no meio sem `trap`/`finally`.
+ */
+export async function publish(options = {}) {
+    const projectRoot = options.projectRoot ?? process.cwd();
+    if (!(await isGitRepo(projectRoot))) {
+        throw new KuyperRefusal({ headline: 'Este diretório não é um repositório Git.' });
+    }
+    const dirty = await dirtyPaths(projectRoot);
+    if (dirty.length > 0)
+        refuseR14(dirty);
+    const hasRemote = await refExists(projectRoot, 'origin/main');
+    if (hasRemote) {
+        const ahead = await commitsAhead(projectRoot, 'origin/main', 'main');
+        if (ahead === 0) {
+            const remoteSha = (await resolveRef(projectRoot, 'origin/main'));
+            refuseR17(remoteSha);
+        }
+    }
+    const originalBranch = await currentBranch(projectRoot);
+    if (originalBranch !== 'main') {
+        await switchBranch(projectRoot, 'main');
+    }
+    const report = await validate({ projectRoot, silent: true });
+    if (report.code !== 0)
+        refuseR18(report);
+    const config = await readConfig(join(projectRoot, '.kuyper', 'config.yaml'));
+    const outcome = await runExact(gatesForStage(config.gates, 'publish'), projectRoot);
+    if (outcome.kind === 'gate-failed')
+        refuseGateFailed(outcome.gate, outcome.output);
+    if (outcome.kind === 'wrote')
+        refuseGateWrote(outcome.paths);
+    const fromRef = hasRemote ? 'origin/main' : undefined;
+    const commitCount = await totalCommits(projectRoot, fromRef !== undefined ? `${fromRef}..main` : 'main');
+    const since = await oldestCommitDate(projectRoot, fromRef !== undefined ? `${fromRef}..main` : 'main');
+    const stat = await diffShortstat(projectRoot, fromRef ?? EMPTY_TREE, 'main');
+    const signals = await collectSignals(projectRoot, fromRef, 'main', config);
+    console.log(formatSummary(commitCount, since, stat, outcome.results, signals));
+    await push(projectRoot, 'origin', 'main');
+    const pushedSha = (await headSha(projectRoot));
+    if (originalBranch !== undefined && originalBranch !== 'main') {
+        await switchBranch(projectRoot, originalBranch);
+    }
+    console.log(`✓  main publicada.   ${pushedSha.slice(0, 7)} → origin/main`);
+    return { code: 0, pushedSha };
+}