dd-harness 0.5.0 → 0.6.0

package/dist/gravar.d.ts

@@ -1,14 +1,9 @@
 /**
  * `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.
+ * A entrada e um markdown no mesmo formato que `ler`/`editar` devolvem e consomem:
+ * frontmatter, corpo, os tres filtros, ancoras. O arquivo e so o veiculo — depois de
+ * gravado, ele nao fica no repositorio, e a memoria passa a viver so no servico.
  */
 export type MemoriaLida = {
     slug: string;

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,22 +21,79 @@ 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") };
 }
-/** `**Dano:** texto` — devolve o texto, sem o rotulo. */
+/**
+ * `**Dano:** texto` — devolve o texto, sem o rotulo.
+ *
+ * O corte para no que vier primeiro: um `## `, o fim do arquivo, ou o rotulo de QUALQUER
+ * um dos tres filtros aparecendo de novo — nao so precedido de linha vazia. Cortar so em
+ * "linha vazia seguida de `**`" quebrava quando os filtros vinham como item de lista
+ * (`- **Invisibilidade:**`, sem linha vazia antes): o campo `dano` engolia o texto dos
+ * outros dois filtros inteiros, sem erro nenhum. Medido: dois agentes-cobaia diferentes
+ * escreveram os filtros assim, de forma independente — e o formato e razoavel em
+ * markdown, entao nao e caso de borda raro.
+ */
 function filtro(corpo, rotulo) {
-    const achado = corpo.match(new RegExp(`\\*\\*${rotulo}:\\*\\*\\s*([\\s\\S]*?)(?=\\n\\s*\\n\\*\\*|\\n## |$)`, "i"));
+    const proximoRotulo = TODOS_OS_FILTROS.filter((r) => r !== rotulo).join("|");
+    const achado = corpo.match(new RegExp(`\\*\\*${rotulo}:\\*\\*\\s*([\\s\\S]*?)(?=\\n\\s*[-*]?\\s*\\*\\*(?:${proximoRotulo}):\\*\\*|\\n## |$)`, "i"));
     const valor = achado?.[1]?.trim() ?? "";
     if (!valor)
         throw new Error(`falta o filtro **${rotulo}:** no arquivo.`);
     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];
@@ -37,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);

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.
@@ -435,14 +436,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 +474,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 +532,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.0",
+  "version": "0.6.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",