dd-harness 0.40.0 → 0.41.0

package/dist/artefato.d.ts

@@ -23,13 +23,40 @@ export declare function leArtefato(raiz: string, tipo: TipoDeArtefato): Promise<
     existe: boolean;
     atualizadaEm: string | null;
 }>;
+/** O que o `PUT` devolve. `sem_alteracao`: o texto era igual ao atual e nao virou versao. */
+export type EscritaDeArtefato = {
+    artefato: string;
+    criou: boolean;
+    tamanho: number;
+    versao: number;
+    sem_alteracao: boolean;
+};
 /**
  * Substituicao total, nao append: quem quer acrescentar um paragrafo le, concatena e
  * reenvia. Conteudo vazio e valido e significa "apagar" — a linha fica no banco, guardando
  * quem mexeu por ultimo.
+ *
+ * Toda escrita vira uma versao numerada no servico, e `resumo` e a linha que o historico
+ * guarda sobre ela: o que mudou e por que.
  */
-export declare function escreveArtefato(raiz: string, tipo: TipoDeArtefato, conteudo: string, atualizadaEm: string | null): Promise<{
-    artefato: string;
-    criou: boolean;
+export declare function escreveArtefato(raiz: string, tipo: TipoDeArtefato, conteudo: string, atualizadaEm: string | null, resumo: string): Promise<EscritaDeArtefato>;
+export type VersaoDeArtefato = {
+    versao: number;
+    resumo: string;
+    criada_em: string;
     tamanho: number;
+};
+/**
+ * O historico do artefato: a lista de versoes, da mais recente para a mais antiga. Nao
+ * entra no boot — chega so quando alguem precisa entender por que o texto esta assim.
+ */
+export declare function leVersoesDoArtefato(raiz: string, tipo: TipoDeArtefato): Promise<VersaoDeArtefato[]>;
+/**
+ * Uma linha por versao, e nao tabela: o resumo e texto livre, e um `|` dentro dele
+ * quebraria a tabela markdown que o agente le.
+ */
+export declare function formataHistorico(tipo: TipoDeArtefato, versoes: VersaoDeArtefato[]): string;
+/** O texto integral de uma versao antiga, com o resumo do que ela mudou. */
+export declare function leVersaoDoArtefato(raiz: string, tipo: TipoDeArtefato, versao: number): Promise<Omit<VersaoDeArtefato, "tamanho"> & {
+    conteudo: string;
 }>;

package/dist/artefato.js

@@ -27,8 +27,11 @@ export async function leArtefato(raiz, tipo) {
  * Substituicao total, nao append: quem quer acrescentar um paragrafo le, concatena e
  * reenvia. Conteudo vazio e valido e significa "apagar" — a linha fica no banco, guardando
  * quem mexeu por ultimo.
+ *
+ * Toda escrita vira uma versao numerada no servico, e `resumo` e a linha que o historico
+ * guarda sobre ela: o que mudou e por que.
  */
-export async function escreveArtefato(raiz, tipo, conteudo, atualizadaEm) {
+export async function escreveArtefato(raiz, tipo, conteudo, atualizadaEm, resumo) {
     const { config, token } = await credencial(raiz);
     const resposta = await pede(`${config.api}/api/v1/artefatos`, {
         method: "PUT",
@@ -43,6 +46,7 @@ export async function escreveArtefato(raiz, tipo, conteudo, atualizadaEm) {
             projeto: config.projeto,
             tipo,
             conteudo,
+            resumo,
         }),
     });
     if (!resposta.ok)
@@ -52,3 +56,42 @@ export async function escreveArtefato(raiz, tipo, conteudo, atualizadaEm) {
     });
     return (await jsonDaEscrita(resposta));
 }
+/**
+ * O historico do artefato: a lista de versoes, da mais recente para a mais antiga. Nao
+ * entra no boot — chega so quando alguem precisa entender por que o texto esta assim.
+ */
+export async function leVersoesDoArtefato(raiz, tipo) {
+    const corpo = (await pedeHistorico(raiz, tipo));
+    return corpo.versoes;
+}
+/**
+ * Uma linha por versao, e nao tabela: o resumo e texto livre, e um `|` dentro dele
+ * quebraria a tabela markdown que o agente le.
+ */
+export function formataHistorico(tipo, versoes) {
+    if (versoes.length === 0)
+        return `O ${tipo} ainda não tem versões — nunca foi escrito.`;
+    return [
+        `Histórico do ${tipo} — ${versoes.length} versão(ões), da mais recente para a mais antiga:`,
+        "",
+        ...versoes.map((v, i) => `- v${v.versao}${i === 0 ? " (atual)" : ""} · ${v.criada_em.slice(0, 16).replace("T", " ")} · ` +
+            `${v.tamanho} caractere(s) — ${v.resumo}`),
+    ].join("\n");
+}
+/** O texto integral de uma versao antiga, com o resumo do que ela mudou. */
+export async function leVersaoDoArtefato(raiz, tipo, versao) {
+    return (await pedeHistorico(raiz, tipo, versao));
+}
+async function pedeHistorico(raiz, tipo, versao) {
+    const { config, token } = await credencial(raiz);
+    const url = new URL(`${config.api}/api/v1/artefatos/historico`);
+    url.searchParams.set("tenant", config.tenant);
+    url.searchParams.set("projeto", config.projeto);
+    url.searchParams.set("tipo", tipo);
+    if (versao !== undefined)
+        url.searchParams.set("versao", String(versao));
+    const resposta = await pede(url, { headers: cabecalhos(token) });
+    if (!resposta.ok)
+        await recusa(resposta);
+    return resposta.json();
+}

package/dist/sessao.js

@@ -1,11 +1,11 @@
 import { createHash, randomUUID } from "node:crypto";
 import { readFile } from "node:fs/promises";
-import { join } from "node:path";
+import { join, resolve } 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 { diretorioDoUsuario, estadoDoRepo, escreveAtomico, revisaoDoContexto } from "./estado-local.js";
 import { buscaPolitica } from "./politica.js";
 import { blocoDeSessao } from "./roadmap.js";
 import { leSkills, escrevePonteirosDeSkills } from "./skill.js";
@@ -14,21 +14,38 @@ 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`);
+const arquivoDaRaiz = (sessao, host) => join(diretorioDoUsuario(), "sessoes", `${hash(host + sessao)}.json`);
+async function raizDaSessao(sessao, host) {
+    try {
+        const lido = JSON.parse(await readFile(arquivoDaRaiz(sessao, host), "utf8"));
+        return typeof lido.raiz === "string" ? lido.raiz : null;
+    }
+    catch {
+        return null;
+    }
+}
+const mesmaRaiz = (a, b) => process.platform === "win32" ? resolve(a).toLowerCase() === resolve(b).toLowerCase() : resolve(a) === resolve(b);
 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) {
+async function estadoConhecido(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;
+        return e.identidade === await identidade(raiz) && Date.now() >= e.em ? e : null;
     }
     catch {
         return null;
     }
 }
+async function estadoAtual(raiz, sessao, host) {
+    const e = await estadoConhecido(raiz, sessao, host);
+    if (!e || Date.now() - e.em >= PRAZO)
+        return null;
+    if (e.estado === "ok" && e.revisao !== await revisaoDoContexto(raiz))
+        return null;
+    return e;
+}
 export function saidaDoBoot(host, contexto, ok) {
     return host === "antigravity"
         ? { injectSteps: contexto ? [{ ephemeralMessage: contexto }] : [] }
@@ -39,7 +56,9 @@ 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 raiz = await achaRaiz(c.raiz).catch(() => raizDaSessao(c.sessao, host));
+    if (!raiz)
+        throw new Error("dd-harness: projeto não encontrado. Abra a sessão a partir de um projeto configurado.");
     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";
@@ -85,6 +104,7 @@ export async function abreSessao(host, entrada) {
         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() }));
+    await escreveAtomico(arquivoDaRaiz(c.sessao, host), JSON.stringify({ raiz }));
     return saidaDoBoot(host, contexto, r.estado !== "inalcancavel");
 }
 export function saidaDaGuarda(host, motivo, contexto) {
@@ -96,7 +116,7 @@ export function saidaDaGuarda(host, motivo, 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)$/;
+const LEITURA_MCP = /^mcp__dd[-_]harness__(ler_artefato|ler_historico_artefato|ler_roadmap|ler_changelog|listar_skills|ler_skill|ler_memoria|buscar_memoria)$/;
 /**
  * O que um projeto SEM politica precisa para ganhar uma.
  *
@@ -113,44 +133,64 @@ const LEITURA_MCP = /^mcp__dd[-_]harness__(ler_artefato|ler_roadmap|ler_changelo
 const ONBOARDING = /^(ToolSearch|mcp__dd[-_]harness__(escrever_artefato|criar_pasta|criar_projeto))$/;
 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;
+    const vinculada = c.sessao ? await raizDaSessao(c.sessao, host) : null;
+    const atual = await achaRaiz(c.raiz).catch(() => null);
+    if (vinculada && atual && !mesmaRaiz(vinculada, atual)) {
+        return saidaDaGuarda(host, "dd-harness: esta sessão pertence a outro projeto. Abra uma sessão neste projeto para carregar sua política e seu briefing.");
+    }
+    const raiz = atual ?? vinculada;
+    if (!raiz) {
+        if (LEITURA.test(c.ferramenta) || LEITURA_MCP.test(c.ferramenta))
+            return saidaDaGuarda(host);
+        return saidaDaGuarda(host, "dd-harness: esta sessão não tem projeto associado. Volte ao projeto configurado e abra uma sessão nele; não rode `dd-harness start` na pasta de rascunho.");
+    }
+    const edicoes = edicoesDaChamada(c);
+    for (const edicao of edicoes) {
+        const projetoDoArquivo = await achaRaiz(edicao.arquivo).catch(() => null);
+        if (projetoDoArquivo && !mesmaRaiz(projetoDoArquivo, raiz)) {
+            return saidaDaGuarda(host, "dd-harness: o arquivo pertence a outro projeto. Abra uma sessão nesse projeto antes de editá-lo.");
+        }
+    }
+    let e = c.sessao ? await estadoAtual(raiz, c.sessao, host) : null;
+    let contextoAtualizado = "";
     if (e?.estado !== "ok") {
         if (LEITURA.test(c.ferramenta) || LEITURA_MCP.test(c.ferramenta))
             return saidaDaGuarda(host);
-        // O dia zero de um projeto novo trava num ciclo: gravar o briefing exige a guarda
-        // liberada, e a guarda so libera com briefing gravado. `estadoAtual` devolve `null`
-        // tanto para "projeto novo" quanto para "sessao expirada", entao o estado local nao
-        // distingue os dois — quem sabe e o SERVICO. Se ele diz que nao ha politica, este
-        // projeto ainda esta em onboarding e as ferramentas de escreve-lo passam.
+        const anterior = c.sessao ? await estadoConhecido(raiz, c.sessao, host) : null;
+        // Projeto novo so pode completar o briefing se as ferramentas que o escrevem passarem.
+        // Quem distingue onboarding de contexto indisponivel e o servico.
         //
         // Nao e afrouxamento: o que passa aqui e so o que CONSTROI o contexto obrigatorio, e
         // so enquanto ele nao existe. Na primeira politica gravada, este caminho fecha sozinho.
+        const revisao = await revisaoDoContexto(raiz);
         const r = await buscaPolitica(raiz).catch(() => null);
         if (ONBOARDING.test(c.ferramenta) && r?.estado === "sem-politica")
             return saidaDaGuarda(host);
-        // O briefing acabou de ser gravado NESTA sessao: o servico ja tem os dois, mas o boot
-        // desta sessao rodou quando nao havia nada, e o estado local ficou velho. O agente sai
-        // do onboarding direto para um segundo bloqueio, sem nada indicando o que fazer —
-        // medido no dd-playwright, onde ele concluiu sozinho que precisava reiniciar e pediu
-        // ao usuario.
-        //
-        // Continua NEGANDO, e de proposito: e o SessionStart que entrega politica e briefing ao
-        // modelo, e liberar aqui daria trabalho sem o contexto que a guarda existe para
-        // garantir. O que muda e a mensagem — quem le passa a saber que o projeto esta pronto e
-        // que falta so reabrir, em vez de procurar o que ainda estaria faltando.
-        if (r?.estado === "ok") {
+        if (r?.estado === "ok" && (anterior?.estado === "ok" || anterior?.estado === "sem-politica")) {
+            if (revisao !== await revisaoDoContexto(raiz)) {
+                return saidaDaGuarda(host, "dd-harness: o contexto mudou durante a atualização. Repita a chamada para carregar a versão atual.");
+            }
+            await guardaCache(raiz, { memorias: r.memorias ?? [] });
+            e = { identidade: anterior.identidade, revisao, ciclo: randomUUID(), estado: "ok", em: Date.now() };
+            contextoAtualizado = "dd-harness: política e briefing atualizados nesta sessão. Este contexto substitui as versões anteriores:\n\n" +
+                r.conteudo + blocoDeSessao(r.roadmap);
+        }
+        else if (r?.estado === "ok") {
             return saidaDaGuarda(host, "dd-harness: política e briefing JÁ EXISTEM no serviço, mas o boot " +
-                "desta sessão rodou antes de eles existirem — por isso o contexto não chegou ao modelo. " +
+                "desta sessão não foi validado — por isso o contexto não chegou ao modelo. " +
                 "Nada falta gravar: **reabra a sessão** para o boot carregá-los. " +
                 "Enquanto isso, leitura (Read/Glob/Grep) e as ferramentas de leitura do dd-harness continuam liberadas.");
         }
-        return saidaDaGuarda(host, "dd-harness: política e briefing não foram carregados nesta sessão/projeto. " +
-            "Se este projeto é novo, conduza o briefing e grave os dois com `escrever_artefato`; " +
-            "se não, reabra a sessão para o boot rodar.");
+        else if (r?.estado === "inalcancavel") {
+            return saidaDaGuarda(host, `dd-harness: não foi possível atualizar política e briefing: ${r.motivo}. Confira a conexão e repita a chamada.`);
+        }
+        else {
+            return saidaDaGuarda(host, "dd-harness: política e briefing não foram carregados nesta sessão/projeto. " +
+                "Se este projeto é novo, conduza o briefing e grave os dois com `escrever_artefato`; " +
+                "se não, confira a conexão e reabra a sessão para o boot rodar.");
+        }
     }
-    const edicoes = edicoesDaChamada(c);
-    const avisos = [];
+    const avisos = contextoAtualizado ? [contextoAtualizado] : [];
     if (edicoes.length && !await leCache(raiz)) {
         const r = await buscaPolitica(raiz);
         if (r.estado !== "ok") {
@@ -167,5 +207,11 @@ export async function guardaSessao(host, entrada) {
         if (r.hookSpecificOutput.additionalContext)
             avisos.push(r.hookSpecificOutput.additionalContext);
     }
+    if (contextoAtualizado) {
+        if (e.revisao !== await revisaoDoContexto(raiz)) {
+            return saidaDaGuarda(host, "dd-harness: o contexto mudou durante a atualização. Repita a chamada para carregar a versão atual.");
+        }
+        await escreveAtomico(arquivo(raiz, c.sessao, host), JSON.stringify(e));
+    }
     return saidaDaGuarda(host, undefined, avisos.join("\n\n"));
 }

package/package.json

@@ -1,44 +1,44 @@
-{
-  "name": "dd-harness",
-  "version": "0.40.0",
-  "type": "module",
-  "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": [
-    "claude-code",
-    "ai-agents",
-    "memory",
-    "brain",
-    "cli"
-  ],
-  "homepage": "https://dd-harness.vercel.app",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/diegodias93/dd-harness-online.git",
-    "directory": "packages/cli"
-  },
-  "bin": {
-    "dd-harness": "dist/index.js"
-  },
-  "//exports": "Aponta para `dist` porque quem IMPORTA isto em tempo de execucao e o Node, que nao executa TypeScript. Nao aponte para `src`: o Node segue os imports relativos de dentro do arquivo e tenta abrir `./api.js` ao lado do `.ts`, que nao existe. Quem consome no workspace e o `packages/mcp`, e ele compila o fonte do CLI junto (ver o tsconfig.build.json dele) em vez de depender deste campo — assim o build funciona num checkout limpo, sem `dist` previo.",
-  "exports": {
-    "./api": "./dist/api.js",
-    "./buscar": "./dist/buscar.js",
-    "./curar": "./dist/curar.js",
-    "./gravar": "./dist/gravar.js",
-    "./pasta": "./dist/pasta.js",
-    "./projeto": "./dist/projeto.js"
-  },
-  "files": [
-    "dist"
-  ],
-  "engines": {
-    "node": ">=20.3.0"
-  },
-  "scripts": {
-    "typecheck": "tsc -p . --noEmit",
-    "build": "tsc -p tsconfig.build.json",
-    "prepublishOnly": "npm run build"
-  }
-}
+{
+  "name": "dd-harness",
+  "version": "0.41.0",
+  "type": "module",
+  "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": [
+    "claude-code",
+    "ai-agents",
+    "memory",
+    "brain",
+    "cli"
+  ],
+  "homepage": "https://dd-harness.vercel.app",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/diegodias93/dd-harness-online.git",
+    "directory": "packages/cli"
+  },
+  "bin": {
+    "dd-harness": "dist/index.js"
+  },
+  "//exports": "Aponta para `dist` porque quem IMPORTA isto em tempo de execucao e o Node, que nao executa TypeScript. Nao aponte para `src`: o Node segue os imports relativos de dentro do arquivo e tenta abrir `./api.js` ao lado do `.ts`, que nao existe. Quem consome no workspace e o `packages/mcp`, e ele compila o fonte do CLI junto (ver o tsconfig.build.json dele) em vez de depender deste campo — assim o build funciona num checkout limpo, sem `dist` previo.",
+  "exports": {
+    "./api": "./dist/api.js",
+    "./buscar": "./dist/buscar.js",
+    "./curar": "./dist/curar.js",
+    "./gravar": "./dist/gravar.js",
+    "./pasta": "./dist/pasta.js",
+    "./projeto": "./dist/projeto.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=20.3.0"
+  },
+  "scripts": {
+    "typecheck": "tsc -p . --noEmit",
+    "build": "tsc -p tsconfig.build.json",
+    "prepublishOnly": "npm run build"
+  }
+}