dd-harness 0.5.1 → 0.7.0

package/dist/curar.d.ts

@@ -25,6 +25,12 @@ export type MemoriaDoServico = {
         valor: string;
         sha: string | null;
     }[];
+    /**
+     * Os OUTROS projetos (slugs do mesmo tenant) que esta memoria tambem alcanca. Sem este
+     * campo no round-trip ler->editar->enviar, o vinculo transversal se perdia em silencio
+     * — achado numa rodada de teste real.
+     */
+    projetos?: string[];
 };
 /**
  * A memoria inteira, no markdown que `gravar` e `editar` consomem.

package/dist/curar.js

@@ -30,6 +30,9 @@ export function comoMarkdown(m) {
         `description: ${m.resumo}`,
         `pasta: ${m.pasta}`,
         ...(m.revisar_ate ? [`revisar-ate: ${m.revisar_ate.slice(0, 10)}`] : []),
+        // So aparece quando ha vinculo — omitir e "so este projeto", igual a `gravar` sem
+        // `projetos:`. Formato inline (`a, b`), que e o que `interpreta` ja sabe ler.
+        ...(m.projetos?.length ? [`projetos: ${m.projetos.join(", ")}`] : []),
         "---",
         "",
         m.corpo.trim(),
@@ -62,6 +65,10 @@ export async function edita(raiz, caminho) {
             invisibilidade: memoria.invisibilidade,
             externalidade: memoria.externalidade,
             ancoras: memoria.ancoras,
+            // So manda quando o arquivo TINHA a chave `projetos:` — omitida, o servico
+            // mantem os vinculos como estao. `le` sempre escreve a chave quando ha vinculo,
+            // entao editar o arquivo que veio de `le` preserva o round-trip.
+            ...(memoria.tambemEmInformado ? { projetos: memoria.tambemEm } : {}),
         }),
     });
     if (!resposta.ok)

package/dist/gravar.d.ts

@@ -16,6 +16,14 @@ export type MemoriaLida = {
     externalidade: string;
     ancoras: string[];
     tambemEm: string[];
+    /**
+     * O frontmatter TINHA a chave `projetos:`? `gravar` nao usa isto (chave ausente e
+     * `projetos: ` vazio significam a mesma coisa ali: "so este projeto"). `editar` usa —
+     * la a ausencia da chave precisa significar "nao estou informando vinculos", diferente
+     * de uma lista vazia explicita, senao editar sem tocar em `projetos:` apagaria o
+     * vinculo transversal por omissao.
+     */
+    tambemEmInformado: boolean;
 };
 export declare function interpreta(texto: string): MemoriaLida;
 export declare function grava(raiz: string, caminho: string): Promise<{

package/dist/gravar.js

@@ -1,7 +1,17 @@
 import { readFile } from "node:fs/promises";
 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. */
+/**
+ * Frontmatter simples: `chave: valor` por linha. Sem lib de YAML — nao ha aninhamento.
+ *
+ * A UNICA forma de lista aceita e a de bloco (`- item` indentado sob a chave), e ela e
+ * juntada com virgula para cair no mesmo caminho do formato inline (`projetos: a, b`).
+ * Antes, a linha `projetos:` sem valor virava string vazia e os `- item` abaixo dela eram
+ * descartados por nao terem `:` — `dd-harness gravar` respondia "valendo para 1 projeto(s)"
+ * e a memoria transversal nascia valendo so onde foi gravada, sem erro nenhum. Medido numa
+ * rodada de teste real: um agente-cobaia escreveu a lista em YAML de bloco, que e o
+ * formato obvio para quem conhece frontmatter.
+ */
 function leFrontmatter(texto) {
     const linhas = texto.replace(/\r\n/g, "\n").split("\n");
     if (linhas[0]?.trim() !== "---") {
@@ -11,11 +21,22 @@ function leFrontmatter(texto) {
     if (fim === -1)
         throw new Error("frontmatter sem `---` de fechamento.");
     const campos = new Map();
+    let ultimaChave = null;
     for (const linha of linhas.slice(1, fim)) {
+        // Item de lista de bloco: pertence a chave anterior, nao e uma chave nova. Vem antes
+        // do corte por `:` porque `- chave: valor` tambem tem dois-pontos.
+        const item = linha.match(/^\s+-\s+(.+?)\s*$/);
+        if (item && ultimaChave) {
+            const ja = campos.get(ultimaChave);
+            const valor = item[1].replace(/^["']|["']$/g, "").trim();
+            campos.set(ultimaChave, ja ? `${ja}, ${valor}` : valor);
+            continue;
+        }
         const corte = linha.indexOf(":");
         if (corte === -1)
             continue;
-        campos.set(linha.slice(0, corte).trim(), linha.slice(corte + 1).trim());
+        ultimaChave = linha.slice(0, corte).trim();
+        campos.set(ultimaChave, linha.slice(corte + 1).trim());
     }
     return { campos, resto: linhas.slice(fim + 1).join("\n") };
 }
@@ -39,6 +60,40 @@ function filtro(corpo, rotulo) {
     return valor;
 }
 const TODOS_OS_FILTROS = ["Dano", "Invisibilidade", "Externalidade"];
+/**
+ * Espelha o CHECK `memory_anchors_valor_valido` do banco, para poder dizer QUAL âncora
+ * está errada e POR QUÊ.
+ *
+ * O servidor devolve 422 com "justificativa curta demais ou âncora inválida" — as duas
+ * causas na mesma frase, sem dizer qual delas foi nem qual âncora. Quem digitou fica
+ * conferindo os três filtros quando o problema era um caminho absoluto. A regra é
+ * conhecida aqui, então recusar antes da rede é mais barato e mais específico.
+ *
+ * Não substitui o CHECK: o banco continua sendo a autoridade. Isto só adianta o erro.
+ */
+function recusaAncoraInvalida(valor) {
+    const diga = (porque) => {
+        throw new Error(`âncora inválida \`${valor}\`: ${porque}`);
+    };
+    if (valor.length > 400)
+        diga("passa de 400 caracteres.");
+    if (valor.startsWith("/"))
+        diga("é caminho absoluto — use caminho relativo à raiz do repositório.");
+    if (/^[A-Za-z]:/.test(valor)) {
+        diga("é caminho absoluto do Windows — use caminho relativo à raiz do repositório.");
+    }
+    if (valor.includes("\\"))
+        diga("tem `\\` — separe os diretórios com `/`, mesmo no Windows.");
+    if (/(^|\/)\.\.(\/|$)/.test(valor))
+        diga("tem `..` — a âncora não pode sair da raiz do repositório.");
+    const partes = valor.split("#");
+    if (partes.length > 2) {
+        diga("tem mais de um `#` — o formato é `arquivo#trecho`, com um só.");
+    }
+    if (partes.length === 2 && (!partes[0] || !partes[1])) {
+        diga("tem `#` sem os dois lados — o formato é `arquivo#trecho`.");
+    }
+}
 /** Itens de lista da secao de ancoras, com ou sem crase em volta. */
 function ancorasDe(texto) {
     const secao = texto.split(/\n##\s+[ÂA]ncoras\s*\n/i)[1];
@@ -49,7 +104,11 @@ function ancorasDe(texto) {
         .map((l) => l.match(/^\s*[-*]\s+(.+?)\s*$/)?.[1])
         .filter((v) => Boolean(v))
         .map((v) => v.replace(/^`|`$/g, "").trim())
-        .filter(Boolean);
+        .filter(Boolean)
+        .map((v) => {
+        recusaAncoraInvalida(v);
+        return v;
+    });
 }
 export function interpreta(texto) {
     const { campos, resto } = leFrontmatter(texto);
@@ -92,6 +151,7 @@ export function interpreta(texto) {
             .split(",")
             .map((s) => s.trim())
             .filter(Boolean),
+        tambemEmInformado: campos.has("projetos"),
     };
 }
 export async function grava(raiz, caminho) {

package/dist/index.js

@@ -46,6 +46,7 @@ const AJUDA = `dd-harness — a política e o Brain do projeto, no serviço
                                      --hook: fala o protocolo do SessionStart do
                                      Claude Code, para pôr a política no contexto
   dd-harness --help
+  dd-harness --version              qual binário está instalado nesta máquina
 
 Nada do dd-harness fica em disco: a política chega pelo hook de sessão, e a
 memória pela busca, na hora.
@@ -270,7 +271,12 @@ async function comandoCheck(argv) {
         console.log(`${r.fechadas} deriva(s) fechada(s): o alvo voltou a bater com a linha de base.`);
     }
     if (!r.ausentes.length && r.novas === 0 && r.jaAbertas === 0 && r.fechadas === 0) {
-        console.log("nenhuma deriva: o mundo ainda bate com o que as memórias dizem.");
+        // "Nenhuma deriva" e nao "o mundo bate com o que a memoria diz": isto mede se a
+        // ANCORA (localizacao/conteudo) mudou, nunca se o COMPORTAMENTO ainda corresponde ao
+        // texto. Dois agentes-cobaia independentes leram a frase antiga como garantia
+        // semantica que o mecanismo nao da — trocar quebra e proposital comportamento
+        // continuar identico ao de antes.
+        console.log("nenhuma âncora mudou de lugar ou de conteúdo desde a última medição.");
     }
     // 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
@@ -435,14 +441,18 @@ async function comandoProjeto(argv) {
     if (!slug || slug.startsWith("-") || !nome) {
         throw new Error('uso: dd-harness projeto <slug> --nome "<nome>" [--tenant <slug>] [--api <url>]');
     }
+    const tenant = argumento(argv, "tenant");
     const r = await criaProjeto(process.cwd(), slug, nome, {
-        tenant: argumento(argv, "tenant"),
+        tenant,
         api: argumento(argv, "api"),
     });
     console.log(r.jaExistia
         ? `projeto ${r.projeto} já existia — nada criado.`
         : `criado  projeto ${r.projeto}.`);
-    console.log(`Agora: dd-harness init --tenant <espaço> --projeto ${r.projeto}`);
+    // O `--tenant` que acabou de ser digitado vai INTEIRO para a proxima linha: imprimir o
+    // placeholder `<espaço>` quando o valor esta na mao obriga a pessoa a reconstruir um
+    // comando que ja podia ser copiado — e foi reportado como erro por duas rodadas de teste.
+    console.log(`Agora: dd-harness init --tenant ${tenant ?? "<espaço>"} --projeto ${r.projeto}`);
 }
 async function comandoPasta(argv) {
     const slug = argv[0];
@@ -469,8 +479,37 @@ async function comandoGravar(argv) {
     console.log(`gravado  ${r.endereco}`);
     console.log(`  ${r.ancoras} âncora(s), valendo para ${r.projetos} projeto(s).`);
 }
+/**
+ * A versao vem do `package.json` publicado, lido em tempo de execucao.
+ *
+ * Sem isto nao havia como perguntar ao proprio CLI qual binario esta instalado — a
+ * resposta exigia `npm ls -g dd-harness`, que e outro programa. Numa rodada de teste real
+ * isso custou caro: dois agentes seguiram com um binario velho depois de a correcao ter
+ * sido publicada, e nada no CLI podia denunciar isso.
+ */
+async function versao() {
+    const { readFile } = await import("node:fs/promises");
+    const { fileURLToPath } = await import("node:url");
+    const { dirname, join } = await import("node:path");
+    const aqui = dirname(fileURLToPath(import.meta.url));
+    // `dist/index.js` -> `package.json` um nivel acima. Em `src` (tsx) o caminho e o mesmo.
+    const lido = await readFile(join(aqui, "..", "package.json"), "utf8");
+    return JSON.parse(lido).version ?? "desconhecida";
+}
+/**
+ * `--help` em qualquer subcomando imprime a ajuda, e nunca executa a acao.
+ *
+ * `check --help` e `status --help` RODAVAM de verdade: `check` media as ancoras contra a
+ * arvore de trabalho e escrevia deriva no servico, quando quem digitou so queria ler o que
+ * o comando faz. `buscar` e `gravar` ja recusavam. Pedir ajuda nunca pode ter efeito.
+ */
+const PEDIU_AJUDA = (argv) => argv.includes("--help") || argv.includes("-h");
 async function principal() {
     const [comando, ...resto] = process.argv.slice(2);
+    if (comando && PEDIU_AJUDA(resto)) {
+        console.log(AJUDA);
+        return;
+    }
     switch (comando) {
         case "init":
             return comandoInit(resto);
@@ -498,6 +537,11 @@ async function principal() {
             return comandoStatus();
         case "politica":
             return comandoPolitica(resto);
+        case "--version":
+        case "-V":
+        case "version":
+            console.log(await versao());
+            return;
         case "--help":
         case "-h":
         case undefined:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dd-harness",
-  "version": "0.5.1",
+  "version": "0.7.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",