dd-harness 0.1.3 → 0.3.0

package/dist/api.d.ts

@@ -0,0 +1,21 @@
+import { type ConfigDoRepo } from "./config.js";
+/**
+ * A fronteira com o servico: ler credencial e falar HTTP.
+ *
+ * Cada comando reimplementava as mesmas tres linhas — le config, le token, monta `fetch`
+ * com `Authorization` — e cada copia era uma chance de divergir na mensagem de erro.
+ * Aqui elas existem uma vez, e o servidor MCP consome as mesmas funcoes que o CLI: as
+ * duas portas falam com a API pelo mesmo caminho, entao corrigir uma corrige a outra.
+ */
+export type Credencial = {
+    config: ConfigDoRepo;
+    token: string;
+};
+export declare function credencial(raiz: string): Promise<Credencial>;
+/**
+ * O `erro` que a API devolve no corpo e mais util que o status, e e o que o agente le.
+ * Sem corpo interpretavel, o status ao menos diz que houve resposta.
+ */
+export declare function recusa(resposta: Response): Promise<never>;
+export declare function cabecalhos(token: string, comCorpo?: boolean): Record<string, string>;
+export declare function pede(url: string | URL, init?: RequestInit, tentativas?: number): Promise<Response>;

package/dist/api.js

@@ -0,0 +1,69 @@
+import { leConfigDoRepo, leToken } from "./config.js";
+export async function credencial(raiz) {
+    const config = await leConfigDoRepo(raiz);
+    const token = await leToken(config.api);
+    if (!token) {
+        throw new Error(`sem credencial para ${config.api}. Rode \`dd-harness login --token <token>\`.`);
+    }
+    return { config, token };
+}
+/**
+ * O `erro` que a API devolve no corpo e mais util que o status, e e o que o agente le.
+ * Sem corpo interpretavel, o status ao menos diz que houve resposta.
+ */
+export async function recusa(resposta) {
+    const { erro } = (await resposta.json().catch(() => ({})));
+    throw new Error(erro ?? `a API respondeu ${resposta.status}.`);
+}
+export function cabecalhos(token, comCorpo = false) {
+    return comCorpo
+        ? { Authorization: `Bearer ${token}`, "Content-Type": "application/json" }
+        : { Authorization: `Bearer ${token}` };
+}
+/**
+ * `fetch` com nova tentativa para falha transitoria.
+ *
+ * Medido em uso real: um `ECONNRESET` de conexao ociosa derrubou um `arquivar` que
+ * funcionou na segunda tentativa manual. Sem retry, falha de rede de um segundo vira erro
+ * final — e para um agente isso e a diferenca entre seguir sozinho e parar para pedir
+ * ajuda. Com varios agentes concorrendo, transitorio deixa de ser raro.
+ *
+ * O que NAO e repetido, e o cuidado que importa:
+ *
+ * - Erro de aplicacao (4xx). Token invalido ou memoria fora dos filtros nao melhora na
+ *   segunda tentativa; repetir so atrasa a mensagem que o agente precisa ler.
+ * - 5xx em requisicao que ESCREVE. `POST /memorias` pode ter gravado antes de a resposta
+ *   se perder, e repetir criaria duas. Perder a resposta de uma escrita que funcionou e
+ *   ruim; gravar duas vezes e pior.
+ *
+ * Entao: repete falha de REDE (o `fetch` nem chegou a receber resposta) sempre, e 5xx
+ * apenas quando o metodo e seguro de repetir.
+ */
+const IDEMPOTENTES = new Set(["GET", "HEAD", "PUT", "DELETE"]);
+const espera = (ms) => new Promise((r) => setTimeout(r, ms));
+export async function pede(url, init = {}, tentativas = 3) {
+    const metodo = (init.method ?? "GET").toUpperCase();
+    const podeRepetirErroDoServidor = IDEMPOTENTES.has(metodo);
+    let ultimoErro;
+    for (let tentativa = 1; tentativa <= tentativas; tentativa += 1) {
+        try {
+            const resposta = await fetch(url, init);
+            if (resposta.status >= 500 && podeRepetirErroDoServidor && tentativa < tentativas) {
+                await espera(tentativa * 400);
+                continue;
+            }
+            return resposta;
+        }
+        catch (erro) {
+            // Aqui o `fetch` falhou antes de qualquer resposta: DNS, conexao recusada,
+            // ECONNRESET. Nada foi processado do outro lado, entao repetir e seguro mesmo
+            // para POST.
+            ultimoErro = erro;
+            if (tentativa === tentativas)
+                break;
+            await espera(tentativa * 400);
+        }
+    }
+    const detalhe = ultimoErro instanceof Error ? ultimoErro.message : String(ultimoErro);
+    throw new Error(`não consegui falar com o serviço depois de ${tentativas} tentativas: ${detalhe}`);
+}

package/dist/argv.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Leitura de argumentos da linha de comando.
+ *
+ * Vive fora do `index.ts` porque aquele modulo executa o CLI ao ser importado
+ * (`principal()` no topo) — teste que o importasse rodaria o programa inteiro.
+ */
+/**
+ * Os termos livres de uma consulta, sem os pares `--flag valor`.
+ *
+ * Filtrar so o que comeca com `--` deixava o VALOR da flag para tras, e ele entrava na
+ * consulta: `buscar "efeito" --limite 2` virava a pergunta `"efeito 2"`. A busca roda, a
+ * resposta parece valida e responde a outra coisa — quem chamou nao tem como notar.
+ */
+export declare function termosDaConsulta(argv: string[]): string;

package/dist/argv.js

@@ -0,0 +1,27 @@
+/**
+ * Leitura de argumentos da linha de comando.
+ *
+ * Vive fora do `index.ts` porque aquele modulo executa o CLI ao ser importado
+ * (`principal()` no topo) — teste que o importasse rodaria o programa inteiro.
+ */
+/**
+ * Os termos livres de uma consulta, sem os pares `--flag valor`.
+ *
+ * Filtrar so o que comeca com `--` deixava o VALOR da flag para tras, e ele entrava na
+ * consulta: `buscar "efeito" --limite 2` virava a pergunta `"efeito 2"`. A busca roda, a
+ * resposta parece valida e responde a outra coisa — quem chamou nao tem como notar.
+ */
+export function termosDaConsulta(argv) {
+    const termos = [];
+    for (let i = 0; i < argv.length; i += 1) {
+        const atual = argv[i];
+        if (atual.startsWith("--")) {
+            // `--flag=valor` carrega o valor no proprio token; `--flag valor` consome o proximo.
+            if (!atual.includes("="))
+                i += 1;
+            continue;
+        }
+        termos.push(atual);
+    }
+    return termos.join(" ").trim();
+}

package/dist/artefato.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Ler e escrever a politica e o briefing do projeto.
+ *
+ * Ate aqui artefato so se editava pela interface, e isso deixava o agente sem saida para a
+ * unica coisa que ele mais precisa saber: a propria politica. O CLI exige que alguem ja
+ * tenha escrito nela que o CLI existe — e era justamente ela que estava fora de alcance.
+ */
+export type TipoDeArtefato = "politica" | "briefing";
+/**
+ * O `GET` devolve o payload inteiro (politica, briefing, pastas e memorias); aqui so o
+ * artefato pedido interessa.
+ *
+ * `null` e `""` significam a mesma coisa para quem le — "ainda nao existe" —, e a diferenca
+ * entre elas e detalhe de como a linha foi parar no banco. Quem chama recebe `existe`, que
+ * e a pergunta real.
+ */
+export declare function leArtefato(raiz: string, tipo: TipoDeArtefato): Promise<{
+    conteudo: string;
+    existe: 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.
+ */
+export declare function escreveArtefato(raiz: string, tipo: TipoDeArtefato, conteudo: string): Promise<{
+    artefato: string;
+    criou: boolean;
+    tamanho: number;
+}>;

package/dist/artefato.js

@@ -0,0 +1,42 @@
+import { cabecalhos, credencial, pede, recusa } from "./api.js";
+/**
+ * O `GET` devolve o payload inteiro (politica, briefing, pastas e memorias); aqui so o
+ * artefato pedido interessa.
+ *
+ * `null` e `""` significam a mesma coisa para quem le — "ainda nao existe" —, e a diferenca
+ * entre elas e detalhe de como a linha foi parar no banco. Quem chama recebe `existe`, que
+ * e a pergunta real.
+ */
+export async function leArtefato(raiz, tipo) {
+    const { config, token } = await credencial(raiz);
+    const url = new URL(`${config.api}/api/v1/artefatos`);
+    url.searchParams.set("tenant", config.tenant);
+    url.searchParams.set("projeto", config.projeto);
+    const resposta = await pede(url, { headers: cabecalhos(token) });
+    if (!resposta.ok)
+        await recusa(resposta);
+    const payload = (await resposta.json());
+    const conteudo = typeof payload[tipo] === "string" ? payload[tipo] : "";
+    return { conteudo, existe: conteudo.length > 0 };
+}
+/**
+ * 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.
+ */
+export async function escreveArtefato(raiz, tipo, conteudo) {
+    const { config, token } = await credencial(raiz);
+    const resposta = await pede(`${config.api}/api/v1/artefatos`, {
+        method: "PUT",
+        headers: cabecalhos(token, true),
+        body: JSON.stringify({
+            tenant: config.tenant,
+            projeto: config.projeto,
+            tipo,
+            conteudo,
+        }),
+    });
+    if (!resposta.ok)
+        await recusa(resposta);
+    return (await resposta.json());
+}

package/dist/buscar.d.ts

@@ -0,0 +1,20 @@
+/**
+ * `dd-harness buscar "<pergunta>"` — recuperacao por relevancia.
+ *
+ * O contraponto da ancora: ela e exata e responde "que memorias falam deste arquivo?";
+ * esta responde "o que ja aprendemos sobre isto?", que e a pergunta de quem ainda esta
+ * entendendo o problema e nem sabe qual arquivo abrir.
+ *
+ * Devolve endereco, nao conteudo: quem quiser o corpo abre o arquivo que o `sync` ja
+ * materializou. Assim a busca continua barata e o Brain em disco continua sendo a fonte.
+ */
+export type Achado = {
+    endereco: string;
+    titulo: string;
+    resumo: string;
+};
+export declare function busca(raiz: string, consulta: string, limite?: number): Promise<{
+    semantica: boolean;
+    provedor: string | null;
+    achados: Achado[];
+}>;

package/dist/buscar.js

@@ -1,21 +1,15 @@
-import { leConfigDoRepo, leToken } from "./config.js";
+import { cabecalhos, credencial, pede, recusa } from "./api.js";
 export async function busca(raiz, consulta, limite) {
-    const config = await leConfigDoRepo(raiz);
-    const token = await leToken(config.api);
-    if (!token) {
-        throw new Error(`sem credencial para ${config.api}. Rode \`dd-harness login --token <token>\`.`);
-    }
+    const { config, token } = await credencial(raiz);
     const url = new URL(`${config.api}/api/v1/busca`);
     url.searchParams.set("tenant", config.tenant);
     url.searchParams.set("projeto", config.projeto);
     url.searchParams.set("q", consulta);
     if (limite)
         url.searchParams.set("limite", String(limite));
-    const resposta = await fetch(url, { headers: { Authorization: `Bearer ${token}` } });
-    if (!resposta.ok) {
-        const { erro } = (await resposta.json().catch(() => ({})));
-        throw new Error(erro ?? `a API respondeu ${resposta.status}.`);
-    }
+    const resposta = await pede(url, { headers: cabecalhos(token) });
+    if (!resposta.ok)
+        await recusa(resposta);
     const lido = (await resposta.json());
     return { semantica: lido.semantica, provedor: lido.provedor, achados: lido.resultados };
 }

package/dist/check.d.ts

@@ -0,0 +1,68 @@
+import { type Tocada } from "./diff.js";
+import type { Brain } from "./materializa.js";
+/**
+ * `dd-harness check` — resolve as âncoras contra a árvore de trabalho.
+ *
+ * Mede cada alvo e manda o resultado ao serviço, que julga. Nunca falha o processo por
+ * encontrar deriva: sai com 0 e imprime. Deriva avisa, não bloqueia — bloqueio antes de
+ * o mecanismo ter reputação ensina o reflexo do `--no-verify`.
+ */
+export type Medicao = {
+    pasta: string;
+    memoria: string;
+    valor: string;
+    sha: string | null;
+    detalhe?: string;
+};
+export type ResultadoDoCheck = {
+    medidas: number;
+    ausentes: string[];
+    novas: number;
+    base: number;
+    jaAbertas: number;
+    /** Observacoes que fecharam sozinhas: o alvo voltou a bater com a linha de base. */
+    fechadas: number;
+    /** Memorias que falam do que o commit mudou. Vazio quando nao ha `--commit`. */
+    tocadas: Tocada[];
+};
+export type ResultadoDoStatus = {
+    /**
+     * O tamanho do acervo, por pasta. Sem isto, um agente que pergunta "o que ha no Brain
+     * deste projeto?" nao tem comando que responda — e a saida que resta e contar arquivo
+     * em disco, que acerta por acidente: memoria gravada e nao sincronizada nao esta la, e
+     * memoria arquivada sai do disco mas continua no indice, em `## Historico`.
+     */
+    acervo: {
+        ativas: number;
+        arquivadas: number;
+        porPasta: {
+            pasta: string;
+            quantas: number;
+        }[];
+    };
+    comDeriva: {
+        pasta: string;
+        memoria: string;
+        titulo: string;
+        abertas: number;
+    }[];
+    vencidas: {
+        pasta: string;
+        memoria: string;
+        titulo: string;
+    }[];
+    /**
+     * Memorias que o indexador desistiu de processar. Sem embedding elas somem da busca
+     * semantica e continuam aparecendo no acervo — o unico sintoma e procurar e nao achar.
+     */
+    travadasNaFila: number;
+};
+/** Separado do IO para poder ser testado sem rede: dado um Brain, o que se mede. */
+export declare function medeAsAncoras(raiz: string, brain: Brain): Promise<Medicao[]>;
+/**
+ * Somente leitura, de proposito: e o que roda na ABERTURA da sessao. Medir e reportar
+ * ali dentro faria toda sessao escrever no servico antes de a pessoa digitar qualquer
+ * coisa — caro, e o tipo de efeito colateral que ninguem espera de "abrir o editor".
+ */
+export declare function status(raiz: string): Promise<ResultadoDoStatus>;
+export declare function check(raiz: string, commit?: string): Promise<ResultadoDoCheck>;

package/dist/check.js

@@ -1,3 +1,4 @@
+import { pede } from "./api.js";
 import { leConfigDoRepo, leToken } from "./config.js";
 import { caminhosDoCommit, memoriasTocadas } from "./diff.js";
 import { mede } from "./medir.js";
@@ -29,7 +30,7 @@ async function buscaOBrain(raiz) {
         throw new Error(`sem credencial para ${config.api}. Rode \`dd-harness login --token <token>\`.`);
     }
     const parametros = `tenant=${encodeURIComponent(config.tenant)}&projeto=${encodeURIComponent(config.projeto)}`;
-    const resposta = await fetch(`${config.api}/api/v1/artefatos?${parametros}`, {
+    const resposta = await pede(`${config.api}/api/v1/artefatos?${parametros}`, {
         headers: { Authorization: `Bearer ${token}` },
     });
     if (resposta.status === 401) {
@@ -49,7 +50,17 @@ export async function status(raiz) {
     const { brain } = await buscaOBrain(raiz);
     const agora = Date.now();
     const ativas = brain.memorias.filter((m) => m.status === "ativa");
+    const porPasta = new Map();
+    for (const m of ativas)
+        porPasta.set(m.pasta, (porPasta.get(m.pasta) ?? 0) + 1);
     return {
+        acervo: {
+            ativas: ativas.length,
+            arquivadas: brain.memorias.length - ativas.length,
+            porPasta: [...porPasta]
+                .map(([pasta, quantas]) => ({ pasta, quantas }))
+                .sort((a, b) => a.pasta.localeCompare(b.pasta)),
+        },
         comDeriva: ativas
             .filter((m) => (m.deriva_aberta ?? 0) > 0)
             .map((m) => ({
@@ -61,6 +72,7 @@ export async function status(raiz) {
         vencidas: ativas
             .filter((m) => m.revisar_ate && new Date(m.revisar_ate).getTime() < agora)
             .map((m) => ({ pasta: m.pasta, memoria: m.slug, titulo: m.titulo })),
+        travadasNaFila: brain.travadas_na_fila ?? 0,
     };
 }
 export async function check(raiz, commit) {
@@ -74,7 +86,7 @@ export async function check(raiz, commit) {
     if (medicoes.length === 0) {
         return { medidas: 0, ausentes: [], novas: 0, base: 0, jaAbertas: 0, fechadas: 0, tocadas };
     }
-    const envio = await fetch(`${config.api}/api/v1/deriva`, {
+    const envio = await pede(`${config.api}/api/v1/deriva`, {
         method: "POST",
         headers: { ...cabecalhos, "Content-Type": "application/json" },
         body: JSON.stringify({

package/dist/config.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Duas configuracoes, em lugares diferentes de proposito.
+ *
+ * `.dd-harness.json` fica **no repositorio** e e versionado: diz qual projeto aquele
+ * repo consome, e isso e informacao do repo, nao da pessoa.
+ *
+ * A credencial fica **na maquina** (`~/.dd-harness/credentials.json`, modo 0600) e nunca
+ * no repo: token e da pessoa e da maquina, e commitado seria segredo publicado.
+ */
+export type ConfigDoRepo = {
+    api: string;
+    tenant: string;
+    projeto: string;
+    /** Onde o gerado vive. Muda-la move tudo de uma vez, menos o CLAUDE.md da raiz. */
+    pasta: string;
+};
+export declare const CAMINHO_CONFIG = ".dd-harness.json";
+export declare const CAMINHO_MANIFESTO = "dd-harness/manifest.json";
+export declare function leConfigDoRepo(raiz: string): Promise<ConfigDoRepo>;
+/**
+ * Credencial por origem da API: a mesma maquina pode falar com uma instalacao local e
+ * com a de producao, e misturar token entre as duas daria 401 confuso.
+ */
+export declare function leToken(api: string): Promise<string | null>;
+export declare function guardaToken(api: string, token: string): Promise<string>;
+export type Manifesto = {
+    etag: string | null;
+    arquivos: Record<string, string>;
+};
+export declare const manifestoVazio: () => Manifesto;
+export declare function leManifesto(raiz: string): Promise<Manifesto>;
+export declare function gravaManifesto(raiz: string, manifesto: Manifesto): Promise<void>;
+export declare const hashDe: (conteudo: string) => string;

package/dist/curar.d.ts

@@ -0,0 +1,12 @@
+export declare function edita(raiz: string, caminho: string): Promise<{
+    endereco: string;
+    ancoras: number;
+}>;
+export type Arquivamento = {
+    motivo: "obsoleta" | "incorreta" | "fora_dos_filtros";
+    substituidaPor?: string;
+};
+export declare function arquiva(raiz: string, endereco: string, opcoes: Arquivamento): Promise<{
+    endereco: string;
+    motivo: string;
+}>;

package/dist/curar.js

@@ -1,5 +1,7 @@
 import { readFile } from "node:fs/promises";
-import { leConfigDoRepo, leToken } from "./config.js";
+import { relative } from "node:path";
+import { cabecalhos, credencial, pede, recusa } from "./api.js";
+import { gravaManifesto, hashDe, leManifesto } from "./config.js";
 import { interpreta } from "./gravar.js";
 /**
  * Curadoria pelo agente: editar e arquivar.
@@ -12,25 +14,33 @@ import { interpreta } from "./gravar.js";
  * que o `sync` materializou e manda de volta. Um formato so para as duas operacoes, e o
  * que ele ja sabe ler.
  */
-async function credencial(raiz) {
-    const config = await leConfigDoRepo(raiz);
-    const token = await leToken(config.api);
-    if (!token) {
-        throw new Error(`sem credencial para ${config.api}. Rode \`dd-harness login --token <token>\`.`);
-    }
-    return { config, token };
-}
-async function recusa(resposta) {
-    const { erro } = (await resposta.json().catch(() => ({})));
-    throw new Error(erro ?? `a API respondeu ${resposta.status}.`);
+/**
+ * Depois que o servico aceita, o arquivo em disco deixa de ser "edicao nao enviada" — e o
+ * manifesto tem que saber, senao o `sync` seguinte para com "editado a mao" e a unica saida
+ * que resta e descartar o arquivo. O ciclo materializa-corrige-envia travava justamente
+ * aqui, com o servico ja atualizado.
+ *
+ * Guarda o hash do que foi enviado, nao do que o servico devolveria: o `sync` seguinte
+ * reescreve o arquivo na forma canonica quando o ETag mudar.
+ */
+async function marcaComoEnviado(raiz, caminho, conteudo) {
+    const chave = relative(raiz, caminho).split("\\").join("/");
+    const manifesto = await leManifesto(raiz);
+    // Arquivo de fora do repositorio (um rascunho em /tmp, por exemplo) nao esta no
+    // manifesto e nao deve entrar: o manifesto descreve o que o `sync` materializou.
+    if (!manifesto.arquivos[chave])
+        return;
+    manifesto.arquivos[chave] = hashDe(conteudo);
+    await gravaManifesto(raiz, manifesto);
 }
 export async function edita(raiz, caminho) {
     const { config, token } = await credencial(raiz);
-    const memoria = interpreta(await readFile(caminho, "utf8"));
+    const cru = await readFile(caminho, "utf8");
+    const memoria = interpreta(cru);
     const endereco = `${memoria.pasta}/${memoria.slug}`;
-    const resposta = await fetch(`${config.api}/api/v1/memorias/${endereco}`, {
+    const resposta = await pede(`${config.api}/api/v1/memorias/${endereco}`, {
         method: "PATCH",
-        headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json" },
+        headers: cabecalhos(token, true),
         body: JSON.stringify({
             tenant: config.tenant,
             projeto: config.projeto,
@@ -45,13 +55,14 @@ export async function edita(raiz, caminho) {
     });
     if (!resposta.ok)
         await recusa(resposta);
+    await marcaComoEnviado(raiz, caminho, cru);
     return { endereco, ancoras: memoria.ancoras.length };
 }
 export async function arquiva(raiz, endereco, opcoes) {
     const { config, token } = await credencial(raiz);
-    const resposta = await fetch(`${config.api}/api/v1/memorias/${endereco}`, {
+    const resposta = await pede(`${config.api}/api/v1/memorias/${endereco}`, {
         method: "DELETE",
-        headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json" },
+        headers: cabecalhos(token, true),
         body: JSON.stringify({
             tenant: config.tenant,
             projeto: config.projeto,

package/dist/diff.d.ts

@@ -0,0 +1,30 @@
+import type { Brain } from "./materializa.js";
+/**
+ * Quais memorias falam do que este commit mudou.
+ *
+ * E a peca que devolve a memoria ao code review. Tirar o Brain do repositorio tirou o
+ * revisor que o diff dava de graca — no modelo file-based a memoria estava ali, no
+ * caminho de quem mexia. Aqui ela volta pelo cruzamento: caminho do diff contra ancora.
+ *
+ * Repare que isto NAO e deriva. Deriva e "o alvo mudou desde a linha de base"; isto e
+ * "voce acabou de mexer no que esta memoria guarda" — util mesmo quando a base ainda
+ * nem foi medida, e util mesmo que a memoria continue valendo.
+ */
+/** Caminhos alterados num commit. Vazio quando o git nao responde — nunca quebra. */
+export declare function caminhosDoCommit(raiz: string, commit: string): Promise<string[]>;
+export type Tocada = {
+    pasta: string;
+    memoria: string;
+    titulo: string;
+    ancora: string;
+};
+/**
+ * Cruza caminhos com ancoras. A ancora casa quando e o proprio caminho ou quando e um
+ * diretorio que o contem — `supabase/migrations` tem que casar com a migration nova.
+ *
+ * Ancora de trecho (`arquivo.js#alvo`) casa pelo ARQUIVO: o `git diff-tree` devolve
+ * caminho puro, nunca com `#`, entao comparar o valor inteiro nao casava nunca — e em
+ * silencio, porque nao casar e resultado valido. O alvo continua no `Tocada.ancora`, que
+ * e o que a mensagem mostra: quem le precisa saber qual trecho a memoria guarda.
+ */
+export declare function memoriasTocadas(brain: Brain, caminhos: string[]): Tocada[];

package/dist/diff.js

@@ -30,6 +30,11 @@ export async function caminhosDoCommit(raiz, commit) {
 /**
  * Cruza caminhos com ancoras. A ancora casa quando e o proprio caminho ou quando e um
  * diretorio que o contem — `supabase/migrations` tem que casar com a migration nova.
+ *
+ * Ancora de trecho (`arquivo.js#alvo`) casa pelo ARQUIVO: o `git diff-tree` devolve
+ * caminho puro, nunca com `#`, entao comparar o valor inteiro nao casava nunca — e em
+ * silencio, porque nao casar e resultado valido. O alvo continua no `Tocada.ancora`, que
+ * e o que a mensagem mostra: quem le precisa saber qual trecho a memoria guarda.
  */
 export function memoriasTocadas(brain, caminhos) {
     const tocadas = [];
@@ -37,7 +42,8 @@ export function memoriasTocadas(brain, caminhos) {
         if (memoria.status !== "ativa")
             continue;
         for (const ancora of memoria.ancoras) {
-            const casa = caminhos.some((c) => c === ancora.valor || c.startsWith(`${ancora.valor}/`));
+            const alvo = ancora.valor.split("#")[0];
+            const casa = caminhos.some((c) => c === alvo || c.startsWith(`${alvo}/`));
             if (casa) {
                 tocadas.push({
                     pasta: memoria.pasta,

package/dist/gravar.d.ts

@@ -0,0 +1,30 @@
+/**
+ * `dd-harness gravar <arquivo.md>` — o caminho pelo qual o agente registra memoria.
+ *
+ * A entrada e um markdown no mesmo formato que o `sync` materializa, porque e o formato
+ * que o agente ja sabe ler: frontmatter, corpo, os tres filtros, ancoras. Escrever um
+ * arquivo e o que ele fazia no modelo file-based; aqui o arquivo vira requisicao em vez
+ * de virar commit.
+ *
+ * O arquivo nao e deixado no repositorio: quem materializa e o `sync`, a partir do
+ * servico. Gravar e depois sincronizar traz a memoria de volta ja com o endereco real —
+ * e evita a divergencia de ter uma copia escrita a mao ao lado da copia gerada.
+ */
+export type MemoriaLida = {
+    slug: string;
+    titulo: string;
+    resumo: string;
+    pasta: string;
+    corpo: string;
+    dano: string;
+    invisibilidade: string;
+    externalidade: string;
+    ancoras: string[];
+    tambemEm: string[];
+};
+export declare function interpreta(texto: string): MemoriaLida;
+export declare function grava(raiz: string, caminho: string): Promise<{
+    endereco: string;
+    ancoras: number;
+    projetos: number;
+}>;

package/dist/gravar.js

@@ -1,5 +1,5 @@
 import { readFile } from "node:fs/promises";
-import { leConfigDoRepo, leToken } from "./config.js";
+import { cabecalhos, credencial, pede, recusa } from "./api.js";
 const OBRIGATORIOS = ["name", "titulo", "description", "pasta"];
 /** Frontmatter simples: `chave: valor` por linha. Sem lib de YAML — nao ha aninhamento. */
 function leFrontmatter(texto) {
@@ -46,9 +46,18 @@ export function interpreta(texto) {
             throw new Error(`frontmatter sem \`${chave}\`.`);
     }
     // O corpo vai ate a secao dos filtros; dali para baixo e metadado, nao conteudo.
-    const corte = resto.search(/\n##\s+Os tr[êe]s filtros\s*\n/i);
-    if (corte === -1)
+    const cabecalhoDosFiltros = /\n##\s+Os tr[êe]s filtros\s*\n/gi;
+    const ocorrencias = [...resto.matchAll(cabecalhoDosFiltros)];
+    if (ocorrencias.length === 0)
         throw new Error("falta a seção `## Os três filtros`.");
+    // Duas ocorrencias tornam o arquivo ambiguo: cortar na primeira trunca o corpo (e os
+    // filtros ainda saem certos da segunda, entao grava e perde dado sem avisar), e cortar
+    // na ultima escolheria em silencio qual secao e a de verdade. Recusar diz o que houve.
+    if (ocorrencias.length > 1) {
+        throw new Error("a seção `## Os três filtros` aparece mais de uma vez — deixe só a real, " +
+            "ou reescreva a citação no corpo (por exemplo, entre crases).");
+    }
+    const corte = ocorrencias[0].index;
     const corpo = resto
         .slice(0, corte)
         .replace(/<!--[\s\S]*?-->/g, "")
@@ -74,15 +83,11 @@ export function interpreta(texto) {
     };
 }
 export async function grava(raiz, caminho) {
-    const config = await leConfigDoRepo(raiz);
-    const token = await leToken(config.api);
-    if (!token) {
-        throw new Error(`sem credencial para ${config.api}. Rode \`dd-harness login --token <token>\`.`);
-    }
+    const { config, token } = await credencial(raiz);
     const memoria = interpreta(await readFile(caminho, "utf8"));
-    const resposta = await fetch(`${config.api}/api/v1/memorias`, {
+    const resposta = await pede(`${config.api}/api/v1/memorias`, {
         method: "POST",
-        headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json" },
+        headers: cabecalhos(token, true),
         body: JSON.stringify({
             tenant: config.tenant,
             projeto: config.projeto,
@@ -98,10 +103,8 @@ export async function grava(raiz, caminho) {
             tambem_em: memoria.tambemEm,
         }),
     });
-    if (!resposta.ok) {
-        const { erro } = (await resposta.json().catch(() => ({})));
-        throw new Error(erro ?? `a API respondeu ${resposta.status}.`);
-    }
+    if (!resposta.ok)
+        await recusa(resposta);
     const { endereco } = (await resposta.json());
     return {
         endereco,

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};