@orkastery/cli 0.2.0

package/dist/ship.js

@@ -0,0 +1,551 @@
+"use strict";
+/**
+ * `ork ship`: merge e push CONTROLADOS e VERIFICADOS (bloco B1, item 5 da paridade).
+ *
+ * A ordem dos passos e o contrato, e ela nao muda por modo de conducao:
+ *
+ *   1. autorizacao de push, pelo gate do modo (#Look/#Ork pausam; #Classic usa a
+ *      autorizacao antecipada registrada no ledger; #Maestro/#Auto usam a propria #TAG);
+ *   2. policies do manifesto no gate `ship` (push_direto_na_base e provider);
+ *   3. verificacao independente: `ork verify` reexecuta claims e comandos no HEAD real;
+ *   4. lease `main-tree`, que serializa: so uma thread mergeia por vez;
+ *   5. `git merge --no-ff`, conferido por `git merge-base --is-ancestor`;
+ *   6. push, PROVADO por `git ls-remote` batendo com o sha local (nao pelo codigo de
+ *      saida do push, e nunca por `gh api`, que nao e confiavel nesta maquina);
+ *   7. `ship_done` no ledger com os dois shas, quem autorizou e a evidencia.
+ *
+ * Qualquer passo que reprove grava `ship_blocked` com MOTIVO TIPADO e nao avanca.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.autorizacaoDePush = autorizacaoDePush;
+exports.arvoreComBranch = arvoreComBranch;
+exports.prepararArvore = prepararArvore;
+exports.shaDaRef = shaDaRef;
+exports.shaNoRemoto = shaNoRemoto;
+exports.remotoConfigurado = remotoConfigurado;
+exports.ship = ship;
+exports.textoDoShip = textoDoShip;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const gates_1 = require("./gates");
+const leases_1 = require("./leases");
+const ledger_1 = require("./ledger");
+const manifest_1 = require("./manifest");
+const modos_1 = require("./modos");
+const policies_1 = require("./policies");
+const thread_1 = require("./thread");
+const util_1 = require("./util");
+const verify_1 = require("./verify");
+/** Modos em que a propria #TAG do pedido autoriza o push antecipadamente. */
+const MODOS_QUE_AUTORIZAM_PUSH = ['maestro', 'auto'];
+/**
+ * Quem autoriza o push desta thread.
+ *
+ * `#Look` e `#Ork` pausam no proprio SHIP e esperam o humano. `#Classic` pausa antes,
+ * no gate de evidencias, com autorizacao ANTECIPADA de push: aqui isso e conferido no
+ * ledger, nao presumido. `#Maestro` e `#Auto` seguem pela #TAG, que fica registrada.
+ */
+function autorizacaoDePush(raiz, thread, opcoes) {
+    const tag = (0, modos_1.tagDoModo)(thread.modo);
+    if (typeof opcoes.autorizarPush === 'string' && opcoes.autorizarPush.trim() !== '') {
+        return {
+            autorizado: true,
+            tipo: 'humano-no-cli',
+            por: opcoes.autorizarPush.trim(),
+            razao: `pausa de push do modo ${tag} autorizada na linha de comando`,
+        };
+    }
+    if (MODOS_QUE_AUTORIZAM_PUSH.includes(thread.modo)) {
+        return {
+            autorizado: true,
+            tipo: 'modo',
+            por: `#TAG ${tag} no pedido do builder`,
+            razao: `o modo ${tag} entrega dentro de um bloco sem pausa: a #TAG e a autorizacao previa`,
+        };
+    }
+    if (thread.modo === 'classic') {
+        const antecipada = (0, gates_1.aprovacoesHumanas)(raiz, thread.id).find((e) => /push|evidencia/i.test(String(e.sobre ?? '')));
+        if (antecipada) {
+            return {
+                autorizado: true,
+                tipo: 'humano-antecipado',
+                por: String(antecipada.autorizadoPor ?? 'humano'),
+                razao: `autorizacao antecipada de push registrada no ledger em ${antecipada.ts}`,
+            };
+        }
+    }
+    return {
+        autorizado: false,
+        tipo: 'pendente',
+        por: '',
+        razao: `o modo ${tag} pausa no push e ainda nao ha autorizacao humana registrada. ` +
+            `Autorize com: ork gate approve ${thread.id} push --por <quem>  ` +
+            `ou rode: ork ship ${thread.id} --para <branch> --autorizar-push <quem>`,
+    };
+}
+/** Diretorio temporario onde a arvore de merge e montada quando preciso. */
+function dirTemporarioDeShip(raiz, para) {
+    const seguro = para.replace(/[^A-Za-z0-9._-]/g, '-');
+    return path.join((0, manifest_1.dirEstado)(raiz), 'tmp', `ship-${seguro}-${Date.now()}`);
+}
+/**
+ * Diretorio da worktree que tem a branch em check-out, se alguma tiver.
+ *
+ * O git recusa `worktree add` de uma branch ja em check-out em outro lugar, e com razao:
+ * duas arvores na mesma branch e receita de estado inconsistente. Entao o `ork` procura
+ * quem a tem antes de tentar montar arvore nova.
+ */
+function arvoreComBranch(raiz, branch) {
+    const r = (0, util_1.exec)('git', ['worktree', 'list', '--porcelain'], raiz);
+    if (!r.ok)
+        return null;
+    let atual = null;
+    for (const linha of r.stdout.split('\n')) {
+        if (linha.startsWith('worktree '))
+            atual = linha.slice('worktree '.length).trim();
+        else if (linha.trim() === `branch refs/heads/${branch}`)
+            return atual;
+    }
+    return null;
+}
+/** A arvore tem alteracao nao commitada em arquivo versionado? (arquivo novo nao conta) */
+function temAlteracaoNaoCommitada(dir) {
+    return !(0, util_1.exec)('git', ['diff', '--quiet'], dir).ok || !(0, util_1.exec)('git', ['diff', '--cached', '--quiet'], dir).ok;
+}
+/**
+ * Prepara a arvore onde o merge acontece.
+ *
+ * Se a branch de destino ja esta em check-out em alguma arvore do repositorio (a raiz do
+ * projeto ou o check-out principal, quando o `ork` roda de dentro de uma worktree), o
+ * merge acontece LA, exigindo arvore limpa: e a unica forma de o resultado do merge nao
+ * deixar aquela arvore inconsistente com a propria branch.
+ *
+ * Se ninguem tem a branch, o `ork` monta uma worktree temporaria e a descarta ao fim:
+ * entregar nunca pode trocar a branch em que o builder esta trabalhando.
+ */
+function prepararArvore(raiz, para) {
+    const dona = arvoreComBranch(raiz, para);
+    if (dona) {
+        if (temAlteracaoNaoCommitada(dona)) {
+            throw new Error(`a branch de destino "${para}" esta em check-out em ${dona} com alteracoes nao commitadas; ` +
+                'commite ou reverta la antes do ship');
+        }
+        return { dir: dona, temporaria: false };
+    }
+    const dir = dirTemporarioDeShip(raiz, para);
+    fs.mkdirSync(path.dirname(dir), { recursive: true });
+    const r = (0, util_1.exec)('git', ['worktree', 'add', dir, para], raiz);
+    if (!r.ok) {
+        throw new Error(`nao foi possivel montar a arvore de merge de "${para}": ${(r.stderr || r.stdout).trim()}`);
+    }
+    return { dir, temporaria: true };
+}
+/** Remove a worktree temporaria do merge (best effort: o lease ja foi liberado). */
+function descartarArvore(raiz, arvore) {
+    if (!arvore.temporaria)
+        return;
+    (0, util_1.exec)('git', ['worktree', 'remove', '--force', arvore.dir], raiz);
+    (0, util_1.exec)('git', ['worktree', 'prune'], raiz);
+}
+/** sha de uma referencia local, ou null quando ela nao existe. */
+function shaDaRef(dir, ref) {
+    const r = (0, util_1.exec)('git', ['rev-parse', '--verify', '--quiet', ref], dir);
+    const sha = r.stdout.trim();
+    return r.ok && /^[0-9a-f]{40}$/.test(sha) ? sha : null;
+}
+/**
+ * Le no REMOTO o sha da branch, com `git ls-remote`.
+ *
+ * E o unico jeito aceito de provar push nesta maquina: `gh api` e imprevisivel aqui, e o
+ * codigo de saida do `git push` nao prova que o remoto ficou com o commit certo.
+ */
+function shaNoRemoto(dir, remoto, branch) {
+    const r = (0, util_1.exec)('git', ['ls-remote', remoto, `refs/heads/${branch}`], dir, 120000);
+    if (!r.ok)
+        return null;
+    const linha = r.stdout.split('\n').find((l) => l.trim() !== '');
+    if (!linha)
+        return null;
+    const sha = linha.split(/\s+/)[0];
+    return /^[0-9a-f]{40}$/.test(sha) ? sha : null;
+}
+/** O remoto esta configurado neste repositorio? */
+function remotoConfigurado(dir, remoto) {
+    return (0, util_1.exec)('git', ['remote', 'get-url', remoto], dir).ok;
+}
+function baseDoResultado(thread, de, opcoes) {
+    return {
+        ok: false,
+        bloqueado: false,
+        motivo: null,
+        detalhe: '',
+        correcao: '',
+        thread: thread.id,
+        de,
+        para: opcoes.para,
+        shaDe: '',
+        shaParaAntes: '',
+        mergeSha: null,
+        jaIncorporado: false,
+        remoto: opcoes.remoto ?? 'origin',
+        shaRemoto: null,
+        pushVerificado: false,
+        autorizacao: { autorizado: false, tipo: 'pendente', por: '', razao: '' },
+        verificacao: null,
+        violacoes: [],
+        lease: null,
+        leaseOcupadoPor: null,
+        passos: [],
+        dryRun: opcoes.dryRun === true,
+    };
+}
+/** Executa o SHIP da thread. Nunca lanca por reprovacao: reprovacao volta tipada. */
+function ship(carregado, threadId, opcoes) {
+    const { raiz, manifesto } = carregado;
+    const thread = (0, thread_1.lerThread)(raiz, threadId);
+    const dir = (0, thread_1.dirThread)(raiz, threadId);
+    const de = opcoes.de ?? thread.base.branch;
+    const para = opcoes.para;
+    const remoto = opcoes.remoto ?? 'origin';
+    const r = baseDoResultado(thread, de, opcoes);
+    const bloquear = (motivo, detalhe, correcao) => {
+        (0, gates_1.registrarGateBloqueado)(dir, threadId, {
+            gate: 'ship',
+            motivo,
+            modo: thread.modo,
+            detalhe,
+            correcao,
+            de,
+            para,
+        });
+        (0, ledger_1.registrar)(dir, threadId, ledger_1.TIPOS_DE_EVENTO.shipBloqueado, {
+            de,
+            para,
+            motivo,
+            detalhe,
+            correcao,
+            modo: thread.modo,
+            dryRun: r.dryRun,
+        });
+        return { ...r, bloqueado: true, ok: false, motivo, detalhe, correcao };
+    };
+    // 1. Autorizacao de push pelo gate do modo de conducao.
+    const autorizacao = autorizacaoDePush(raiz, thread, opcoes);
+    r.autorizacao = autorizacao;
+    if (!autorizacao.autorizado) {
+        return bloquear('human.pending', autorizacao.razao, `ork gate approve ${threadId} push --por <quem>`);
+    }
+    // 2. Policies do manifesto que valem no gate `ship`.
+    const violacoes = (0, policies_1.avaliarPolicies)(manifesto, {
+        gate: 'ship',
+        de,
+        para,
+        baseBranch: manifesto.worktree.base_branch,
+    });
+    r.violacoes = violacoes;
+    const bloqueiam = (0, policies_1.bloqueantes)(violacoes);
+    if (bloqueiam.length > 0) {
+        return bloquear('policy.violation', bloqueiam.map((v) => `${v.policy}: ${v.detalhe}`).join('; '), bloqueiam.map((v) => v.correcao).join('; '));
+    }
+    // 3. Verificacao independente: reexecuta claims e comandos no HEAD real da thread.
+    const verificacao = (0, verify_1.verificar)(carregado, threadId);
+    r.verificacao = verificacao;
+    if (!verificacao.ok) {
+        const motivo = verificacao.motivos.find((m) => m !== 'claims.unverifiable');
+        return bloquear(motivo, `verificacao reprovou no HEAD ${verificacao.commit}: ${verificacao.motivos.join(', ')}`, 'rode `ork verify ' + threadId + '` e corrija antes de entregar');
+    }
+    // Referencias locais, resolvidas antes de tomar o lease.
+    const shaDe = shaDaRef(raiz, `refs/heads/${de}`);
+    const shaPara = shaDaRef(raiz, `refs/heads/${para}`);
+    if (!shaDe) {
+        return bloquear('artifact.missing', `branch de origem "${de}" nao existe neste repositorio`, `use --de <branch> ou crie a branch da thread`);
+    }
+    if (!shaPara) {
+        return bloquear('artifact.missing', `branch de destino "${para}" nao existe neste repositorio`, `crie a branch de destino ou informe outra em --para`);
+    }
+    r.shaDe = shaDe;
+    r.shaParaAntes = shaPara;
+    // 4. Lease `main-tree`: so uma thread mergeia por vez.
+    if (r.dryRun) {
+        const ocupado = (0, leases_1.lerLease)(raiz, leases_1.LEASE_MAIN_TREE);
+        r.leaseOcupadoPor = ocupado;
+        // O ensaio tambem responde ONDE o merge aconteceria e se aquela arvore esta limpa:
+        // descobrir isso so na hora do merge real seria descobrir tarde demais.
+        const dona = arvoreComBranch(raiz, para);
+        const arvoreDoMerge = dona
+            ? `${dona} (arvore que tem ${para} em check-out; ${temAlteracaoNaoCommitada(dona) ? 'SUJA, o ship reprovaria com tree.blocked' : 'limpa'})`
+            : `worktree temporaria em ${path.join((0, manifest_1.dirEstado)(raiz), 'tmp')} (ninguem tem ${para} em check-out)`;
+        r.detalhe = `arvore de merge: ${arvoreDoMerge}`;
+        r.passos = [
+            `arvore de merge: ${arvoreDoMerge}`,
+            `git merge --no-ff ${de} -m "<mensagem de ship>"`,
+            `git push ${remoto} ${para}`,
+            `git ls-remote ${remoto} refs/heads/${para}   (prova do push)`,
+        ];
+        (0, ledger_1.registrar)(dir, threadId, ledger_1.TIPOS_DE_EVENTO.shipIniciado, {
+            de,
+            para,
+            shaDe,
+            shaPara,
+            modo: thread.modo,
+            autorizadoPor: autorizacao.por,
+            dryRun: true,
+            leaseLivre: ocupado === null,
+        });
+        return { ...r, ok: true, bloqueado: false };
+    }
+    // A merge queue do B2: quem nao pega o lease entra na FILA, em vez de sumir. A fila
+    // fica visivel em `ork lease list` e em `ork board --all`, e e ela que serializa o
+    // merge de N threads paralelas sem ninguem perder a vez.
+    const aquisicao = (0, leases_1.adquirirRegiao)(raiz, leases_1.LEASE_MAIN_TREE, {
+        thread: threadId,
+        motivo: `ship de ${de} para ${para}`,
+        ttlMs: opcoes.ttlLeaseMs,
+    });
+    if (!aquisicao.ok) {
+        r.leaseOcupadoPor = aquisicao.ocupadoPor;
+        const dono = aquisicao.ocupadoPor;
+        (0, ledger_1.registrar)(dir, threadId, ledger_1.TIPOS_DE_EVENTO.leaseEnfileirado, {
+            lease: leases_1.LEASE_MAIN_TREE,
+            posicao: aquisicao.posicaoNaFila,
+            naFrente: (0, leases_1.esperandoPor)(raiz, leases_1.LEASE_MAIN_TREE).length,
+            bloqueadaPor: dono?.thread ?? '(desconhecida)',
+            motivo: 'lease.busy',
+        });
+        return bloquear('lease.busy', `lease ${leases_1.LEASE_MAIN_TREE} esta com a thread ${dono?.thread ?? '(desconhecida)'} ` +
+            `desde ${dono?.adquiridoEm ?? '?'} (${dono?.motivo ?? 'sem motivo'}); ` +
+            `esta thread entrou na merge queue na posicao ${aquisicao.posicaoNaFila}`, `espere a vez na fila (ork lease list), ou libere com: ork lease release ${leases_1.LEASE_MAIN_TREE} --forcar`);
+    }
+    r.lease = aquisicao.lease;
+    (0, ledger_1.registrar)(dir, threadId, ledger_1.TIPOS_DE_EVENTO.leaseAdquirido, {
+        lease: leases_1.LEASE_MAIN_TREE,
+        expiraEm: aquisicao.lease?.expiraEm,
+        tomadoDeVencido: aquisicao.tomadoDeVencido,
+        motivo: `ship de ${de} para ${para}`,
+    });
+    (0, ledger_1.registrar)(dir, threadId, ledger_1.TIPOS_DE_EVENTO.shipIniciado, {
+        de,
+        para,
+        shaDe,
+        shaPara,
+        modo: thread.modo,
+        autorizadoPor: autorizacao.por,
+        tipoDeAutorizacao: autorizacao.tipo,
+        verificadoNoCommit: verificacao.commit,
+    });
+    let arvore = null;
+    try {
+        try {
+            arvore = prepararArvore(raiz, para);
+        }
+        catch (e) {
+            // Arvore de destino indisponivel e reprovacao tipada, nao excecao vazando pelo CLI.
+            return bloquear('tree.blocked', e.message, 'deixe a arvore da branch de destino limpa (ou libere a branch) e rode o ship de novo');
+        }
+        const passos = [];
+        // 5. Merge --no-ff, conferido no proprio git.
+        const jaIncorporado = (0, util_1.exec)('git', ['merge-base', '--is-ancestor', shaDe, shaPara], raiz).ok;
+        r.jaIncorporado = jaIncorporado;
+        let mergeSha = shaPara;
+        if (!jaIncorporado) {
+            const mensagem = opcoes.mensagem ??
+                `ship(${threadId}): merge de ${de} em ${para}\n\n` +
+                    `thread: ${thread.id} (${thread.slug})\n` +
+                    `modo: ${(0, modos_1.tagDoModo)(thread.modo)}\n` +
+                    `autorizado por: ${autorizacao.por} (${autorizacao.tipo})\n` +
+                    `verificado em: HEAD ${verificacao.commit}\n`;
+            const merge = (0, util_1.exec)('git', ['merge', '--no-ff', de, '-m', mensagem], arvore.dir, 300000);
+            passos.push(`git merge --no-ff ${de}`);
+            if (!merge.ok) {
+                (0, util_1.exec)('git', ['merge', '--abort'], arvore.dir);
+                r.passos = [...passos, 'git merge --abort'];
+                return bloquear('artifact.missing', `merge de ${de} em ${para} falhou: ${(merge.stderr || merge.stdout).trim().slice(0, 400)}`, 'resolva o conflito na branch da thread e rode o ship de novo');
+            }
+            const novo = shaDaRef(arvore.dir, 'HEAD');
+            if (!novo) {
+                return bloquear('artifact.missing', 'nao foi possivel ler o HEAD apos o merge', 'confira o repositorio');
+            }
+            mergeSha = novo;
+            // Verificacao independente do merge: a origem precisa ser ancestral do resultado.
+            const incorporou = (0, util_1.exec)('git', ['merge-base', '--is-ancestor', shaDe, mergeSha], arvore.dir).ok;
+            passos.push(`git merge-base --is-ancestor ${shaDe.slice(0, 8)} ${mergeSha.slice(0, 8)}`);
+            if (!incorporou) {
+                return bloquear('artifact.missing', `o commit de ${de} nao aparece como ancestral do merge ${mergeSha}`, 'nao empurre: investigue o estado do repositorio');
+            }
+        }
+        else {
+            passos.push(`(nada a mergear: ${de} ja e ancestral de ${para})`);
+        }
+        r.mergeSha = mergeSha;
+        // 6. Push PROVADO por ls-remote.
+        const temRemoto = remotoConfigurado(arvore.dir, remoto);
+        r.remoto = temRemoto ? remoto : null;
+        if (opcoes.semPush || !temRemoto) {
+            r.pushVerificado = false;
+            r.detalhe = opcoes.semPush
+                ? 'push nao executado por --sem-push (merge local concluido)'
+                : `remoto "${remoto}" nao configurado: merge local concluido, sem push a provar`;
+        }
+        else {
+            const existeNoRemoto = shaNoRemoto(arvore.dir, remoto, para) !== null;
+            const argsPush = existeNoRemoto
+                ? ['push', remoto, `${para}:refs/heads/${para}`]
+                : ['push', '-u', remoto, `${para}:refs/heads/${para}`];
+            const push = (0, util_1.exec)('git', argsPush, arvore.dir, 300000);
+            passos.push(`git ${argsPush.join(' ')}`);
+            if (!push.ok) {
+                r.passos = passos;
+                return bloquear('runtime.unavailable', `push para ${remoto}/${para} falhou: ${(push.stderr || push.stdout).trim().slice(0, 400)}`, 'resolva o acesso ao remoto e rode o ship de novo (o merge local ja aconteceu)');
+            }
+            // A prova: o sha que o REMOTO devolve tem que ser o mesmo do destino local.
+            const shaRemoto = shaNoRemoto(arvore.dir, remoto, para);
+            passos.push(`git ls-remote ${remoto} refs/heads/${para}`);
+            r.shaRemoto = shaRemoto;
+            r.pushVerificado = shaRemoto !== null && shaRemoto === mergeSha;
+            if (!r.pushVerificado) {
+                r.passos = passos;
+                return bloquear('runtime.unavailable', `ls-remote devolveu ${shaRemoto ?? '(nada)'} e o destino local esta em ${mergeSha}: ` +
+                    'o push nao ficou provado', 'rode o ship de novo e confira o remoto');
+            }
+        }
+        r.passos = passos;
+        // 7. Evidencia no ledger e estado da thread.
+        (0, gates_1.registrarGateLiberado)(dir, threadId, {
+            gate: 'ship',
+            modo: thread.modo,
+            autorizadoPor: autorizacao.por,
+            evidencia: `merge ${mergeSha} verificado; ls-remote ${r.shaRemoto ?? '(sem remoto)'}`,
+            tipoDeAutorizacao: autorizacao.tipo,
+        });
+        (0, ledger_1.registrar)(dir, threadId, ledger_1.TIPOS_DE_EVENTO.shipConcluido, {
+            de,
+            para,
+            shaDe,
+            shaParaAntes: shaPara,
+            mergeSha,
+            jaIncorporado,
+            remoto: r.remoto,
+            shaRemoto: r.shaRemoto,
+            pushVerificado: r.pushVerificado,
+            fonteDaProva: r.pushVerificado ? `git ls-remote ${remoto} refs/heads/${para}` : null,
+            autorizadoPor: autorizacao.por,
+            tipoDeAutorizacao: autorizacao.tipo,
+            modo: thread.modo,
+            tag: (0, modos_1.tagDoModo)(thread.modo),
+            evidencia: {
+                verificadoNoCommit: verificacao.commit,
+                claimsVerificadas: verificacao.claims.filter((c) => c.verificado).map((c) => c.claim.id),
+                comandos: verificacao.comandos.map((c) => ({ nome: c.nome, ok: c.ok })),
+                passos,
+            },
+        });
+        const atualizada = (0, thread_1.lerThread)(raiz, threadId);
+        atualizada.faseAtual = 'SHIP';
+        atualizada.leases = [
+            ...(atualizada.leases ?? []),
+            { nome: leases_1.LEASE_MAIN_TREE, adquiridoEm: aquisicao.lease?.adquiridoEm ?? (0, util_1.agora)(), liberadoEm: (0, util_1.agora)() },
+        ];
+        (0, thread_1.gravarThread)(raiz, atualizada);
+        return { ...r, ok: true, bloqueado: false };
+    }
+    finally {
+        if (arvore)
+            descartarArvore(raiz, arvore);
+        const solto = (0, leases_1.liberar)(raiz, leases_1.LEASE_MAIN_TREE, threadId);
+        (0, ledger_1.registrar)(dir, threadId, ledger_1.TIPOS_DE_EVENTO.leaseLiberado, {
+            lease: leases_1.LEASE_MAIN_TREE,
+            ok: solto.ok,
+            detalhe: solto.detalhe,
+        });
+    }
+}
+/** Texto de `ork ship` para o CLI. */
+function textoDoShip(r) {
+    const linhas = [];
+    const cabecalho = r.dryRun ? 'ork ship (--dry-run, nada foi executado)' : 'ork ship';
+    linhas.push(`${cabecalho}: thread ${r.thread}`);
+    linhas.push(`  de            ${r.de}${r.shaDe ? ` @ ${r.shaDe.slice(0, 8)}` : ''}`);
+    linhas.push(`  para          ${r.para}${r.shaParaAntes ? ` @ ${r.shaParaAntes.slice(0, 8)}` : ''}`);
+    linhas.push(`  autorizacao   ${r.autorizacao.autorizado ? `AUTORIZADO por ${r.autorizacao.por} (${r.autorizacao.tipo})` : 'AGUARDANDO AUTORIZACAO HUMANA'}`);
+    linhas.push(`                ${r.autorizacao.razao}`);
+    if (r.verificacao) {
+        const v = r.verificacao;
+        linhas.push(`  verificacao   ${v.ok ? 'passou' : 'REPROVOU'} no HEAD ${v.commit.slice(0, 8)} ` +
+            `(${v.claims.filter((c) => c.verificado).length}/${v.claims.length} claims, ` +
+            `${v.comandos.filter((c) => c.ok).length}/${v.comandos.length} comandos)`);
+    }
+    if (r.leaseOcupadoPor) {
+        linhas.push(`  lease         ${leases_1.LEASE_MAIN_TREE} OCUPADO pela thread ${r.leaseOcupadoPor.thread} (desde ${r.leaseOcupadoPor.adquiridoEm})`);
+    }
+    else if (r.lease) {
+        linhas.push(`  lease         ${leases_1.LEASE_MAIN_TREE} tomado por ${r.thread} e liberado ao fim`);
+    }
+    else if (r.dryRun) {
+        linhas.push(`  lease         ${leases_1.LEASE_MAIN_TREE} livre`);
+    }
+    if (r.bloqueado) {
+        linhas.push('');
+        linhas.push(`BLOQUEADO. motivo tipado: ${r.motivo}`);
+        linhas.push(`  detalhe   ${r.detalhe}`);
+        linhas.push(`  correcao  ${r.correcao}`);
+        return linhas.join('\n');
+    }
+    if (r.dryRun) {
+        linhas.push('');
+        linhas.push('Passos que o ship real executaria, nesta ordem:');
+        for (const p of r.passos)
+            linhas.push(`  ${p}`);
+        return linhas.join('\n');
+    }
+    linhas.push('');
+    linhas.push(r.jaIncorporado
+        ? `Nada a mergear: ${r.de} ja estava em ${r.para}.`
+        : `Merge --no-ff concluido: ${r.mergeSha}`);
+    if (r.pushVerificado) {
+        linhas.push(`Push PROVADO: ls-remote de ${r.remoto}/${r.para} devolveu ${r.shaRemoto}`);
+        linhas.push(`  e o destino local esta no mesmo sha: ${r.mergeSha}`);
+    }
+    else {
+        linhas.push(`Push nao provado: ${r.detalhe || 'sem remoto configurado'}`);
+    }
+    linhas.push('');
+    linhas.push('Evidencia (comandos executados):');
+    for (const p of r.passos)
+        linhas.push(`  ${p}`);
+    linhas.push('');
+    linhas.push(`Ledger: ork phase list ${r.thread}  (evento ship_done)`);
+    return linhas.join('\n');
+}

package/dist/slug.js

@@ -0,0 +1,100 @@
+"use strict";
+/**
+ * Slug de sessao em 3 partes (visao unificada, secao 3.4).
+ *
+ *   <produto ate 3 letras>-<assunto ate 12 chars>-<fases>[-<rotacao>]
+ *
+ * A parte 1 vem de `project.abbrev` no manifesto. A parte 2 nao tem hifen interno,
+ * o que preserva o parse deterministico. A parte 3 diz que fases a sessao conduz.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.REGEX_SLUG = void 0;
+exports.normalizarAbbrev = normalizarAbbrev;
+exports.normalizarAssunto = normalizarAssunto;
+exports.validarAbbrev = validarAbbrev;
+exports.montarSlug = montarSlug;
+exports.parseSlug = parseSlug;
+exports.slugValido = slugValido;
+exports.idDaThreadPeloSlug = idDaThreadPeloSlug;
+exports.proximaRotacao = proximaRotacao;
+/** Regex canonica do slug, aplicada em toda geracao e todo override `--slug`. */
+exports.REGEX_SLUG = /^[a-z0-9]{1,3}-[a-z0-9]{1,12}-(goal|plan|go|check|ship|master|f[1-6]{2,6}|full)(-[0-9]+)?$/;
+/** Remove acentos e reduz a `[a-z0-9]`, o alfabeto aceito nas partes 1 e 2. */
+function apenasAlfanumerico(texto) {
+    return texto
+        .normalize('NFD')
+        .replace(/[\u0300-\u036f]/g, '')
+        .toLowerCase()
+        .replace(/[^a-z0-9]/g, '');
+}
+/** Normaliza a abreviacao do produto para a parte 1 (ate 3 caracteres). */
+function normalizarAbbrev(bruto) {
+    return apenasAlfanumerico(bruto).slice(0, 3);
+}
+/** Normaliza o nome dado pelo builder para a parte 2 (ate 12 caracteres). */
+function normalizarAssunto(bruto) {
+    return apenasAlfanumerico(bruto).slice(0, 12);
+}
+/** Valida a abreviacao do projeto, com mensagem de erro acionavel. */
+function validarAbbrev(abbrev) {
+    if (!abbrev) {
+        return { ok: false, erro: 'project.abbrev ausente no manifesto (parte 1 do slug)' };
+    }
+    if (!/^[a-z0-9]{1,3}$/.test(abbrev)) {
+        return {
+            ok: false,
+            erro: `project.abbrev invalido: "${abbrev}" (esperado ate 3 caracteres [a-z0-9])`,
+        };
+    }
+    return { ok: true };
+}
+/** Monta o slug de 3 partes. Lanca erro se o resultado nao casar com a regex canonica. */
+function montarSlug(abbrev, assunto, fases, rotacao) {
+    const partes = [normalizarAbbrev(abbrev), normalizarAssunto(assunto), fases.toLowerCase()];
+    let slug = partes.join('-');
+    if (rotacao && rotacao > 1)
+        slug += `-${rotacao}`;
+    if (!exports.REGEX_SLUG.test(slug)) {
+        throw new Error(`slug gerado invalido: "${slug}" (regex canonica: ${exports.REGEX_SLUG.source})`);
+    }
+    return slug;
+}
+/** Faz o parse do slug nas 3 partes. Retorna null quando o slug e invalido. */
+function parseSlug(slug) {
+    if (!exports.REGEX_SLUG.test(slug))
+        return null;
+    const partes = slug.split('-');
+    const rotacao = partes.length === 4 ? Number(partes[3]) : null;
+    return {
+        produto: partes[0],
+        assunto: partes[1],
+        fases: partes[2],
+        rotacao,
+    };
+}
+/** O slug e valido pela regex canonica? */
+function slugValido(slug) {
+    return exports.REGEX_SLUG.test(slug);
+}
+/** Id da thread a partir do slug: as duas primeiras partes (`<produto>-<assunto>`). */
+function idDaThreadPeloSlug(slug) {
+    const p = parseSlug(slug);
+    return p ? `${p.produto}-${p.assunto}` : null;
+}
+/** Proximo slug de rotacao de sessao dentro do mesmo bloco (gate de tokens, B1). */
+function proximaRotacao(slug, jaExistentes) {
+    const p = parseSlug(slug);
+    if (!p)
+        throw new Error(`slug invalido para rotacao: ${slug}`);
+    const base = `${p.produto}-${p.assunto}-${p.fases}`;
+    let n = 1;
+    for (const existente of jaExistentes) {
+        const q = parseSlug(existente);
+        if (!q)
+            continue;
+        if (`${q.produto}-${q.assunto}-${q.fases}` !== base)
+            continue;
+        n = Math.max(n, q.rotacao ?? 1);
+    }
+    return montarSlug(p.produto, p.assunto, p.fases, n + 1);
+}