dd-harness-mcp 0.7.0 → 0.9.0

package/dist/cli/src/index.js

@@ -2,6 +2,15 @@
 import { spawn } from "node:child_process";
 import { access } from "node:fs/promises";
 import { join } from "node:path";
+// DEP0190: Node imprime esse warning direto no stderr no instante em que
+// `spawn(..., { shell: true })` recebe um array de args — de forma sincrona, ANTES de
+// qualquer listener rodar, entao filtrar dentro de um `process.on("warning")` normal nao
+// bloqueia a impressao (so o listener default e que imprime, e ele continua registrado
+// junto do nosso). Por isso remover o listener default e a unica forma de suprimir.
+// Real quando algum arg vem de fora, mas `instalaMcp` (mais abaixo) so passa literais
+// fixos — sem isto o wizard de `start` mostrava um "DeprecationWarning" no meio do fluxo
+// que parecia falha para quem esta vendo por dentro pela primeira vez.
+process.removeAllListeners("warning");
 import { termosDaConsulta } from "./argv.js";
 import { check, status } from "./check.js";
 import { CAMINHO_CONFIG, guardaConfigDaMaquina, guardaToken, leConfigDaMaquina, leConfigDoRepo, leToken, } from "./config.js";
@@ -24,61 +33,107 @@ import { subiuOWorker } from "./worker.js";
  * em repositorio alheio tem que envelhecer bem, e cada dependencia e uma chance de nao
  * envelhecer.
  */
-const AJUDA = `dd-harness — a política e o Brain do projeto, no serviço
-
-  dd-harness start                  numa pasta vazia: conduz tudo (login,
-                                     espaço, projeto, config) numa tacada
-  dd-harness login --token <token> [--api <url>]
-                                     guarda a credencial desta máquina
-  dd-harness projeto <slug> --nome "<nome>" [--tenant <t>] [--api <url>]
-                                     cria o projeto no serviço (antes do init)
-  dd-harness init --tenant <t> --projeto <p> [--api <url>]
-                                     prepara o repositório (config + CLAUDE.md)
-  dd-harness pasta <slug> --definicao "o que entra e o que não entra"
-                                     cria a pasta que o gravar exige
-  dd-harness gravar <arquivo.md>     registra uma memória a partir de um markdown
-  dd-harness editar <arquivo.md>     corrige o que já está gravado
-  dd-harness arquivar <pasta>/<slug> --motivo <obsoleta|incorreta|fora_dos_filtros>
-                     [--substituida-por <pasta>/<slug>]
-                                     tira de circulação sem apagar
-  dd-harness buscar "<pergunta>"     acha memória por relevância, não por arquivo
-  dd-harness ler <pasta>/<slug>      imprime a memória inteira, no formato de gravar
-  dd-harness reancorar <pasta>/<slug> --de "<alvo>" --para "<alvo>"
-                                     troca o alvo de uma âncora que mudou de lugar
-  dd-harness check [--commit <sha>]  mede as âncoras e reporta a deriva
-  dd-harness status                  só lê: o tamanho do Brain e o que espera julgamento
-  dd-harness politica [--hook]       imprime a política do serviço
-                                     saída 0 = veio; 3 = projeto sem política;
-                                     1 = não consegui buscar
-                                     --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.
+const AJUDA = `dd-harness — a política e o Brain do projeto, no serviço
+
+  dd-harness start                  numa pasta vazia: conduz tudo (login,
+                                     espaço, projeto, config) numa tacada
+  dd-harness login --token <token> [--api <url>]
+                                     guarda a credencial desta máquina
+  dd-harness projeto <slug> --nome "<nome>" [--tenant <t>] [--api <url>]
+                                     cria o projeto no serviço (antes do init)
+  dd-harness init --tenant <t> --projeto <p> [--api <url>]
+                                     prepara o repositório (config + CLAUDE.md)
+  dd-harness pasta <slug> --definicao "o que entra e o que não entra"
+                                     cria a pasta que o gravar exige
+  dd-harness gravar <arquivo.md>     registra uma memória a partir de um markdown
+  dd-harness editar <arquivo.md>     corrige o que já está gravado
+  dd-harness arquivar <pasta>/<slug> --motivo <obsoleta|incorreta|fora_dos_filtros>
+                     [--substituida-por <pasta>/<slug>]
+                                     tira de circulação sem apagar
+  dd-harness buscar "<pergunta>"     acha memória por relevância, não por arquivo
+  dd-harness ler <pasta>/<slug>      imprime a memória inteira, no formato de gravar
+  dd-harness reancorar <pasta>/<slug> --de "<alvo>" --para "<alvo>"
+                                     troca o alvo de uma âncora que mudou de lugar
+  dd-harness check [--commit <sha>]  mede as âncoras e reporta a deriva
+  dd-harness status                  só lê: o tamanho do Brain e o que espera julgamento
+  dd-harness politica [--hook]       imprime a política do serviço
+                                     saída 0 = veio; 3 = projeto sem política;
+                                     1 = não consegui buscar
+                                     --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.
 `;
 /**
  * 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 — o gancho que devolve a memória ao code review:
-
-  .git/hooks/post-commit   (avisa quais memórias falam do que você mudou)
-    #!/bin/sh
-    dd-harness check --commit "$(git rev-parse HEAD)" || true
-
-Termina em sucesso mesmo com deriva: avisa, não bloqueia.
-
-O hook da política (\`dd-harness politica --hook\`) é outra coisa, e não é
+const GANCHOS = `
+Opcional — o gancho que devolve a memória ao code review:
+
+  .git/hooks/post-commit   (avisa quais memórias falam do que você mudou)
+    #!/bin/sh
+    dd-harness check --commit "$(git rev-parse HEAD)" || true
+
+Termina em sucesso mesmo com deriva: avisa, não bloqueia.
+
+O hook da política (\`dd-harness politica --hook\`) é outra coisa, e não é
 opcional — \`dd-harness init\` imprime a linha para o \`.claude/settings.json\`.`;
 function argumento(argv, nome) {
     const i = argv.indexOf(`--${nome}`);
     return i >= 0 ? argv[i + 1] : undefined;
 }
 const API_PADRAO = "https://dd-harness.vercel.app";
+/**
+ * Forca o `npx` a baixar e cachear `dd-harness-mcp` AGORA, dentro do wizard — nunca na
+ * primeira conexao do Claude Code. Sem isto, a primeira instalacao acontecia so quando
+ * o host tentava conectar ao servidor MCP, e o handshake tem timeout curto demais para
+ * esperar o download: a sessao real via `CONNECTION_CLOSED` em vez de "instalando".
+ */
+function instalaMcp() {
+    return new Promise((resolve) => {
+        // stdio "inherit": o usuario ve o download do npx acontecendo (pode levar alguns
+        // segundos) e, se falhar, ve POR QUE — em vez do "nao consegui" mudo que nao dava
+        // pista nenhuma para diagnosticar. O DEP0190 que isto dispara e suprimido no topo
+        // do arquivo (`process.removeAllListeners("warning")`).
+        const p = spawn("npx", ["-y", "dd-harness-mcp", "--help"], {
+            shell: process.platform === "win32",
+            stdio: "inherit",
+        });
+        p.on("exit", (code) => resolve({ ok: code === 0, erro: code === 0 ? undefined : `código de saída ${code}` }));
+        p.on("error", (e) => resolve({ ok: false, erro: e.message }));
+    });
+}
+/**
+ * `start` e o primeiro comando de quem esta chegando — rodar desatualizado aqui e o
+ * peor lugar para isso: foi assim que a pre-instalacao do MCP (esta mesma funcao,
+ * mais abaixo) ficou muda numa versao anterior que nao tinha essa etapa ainda.
+ * Falha de rede aqui nunca trava o wizard — so segue sem avisar.
+ */
+async function versaoDesatualizada() {
+    try {
+        const atual = await versao();
+        const controle = new AbortController();
+        const corte = setTimeout(() => controle.abort(), 3000);
+        const resp = await fetch("https://registry.npmjs.org/dd-harness/latest", {
+            signal: controle.signal,
+        });
+        clearTimeout(corte);
+        if (!resp.ok)
+            return null;
+        const { version: ultima } = (await resp.json());
+        if (!ultima || ultima === atual)
+            return null;
+        return { atual, ultima };
+    }
+    catch {
+        return null;
+    }
+}
 /**
  * Tenta abrir o navegador padrao. Nunca lanca — falhar em abrir nao pode travar o
  * wizard, so degrada para "aqui esta a URL, abra voce mesmo".
@@ -96,6 +151,10 @@ function tentaAbrirNavegador(url) {
         // Segue sem navegador — a URL impressa antes desta chamada ja resolve.
     }
 }
+/** Token no terminal aparece mascarado: o prefixo basta para reconhecer, o segredo nao precisa ser lido em voz alta. */
+function mascara(token) {
+    return token.length <= 16 ? "***" : `${token.slice(0, 12)}...${token.slice(-4)}`;
+}
 /**
  * `dd-harness start` — o wizard para pasta vazia.
  *
@@ -120,14 +179,37 @@ async function comandoStart() {
         // ENOENT: exatamente o caso esperado, segue.
     }
     console.log("Iniciando o dd-harness nesta pasta.\n");
+    // 0. Versao. `start` e o comando de bootstrap: rodar velho aqui significa perder
+    // correcoes deste proprio wizard sem nenhum aviso (foi o que aconteceu com a
+    // pre-instalacao do MCP, passo 5.5 abaixo, numa versao anterior a ela existir).
+    const desatualizado = await versaoDesatualizada();
+    if (desatualizado) {
+        console.log(`AVISO: você está na versão ${desatualizado.atual}, e a mais recente é ` +
+            `${desatualizado.ultima}. Rode \`npm install -g dd-harness@latest\` e comece de ` +
+            "novo — start segue mesmo assim, mas pode faltar correção.\n");
+    }
     // 1. Credencial. Sem ela nada do resto e possivel — nem listar tenant.
+    // O estado aparece SEMPRE, mesmo quando ja existe credencial: antes o passo era
+    // pulado em silencio, e quem rodava `start` com um token velho (ou de outra conta)
+    // nao tinha como perceber — o wizard so falhava depois, ao listar espacos.
     let token = await leToken(API_PADRAO);
+    if (token) {
+        console.log(`Credencial: ${mascara(token)} (${API_PADRAO})`);
+        const troca = await pergunta("Usar esta credencial? [S/n]: ");
+        if (/^n/i.test(troca))
+            token = null;
+    }
     if (!token) {
-        console.log(`Sem credencial salva para ${API_PADRAO}.`);
-        token = await pergunta("Cole o token pessoal (crie um em /tokens na interface): ");
+        const url = `${API_PADRAO}/tokens`;
+        console.log(`\nCrie um token pessoal em ${url} — abrindo no navegador...`);
+        tentaAbrirNavegador(url);
+        token = await pergunta("Cole o token aqui: ");
+        if (!token)
+            throw new Error("sem token não dá para seguir: `start` fala com o serviço em todos os passos.");
         await guardaToken(API_PADRAO, token);
-        console.log("Credencial guardada.\n");
+        console.log("Credencial guardada.");
     }
+    console.log("");
     // 2. Espaco (tenant). Criar um e ato de dono — nunca por aqui — mas ESCOLHER entre
     // os que ja existem e so leitura, e e o que faltava para nao exigir o slug de memoria.
     let tenants = await listaTenants(API_PADRAO, token);
@@ -139,18 +221,28 @@ async function comandoStart() {
         tenants = await listaTenants(API_PADRAO, token);
     }
     const tenant = await escolha("\nEscolha um espaço:", tenants.map((t) => ({ rotulo: `${t.nome} (${t.slug})`, valor: t.slug })));
-    // 3. Projeto. Criar e subordinado a estar num espaco — isso o CLI ja faz sozinho.
-    const nomeSugerido = process.cwd().split(/[\\/]/).pop() ?? "meu-projeto";
+    // 3. Projeto. Criar e subordinado a estar num espaco - isso o CLI ja faz sozinho.
+    // A pasta se chama `tiktok-drawer`; o projeto se chama `TikTok Drawer`. Sugerir o
+    // nome da pasta cru fazia o wizard propor um identificador onde se pede um titulo —
+    // e o slug, que e quem precisa daquele formato, ja sai daqui de baixo sozinho.
+    const pasta = process.cwd().split(/[\\/]/).pop() ?? "meu-projeto";
+    const nomeSugerido = pasta
+        .replace(/[-_]+/g, " ")
+        .replace(/\s+/g, " ")
+        .trim()
+        .replace(/\b\w/g, (c) => c.toUpperCase()) || "Meu Projeto";
     const nome = (await pergunta(`\nNome do projeto [${nomeSugerido}]: `)) || nomeSugerido;
-    // Nome so com caracteres especiais (ex: "!!!") normaliza para string vazia — o
-    // fallback evita sugerir slug vazio, que o servidor recusaria com erro confuso.
-    const slugSugerido = nome
+    // O slug sai do nome, sem perguntar: e identificador, nao escolha editorial, e quem
+    // esta comecando nao tem como saber que ele vira a chave do `.dd-harness.json`.
+    // Nome so com caracteres especiais (ex: "!!!") normaliza para string vazia - o
+    // fallback evita slug vazio, que o servidor recusaria com erro confuso.
+    const slugDoProjeto = nome
         .toLowerCase()
         .normalize("NFD")
         .replace(/[̀-ͯ]/g, "")
         .replace(/[^a-z0-9]+/g, "-")
         .replace(/^-+|-+$/g, "") || "meu-projeto";
-    const slugDoProjeto = (await pergunta(`Identificador curto (slug) [${slugSugerido}]: `)) || slugSugerido;
+    console.log(`Identificador: ${slugDoProjeto}`);
     const resultadoProjeto = await criaProjeto(process.cwd(), slugDoProjeto, nome, {
         tenant,
         api: API_PADRAO,
@@ -186,6 +278,15 @@ async function comandoStart() {
             acrescentado: "atualizado .mcp.json (servidor adicionado ao que já existia)",
         }[mcp.estado]);
     }
+    if (mcp.ok) {
+        console.log("\nInstalando o servidor dd-harness-mcp (primeira vez pode demorar um pouco)...");
+        const { ok: instalou, erro: erroInstalacao } = await instalaMcp();
+        console.log(instalou
+            ? "dd-harness-mcp instalado — a próxima sessão do Claude Code conecta na hora."
+            : `AVISO: não consegui pré-instalar dd-harness-mcp (${erroInstalacao}). A primeira ` +
+                "conexão do Claude Code pode demorar ou falhar; se falhar, abra uma nova sessão " +
+                "e tente de novo.");
+    }
     // 6. AGENTS.md — so quem usa outra ferramenta alem do Claude Code precisa.
     const outraFerramenta = await pergunta("\nVai abrir este projeto em Codex, Cursor ou outra ferramenta além do Claude " +
         "Code? [s/N]: ");

package/dist/mcp/src/index.js

@@ -1,3 +1,4 @@
+#!/usr/bin/env node
 import { McpServer } from "@modelcontextprotocol/server";
 import { serveStdio } from "@modelcontextprotocol/server/stdio";
 import * as z from "zod/v4";
@@ -293,4 +294,35 @@ Conteúdo vazio é válido e significa apagar o artefato.`,
     });
     return server;
 }
-serveStdio(criaServidor);
+/**
+ * `--help` / `--version` respondem e SAEM. Sem isto, qualquer invocacao com argumento
+ * caia no `serveStdio` e ficava esperando stdin para sempre — e foi assim que o
+ * aquecedor de cache do `dd-harness start` (que chamava `npx -y dd-harness-mcp --help`
+ * so para forcar o download) travou o wizard inteiro depois que o shebang passou a
+ * deixar o servidor subir de verdade.
+ */
+const args = process.argv.slice(2);
+if (args.includes("--help") || args.includes("-h")) {
+    console.log(`dd-harness-mcp — servidor MCP do dd-harness (fala por stdio, nao por terminal)
+
+Nao se roda a mao: quem o inicia e o host MCP (Claude Code, Codex, Cursor), pela
+declaracao em \`.mcp.json\`. Sem um host do outro lado ele fica esperando mensagem
+no stdin, que e o comportamento correto de um servidor stdio.
+
+  --help      esta mensagem
+  --version   a versao instalada
+
+Para declarar no seu repositorio, rode \`dd-harness start\`.`);
+}
+else if (args.includes("--version") || args.includes("-V")) {
+    const { readFile } = await import("node:fs/promises");
+    const { fileURLToPath } = await import("node:url");
+    const { dirname, join } = await import("node:path");
+    // `dist/mcp/src/index.js` -> tres niveis ate a raiz do pacote.
+    const aqui = dirname(fileURLToPath(import.meta.url));
+    const lido = await readFile(join(aqui, "..", "..", "..", "package.json"), "utf8");
+    console.log(JSON.parse(lido).version ?? "desconhecida");
+}
+else {
+    serveStdio(criaServidor);
+}

package/package.json

@@ -1,40 +1,40 @@
-{
-  "name": "dd-harness-mcp",
-  "version": "0.7.0",
-  "type": "module",
-  "description": "Servidor MCP do dd-harness: o agente consulta e grava memoria como ferramenta, sem passar por arquivo.",
-  "license": "UNLICENSED",
-  "author": "Diego Dias",
-  "keywords": [
-    "claude-code",
-    "mcp",
-    "model-context-protocol",
-    "ai-agents",
-    "memory"
-  ],
-  "homepage": "https://dd-harness.vercel.app",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/diegodias93/dd-harness-online.git",
-    "directory": "packages/mcp"
-  },
-  "//bin": "`dist/mcp/src/` e nao `dist/` porque o build abrange dois diretorios (este pacote e o fonte do CLI), e o `rootDir` comum e `packages/`. Conferir com `node dist/mcp/src/index.js` antes de publicar: caminho errado aqui instala e quebra no primeiro uso.",
-  "bin": {
-    "dd-harness-mcp": "dist/mcp/src/index.js"
-  },
-  "files": [
-    "dist"
-  ],
-  "engines": {
-    "node": ">=20"
-  },
-  "dependencies": {
-    "@modelcontextprotocol/server": "^2.0.0",
-    "zod": "^4.5.4"
-  },
-  "scripts": {
-    "typecheck": "tsc -p . --noEmit",
-    "build": "tsc -p tsconfig.build.json",
-    "prepublishOnly": "npm run build"
-  }
-}
+{
+  "name": "dd-harness-mcp",
+  "version": "0.9.0",
+  "type": "module",
+  "description": "Servidor MCP do dd-harness: o agente consulta e grava memoria como ferramenta, sem passar por arquivo.",
+  "license": "UNLICENSED",
+  "author": "Diego Dias",
+  "keywords": [
+    "claude-code",
+    "mcp",
+    "model-context-protocol",
+    "ai-agents",
+    "memory"
+  ],
+  "homepage": "https://dd-harness.vercel.app",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/diegodias93/dd-harness-online.git",
+    "directory": "packages/mcp"
+  },
+  "//bin": "`dist/mcp/src/` e nao `dist/` porque o build abrange dois diretorios (este pacote e o fonte do CLI), e o `rootDir` comum e `packages/`. Conferir com `npx -y dd-harness-mcp` numa cache limpa antes de publicar — NAO com `node dist/mcp/src/index.js`: rodar pelo caminho direto passa mesmo quando o pacote instalado esta quebrado, porque o defeito mora no shim que o npm gera. Sem o shebang em `src/index.ts` o shim `.cmd` do Windows chama o `.js` sem `node` na frente, e o servidor morre limpo (exit 0, em silencio) antes do handshake — o cliente so ve CONNECTION_CLOSED.",
+  "bin": {
+    "dd-harness-mcp": "dist/mcp/src/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/server": "^2.0.0",
+    "zod": "^4.5.4"
+  },
+  "scripts": {
+    "typecheck": "tsc -p . --noEmit",
+    "build": "tsc -p tsconfig.build.json",
+    "prepublishOnly": "npm run build"
+  }
+}