dd-harness 0.3.0 → 0.5.0

package/dist/init.js

@@ -1,37 +1,72 @@
 import { readFile, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 import { CAMINHO_CONFIG } from "./config.js";
-import { LINHA_DE_IMPORT } from "./materializa.js";
 /**
- * Prepara um repositorio para o dd-harness.
+ * O `.mcp.json` e sugerido, nunca escrito.
  *
- * Funciona nos dois casos, e o segundo e o que importa para a ambicao de adotar projeto
- * que ja existe: se nao ha `CLAUDE.md`, cria um com a linha de import; se **ja ha**,
- * acrescenta a linha ao que voce escreveu, sem tocar no resto. Adotar um projeto vira
- * uma linha, e nao um ritual de mover arquivo.
+ * O arquivo e do repositorio, pode ja declarar outros servidores, e mesclar JSON alheio e
+ * onde falha silenciosa nasce — entrada errada nao da erro, a ferramenta so nao aparece.
+ * Quem cola sabe o que colou.
  */
-const CABECALHO = `# CLAUDE.md
-
-Este arquivo é seu: escreva aqui o que for específico deste repositório.
-
-A linha abaixo importa a política gerenciada pelo dd-harness. **Não a remova** — sem
-ela a sessão abre sem protocolo, e nada avisa.
-`;
+export const SUGESTAO_MCP = `{
+  "mcpServers": {
+    "dd-harness": {
+      "command": "npx",
+      "args": ["-y", "dd-harness-mcp"]
+    }
+  }
+}`;
 /**
- * O `.mcp.json` e sugerido, nunca escrito.
+ * O hook que carrega a politica no inicio de cada sessao.
+ *
+ * E a garantia de que nenhuma sessao abre sem protocolo — o papel que antes era do
+ * arquivo materializado mais a linha de import. Vive num hook, e nao numa instrucao no
+ * `CLAUDE.md`, porque instrucao o modelo pode pular: o import quebrado falhava em
+ * silencio, e isso foi medido.
  *
- * Pelo mesmo motivo do `CLAUDE.md` da raiz: o arquivo e do repositorio, pode ja declarar
- * outros servidores, e mesclar JSON alheio e onde falha silenciosa nasce — entrada errada
- * nao da erro, a ferramenta so nao aparece. Quem cola sabe o que colou.
+ * Sugerido e nao escrito, pelo mesmo motivo do `.mcp.json`.
  */
-export const SUGESTAO_MCP = `{
-  "mcpServers": {
-    "dd-harness": {
-      "command": "npx",
-      "args": ["-y", "dd-harness-mcp"]
-    }
-  }
+export const SUGESTAO_HOOK = `{
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "dd-harness politica --hook",
+            "statusMessage": "Carregando a política do dd-harness..."
+          }
+        ]
+      }
+    ]
+  }
 }`;
+/**
+ * O que escrever num `AGENTS.md`, para agente que NAO e o Claude Code.
+ *
+ * O hook de `SessionStart` e um mecanismo do Claude Code: Codex, Cursor, Gemini CLI e
+ * Windsurf nao o executam. Nessas ferramentas nada carrega a politica sozinho — e o
+ * resultado e a mesma falha de sempre, a sessao abrindo sem protocolo sem avisar.
+ *
+ * O que resta la e o servidor MCP, que essas ferramentas suportam. Mas ferramenta
+ * disponivel nao e ferramenta chamada: sem uma instrucao explicita, o agente pode
+ * simplesmente nunca perguntar pela politica. Dai esta linha, que e curta de proposito —
+ * ela manda buscar a regra, nao repete a regra.
+ */
+export const SUGESTAO_AGENTS = `# AGENTS.md
+
+Este projeto tem um protocolo de trabalho que **não está neste arquivo**.
+
+**ANTES de qualquer outra coisa**, chame a ferramenta MCP \`ler_artefato\` com
+\`tipo: "politica"\` e siga o que ela devolver. É a primeira ação da sessão, antes
+de ler código, responder ou planejar.
+
+- Se a ferramenta não existir, o servidor MCP do dd-harness não está declarado:
+  avise o usuário e **não modifique nada** até ele resolver.
+- Se ela devolver vazio, este projeto nunca foi briefado — diga isso ao usuário.
+
+O Claude Code carrega a política sozinho, por hook. Nas outras ferramentas, a
+chamada acima é o que substitui esse hook.`;
 async function declaraMcp(raiz) {
     try {
         const cru = await readFile(join(raiz, ".mcp.json"), "utf8");
@@ -43,6 +78,26 @@ async function declaraMcp(raiz) {
         return "a-declarar";
     }
 }
+/**
+ * O hook ja esta declarado?
+ *
+ * Procura pelo COMANDO, nao pela forma: `settings.json` aceita varios formatos de
+ * matcher, e quem ja tem o hook pode te-lo escrito de outro jeito. O que importa e se
+ * `dd-harness politica` roda no inicio da sessao.
+ */
+async function declaraHook(raiz) {
+    for (const arquivo of [".claude/settings.json", ".claude/settings.local.json"]) {
+        try {
+            const cru = await readFile(join(raiz, arquivo), "utf8");
+            if (cru.includes("dd-harness politica"))
+                return "ja-declarado";
+        }
+        catch {
+            // Sem arquivo: segue para o proximo.
+        }
+    }
+    return "a-declarar";
+}
 export async function init(raiz, dados) {
     const caminhoConfig = join(raiz, CAMINHO_CONFIG);
     let config = "ja-existia";
@@ -58,27 +113,26 @@ export async function init(raiz, dados) {
         await writeFile(caminhoConfig, `${JSON.stringify(conteudo, null, 2)}\n`, "utf8");
         config = "criada";
     }
-    const caminhoClaude = join(raiz, "CLAUDE.md");
-    let claudeMd;
-    let atual = null;
+    return {
+        config,
+        mcp: await declaraMcp(raiz),
+        hook: await declaraHook(raiz),
+        agents: await apontaNoAgents(raiz),
+    };
+}
+/**
+ * O `AGENTS.md` ja manda buscar a politica?
+ *
+ * Procura pela CHAMADA (`ler_artefato`), nao por uma frase exata: quem ja escreveu a
+ * instrucao pode te-la redigido de outro jeito, e sugerir de novo por causa de palavra
+ * diferente e ruido.
+ */
+async function apontaNoAgents(raiz) {
     try {
-        atual = await readFile(caminhoClaude, "utf8");
+        const cru = await readFile(join(raiz, "AGENTS.md"), "utf8");
+        return cru.includes("ler_artefato") ? "ja-aponta" : "a-apontar";
     }
     catch {
-        atual = null;
-    }
-    if (atual === null) {
-        await writeFile(caminhoClaude, `${CABECALHO}\n${LINHA_DE_IMPORT}\n`, "utf8");
-        claudeMd = "criado";
-    }
-    else if (atual.includes(LINHA_DE_IMPORT)) {
-        claudeMd = "ja-tinha-a-linha";
-    }
-    else {
-        // Acrescenta no fim, sem reescrever nada do que ja estava la.
-        const separador = atual.endsWith("\n") ? "\n" : "\n\n";
-        await writeFile(caminhoClaude, `${atual}${separador}${LINHA_DE_IMPORT}\n`, "utf8");
-        claudeMd = "linha-acrescentada";
+        return "a-apontar";
     }
-    return { config, claudeMd, mcp: await declaraMcp(raiz) };
 }

package/dist/politica.d.ts

@@ -15,7 +15,7 @@
  * A diferenca entre as duas ultimas e o que o `GET /api/v1/artefatos` responde: `404` e
  * "nao ha projeto"; `200` com `politica` nula e "existe, nunca briefado".
  */
-export type ResultadoDaPolitica = {
+export type ResultadoDaPolitica = ({
     estado: "ok";
     conteudo: string;
 } | {
@@ -23,5 +23,11 @@ export type ResultadoDaPolitica = {
 } | {
     estado: "inalcancavel";
     motivo: string;
+}) & {
+    /**
+     * Memorias esperando o worker. Vem de carona no mesmo payload da politica — o hook ja
+     * faz esta chamada, entao saber o estado da fila custa zero requisicao.
+     */
+    esperandoIndexacao?: number;
 };
 export declare function buscaPolitica(raiz: string): Promise<ResultadoDaPolitica>;

package/dist/politica.js

@@ -23,10 +23,11 @@ export async function buscaPolitica(raiz) {
         }
         const payload = (await resposta.json());
         const conteudo = payload.politica?.trim();
+        const esperandoIndexacao = payload.esperando_indexacao ?? 0;
         // Vazio e nulo sao a mesma coisa aqui, e os dois significam "nunca foi escrita".
         if (!conteudo)
-            return { estado: "sem-politica" };
-        return { estado: "ok", conteudo };
+            return { estado: "sem-politica", esperandoIndexacao };
+        return { estado: "ok", conteudo, esperandoIndexacao };
     }
     catch (erro) {
         return { estado: "inalcancavel", motivo: mensagem(erro) };

package/dist/reancorar.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Trocar o alvo de uma ancora, sem reescrever a memoria.
+ *
+ * O caso: uma refatoracao move um arquivo, e toda memoria ancorada nele passa a acusar
+ * "alvo ausente". O `check --commit` cruza isso com os renames do git e diz para onde o
+ * conteudo foi; este comando aplica a troca.
+ *
+ * Separado de `editar` de proposito: editar exige o markdown inteiro e mexe no conteudo,
+ * que nao e o que mudou aqui. Reancorar troca um endereco e mais nada — misturar as duas
+ * coisas convidaria a reescrever o corpo de memoria enquanto se conserta um caminho.
+ */
+export declare function reancora(raiz: string, endereco: string, de: string, para: string): Promise<{
+    endereco: string;
+    de: string;
+    para: string;
+}>;

package/dist/reancorar.js

@@ -0,0 +1,48 @@
+import { cabecalhos, credencial, pede, recusa } from "./api.js";
+import {} from "./curar.js";
+/**
+ * Trocar o alvo de uma ancora, sem reescrever a memoria.
+ *
+ * O caso: uma refatoracao move um arquivo, e toda memoria ancorada nele passa a acusar
+ * "alvo ausente". O `check --commit` cruza isso com os renames do git e diz para onde o
+ * conteudo foi; este comando aplica a troca.
+ *
+ * Separado de `editar` de proposito: editar exige o markdown inteiro e mexe no conteudo,
+ * que nao e o que mudou aqui. Reancorar troca um endereco e mais nada — misturar as duas
+ * coisas convidaria a reescrever o corpo de memoria enquanto se conserta um caminho.
+ */
+export async function reancora(raiz, endereco, de, para) {
+    const { config, token } = await credencial(raiz);
+    const url = new URL(`${config.api}/api/v1/memorias/${endereco}`);
+    url.searchParams.set("tenant", config.tenant);
+    url.searchParams.set("projeto", config.projeto);
+    const leitura = await pede(url, { headers: cabecalhos(token) });
+    if (!leitura.ok)
+        await recusa(leitura);
+    const memoria = (await leitura.json());
+    if (!memoria.ancoras.some((a) => a.valor === de)) {
+        throw new Error(`${endereco} não tem âncora em "${de}". Âncoras atuais: ` +
+            (memoria.ancoras.map((a) => a.valor).join(", ") || "nenhuma"));
+    }
+    const novas = memoria.ancoras.map((a) => (a.valor === de ? { ...a, valor: para } : a));
+    // Reaproveita o PATCH de edicao: ele recebe a memoria inteira, entao mandamos o que ja
+    // estava la com a ancora trocada. Uma porta so para escrever memoria, e nao duas.
+    const envio = await pede(`${config.api}/api/v1/memorias/${endereco}`, {
+        method: "PATCH",
+        headers: cabecalhos(token, true),
+        body: JSON.stringify({
+            tenant: config.tenant,
+            projeto: config.projeto,
+            titulo: memoria.titulo,
+            resumo: memoria.resumo,
+            corpo: memoria.corpo,
+            dano: memoria.dano,
+            invisibilidade: memoria.invisibilidade,
+            externalidade: memoria.externalidade,
+            ancoras: novas.map((a) => a.valor),
+        }),
+    });
+    if (!envio.ok)
+        await recusa(envio);
+    return { endereco, de, para };
+}

package/dist/worker.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Subir o worker de embeddings quando ha fila esperando.
+ *
+ * O worker nao esta hospedado (decisao de custo, registrada no ROADMAP): roda local, a
+ * mao. O problema disso e a degradacao SILENCIOSA — a memoria e gravada, a busca responde
+ * `semantica: true` porque a CONSULTA foi vetorizada, e mesmo assim nao acha nada, porque
+ * a BASE ainda nao tem vetor. Quem procura conclui "nao existe" quando o certo era
+ * "ainda nao indexei".
+ *
+ * Por isso o hook de sessao sobe o worker sozinho. Duas travas, e as duas importam:
+ *
+ * - **So sobe quando ha fila.** O hook roda em TODA sessao, inclusive nas que so leem
+ *   codigo. Subir com a fila vazia gastaria chamada de embedding sem ninguem ter pedido.
+ * - **So no repositorio que TEM o worker.** Ele vive neste monorepo, nao no repositorio
+ *   consumidor: la o `pnpm worker` nao existe, e tentar rodar daria erro a cada sessao.
+ */
+/** O worker vive aqui dentro. Noutro repositorio, nao ha o que subir. */
+export declare function temWorkerLocal(raiz: string): Promise<boolean>;
+export type Subida = {
+    subiu: true;
+} | {
+    subiu: false;
+    motivo: "sem-fila" | "sem-worker" | "falhou";
+    detalhe?: string;
+};
+/**
+ * Dispara um lote e devolve na hora — nao espera terminar.
+ *
+ * `--uma-vez` e nao o modo continuo: o hook de sessao nao pode deixar processo de pe que
+ * ninguem mandou subir, e um lote basta para o caso comum (as memorias gravadas na sessao
+ * anterior). Fila grande volta a aparecer na proxima sessao, e ai o numero cresce em vez
+ * de sumir — que e o sinal de que esta na hora de hospedar de verdade.
+ *
+ * `unref()` solta o processo do pai: sem isso o hook so retornaria quando o worker
+ * terminasse, e a sessao ficaria esperando embedding para abrir.
+ */
+export declare function subiuOWorker(raiz: string, esperando: number): Promise<Subida>;

package/dist/worker.js

@@ -0,0 +1,65 @@
+import { spawn } from "node:child_process";
+import { access } from "node:fs/promises";
+import { join } from "node:path";
+/**
+ * Subir o worker de embeddings quando ha fila esperando.
+ *
+ * O worker nao esta hospedado (decisao de custo, registrada no ROADMAP): roda local, a
+ * mao. O problema disso e a degradacao SILENCIOSA — a memoria e gravada, a busca responde
+ * `semantica: true` porque a CONSULTA foi vetorizada, e mesmo assim nao acha nada, porque
+ * a BASE ainda nao tem vetor. Quem procura conclui "nao existe" quando o certo era
+ * "ainda nao indexei".
+ *
+ * Por isso o hook de sessao sobe o worker sozinho. Duas travas, e as duas importam:
+ *
+ * - **So sobe quando ha fila.** O hook roda em TODA sessao, inclusive nas que so leem
+ *   codigo. Subir com a fila vazia gastaria chamada de embedding sem ninguem ter pedido.
+ * - **So no repositorio que TEM o worker.** Ele vive neste monorepo, nao no repositorio
+ *   consumidor: la o `pnpm worker` nao existe, e tentar rodar daria erro a cada sessao.
+ */
+/** O worker vive aqui dentro. Noutro repositorio, nao ha o que subir. */
+export async function temWorkerLocal(raiz) {
+    try {
+        await access(join(raiz, "src", "worker", "indexador.ts"));
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Dispara um lote e devolve na hora — nao espera terminar.
+ *
+ * `--uma-vez` e nao o modo continuo: o hook de sessao nao pode deixar processo de pe que
+ * ninguem mandou subir, e um lote basta para o caso comum (as memorias gravadas na sessao
+ * anterior). Fila grande volta a aparecer na proxima sessao, e ai o numero cresce em vez
+ * de sumir — que e o sinal de que esta na hora de hospedar de verdade.
+ *
+ * `unref()` solta o processo do pai: sem isso o hook so retornaria quando o worker
+ * terminasse, e a sessao ficaria esperando embedding para abrir.
+ */
+export async function subiuOWorker(raiz, esperando) {
+    if (esperando <= 0)
+        return { subiu: false, motivo: "sem-fila" };
+    if (!(await temWorkerLocal(raiz))) {
+        return { subiu: false, motivo: "sem-worker" };
+    }
+    try {
+        const filho = spawn("npx", ["pnpm@latest", "worker", "--uma-vez"], {
+            cwd: raiz,
+            detached: true,
+            stdio: "ignore",
+            shell: process.platform === "win32",
+            windowsHide: true,
+        });
+        filho.unref();
+        return { subiu: true };
+    }
+    catch (erro) {
+        return {
+            subiu: false,
+            motivo: "falhou",
+            detalhe: erro instanceof Error ? erro.message : String(erro),
+        };
+    }
+}

package/package.json

@@ -1,44 +1,44 @@
-{
-  "name": "dd-harness",
-  "version": "0.3.0",
-  "type": "module",
-  "description": "Materializa politica, briefing e Brain do dd-harness no repositorio. Sem dependencia: fetch, crypto e fs sao do Node.",
-  "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"
-  },
-  "scripts": {
-    "typecheck": "tsc -p . --noEmit",
-    "build": "tsc -p tsconfig.build.json",
-    "prepublishOnly": "npm run build"
-  }
-}
+{
+  "name": "dd-harness",
+  "version": "0.5.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.",
+  "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"
+  },
+  "scripts": {
+    "typecheck": "tsc -p . --noEmit",
+    "build": "tsc -p tsconfig.build.json",
+    "prepublishOnly": "npm run build"
+  }
+}