dd-harness 0.30.0 → 0.32.0

package/dist/regras-de-commit.js

@@ -0,0 +1,15 @@
+/** Regra do produto, entregue junto da política sem reescrever o artefato no serviço. */
+export const REGRA_DE_COMMITS = `## Identificação do agente nos commits
+
+Todo commit feito por agente começa com [IDENTIFICAÇÃO] - tipo: descrição.
+Exemplos: [CODEX] - feat: nova funcionalidade; [CLAUDE] - fix: corrige a busca;
+[GEMINI] - docs: atualiza o guia. Outro agente usa seu nome em maiúsculas entre colchetes.
+Identifique o agente/modelo que efetivamente realizou o commit, não apenas o editor:
+Claude no Antigravity continua [CLAUDE]; Gemini usa [GEMINI]; Codex usa [CODEX].
+Não invente a identidade. A regra não concede autorização para commitar, não altera
+o autor do Git e não pede reescrita de commits antigos.`;
+export function politicaParaSessao(conteudo) {
+    if (!conteudo.trim() || conteudo.includes(REGRA_DE_COMMITS))
+        return conteudo;
+    return `${conteudo}\n\n---\n\n${REGRA_DE_COMMITS}`;
+}

package/dist/roadmap.js

@@ -1,4 +1,4 @@
-import { cabecalhos, credencial, pede, recusa } from "./api.js";
+import { jsonDaEscrita, cabecalhos, credencial, pede, recusa } from "./api.js";
 // --- rede ---
 export async function leFases(raiz, filtro = {}) {
     const { config, token } = await credencial(raiz);
@@ -33,7 +33,7 @@ export async function criaFase(raiz, dados) {
     });
     if (!resposta.ok)
         await recusa(resposta);
-    return (await resposta.json());
+    return (await jsonDaEscrita(resposta));
 }
 export async function editaFase(raiz, slug, dados) {
     const { config, token } = await credencial(raiz);
@@ -44,7 +44,7 @@ export async function editaFase(raiz, slug, dados) {
     });
     if (!resposta.ok)
         await recusa(resposta);
-    return (await resposta.json());
+    return (await jsonDaEscrita(resposta));
 }
 // --- formatacao (pura) ---
 /** Rotulo do grupo de fases concluidas sem versao: o "Unreleased" do Keep a Changelog. */

package/dist/sessao.d.ts

@@ -0,0 +1,5 @@
+import { type Host } from "./edicoes.js";
+export declare function saidaDoBoot(host: Host, contexto: string, ok: boolean): object;
+export declare function abreSessao(host: Host, entrada: Record<string, unknown>): Promise<object>;
+export declare function saidaDaGuarda(host: Host, motivo?: string, contexto?: string): object;
+export declare function guardaSessao(host: Host, entrada: Record<string, unknown>): Promise<object>;

package/dist/sessao.js

@@ -0,0 +1,125 @@
+import { createHash, randomUUID } from "node:crypto";
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { credencial } from "./api.js";
+import { achaRaiz } from "./config.js";
+import { decideDoHook, guardaCache, leCache } from "./cinto.js";
+import { edicoesDaChamada, normalizaEntrada } from "./edicoes.js";
+import { estadoDoRepo, escreveAtomico, revisaoDoContexto } from "./estado-local.js";
+import { buscaPolitica } from "./politica.js";
+import { blocoDeSessao } from "./roadmap.js";
+import { leSkills, escrevePonteirosDeSkills } from "./skill.js";
+import { REGRA_DE_COMMITS } from "./regras-de-commit.js";
+import { subiuOWorker } from "./worker.js";
+const PRAZO = 4 * 60 * 60 * 1000;
+const hash = (s) => createHash("sha256").update(s).digest("hex");
+const arquivo = (raiz, sessao, host) => join(estadoDoRepo(raiz), `sessao-${hash(host + sessao)}.json`);
+async function identidade(raiz) {
+    const c = await credencial(raiz);
+    return hash(JSON.stringify(c)); // inclui token sem expô-lo em disco/log.
+}
+async function estadoAtual(raiz, sessao, host) {
+    try {
+        const e = JSON.parse(await readFile(arquivo(raiz, sessao, host), "utf8"));
+        if (e.estado === "ok" && e.revisao !== await revisaoDoContexto(raiz))
+            return null;
+        return e.identidade === await identidade(raiz) && Date.now() >= e.em && Date.now() - e.em < PRAZO ? e : null;
+    }
+    catch {
+        return null;
+    }
+}
+export function saidaDoBoot(host, contexto, ok) {
+    return host === "antigravity"
+        ? { injectSteps: contexto ? [{ ephemeralMessage: contexto }] : [] }
+        : { ...(ok ? {} : { continue: false, stopReason: "dd-harness: contexto obrigatório indisponível" }),
+            hookSpecificOutput: { hookEventName: "SessionStart", additionalContext: contexto } };
+}
+export async function abreSessao(host, entrada) {
+    const c = normalizaEntrada(host, entrada);
+    if (!c.sessao)
+        throw new Error("hook sem identificador de sessão: não é possível validar o boot");
+    const raiz = await achaRaiz(c.raiz);
+    const anterior = await estadoAtual(raiz, c.sessao, host);
+    // A mensagem do Antigravity é efêmera: não presumir que sobreviva à próxima inferência.
+    const inicio = host !== "antigravity" || Number(entrada.invocationNum) === 0 || anterior?.estado !== "ok";
+    const ciclo = inicio ? randomUUID() : anterior.ciclo;
+    await escreveAtomico(arquivo(raiz, c.sessao, host), JSON.stringify({ estado: "inalcancavel", em: 0 }));
+    const id = await identidade(raiz).catch(() => "");
+    const revisao = await revisaoDoContexto(raiz);
+    const r = await buscaPolitica(raiz);
+    let contexto;
+    if (r.estado === "ok") {
+        contexto = r.conteudo + blocoDeSessao(r.roadmap);
+        await guardaCache(raiz, { memorias: r.memorias ?? [] });
+        if (inicio)
+            try {
+                const skills = await leSkills(raiz, AbortSignal.timeout(6000));
+                const sync = await escrevePonteirosDeSkills(raiz, skills, [host === "claude" ? ".claude" : ".agents"]);
+                if (skills.length)
+                    contexto += "\n\nSkills disponíveis (use ler_skill para o procedimento):\n" +
+                        skills.map(s => `- ${s.slug}${s.so_por_comando ? " (só por pedido explícito)" : ""}: ${s.descricao}`).join("\n");
+                if (sync.conflitos.length)
+                    contexto += `\n\n${sync.conflitos.length} ponteiro(s) preservado(s) por conflito local; consulte listar_skills.`;
+            }
+            catch {
+                contexto += "\n\nNão foi possível atualizar as skills; consulte listar_skills quando o serviço voltar.";
+            }
+        if (r.esperandoIndexacao && inicio) {
+            const worker = await subiuOWorker(raiz, r.esperandoIndexacao);
+            contexto += `\n\n${r.esperandoIndexacao} memória(s) aguardam indexação; a busca pode estar incompleta. ` +
+                (worker.subiu ? `Lote solicitado; isto não comprova conclusão. Consulte status e o log ${worker.log}.` :
+                    "Worker não iniciado; execute o worker configurado e confira status.");
+        }
+    }
+    else if (r.estado === "sem-politica") {
+        contexto = "Projeto sem política e/ou briefing. Conduza o briefing com o usuário e, após aprovação, " +
+            "grave os dois com escrever_artefato. Defina permissões de commit e push separadamente. " +
+            "Depois consulte ler_artefato para verificar e reabra a sessão. Escritas no código permanecem bloqueadas.\n\n" + REGRA_DE_COMMITS;
+    }
+    else
+        contexto = `PARE: não foi possível carregar a política e o briefing. ${r.motivo}. Corrija a conexão/configuração e reabra a sessão.`;
+    await escreveAtomico(arquivo(raiz, c.sessao, host), JSON.stringify({ identidade: id,
+        revisao, ciclo, estado: r.estado, em: Date.now() }));
+    return saidaDoBoot(host, contexto, r.estado !== "inalcancavel");
+}
+export function saidaDaGuarda(host, motivo, contexto) {
+    if (host === "antigravity")
+        return { decision: motivo ? "deny" : "ask", reason: motivo ?? contexto ?? "" };
+    return { hookSpecificOutput: { hookEventName: "PreToolUse",
+            ...(motivo ? { permissionDecision: "deny", permissionDecisionReason: motivo } : {}),
+            ...(contexto ? { additionalContext: contexto } : {}) } };
+}
+// Só ferramentas conhecidas de leitura passam quando o boot falta. Shell não é classificado por regex.
+const LEITURA = /^(Read|Glob|Grep|view_file|list_dir|find_by_name|grep_search|ask_question|AskUserQuestion|request_user_input)$/;
+const LEITURA_MCP = /^mcp__dd[-_]harness__(ler_artefato|ler_roadmap|ler_changelog|listar_skills|ler_skill|ler_memoria|buscar_memoria)$/;
+export async function guardaSessao(host, entrada) {
+    const c = normalizaEntrada(host, entrada);
+    const raiz = await achaRaiz(c.raiz);
+    const e = c.sessao ? await estadoAtual(raiz, c.sessao, host) : null;
+    if (e?.estado !== "ok") {
+        const onboarding = e?.estado === "sem-politica" && /^mcp__dd[-_]harness__escrever_artefato$/.test(c.ferramenta);
+        if (LEITURA.test(c.ferramenta) || LEITURA_MCP.test(c.ferramenta) || onboarding)
+            return saidaDaGuarda(host);
+        return saidaDaGuarda(host, "dd-harness: política e briefing não foram carregados nesta sessão/projeto. Corrija o boot e reabra a sessão.");
+    }
+    const edicoes = edicoesDaChamada(c);
+    const avisos = [];
+    if (edicoes.length && !await leCache(raiz)) {
+        const r = await buscaPolitica(raiz);
+        if (r.estado !== "ok") {
+            await escreveAtomico(arquivo(raiz, c.sessao, host), JSON.stringify({ estado: "inalcancavel", em: 0 }));
+            return saidaDaGuarda(host, "dd-harness: falha ao revalidar contexto após mudança. Reabra a sessão.");
+        }
+        if (r.memorias)
+            await guardaCache(raiz, { memorias: r.memorias });
+    }
+    for (const edicao of edicoes) {
+        const depois = edicao.origem ? await readFile(edicao.origem, "utf8").catch(() => undefined) : edicao.depois;
+        const r = JSON.parse(await decideDoHook({ cwd: raiz, session_id: host + c.sessao + e.ciclo,
+            tool_input: { file_path: edicao.arquivo, old_string: edicao.antes, new_string: depois } }));
+        if (r.hookSpecificOutput.additionalContext)
+            avisos.push(r.hookSpecificOutput.additionalContext);
+    }
+    return saidaDaGuarda(host, undefined, avisos.join("\n\n"));
+}

package/dist/skill.d.ts

@@ -26,7 +26,7 @@ export type Skill = {
 export type SkillCompleta = Skill & {
     conteudo: string;
 };
-export declare function leSkills(raiz: string): Promise<Skill[]>;
+export declare function leSkills(raiz: string, signal?: AbortSignal): Promise<Skill[]>;
 export declare function leSkill(raiz: string, slug: string): Promise<SkillCompleta>;
 export declare function criaSkill(raiz: string, dados: NovaSkillInicial & Partial<Pick<Skill, "so_por_comando" | "ferramentas" | "caminhos" | "dica_de_argumento">>): Promise<{
     skill: Skill;
@@ -38,17 +38,15 @@ export declare function criaSkill(raiz: string, dados: NovaSkillInicial & Partia
  * pediria permissao para ler a propria skill, e um "permitir?" antes de cada invocacao
  * ensina a desligar o mecanismo.
  */
-export declare function ponteiroDaSkill(skill: Skill): string;
+export declare function ponteiroDaSkill(skill: Skill, formato?: "claude" | "padrao"): string;
 /**
- * Escreve os ponteiros de todas as skills do projeto.
- *
- * NAO apaga diretorio que sobrou: uma skill apagada no servico deixa o ponteiro orfao, e
- * varrer `.claude/skills/` inteiro levaria junto as skills que a pessoa escreveu a mao —
- * que sao legitimas e nao passam por aqui. O DELETE da API avisa o que apagar; a decisao
- * de apagar arquivo alheio nao e nossa.
+ * Atualiza/remove somente ponteiros registrados e intactos. Preserva arquivos manuais,
+ * edições locais e recursos adicionais nos diretórios de skills.
  */
-export declare function escrevePonteirosDeSkills(raiz: string, skills: Skill[]): Promise<{
+export declare function escrevePonteirosDeSkills(raiz: string, skills: Skill[], destinos?: (".claude" | ".agents")[]): Promise<{
     escritos: number;
+    removidos: number;
+    conflitos: string[];
 }>;
 /** O minimo para criar uma skill: o resto tem default no banco. */
 export type NovaSkillInicial = {

package/dist/skill.js

@@ -1,13 +1,15 @@
-import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { createHash } from "node:crypto";
+import { estadoDoRepo, escreveAtomico } from "./estado-local.js";
+import { mkdir, readFile, rm, lstat } from "node:fs/promises";
 import { join } from "node:path";
-import { cabecalhos, credencial, pede, recusa } from "./api.js";
+import { jsonDaEscrita, cabecalhos, credencial, pede, recusa } from "./api.js";
 // --- rede ---
-export async function leSkills(raiz) {
+export async function leSkills(raiz, signal) {
     const { config, token } = await credencial(raiz);
     const url = new URL(`${config.api}/api/v1/skills`);
     url.searchParams.set("tenant", config.tenant);
     url.searchParams.set("projeto", config.projeto);
-    const resposta = await pede(url, { headers: cabecalhos(token) });
+    const resposta = await pede(url, { headers: cabecalhos(token), signal });
     if (!resposta.ok)
         await recusa(resposta);
     return (await resposta.json()).skills;
@@ -34,7 +36,7 @@ dados) {
     });
     if (!resposta.ok)
         await recusa(resposta);
-    return (await resposta.json());
+    return (await jsonDaEscrita(resposta));
 }
 // --- o ponteiro em disco (puro, para ser testado sem rede) ---
 /**
@@ -55,27 +57,28 @@ function comoEscalarYaml(texto) {
  * pediria permissao para ler a propria skill, e um "permitir?" antes de cada invocacao
  * ensina a desligar o mecanismo.
  */
-export function ponteiroDaSkill(skill) {
+export function ponteiroDaSkill(skill, formato = "claude") {
     const frontmatter = [
         "---",
         `name: ${skill.slug}`,
         `description: ${comoEscalarYaml(skill.descricao)}`,
     ];
-    if (skill.so_por_comando)
+    if (skill.so_por_comando && formato === "claude")
         frontmatter.push("disable-model-invocation: true");
     if (skill.dica_de_argumento) {
         frontmatter.push(`argument-hint: ${comoEscalarYaml(skill.dica_de_argumento)}`);
     }
     const ferramentas = ["mcp__dd-harness__ler_skill", ...skill.ferramentas];
-    frontmatter.push(`allowed-tools: ${ferramentas.join(", ")}`);
-    if (skill.caminhos.length > 0) {
+    if (formato === "claude")
+        frontmatter.push(`allowed-tools: ${ferramentas.join(", ")}`);
+    if (formato === "claude" && skill.caminhos.length > 0) {
         frontmatter.push(`paths: ${skill.caminhos.join(", ")}`);
     }
     frontmatter.push("---");
     return `${frontmatter.join("\n")}
 
 # ${skill.slug}
-
+${skill.so_por_comando ? "\nSó execute quando o usuário pedir explicitamente esta skill.\n" : ""}
 O procedimento desta skill vive no dd-harness, não neste arquivo.
 
 **Chame a ferramenta MCP \`ler_skill\` com \`slug: "${skill.slug}"\` e siga o que ela
@@ -87,28 +90,96 @@ usuário em vez de improvisar um procedimento.
 `;
 }
 /**
- * Escreve os ponteiros de todas as skills do projeto.
- *
- * NAO apaga diretorio que sobrou: uma skill apagada no servico deixa o ponteiro orfao, e
- * varrer `.claude/skills/` inteiro levaria junto as skills que a pessoa escreveu a mao —
- * que sao legitimas e nao passam por aqui. O DELETE da API avisa o que apagar; a decisao
- * de apagar arquivo alheio nao e nossa.
+ * Atualiza/remove somente ponteiros registrados e intactos. Preserva arquivos manuais,
+ * edições locais e recursos adicionais nos diretórios de skills.
  */
-export async function escrevePonteirosDeSkills(raiz, skills) {
-    let escritos = 0;
-    for (const skill of skills) {
-        const dir = join(raiz, ".claude", "skills", skill.slug);
-        const caminho = join(dir, "SKILL.md");
-        const novo = ponteiroDaSkill(skill);
-        // Só escreve quando muda: reescrever igual sujaria o `git status` a cada `start`.
-        const atual = await readFile(caminho, "utf8").catch(() => null);
-        if (atual === novo)
-            continue;
-        await mkdir(dir, { recursive: true });
-        await writeFile(caminho, novo, "utf8");
-        escritos++;
+export async function escrevePonteirosDeSkills(raiz, skills, destinos = [".claude"]) {
+    let escritos = 0, removidos = 0;
+    const conflitos = [];
+    const hash = (s) => createHash("sha256").update(s).digest("hex");
+    async function temLink(destino, slug) {
+        for (const caminho of [join(raiz, destino), join(raiz, destino, "skills"),
+            join(raiz, destino, "skills", slug), join(raiz, destino, "skills", slug, "SKILL.md")]) {
+            const st = await lstat(caminho).catch((e) => {
+                if (e.code === "ENOENT")
+                    return null;
+                throw e;
+            });
+            if (st?.isSymbolicLink())
+                return true;
+        }
+        return false;
+    }
+    for (const destino of new Set(destinos)) {
+        const manifesto = join(estadoDoRepo(raiz), 'skills-' + destino.slice(1) + '.json');
+        let anterior = {};
+        try {
+            anterior = JSON.parse(await readFile(manifesto, "utf8"));
+        }
+        catch { /* Sem manifesto, arquivo existente pertence ao dono. */ }
+        const proximo = { ...anterior };
+        const presentes = new Set();
+        for (const skill of skills) {
+            if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(skill.slug))
+                throw new Error("slug de skill inválido");
+            presentes.add(skill.slug);
+            // Hosts sem disable-model-invocation não recebem descoberta automática destas skills.
+            // O procedimento continua acessível por listar_skills/ler_skill quando o usuário pedir.
+            if (destino === ".agents" && skill.so_por_comando) {
+                presentes.delete(skill.slug);
+                continue;
+            }
+            const dir = join(raiz, destino, "skills", skill.slug);
+            const caminho = join(dir, "SKILL.md");
+            if (await temLink(destino, skill.slug)) {
+                conflitos.push(caminho);
+                continue;
+            }
+            const novo = ponteiroDaSkill(skill, destino === ".claude" ? "claude" : "padrao");
+            const atual = await readFile(caminho, "utf8").catch((e) => {
+                if (e.code === "ENOENT")
+                    return null;
+                throw e;
+            });
+            if (atual !== null && hash(atual) !== anterior[skill.slug]) {
+                conflitos.push(caminho);
+                continue;
+            }
+            if (atual !== novo) {
+                await mkdir(dir, { recursive: true });
+                await escreveAtomico(caminho, novo);
+                escritos++;
+            }
+            proximo[skill.slug] = hash(novo);
+        }
+        for (const [slug, assinatura] of Object.entries(anterior)) {
+            if (presentes.has(slug))
+                continue;
+            if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(slug))
+                continue;
+            const caminho = join(raiz, destino, "skills", slug, "SKILL.md");
+            if (await temLink(destino, slug)) {
+                conflitos.push(caminho);
+                continue;
+            }
+            const atual = await readFile(caminho, "utf8").catch((e) => {
+                if (e.code === "ENOENT")
+                    return null;
+                throw e;
+            });
+            if (atual !== null && hash(atual) !== assinatura) {
+                conflitos.push(caminho);
+                continue;
+            }
+            if (atual !== null) {
+                await rm(caminho);
+                removidos++;
+            }
+            delete proximo[slug];
+        }
+        await escreveAtomico(manifesto, JSON.stringify(proximo));
     }
-    return { escritos };
+    return { escritos, removidos, conflitos };
 }
 /**
  * Semeia as skills iniciais — so num projeto que ainda nao tem nenhuma.

package/dist/versao.d.ts

@@ -0,0 +1 @@
+export declare function versaoDoPacote(url: string, nome: string): Promise<string>;

package/dist/versao.js

@@ -0,0 +1,18 @@
+import { readFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+export async function versaoDoPacote(url, nome) {
+    let dir = dirname(fileURLToPath(url));
+    for (;;) {
+        try {
+            const p = JSON.parse(await readFile(join(dir, "package.json"), "utf8"));
+            if (p.name === nome)
+                return p.version;
+        }
+        catch { /* Procura o pacote do bin, não assume a profundidade do build. */ }
+        const pai = dirname(dir);
+        if (pai === dir)
+            throw new Error(`package.json de ${nome} não encontrado`);
+        dir = pai;
+    }
+}

package/dist/worker.d.ts

@@ -9,6 +9,7 @@
 export declare function achaOWorker(raiz: string): Promise<string | null>;
 export type Subida = {
     subiu: true;
+    log: string;
 } | {
     subiu: false;
     motivo: "sem-fila" | "sem-worker" | "falhou";

package/dist/worker.js

@@ -1,7 +1,8 @@
 import { spawn } from "node:child_process";
-import { access } from "node:fs/promises";
+import { access, mkdir, open } from "node:fs/promises";
 import { join } from "node:path";
 import { leConfigDaMaquina } from "./config.js";
+import { diretorioDoUsuario } from "./estado-local.js";
 /**
  * Subir o worker de embeddings quando ha fila esperando.
  *
@@ -65,15 +66,25 @@ export async function subiuOWorker(raiz, esperando) {
     if (!repo)
         return { subiu: false, motivo: "sem-worker" };
     try {
-        const filho = spawn("npx", ["pnpm@latest", "worker", "--uma-vez"], {
-            cwd: repo,
-            detached: true,
-            stdio: "ignore",
-            shell: process.platform === "win32",
-            windowsHide: true,
-        });
-        filho.unref();
-        return { subiu: true };
+        const dir = diretorioDoUsuario();
+        await mkdir(dir, { recursive: true });
+        const caminhoLog = join(dir, "worker.log");
+        const log = await open(caminhoLog, "a", 0o600);
+        try {
+            const filho = spawn("npx", ["pnpm@latest", "worker", "--uma-vez"], {
+                cwd: repo,
+                detached: true,
+                stdio: ["ignore", log.fd, log.fd],
+                shell: process.platform === "win32",
+                windowsHide: true,
+            });
+            await new Promise((resolve, reject) => { filho.once("spawn", resolve); filho.once("error", reject); });
+            filho.unref();
+            return { subiu: true, log: caminhoLog };
+        }
+        finally {
+            await log.close();
+        }
     }
     catch (erro) {
         return {

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "dd-harness",
-  "version": "0.30.0",
+  "version": "0.32.0",
   "type": "module",
-  "description": "Cliente do dd-harness: politica no inicio da sessao, e memoria por busca — nada em disco. Sem dependencia: fetch, crypto e fs sao do Node.",
+  "description": "Política, memória e integrações de Claude Code, Codex e Antigravity. CLI sem dependências de runtime.",
   "license": "UNLICENSED",
   "author": "Diego Dias",
   "keywords": [
@@ -34,7 +34,7 @@
     "dist"
   ],
   "engines": {
-    "node": ">=20"
+    "node": ">=20.3.0"
   },
   "scripts": {
     "typecheck": "tsc -p . --noEmit",