dd-harness 0.1.0

package/LICENSE

@@ -0,0 +1,11 @@
+Copyright (c) 2026 Diego Dias
+
+Todos os direitos reservados.
+
+Este software é publicado no registro npm apenas para distribuição ao seu autor e a
+quem ele autorizar expressamente. Nenhuma permissão de uso, cópia, modificação,
+distribuição ou criação de obras derivadas é concedida por esta publicação.
+
+All rights reserved. This software is published to the npm registry for distribution
+to its author and to those he expressly authorizes. No permission to use, copy,
+modify, distribute, or create derivative works is granted by this publication.

package/README.md

@@ -0,0 +1,64 @@
+# dd-harness
+
+Materializa a **política**, o **briefing** e o **Brain** do
+[dd-harness](https://dd-harness.vercel.app) dentro do seu repositório, para que a sessão
+do agente de código abra já sabendo as regras e as decisões do projeto.
+
+Sem dependência: `fetch`, `crypto` e `fs` são do Node. Um CLI que vive pinado em
+repositório alheio precisa envelhecer bem, e cada dependência é uma chance de não
+envelhecer.
+
+## Instalação
+
+```sh
+npm install -g dd-harness
+```
+
+Ou sem instalar nada:
+
+```sh
+npx dd-harness sync
+```
+
+Requer Node 20 ou mais novo.
+
+## Uso
+
+```sh
+dd-harness init --tenant <espaço> --projeto <projeto>   # prepara o repositório
+dd-harness login --token <token>                        # credencial desta máquina
+dd-harness sync                                         # escreve os artefatos
+dd-harness check [--commit <sha>]                       # mede âncoras e reporta deriva
+dd-harness status                                       # só lê: o que espera julgamento
+```
+
+O token pessoal nasce na tela `/tokens` do serviço. Ele é guardado em
+`~/.dd-harness/credentials.json` (modo `0600`, por origem de API) — **fora** do
+repositório, para não viajar num commit.
+
+## O que aparece no seu repositório
+
+```
+.dd-harness.json      configuração (tenant, projeto, api) — escrita à mão
+CLAUDE.md             SEU arquivo; o sync nunca o reescreve
+dd-harness/           tudo o que é gerado
+  politica.md
+  BRIEFING.md
+  brain/
+  manifest.json
+```
+
+Na raiz fica apenas o **seu** `CLAUDE.md`, que importa a política com a linha
+`@dd-harness/politica.md`. Isso deixa conviverem a parte gerenciada e o que o
+repositório tem de próprio — adotar um projeto existente é acrescentar uma linha, não
+sobrescrever nada.
+
+O `sync` confere esse ponteiro a cada execução, inclusive quando o serviço não mudou:
+import quebrado ou linha ausente faz a sessão abrir **sem política e sem avisar**. Isso
+foi medido, não suposto.
+
+## Deriva
+
+`dd-harness check` mede as âncoras das memórias contra o estado real do repositório e
+reporta o que saiu do lugar. Com `--commit <sha>` ele também cruza as âncoras com o diff
+daquele commit — a memória volta ao code review. Nada bloqueia: avisa.

package/dist/check.js

@@ -0,0 +1,102 @@
+import { leConfigDoRepo, leToken } from "./config.js";
+import { caminhosDoCommit, memoriasTocadas } from "./diff.js";
+import { mede } from "./medir.js";
+/** Separado do IO para poder ser testado sem rede: dado um Brain, o que se mede. */
+export async function medeAsAncoras(raiz, brain) {
+    const medicoes = [];
+    for (const memoria of brain.memorias) {
+        // Memória arquivada não interessa: ela já saiu de circulação, e medir o alvo dela
+        // encheria a fila de deriva que ninguém vai resolver.
+        if (memoria.status !== "ativa")
+            continue;
+        for (const ancora of memoria.ancoras) {
+            const sha = await mede(raiz, ancora.valor);
+            medicoes.push({
+                pasta: memoria.pasta,
+                memoria: memoria.slug,
+                valor: ancora.valor,
+                sha,
+                ...(sha === null ? { detalhe: "alvo não encontrado na árvore de trabalho" } : {}),
+            });
+        }
+    }
+    return medicoes;
+}
+async function buscaOBrain(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>\`.`);
+    }
+    const parametros = `tenant=${encodeURIComponent(config.tenant)}&projeto=${encodeURIComponent(config.projeto)}`;
+    const resposta = await fetch(`${config.api}/api/v1/artefatos?${parametros}`, {
+        headers: { Authorization: `Bearer ${token}` },
+    });
+    if (resposta.status === 401) {
+        throw new Error("token recusado. Rode `dd-harness login --token <token>`.");
+    }
+    if (!resposta.ok) {
+        throw new Error(`a API respondeu ${resposta.status} ao buscar as âncoras.`);
+    }
+    return { config, token, brain: (await resposta.json()) };
+}
+/**
+ * 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 async function status(raiz) {
+    const { brain } = await buscaOBrain(raiz);
+    const agora = Date.now();
+    const ativas = brain.memorias.filter((m) => m.status === "ativa");
+    return {
+        comDeriva: ativas
+            .filter((m) => (m.deriva_aberta ?? 0) > 0)
+            .map((m) => ({
+            pasta: m.pasta,
+            memoria: m.slug,
+            titulo: m.titulo,
+            abertas: m.deriva_aberta ?? 0,
+        })),
+        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 })),
+    };
+}
+export async function check(raiz, commit) {
+    const { config, token, brain } = await buscaOBrain(raiz);
+    const cabecalhos = { Authorization: `Bearer ${token}` };
+    const medicoes = await medeAsAncoras(raiz, brain);
+    // O cruzamento com o diff so faz sentido quando ha um commit para olhar.
+    const tocadas = commit
+        ? memoriasTocadas(brain, await caminhosDoCommit(raiz, commit))
+        : [];
+    if (medicoes.length === 0) {
+        return { medidas: 0, ausentes: [], novas: 0, base: 0, jaAbertas: 0, tocadas };
+    }
+    const envio = await fetch(`${config.api}/api/v1/deriva`, {
+        method: "POST",
+        headers: { ...cabecalhos, "Content-Type": "application/json" },
+        body: JSON.stringify({
+            tenant: config.tenant,
+            projeto: config.projeto,
+            commit: commit ?? null,
+            medicoes,
+        }),
+    });
+    if (envio.status === 403) {
+        throw new Error("este token não pode reportar deriva. Crie outro na interface e refaça o login.");
+    }
+    if (!envio.ok) {
+        throw new Error(`a API respondeu ${envio.status} ao registrar as medições.`);
+    }
+    const julgamento = (await envio.json());
+    return {
+        medidas: medicoes.length,
+        ausentes: medicoes.filter((m) => m.sha === null).map((m) => m.valor).sort(),
+        novas: julgamento.novas,
+        base: julgamento.base,
+        jaAbertas: julgamento.ja_abertas,
+        tocadas,
+    };
+}

package/dist/config.js

@@ -0,0 +1,81 @@
+import { createHash } from "node:crypto";
+import { chmod, mkdir, readFile, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+/**
+ * O servico publicado e o padrao: um repositorio que so declara `tenant` e `projeto` ja
+ * fala com quem existe. Para desenvolver contra a maquina local, ponha `api` explicito no
+ * `.dd-harness.json` — apontar para `localhost` por omissao deixaria todo repo novo
+ * falando com um servidor que ninguem esta rodando.
+ */
+const PADRAO = { api: "https://dd-harness.vercel.app", pasta: "dd-harness" };
+export const CAMINHO_CONFIG = ".dd-harness.json";
+export const CAMINHO_MANIFESTO = "dd-harness/manifest.json";
+export async function leConfigDoRepo(raiz) {
+    let cru;
+    try {
+        cru = await readFile(join(raiz, CAMINHO_CONFIG), "utf8");
+    }
+    catch {
+        throw new Error(`não encontrei ${CAMINHO_CONFIG} em ${raiz}. Crie com: {"tenant":"...","projeto":"..."}`);
+    }
+    const lido = JSON.parse(cru);
+    if (!lido.tenant || !lido.projeto) {
+        throw new Error(`${CAMINHO_CONFIG} precisa de "tenant" e "projeto".`);
+    }
+    return {
+        api: (lido.api ?? PADRAO.api).replace(/\/$/, ""),
+        tenant: lido.tenant,
+        projeto: lido.projeto,
+        pasta: lido.pasta ?? PADRAO.pasta,
+    };
+}
+const arquivoDeCredenciais = () => join(homedir(), ".dd-harness", "credentials.json");
+/**
+ * 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 async function leToken(api) {
+    try {
+        const cru = await readFile(arquivoDeCredenciais(), "utf8");
+        const mapa = JSON.parse(cru);
+        return mapa[api] ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+export async function guardaToken(api, token) {
+    const caminho = arquivoDeCredenciais();
+    await mkdir(join(homedir(), ".dd-harness"), { recursive: true });
+    let mapa = {};
+    try {
+        mapa = JSON.parse(await readFile(caminho, "utf8"));
+    }
+    catch {
+        // Primeiro token desta maquina.
+    }
+    mapa[api] = token;
+    await writeFile(caminho, `${JSON.stringify(mapa, null, 2)}\n`, "utf8");
+    // 0600 depois de escrever. No Windows o chmod e no-op — o arquivo herda a ACL do
+    // perfil do usuario, que ja e privada; em POSIX sem isto o token nasce legivel por
+    // qualquer processo do sistema.
+    await chmod(caminho, 0o600).catch(() => { });
+    return caminho;
+}
+export const manifestoVazio = () => ({ etag: null, arquivos: {} });
+export async function leManifesto(raiz) {
+    try {
+        const cru = await readFile(join(raiz, CAMINHO_MANIFESTO), "utf8");
+        const lido = JSON.parse(cru);
+        return { etag: lido.etag ?? null, arquivos: lido.arquivos ?? {} };
+    }
+    catch {
+        return manifestoVazio();
+    }
+}
+export async function gravaManifesto(raiz, manifesto) {
+    await mkdir(join(raiz, "dd-harness"), { recursive: true });
+    await writeFile(join(raiz, CAMINHO_MANIFESTO), `${JSON.stringify(manifesto, null, 2)}\n`, "utf8");
+}
+export const hashDe = (conteudo) => createHash("sha256").update(conteudo, "utf8").digest("hex");

package/dist/diff.js

@@ -0,0 +1,52 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+const roda = promisify(execFile);
+/**
+ * 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 async function caminhosDoCommit(raiz, commit) {
+    try {
+        const { stdout } = await roda("git", ["diff-tree", "--no-commit-id", "--name-only", "-r", commit], { cwd: raiz });
+        return stdout
+            .split(/\r?\n/)
+            .map((l) => l.trim())
+            .filter(Boolean);
+    }
+    catch {
+        // Sem git, commit inexistente, repositorio raso: o cruzamento simplesmente nao
+        // acontece. Um aviso que nao pode ser dado nao vira erro que atrapalha o commit.
+        return [];
+    }
+}
+/**
+ * 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.
+ */
+export function memoriasTocadas(brain, caminhos) {
+    const tocadas = [];
+    for (const memoria of brain.memorias) {
+        if (memoria.status !== "ativa")
+            continue;
+        for (const ancora of memoria.ancoras) {
+            const casa = caminhos.some((c) => c === ancora.valor || c.startsWith(`${ancora.valor}/`));
+            if (casa) {
+                tocadas.push({
+                    pasta: memoria.pasta,
+                    memoria: memoria.slug,
+                    titulo: memoria.titulo,
+                    ancora: ancora.valor,
+                });
+            }
+        }
+    }
+    return tocadas;
+}

package/dist/index.js

@@ -0,0 +1,205 @@
+#!/usr/bin/env node
+import { check, status } from "./check.js";
+import { leConfigDoRepo, guardaToken } from "./config.js";
+import { init } from "./init.js";
+import { LINHA_DE_IMPORT } from "./materializa.js";
+import { sync } from "./sync.js";
+/**
+ * `dd-harness` — o cliente que materializa os artefatos no repositorio.
+ *
+ * Sem dependencia de proposito: `fetch`, `crypto` e `fs` sao do Node, e o molde original
+ * ja seguia a regra de validador determinístico sem dependencia. Um CLI que vive pinado
+ * em repositorio alheio tem que envelhecer bem, e cada dependencia e uma chance de nao
+ * envelhecer.
+ */
+const AJUDA = `dd-harness — materializa política, briefing e Brain no repositório
+
+  dd-harness init --tenant <t> --projeto <p> [--api <url>]
+                                     prepara o repositório (config + CLAUDE.md)
+  dd-harness login --token <token>   guarda a credencial desta máquina
+  dd-harness sync                    escreve os artefatos em disco
+  dd-harness check [--commit <sha>]  mede as âncoras e reporta a deriva
+  dd-harness status                  só lê: o que espera julgamento
+  dd-harness --help
+
+O gerado vive em dd-harness/. Na raiz fica só o seu CLAUDE.md, que importa a
+política com a linha ${LINHA_DE_IMPORT}
+`;
+/** O aviso existe porque o import falha em silêncio — foi medido, não suposto. */
+function avisaSobreOPonteiro(ponteiro) {
+    if (ponteiro === "ok" || ponteiro === "sem-politica")
+        return;
+    const motivo = ponteiro === "sem-claude-md"
+        ? "não há CLAUDE.md na raiz"
+        : "o CLAUDE.md da raiz não importa a política";
+    console.error([
+        "",
+        `AVISO: ${motivo}.`,
+        "A política existe no serviço e está em disco, mas não chega à sessão: o import",
+        "ausente falha em silêncio, e a sessão abre sem protocolo sem avisar ninguém.",
+        "",
+        `Acrescente esta linha ao CLAUDE.md da raiz:  ${LINHA_DE_IMPORT}`,
+        "Ou rode: dd-harness init --tenant <t> --projeto <p>",
+    ].join("\n"));
+}
+/**
+ * Os ganchos sao IMPRESSOS, nunca instalados. `.git/hooks` nao e versionado e nao e
+ * nosso: escrever la dentro sem a pessoa pedir e o mesmo tipo de invasao que
+ * sobrescrever o CLAUDE.md dela. Quem cola, decide.
+ */
+const GANCHOS = `
+Opcional — dois ganchos que valem a pena:
+
+  .git/hooks/post-commit   (avisa quais memórias falam do que você mudou)
+    #!/bin/sh
+    dd-harness check --commit "$(git rev-parse HEAD)" || true
+
+  .claude/settings.json    (na abertura da sessão, o que espera julgamento)
+    "hooks": { "SessionStart": [{ "hooks": [{ "type": "command",
+      "command": "dd-harness status" }] }] }
+
+Os dois terminam em sucesso mesmo com deriva: avisam, não bloqueiam.`;
+function argumento(argv, nome) {
+    const i = argv.indexOf(`--${nome}`);
+    return i >= 0 ? argv[i + 1] : undefined;
+}
+async function comandoInit(argv) {
+    const tenant = argumento(argv, "tenant");
+    const projeto = argumento(argv, "projeto");
+    if (!tenant || !projeto) {
+        throw new Error("uso: dd-harness init --tenant <t> --projeto <p> [--api <url>]");
+    }
+    const r = await init(process.cwd(), {
+        tenant,
+        projeto,
+        api: argumento(argv, "api"),
+    });
+    console.log(r.config === "criada" ? "criado  .dd-harness.json" : "mantido .dd-harness.json");
+    console.log({
+        criado: "criado  CLAUDE.md com a linha de import",
+        "linha-acrescentada": "ajustado CLAUDE.md — linha de import acrescentada ao seu",
+        "ja-tinha-a-linha": "mantido CLAUDE.md — já importava a política",
+    }[r.claudeMd]);
+    console.log("\nAgora: dd-harness login --token <token> && dd-harness sync");
+}
+async function comandoLogin(argv) {
+    const token = argumento(argv, "token");
+    if (!token)
+        throw new Error("uso: dd-harness login --token <token>");
+    const config = await leConfigDoRepo(process.cwd());
+    const caminho = await guardaToken(config.api, token);
+    console.log(`credencial de ${config.api} guardada em ${caminho}`);
+}
+async function comandoSync() {
+    const resultado = await sync(process.cwd());
+    if (resultado.tipo === "editado-a-mao") {
+        console.error([
+            "parei sem escrever nada: estes arquivos foram editados à mão.",
+            ...resultado.arquivos.map((a) => `  ${a}`),
+            "",
+            "O disco é projeção do serviço, uma direção só. Leve a mudança para o serviço,",
+            "ou descarte a edição local (git checkout / apague o arquivo) e sincronize de novo.",
+        ].join("\n"));
+        process.exitCode = 1;
+        return;
+    }
+    if (resultado.tipo === "sem-mudanca") {
+        console.log("nada mudou no serviço — disco já está em dia.");
+    }
+    else {
+        for (const a of resultado.escritos)
+            console.log(`escrito  ${a}`);
+        for (const a of resultado.removidos)
+            console.log(`removido ${a}`);
+        if (!resultado.escritos.length && !resultado.removidos.length) {
+            console.log("conteúdo novo do serviço, sem diferença em disco.");
+        }
+    }
+    avisaSobreOPonteiro(resultado.ponteiro);
+}
+async function comandoCheck(argv) {
+    const r = await check(process.cwd(), argumento(argv, "commit"));
+    if (r.medidas === 0) {
+        console.log("nenhuma âncora para medir.");
+        return;
+    }
+    console.log(`medidas ${r.medidas} âncora(s).`);
+    if (r.base > 0) {
+        console.log(`  ${r.base} medida(s) pela primeira vez — viraram linha de base.`);
+    }
+    // Ausente e alterado nao pesam igual: o alvo ter sumido e sinal forte, e some no meio
+    // do ruido se for anunciado do mesmo jeito que "mudou".
+    if (r.ausentes.length) {
+        console.log("");
+        console.log("ALVO AUSENTE — alguém apagou ou moveu o que uma memória guarda:");
+        for (const valor of r.ausentes)
+            console.log(`  ${valor}`);
+    }
+    if (r.novas > 0) {
+        console.log("");
+        console.log(`${r.novas} deriva(s) nova(s) registrada(s) no serviço.`);
+    }
+    if (r.jaAbertas > 0) {
+        console.log(`${r.jaAbertas} já estava(m) aberta(s) — nada novo, só o carimbo.`);
+    }
+    if (!r.ausentes.length && r.novas === 0 && r.jaAbertas === 0) {
+        console.log("nenhuma deriva: o mundo ainda bate com o que as memórias dizem.");
+    }
+    // O cruzamento com o diff e outra coisa que deriva: e "voce acabou de mexer no que
+    // esta memoria guarda". Vale mesmo quando a memoria continua valendo — e o revisor
+    // que o modelo file-based dava de graca, e que centralizar tinha tirado.
+    if (r.tocadas.length) {
+        console.log("");
+        console.log("Este commit mexeu no que estas memórias guardam:");
+        for (const t of r.tocadas) {
+            console.log(`  ${t.pasta}/${t.memoria} — ${t.titulo}`);
+            console.log(`    âncora: ${t.ancora}`);
+        }
+    }
+}
+async function comandoStatus() {
+    const r = await status(process.cwd());
+    if (!r.comDeriva.length && !r.vencidas.length) {
+        console.log("dd-harness: nada esperando julgamento.");
+        return;
+    }
+    if (r.comDeriva.length) {
+        const total = r.comDeriva.reduce((soma, m) => soma + m.abertas, 0);
+        console.log(`dd-harness: ${total} deriva(s) aberta(s), esperando julgamento:`);
+        for (const m of r.comDeriva) {
+            console.log(`  ${m.pasta}/${m.memoria} — ${m.titulo} (${m.abertas})`);
+        }
+    }
+    if (r.vencidas.length) {
+        console.log("");
+        console.log("Memórias com revisão vencida:");
+        for (const m of r.vencidas)
+            console.log(`  ${m.pasta}/${m.memoria} — ${m.titulo}`);
+    }
+}
+async function principal() {
+    const [comando, ...resto] = process.argv.slice(2);
+    switch (comando) {
+        case "init":
+            return comandoInit(resto);
+        case "login":
+            return comandoLogin(resto);
+        case "sync":
+            return comandoSync();
+        case "check":
+            return comandoCheck(resto);
+        case "status":
+            return comandoStatus();
+        case "--help":
+        case "-h":
+        case undefined:
+            console.log(AJUDA);
+            return;
+        default:
+            throw new Error(`comando desconhecido: ${comando}`);
+    }
+}
+principal().catch((erro) => {
+    console.error(erro instanceof Error ? erro.message : String(erro));
+    process.exitCode = 1;
+});

package/dist/init.js

@@ -0,0 +1,58 @@
+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.
+ *
+ * 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.
+ */
+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 async function init(raiz, dados) {
+    const caminhoConfig = join(raiz, CAMINHO_CONFIG);
+    let config = "ja-existia";
+    try {
+        await readFile(caminhoConfig, "utf8");
+    }
+    catch {
+        const conteudo = {
+            ...(dados.api ? { api: dados.api } : {}),
+            tenant: dados.tenant,
+            projeto: dados.projeto,
+        };
+        await writeFile(caminhoConfig, `${JSON.stringify(conteudo, null, 2)}\n`, "utf8");
+        config = "criada";
+    }
+    const caminhoClaude = join(raiz, "CLAUDE.md");
+    let claudeMd;
+    let atual = null;
+    try {
+        atual = await readFile(caminhoClaude, "utf8");
+    }
+    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 { config, claudeMd };
+}

package/dist/materializa.js

@@ -0,0 +1,120 @@
+/**
+ * Do payload do contrato para arquivos em disco.
+ *
+ * Funcao pura de proposito: recebe o Brain e devolve caminho -> conteudo, sem rede e sem
+ * `fs`. E a parte que precisa de teste — o formato tem que casar com o que o
+ * `validate_brain.cjs` do molde espera (frontmatter `name` igual ao arquivo, `pasta`
+ * igual a pasta que o contem, e uma linha de indice por memoria).
+ */
+const AVISO = "<!-- GERADO por `dd-harness sync`. Edite no serviço, não aqui: a próxima sincronização recusa arquivo alterado à mão. -->";
+/** Uma linha por âncora, para o leitor humano saber de que a memória depende. */
+function secaoDeAncoras(ancoras) {
+    if (ancoras.length === 0)
+        return "";
+    const linhas = ancoras.map((a) => `- \`${a.valor}\``).join("\n");
+    return `\n## Âncoras\n\nDe que esta memória depende — mudança aqui é o que dispara aviso de deriva.\n\n${linhas}\n`;
+}
+/**
+ * Os três filtros existem como coluna no serviço, e é isso que os torna auditáveis.
+ * Em disco eles viram seção, porque o frontmatter do molde não tem campo para texto
+ * longo e YAML multilinha é armadilha de escape.
+ */
+function secaoDeFiltros(m) {
+    return [
+        "\n## Os três filtros\n",
+        `**Dano:** ${m.dano}\n`,
+        `**Invisibilidade:** ${m.invisibilidade}\n`,
+        `**Externalidade:** ${m.externalidade}\n`,
+    ].join("\n");
+}
+export function arquivoDaMemoria(m) {
+    const frontmatter = [
+        "---",
+        `name: ${m.slug}`,
+        `description: ${m.resumo.replace(/\n/g, " ")}`,
+        `pasta: ${m.pasta}`,
+        ...(m.revisar_ate ? [`revisar-ate: ${m.revisar_ate.slice(0, 10)}`] : []),
+        "---",
+    ].join("\n");
+    return [
+        frontmatter,
+        "",
+        AVISO,
+        "",
+        m.corpo.trimEnd(),
+        secaoDeFiltros(m),
+        secaoDeAncoras(m.ancoras),
+    ]
+        .join("\n")
+        .replace(/\n{3,}/g, "\n\n")
+        .trimEnd()
+        .concat("\n");
+}
+export function arquivoDoIndice(brain) {
+    const ativas = brain.memorias.filter((m) => m.status === "ativa");
+    const historico = brain.memorias.filter((m) => m.status === "historico");
+    const linha = (m) => `- [${m.titulo}](${m.pasta}/${m.slug}.md) — ${m.resumo.replace(/\n/g, " ")}`;
+    const secoes = brain.pastas
+        .map((pasta) => {
+        const memorias = ativas.filter((m) => m.pasta === pasta.slug);
+        return [
+            `## ${pasta.slug}`,
+            `<!-- ${pasta.definicao} -->`,
+            ...(memorias.length ? memorias.map(linha) : ["<!-- (vazia) -->"]),
+        ].join("\n");
+    })
+        .join("\n\n");
+    const secaoHistorico = [
+        "## Histórico",
+        "<!-- Memórias substituídas por uma decisão mais nova. -->",
+        ...(historico.length ? historico.map(linha) : []),
+    ].join("\n");
+    return [
+        "# 🧠 Brain — Índice",
+        "",
+        AVISO,
+        "",
+        `Projeto **${brain.projeto.nome}** (\`${brain.projeto.slug}\`), espaço **${brain.tenant.nome}**.`,
+        "Uma linha por memória. As regras de gravar, encaixar e curar estão no `CLAUDE.md`.",
+        "",
+        "---",
+        "",
+        secoes,
+        "",
+        secaoHistorico,
+        "",
+    ].join("\n");
+}
+/** Tudo o que o servico gera vive aqui — e nada fora daqui e escrito pelo `sync`. */
+export const PASTA = "dd-harness";
+/** O que a raiz precisa conter para a politica chegar a sessao. */
+export const LINHA_DE_IMPORT = `@${PASTA}/politica.md`;
+/**
+ * Caminho relativo (POSIX) -> conteúdo. As chaves são o que o manifesto guarda.
+ *
+ * Tudo dentro de `dd-harness/`, inclusive a política. Na raiz fica só o `CLAUDE.md`, que
+ * é **seu**: o `sync` não o escreve, apenas confere que ele importa a política. É o que
+ * deixa conviverem a parte gerenciada e o que aquele repositório tem de próprio — e o
+ * que faz adotar um projeto existente ser uma linha, não um ritual.
+ *
+ * Artefato vazio ou ausente não entra no mapa; como o manifesto remove o que saiu do
+ * conjunto, esvaziar no serviço apaga o arquivo no próximo `sync`.
+ */
+export function materializa(brain, pasta = PASTA) {
+    const arquivos = new Map();
+    const artefatos = [
+        [`${pasta}/politica.md`, brain.politica],
+        [`${pasta}/BRIEFING.md`, brain.briefing],
+    ];
+    for (const [caminho, conteudo] of artefatos) {
+        // Termina com quebra de linha: arquivo de texto sem ela irrita todo diff.
+        if (conteudo && conteudo.trim()) {
+            arquivos.set(caminho, conteudo.replace(/\n*$/, "\n"));
+        }
+    }
+    arquivos.set(`${pasta}/brain/MEMORY.md`, arquivoDoIndice(brain));
+    for (const m of brain.memorias) {
+        arquivos.set(`${pasta}/brain/${m.pasta}/${m.slug}.md`, arquivoDaMemoria(m));
+    }
+    return arquivos;
+}

package/dist/medir.js

@@ -0,0 +1,46 @@
+import { createHash } from "node:crypto";
+import { readdir, readFile, stat } from "node:fs/promises";
+import { join, posix } from "node:path";
+/**
+ * Medir o alvo de uma ancora. E a metade da deriva que so o cliente pode fazer: o
+ * servico nunca ve o repositorio.
+ *
+ * Devolve `null` quando o alvo nao existe — e o servico que decide se isso e deriva.
+ */
+/** Arquivo: hash do conteudo. E o que responde "mudou?" sem ambiguidade. */
+async function hashDeArquivo(caminho) {
+    return createHash("sha256").update(await readFile(caminho)).digest("hex");
+}
+/**
+ * Diretorio: hash da LISTA de arquivos, nao do conteudo deles.
+ *
+ * Uma ancora em `supabase/migrations` quer dizer "o conjunto de migrations importa" —
+ * migration nova e o sinal. Se o hash levasse o conteudo junto, qualquer ajuste de
+ * comentario dentro de qualquer arquivo acusaria deriva, e a fila viraria ruido.
+ */
+async function hashDeDiretorio(caminho) {
+    const nomes = [];
+    async function anda(dir, prefixo) {
+        for (const entrada of await readdir(dir, { withFileTypes: true })) {
+            const rel = prefixo ? posix.join(prefixo, entrada.name) : entrada.name;
+            if (entrada.isDirectory())
+                await anda(join(dir, entrada.name), rel);
+            else
+                nomes.push(rel);
+        }
+    }
+    await anda(caminho, "");
+    return createHash("sha256").update(nomes.sort().join("\n")).digest("hex");
+}
+export async function mede(raiz, valor) {
+    const caminho = join(raiz, valor);
+    try {
+        const info = await stat(caminho);
+        return info.isDirectory()
+            ? await hashDeDiretorio(caminho)
+            : await hashDeArquivo(caminho);
+    }
+    catch {
+        return null;
+    }
+}

package/dist/sync.js

@@ -0,0 +1,149 @@
+import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { gravaManifesto, hashDe, leConfigDoRepo, leManifesto, leToken, } from "./config.js";
+import { LINHA_DE_IMPORT, materializa } from "./materializa.js";
+async function leSeExistir(caminho) {
+    try {
+        return await readFile(caminho, "utf8");
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Estado do que este comando escreveu, contra o hash guardado.
+ *
+ * Duas situacoes diferentes, e confundi-las custa caro: hash diferente e **edicao a
+ * mao**, e o comando tem que parar sem escrever; arquivo **ausente** nao e edicao — e
+ * trabalho a refazer, e o comando tem que reescrever.
+ */
+export async function confereDisco(raiz, arquivos) {
+    const editados = [];
+    const faltando = [];
+    for (const [relativo, hashGuardado] of Object.entries(arquivos)) {
+        const atual = await leSeExistir(join(raiz, relativo));
+        if (atual === null)
+            faltando.push(relativo);
+        else if (hashDe(atual) !== hashGuardado)
+            editados.push(relativo);
+    }
+    return { editados: editados.sort(), faltando: faltando.sort() };
+}
+async function buscaBrain(config, token, etag) {
+    const url = `${config.api}/api/v1/artefatos?tenant=${encodeURIComponent(config.tenant)}&projeto=${encodeURIComponent(config.projeto)}`;
+    const resposta = await fetch(url, {
+        headers: {
+            Authorization: `Bearer ${token}`,
+            ...(etag ? { "If-None-Match": etag } : {}),
+        },
+    });
+    if (resposta.status === 304)
+        return { naoMudou: true };
+    if (resposta.status === 401) {
+        throw new Error("token recusado. Rode `dd-harness login --token <token>`.");
+    }
+    if (resposta.status === 404) {
+        throw new Error(`projeto ${config.tenant}/${config.projeto} não encontrado — ou não é seu.`);
+    }
+    if (!resposta.ok) {
+        throw new Error(`a API respondeu ${resposta.status}.`);
+    }
+    return {
+        naoMudou: false,
+        brain: (await resposta.json()),
+        etag: resposta.headers.get("etag"),
+    };
+}
+/**
+ * O `CLAUDE.md` da raiz existe e importa a politica?
+ *
+ * Nao ha politica no servico? Entao nao ha o que apontar, e a ausencia do ponteiro nao e
+ * problema — avisar aqui seria ruido que ensina a ignorar aviso.
+ */
+export async function confereOPonteiro(raiz, temPolitica) {
+    if (!temPolitica)
+        return "sem-politica";
+    const claudeMd = await leSeExistir(join(raiz, "CLAUDE.md"));
+    if (claudeMd === null)
+        return "sem-claude-md";
+    return claudeMd.includes(LINHA_DE_IMPORT) ? "ok" : "sem-a-linha";
+}
+export async function sync(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>\`.`);
+    }
+    const manifesto = await leManifesto(raiz);
+    // A guarda vem ANTES da rede, e nao depois do 304, porque a divergencia pode estar
+    // deste lado: servico igual e disco editado a mao e o caso que mais interessa avisar,
+    // e um 304 que respondesse "nada mudou" o esconderia.
+    const { editados, faltando } = await confereDisco(raiz, manifesto.arquivos);
+    const politicaNoManifesto = Object.keys(manifesto.arquivos).some((a) => a.endsWith(`${config.pasta}/politica.md`));
+    if (editados.length) {
+        return {
+            tipo: "editado-a-mao",
+            arquivos: editados,
+            ponteiro: await confereOPonteiro(raiz, politicaNoManifesto),
+        };
+    }
+    // `If-None-Match` so quando o disco esta completo. Faltando arquivo, um 304 diria
+    // "nada a fazer" e o comando nunca conseguiria reescrever o que foi apagado — a
+    // sincronizacao ficaria incapaz de consertar o disco, que e metade do trabalho dela.
+    const resposta = await buscaBrain(config, token, faltando.length ? null : manifesto.etag);
+    if (resposta.naoMudou) {
+        // Confere mesmo sem mudanca no servico: quem apaga a linha de import e quem mexe no
+        // repositorio, e um 304 nao sabe nada sobre isso.
+        return {
+            tipo: "sem-mudanca",
+            ponteiro: await confereOPonteiro(raiz, politicaNoManifesto),
+        };
+    }
+    const desejado = materializa(resposta.brain, config.pasta);
+    // Arquivo que o servico quer escrever e que existe em disco sem estar no manifesto e
+    // de outra origem — escrito a mao antes do primeiro sync. Tambem nao e nosso.
+    const alheios = [];
+    for (const relativo of desejado.keys()) {
+        if (manifesto.arquivos[relativo])
+            continue;
+        if ((await leSeExistir(join(raiz, relativo))) !== null)
+            alheios.push(relativo);
+    }
+    if (alheios.length) {
+        return {
+            tipo: "editado-a-mao",
+            arquivos: alheios.sort(),
+            ponteiro: await confereOPonteiro(raiz, desejado.has(`${config.pasta}/politica.md`)),
+        };
+    }
+    const escritos = [];
+    for (const [relativo, conteudo] of desejado) {
+        const caminho = join(raiz, relativo);
+        const atual = await leSeExistir(caminho);
+        if (atual === conteudo)
+            continue;
+        await mkdir(dirname(caminho), { recursive: true });
+        await writeFile(caminho, conteudo, "utf8");
+        escritos.push(relativo);
+    }
+    // Memoria que saiu do servico tem que sair do disco, senao o repo guarda para sempre
+    // uma memoria que ninguem mais vai atualizar. So remove o que era nosso e nao mudou.
+    const removidos = [];
+    for (const relativo of Object.keys(manifesto.arquivos)) {
+        if (desejado.has(relativo))
+            continue;
+        await rm(join(raiz, relativo), { force: true });
+        removidos.push(relativo);
+    }
+    const novo = {
+        etag: resposta.etag,
+        arquivos: Object.fromEntries([...desejado].map(([relativo, conteudo]) => [relativo, hashDe(conteudo)])),
+    };
+    await gravaManifesto(raiz, novo);
+    return {
+        tipo: "sincronizado",
+        escritos: escritos.sort(),
+        removidos: removidos.sort(),
+        ponteiro: await confereOPonteiro(raiz, desejado.has(`${config.pasta}/politica.md`)),
+    };
+}

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "dd-harness",
+  "version": "0.1.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"
+  },
+  "files": ["dist"],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "typecheck": "tsc -p . --noEmit",
+    "build": "tsc -p tsconfig.build.json",
+    "prepublishOnly": "npm run build"
+  }
+}