dd-harness 0.8.0 → 0.10.0

package/dist/acentuacao.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Recusa conteudo em pt-BR escrito sem acento — o portao, nao um pedido.
+ *
+ * **Gemeo de `src/lib/acentuacao.ts`, de proposito.** O CLI e publicado no npm com
+ * `files: ["dist"]` e sem nenhuma dependencia; importar do app quebraria o pacote
+ * instalado, e fazer o app depender do pacote publicavel so para compartilhar uma lista
+ * de palavras acopla mais do que resolve. O `tsconfig.build.json` do MCP ja assume essa
+ * troca ("duplica algumas funcoes no pacote publicado, e esse e o preco"). Mesma escolha
+ * de `recusaAncoraInvalida`, que tambem espelha de proposito um CHECK do banco: a API e a
+ * autoridade, isto aqui so adianta o erro antes da rede. **Mudou a lista aqui, mude la.**
+ *
+ * **Por que isto existe.** Acento entra no embedding. Medido com
+ * `text-embedding-3-small` nas frases reais do acervo, a mesma sentenca com e sem acento
+ * da ~0,94 de similaridade: 6% de perda. Sozinho nao seria fatal; o que quebra a busca e
+ * a **assimetria** — com metade do acervo acentuado e metade nao, o vizinho mais proximo
+ * passa a ser quem casa com a GRAFIA da consulta, nao quem e mais relevante. A busca nao
+ * devolve erro: devolve resultado ruim com aparencia de bom, que e a falha que este
+ * projeto mais combate (mesma razao de `provedor.ts` recusar vetor de outro provedor).
+ *
+ * **Por que recusar em vez de corrigir.** Restaurar acento por heuristica erra: `e`/`é`,
+ * `esta`/`está`, `secretaria`/`secretária` dependem de sintaxe, nao de ortografia. Corrigir
+ * gravaria conteudo adulterado em silencio — pior que recusar, porque ninguem revisa.
+ *
+ * **Por que lista de palavras e nao dicionario.** Sem dependencia nova, e o alvo e o caso
+ * real observado: o texto INTEIRO em ASCII. Codigo, termo em ingles e nome proprio nao
+ * disparam porque nao estao na lista.
+ */
+/** Uma palavra suspeita encontrada no texto. */
+export type Suspeita = {
+    escrito: string;
+    correto: string;
+};
+/**
+ * Devolve as palavras que exigem acento e apareceram sem ele.
+ *
+ * Percorre o texto ja em minusculas e sem os trechos onde ASCII e legitimo: bloco de
+ * codigo (``` ... ```), codigo inline (`...`), URL e caminho de arquivo. Sem isso, um
+ * `preco_centavos` no meio de um identificador acusaria prosa que esta correta.
+ */
+export declare function palavrasSemAcento(texto: string): Suspeita[];
+/**
+ * A mensagem de recusa, ou `null` se o texto passa.
+ *
+ * Recebe os campos ja separados para poder dizer ONDE esta o problema — quem escreveu o
+ * corpo inteiro sem acento nao quer procurar a palavra em 40 linhas.
+ */
+export declare function recusaPorAcentuacao(campos: {
+    campo: string;
+    texto: string;
+}[]): string | null;

package/dist/acentuacao.js

@@ -0,0 +1,251 @@
+/**
+ * Recusa conteudo em pt-BR escrito sem acento — o portao, nao um pedido.
+ *
+ * **Gemeo de `src/lib/acentuacao.ts`, de proposito.** O CLI e publicado no npm com
+ * `files: ["dist"]` e sem nenhuma dependencia; importar do app quebraria o pacote
+ * instalado, e fazer o app depender do pacote publicavel so para compartilhar uma lista
+ * de palavras acopla mais do que resolve. O `tsconfig.build.json` do MCP ja assume essa
+ * troca ("duplica algumas funcoes no pacote publicado, e esse e o preco"). Mesma escolha
+ * de `recusaAncoraInvalida`, que tambem espelha de proposito um CHECK do banco: a API e a
+ * autoridade, isto aqui so adianta o erro antes da rede. **Mudou a lista aqui, mude la.**
+ *
+ * **Por que isto existe.** Acento entra no embedding. Medido com
+ * `text-embedding-3-small` nas frases reais do acervo, a mesma sentenca com e sem acento
+ * da ~0,94 de similaridade: 6% de perda. Sozinho nao seria fatal; o que quebra a busca e
+ * a **assimetria** — com metade do acervo acentuado e metade nao, o vizinho mais proximo
+ * passa a ser quem casa com a GRAFIA da consulta, nao quem e mais relevante. A busca nao
+ * devolve erro: devolve resultado ruim com aparencia de bom, que e a falha que este
+ * projeto mais combate (mesma razao de `provedor.ts` recusar vetor de outro provedor).
+ *
+ * **Por que recusar em vez de corrigir.** Restaurar acento por heuristica erra: `e`/`é`,
+ * `esta`/`está`, `secretaria`/`secretária` dependem de sintaxe, nao de ortografia. Corrigir
+ * gravaria conteudo adulterado em silencio — pior que recusar, porque ninguem revisa.
+ *
+ * **Por que lista de palavras e nao dicionario.** Sem dependencia nova, e o alvo e o caso
+ * real observado: o texto INTEIRO em ASCII. Codigo, termo em ingles e nome proprio nao
+ * disparam porque nao estao na lista.
+ */
+/**
+ * Palavras cuja grafia correta em pt-BR SEMPRE leva acento — nao existe homografo sem
+ * acento que as torne ambiguas.
+ *
+ * Criterio de entrada nesta lista: a forma sem acento **nao e palavra** do portugues.
+ * Por isso `e` (de `é`), `esta` (de `está`), `so` (de `só`), `ate` (de `até`) ficam de
+ * FORA por mais comuns que sejam — `e`, `esta` e `so` existem sozinhas, e acusar um texto
+ * legitimo e pior do que deixar um passar. A lista nao precisa ser exaustiva: basta pegar
+ * texto corrido em pt-BR, e um paragrafo de verdade quase sempre tem varias destas.
+ */
+const SEMPRE_ACENTUADAS = new Map([
+    ["nao", "não"],
+    ["sao", "são"],
+    ["tambem", "também"],
+    ["entao", "então"],
+    ["porem", "porém"],
+    ["alem", "além"],
+    ["memoria", "memória"],
+    ["memorias", "memórias"],
+    ["codigo", "código"],
+    ["funcao", "função"],
+    ["funcoes", "funções"],
+    ["versao", "versão"],
+    ["versoes", "versões"],
+    ["validacao", "validação"],
+    ["informacao", "informação"],
+    ["informacoes", "informações"],
+    ["aplicacao", "aplicação"],
+    ["configuracao", "configuração"],
+    ["implementacao", "implementação"],
+    ["decisao", "decisão"],
+    ["decisoes", "decisões"],
+    ["excecao", "exceção"],
+    ["excecoes", "exceções"],
+    ["padrao", "padrão"],
+    ["usuario", "usuário"],
+    ["usuarios", "usuários"],
+    ["necessario", "necessário"],
+    ["obrigatorio", "obrigatório"],
+    ["proprio", "próprio"],
+    ["propria", "própria"],
+    ["publico", "público"],
+    ["publica", "pública"],
+    ["unico", "único"],
+    ["unica", "única"],
+    ["basico", "básico"],
+    ["automatico", "automático"],
+    ["historico", "histórico"],
+    ["numero", "número"],
+    ["numeros", "números"],
+    ["calculo", "cálculo"],
+    ["metodo", "método"],
+    ["modulo", "módulo"],
+    ["servico", "serviço"],
+    ["servicos", "serviços"],
+    ["referencia", "referência"],
+    ["consequencia", "consequência"],
+    ["dependencia", "dependência"],
+    ["experiencia", "experiência"],
+    ["sequencia", "sequência"],
+    ["transacao", "transação"],
+    ["sessao", "sessão"],
+    ["expiracao", "expiração"],
+    ["precisao", "precisão"],
+    ["preco", "preço"],
+    ["precos", "preços"],
+    ["cabecalho", "cabeçalho"],
+    ["comeca", "começa"],
+    ["comecar", "começar"],
+    ["criterio", "critério"],
+    ["criterios", "critérios"],
+    ["dominio", "domínio"],
+    ["indice", "índice"],
+    ["minimo", "mínimo"],
+    ["maximo", "máximo"],
+    ["ultimo", "último"],
+    ["proximo", "próximo"],
+    ["disponivel", "disponível"],
+    ["possivel", "possível"],
+    ["impossivel", "impossível"],
+    ["responsavel", "responsável"],
+    ["nivel", "nível"],
+    ["util", "útil"],
+    ["dificil", "difícil"],
+    ["facil", "fácil"],
+    ["ja", "já"],
+    ["voce", "você"],
+    ["ambiguo", "ambíguo"],
+    ["generico", "genérico"],
+    ["especifico", "específico"],
+    ["logica", "lógica"],
+    ["pagina", "página"],
+    ["paginas", "páginas"],
+    ["orfao", "órfão"],
+    ["apos", "após"],
+    ["atraves", "através"],
+    ["representacao", "representação"],
+    ["representacoes", "representações"],
+    ["operacao", "operação"],
+    ["operacoes", "operações"],
+    ["integracao", "integração"],
+    ["migracao", "migração"],
+    ["autenticacao", "autenticação"],
+    ["autorizacao", "autorização"],
+    ["indexacao", "indexação"],
+    ["condicao", "condição"],
+    ["condicoes", "condições"],
+    ["relacao", "relação"],
+    ["situacao", "situação"],
+    ["definicao", "definição"],
+    ["descricao", "descrição"],
+    ["restricao", "restrição"],
+    ["restricoes", "restrições"],
+    ["execucao", "execução"],
+    ["atencao", "atenção"],
+    ["intencao", "intenção"],
+    ["manutencao", "manutenção"],
+    ["observacao", "observação"],
+    ["alteracao", "alteração"],
+    ["criacao", "criação"],
+    ["remocao", "remoção"],
+    ["gravacao", "gravação"],
+    ["duplicacao", "duplicação"],
+    ["comparacao", "comparação"],
+    ["verificacao", "verificação"],
+    ["conteudo", "conteúdo"],
+    ["politica", "política"],
+    ["politicas", "políticas"],
+    ["estrategia", "estratégia"],
+    ["tecnico", "técnico"],
+    ["tecnica", "técnica"],
+    ["semantica", "semântica"],
+    ["semantico", "semântico"],
+    ["parametro", "parâmetro"],
+    ["parametros", "parâmetros"],
+    ["variavel", "variável"],
+    ["variaveis", "variáveis"],
+    ["multiplo", "múltiplo"],
+    ["multiplos", "múltiplos"],
+    ["multipla", "múltipla"],
+    ["invalido", "inválido"],
+    ["invalida", "inválida"],
+    ["valido", "válido"],
+    ["obrigatoria", "obrigatória"],
+    ["tres", "três"],
+    ["proposito", "propósito"],
+    ["cenario", "cenário"],
+    ["relatorio", "relatório"],
+    ["diretorio", "diretório"],
+    ["repositorio", "repositório"],
+    ["formulario", "formulário"],
+    ["comentario", "comentário"],
+    ["comentarios", "comentários"],
+    ["glossario", "glossário"],
+    ["saidas", "saídas"],
+    ["duvida", "dúvida"],
+    ["duvidas", "dúvidas"],
+    ["ausencia", "ausência"],
+    ["presenca", "presença"],
+    ["diferenca", "diferença"],
+    ["diferencas", "diferenças"],
+    ["seguranca", "segurança"],
+    ["licenca", "licença"],
+    ["mudanca", "mudança"],
+    ["mudancas", "mudanças"],
+    ["heranca", "herança"],
+    ["cabecalhos", "cabeçalhos"],
+    ["comecam", "começam"],
+    ["sera", "será"],
+    ["serao", "serão"],
+]);
+/**
+ * Devolve as palavras que exigem acento e apareceram sem ele.
+ *
+ * Percorre o texto ja em minusculas e sem os trechos onde ASCII e legitimo: bloco de
+ * codigo (``` ... ```), codigo inline (`...`), URL e caminho de arquivo. Sem isso, um
+ * `preco_centavos` no meio de um identificador acusaria prosa que esta correta.
+ */
+export function palavrasSemAcento(texto) {
+    const limpo = texto
+        .replace(/```[\s\S]*?```/g, " ")
+        .replace(/`[^`\n]*`/g, " ")
+        .replace(/\bhttps?:\/\/\S+/gi, " ")
+        .replace(/\b[\w./-]+\.(?:ts|tsx|js|mjs|json|md|sql|css|html|py|sh)\b/gi, " ")
+        .toLowerCase();
+    const achadas = new Map();
+    for (const bruta of limpo.split(/[^a-zà-ÿ]+/)) {
+        if (!bruta)
+            continue;
+        const correto = SEMPRE_ACENTUADAS.get(bruta);
+        if (correto)
+            achadas.set(bruta, correto);
+    }
+    return [...achadas].map(([escrito, correto]) => ({ escrito, correto }));
+}
+/**
+ * A mensagem de recusa, ou `null` se o texto passa.
+ *
+ * Recebe os campos ja separados para poder dizer ONDE esta o problema — quem escreveu o
+ * corpo inteiro sem acento nao quer procurar a palavra em 40 linhas.
+ */
+export function recusaPorAcentuacao(campos) {
+    const porCampo = campos
+        .map(({ campo, texto }) => ({ campo, suspeitas: palavrasSemAcento(texto) }))
+        .filter((c) => c.suspeitas.length > 0);
+    if (porCampo.length === 0)
+        return null;
+    const detalhe = porCampo
+        .map(({ campo, suspeitas }) => {
+        const amostra = suspeitas
+            .slice(0, 5)
+            .map((s) => `${s.escrito} → ${s.correto}`)
+            .join(", ");
+        const resto = suspeitas.length > 5 ? `, e mais ${suspeitas.length - 5}` : "";
+        return `  ${campo}: ${amostra}${resto}`;
+    })
+        .join("\n");
+    return ("conteúdo em pt-BR sem acentuação. A acentuação entra no embedding: a mesma frase " +
+        "sem acento cai para ~0,94 de similaridade, e um acervo com grafia misturada faz a " +
+        "busca premiar quem escreve igual à consulta em vez de quem é relevante.\n" +
+        `${detalhe}\n` +
+        "Reescreva com a acentuação correta — não é corrigido automaticamente porque " +
+        "adivinhar entre `e`/`é` e `esta`/`está` gravaria texto adulterado em silêncio.");
+}

package/dist/config.d.ts

@@ -17,6 +17,17 @@ export type ConfigDoRepo = {
 export declare const CAMINHO_CONFIG = ".dd-harness.json";
 export declare const CAMINHO_MANIFESTO = "dd-harness/manifest.json";
 export declare function leConfigDoRepo(raiz: string): Promise<ConfigDoRepo>;
+export type ConfigDaMaquina = {
+    /**
+     * Onde o monorepo `dd-harness_new` esta clonado nesta maquina. O worker de embeddings
+     * (`pnpm worker`) so existe ali dentro — sem este caminho, o hook de sessao nao tem
+     * como subir o worker quando roda de dentro do projeto CONSUMIDOR, que e o caso comum.
+     * Opcional: sem ele, so degrada para "avisa que a fila esta parada", nunca quebra.
+     */
+    workerRepo?: string;
+};
+export declare function leConfigDaMaquina(): Promise<ConfigDaMaquina>;
+export declare function guardaConfigDaMaquina(parcial: ConfigDaMaquina): Promise<string>;
 /**
  * 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.

package/dist/config.js

@@ -31,6 +31,24 @@ export async function leConfigDoRepo(raiz) {
     };
 }
 const arquivoDeCredenciais = () => join(homedir(), ".dd-harness", "credentials.json");
+const arquivoDeConfigDaMaquina = () => join(homedir(), ".dd-harness", "config.json");
+export async function leConfigDaMaquina() {
+    try {
+        const cru = await readFile(arquivoDeConfigDaMaquina(), "utf8");
+        return JSON.parse(cru);
+    }
+    catch {
+        return {};
+    }
+}
+export async function guardaConfigDaMaquina(parcial) {
+    const caminho = arquivoDeConfigDaMaquina();
+    await mkdir(join(homedir(), ".dd-harness"), { recursive: true });
+    const atual = await leConfigDaMaquina();
+    const mesclado = { ...atual, ...parcial };
+    await writeFile(caminho, `${JSON.stringify(mesclado, null, 2)}\n`, "utf8");
+    return caminho;
+}
 /**
  * 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.

package/dist/escreve-config.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Escrita de `.claude/settings.json`, `.mcp.json` e `AGENTS.md`, com merge.
+ *
+ * `init` (o comando antigo) so SUGERE esses arquivos — decisao de proposito, porque
+ * mesclar JSON alheio e onde falha silenciosa nasce. `start` (o wizard) reverte essa
+ * decisao para ganhar "funciona de primeira sem copiar e colar", mas o preco combinado
+ * e nunca perder o que a pessoa ja tinha: cada funcao aqui LE o arquivo antes de
+ * escrever, e so INSERE a chave do dd-harness — nunca substitui o resto.
+ *
+ * JSON que nao interpreta e tratado como "nao sei mesclar", nao como "esta vazio": e
+ * mais seguro parar e avisar do que sobrescrever um arquivo que a pessoa escreveu a mao
+ * e que, por acaso, tem um erro de sintaxe.
+ */
+export type ResultadoDaEscrita<T extends string> = {
+    ok: true;
+    estado: T;
+} | {
+    ok: false;
+    motivo: "json-invalido";
+    caminho: string;
+};
+/**
+ * Acrescenta o hook do dd-harness a `.claude/settings.json`, sem tocar em outros hooks.
+ *
+ * `SessionStart` e um ARRAY de matcher groups no schema do Claude Code — pensado para
+ * varios hooks convivendo. Por isso a acao certa quando ja existe outro hook de
+ * SessionStart e ACRESCENTAR um grupo novo ao array, nao substituir nem perguntar: sao
+ * dois hooks independentes, cada um cuidando da sua coisa.
+ */
+export declare function escreveHook(raiz: string): Promise<ResultadoDaEscrita<"criado" | "ja-tinha" | "acrescentado">>;
+/** Acrescenta o servidor MCP a `.mcp.json`, sem tocar em outros servidores. */
+export declare function escreveMcp(raiz: string): Promise<ResultadoDaEscrita<"criado" | "ja-tinha" | "acrescentado">>;
+/**
+ * `AGENTS.md` e markdown livre, nao JSON — nao ha "mesclar" de verdade. Se o arquivo ja
+ * existe (com qualquer conteudo), so acrescenta a instrucao no fim; nunca sobrescreve
+ * o que a pessoa escreveu, porque markdown de outra ferramenta e mais dificil de separar
+ * do nosso do que uma chave de objeto.
+ */
+export declare function escreveAgents(raiz: string): Promise<{
+    estado: "criado" | "ja-tinha" | "acrescentado";
+}>;

package/dist/escreve-config.js

@@ -0,0 +1,101 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+const COMANDO_DO_HOOK = "dd-harness politica --hook";
+/**
+ * Acrescenta o hook do dd-harness a `.claude/settings.json`, sem tocar em outros hooks.
+ *
+ * `SessionStart` e um ARRAY de matcher groups no schema do Claude Code — pensado para
+ * varios hooks convivendo. Por isso a acao certa quando ja existe outro hook de
+ * SessionStart e ACRESCENTAR um grupo novo ao array, nao substituir nem perguntar: sao
+ * dois hooks independentes, cada um cuidando da sua coisa.
+ */
+export async function escreveHook(raiz) {
+    const caminho = join(raiz, ".claude", "settings.json");
+    let doc = {};
+    try {
+        const cru = await readFile(caminho, "utf8");
+        doc = JSON.parse(cru);
+    }
+    catch (erro) {
+        if (erro.code !== "ENOENT") {
+            return { ok: false, motivo: "json-invalido", caminho };
+        }
+    }
+    const hooks = (doc.hooks ??= {});
+    const sessionStart = (hooks.SessionStart ??= []);
+    const jaTemONosso = JSON.stringify(sessionStart).includes(COMANDO_DO_HOOK);
+    if (jaTemONosso)
+        return { ok: true, estado: "ja-tinha" };
+    const eraVazio = sessionStart.length === 0;
+    sessionStart.push({
+        hooks: [
+            {
+                type: "command",
+                command: COMANDO_DO_HOOK,
+                statusMessage: "Carregando a política do dd-harness...",
+            },
+        ],
+    });
+    await mkdir(dirname(caminho), { recursive: true });
+    await writeFile(caminho, `${JSON.stringify(doc, null, 2)}\n`, "utf8");
+    return { ok: true, estado: eraVazio ? "criado" : "acrescentado" };
+}
+/** Acrescenta o servidor MCP a `.mcp.json`, sem tocar em outros servidores. */
+export async function escreveMcp(raiz) {
+    const caminho = join(raiz, ".mcp.json");
+    let doc = {};
+    try {
+        const cru = await readFile(caminho, "utf8");
+        doc = JSON.parse(cru);
+    }
+    catch (erro) {
+        if (erro.code !== "ENOENT") {
+            return { ok: false, motivo: "json-invalido", caminho };
+        }
+    }
+    const servidores = (doc.mcpServers ??= {});
+    if (servidores["dd-harness"])
+        return { ok: true, estado: "ja-tinha" };
+    const eraVazio = Object.keys(servidores).length === 0;
+    servidores["dd-harness"] = { command: "npx", args: ["-y", "dd-harness-mcp"] };
+    await mkdir(dirname(caminho), { recursive: true });
+    await writeFile(caminho, `${JSON.stringify(doc, null, 2)}\n`, "utf8");
+    return { ok: true, estado: eraVazio ? "criado" : "acrescentado" };
+}
+/**
+ * `AGENTS.md` e markdown livre, nao JSON — nao ha "mesclar" de verdade. Se o arquivo ja
+ * existe (com qualquer conteudo), so acrescenta a instrucao no fim; nunca sobrescreve
+ * o que a pessoa escreveu, porque markdown de outra ferramenta e mais dificil de separar
+ * do nosso do que uma chave de objeto.
+ */
+export async function escreveAgents(raiz) {
+    const caminho = join(raiz, "AGENTS.md");
+    const instrucao = SUGESTAO_AGENTS;
+    let atual = null;
+    try {
+        atual = await readFile(caminho, "utf8");
+    }
+    catch {
+        // Sem arquivo: cria do zero.
+    }
+    if (atual === null) {
+        await writeFile(caminho, `${instrucao}\n`, "utf8");
+        return { estado: "criado" };
+    }
+    if (atual.includes("ler_artefato"))
+        return { estado: "ja-tinha" };
+    const separador = atual.endsWith("\n") ? "\n" : "\n\n";
+    await writeFile(caminho, `${atual}${separador}${instrucao}\n`, "utf8");
+    return { estado: "acrescentado" };
+}
+const SUGESTAO_AGENTS = `## Protocolo do dd-harness
+
+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.`;

package/dist/gravar.js

@@ -1,4 +1,5 @@
 import { readFile } from "node:fs/promises";
+import { recusaPorAcentuacao } from "./acentuacao.js";
 import { cabecalhos, credencial, pede, recusa } from "./api.js";
 const OBRIGATORIOS = ["name", "titulo", "description", "pasta"];
 /**
@@ -135,6 +136,15 @@ export function interpreta(texto) {
         .trim();
     if (!corpo)
         throw new Error("o corpo da memória está vazio.");
+    // A acentuacao entra no embedding, entao grafia misturada degrada a busca de todo o
+    // acervo. A API recusa igual; aqui o erro chega antes da rede e ja aponta a palavra.
+    const semAcento = recusaPorAcentuacao([
+        { campo: "titulo", texto: campos.get("titulo") },
+        { campo: "description", texto: campos.get("description") },
+        { campo: "corpo", texto: corpo },
+    ]);
+    if (semAcento)
+        throw new Error(semAcento);
     const cauda = resto.slice(corte);
     const tambem = campos.get("projetos") ?? "";
     return {

package/dist/index.js

@@ -1,14 +1,19 @@
 #!/usr/bin/env node
+import { spawn } from "node:child_process";
+import { access } from "node:fs/promises";
+import { join } from "node:path";
 import { termosDaConsulta } from "./argv.js";
 import { check, status } from "./check.js";
-import { leConfigDoRepo, guardaToken } from "./config.js";
+import { CAMINHO_CONFIG, guardaConfigDaMaquina, guardaToken, leConfigDaMaquina, leConfigDoRepo, leToken, } from "./config.js";
+import { escreveAgents, escreveHook, escreveMcp } from "./escreve-config.js";
 import { grava } from "./gravar.js";
 import { init, SUGESTAO_AGENTS, SUGESTAO_HOOK, SUGESTAO_MCP } from "./init.js";
+import { pergunta, escolha, fechaPerguntas } from "./pergunta.js";
 import { buscaPolitica } from "./politica.js";
 import { busca } from "./buscar.js";
 import { arquiva, edita, le } from "./curar.js";
 import { criaPasta } from "./pasta.js";
-import { criaProjeto } from "./projeto.js";
+import { criaProjeto, listaTenants } from "./projeto.js";
 import { reancora } from "./reancorar.js";
 import { subiuOWorker } from "./worker.js";
 /**
@@ -21,6 +26,8 @@ import { subiuOWorker } from "./worker.js";
  */
 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>]
@@ -71,6 +78,166 @@ 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) => {
+        const p = spawn("npx", ["-y", "dd-harness-mcp", "--help"], {
+            shell: process.platform === "win32",
+            stdio: "ignore",
+        });
+        p.on("exit", (code) => resolve(code === 0));
+        p.on("error", () => resolve(false));
+    });
+}
+/**
+ * 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".
+ */
+function tentaAbrirNavegador(url) {
+    const comando = process.platform === "win32" ? "start" : process.platform === "darwin" ? "open" : "xdg-open";
+    try {
+        spawn(comando, process.platform === "win32" ? ["", url] : [url], {
+            shell: process.platform === "win32",
+            stdio: "ignore",
+            detached: true,
+        }).unref();
+    }
+    catch {
+        // Segue sem navegador — a URL impressa antes desta chamada ja resolve.
+    }
+}
+/**
+ * `dd-harness start` — o wizard para pasta vazia.
+ *
+ * Ate aqui, comecar um projeto exigia saber de memoria a sequencia certa
+ * (`projeto` -> `init` -> copiar tres blocos de JSON) e o slug do tenant. `start`
+ * conduz tudo numa tacada, perguntando so o que falta.
+ *
+ * Reverte "sugerir, nunca escrever" para `.claude/settings.json` e `.mcp.json` — decisao
+ * tomada de proposito aqui, ao contrario de `init`, que continua so sugerindo. O preco e
+ * o merge cuidadoso em `escreve-config.ts`: nunca perder o que a pessoa ja tinha.
+ */
+async function comandoStart() {
+    const caminhoConfig = join(process.cwd(), CAMINHO_CONFIG);
+    try {
+        await access(caminhoConfig);
+        throw new Error(`este repositório já tem ${CAMINHO_CONFIG} — start é só para pasta vazia. ` +
+            "Use `dd-harness init` para ajustar um projeto já existente.");
+    }
+    catch (erro) {
+        if (erro instanceof Error && erro.message.includes("já tem"))
+            throw erro;
+        // ENOENT: exatamente o caso esperado, segue.
+    }
+    console.log("Iniciando o dd-harness nesta pasta.\n");
+    // 1. Credencial. Sem ela nada do resto e possivel — nem listar tenant.
+    let token = await leToken(API_PADRAO);
+    if (!token) {
+        console.log(`Sem credencial salva para ${API_PADRAO}.`);
+        token = await pergunta("Cole o token pessoal (crie um em /tokens na interface): ");
+        await guardaToken(API_PADRAO, token);
+        console.log("Credencial guardada.\n");
+    }
+    // 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);
+    while (tenants.length === 0) {
+        const url = `${API_PADRAO}/tenants`;
+        console.log(`\nVocê ainda não participa de nenhum espaço. Abrindo ${url} ...`);
+        tentaAbrirNavegador(url);
+        await pergunta("Crie um espaço lá e volte aqui. Pressione Enter para continuar: ");
+        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";
+    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
+        .toLowerCase()
+        .normalize("NFD")
+        .replace(/[̀-ͯ]/g, "")
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "") || "meu-projeto";
+    const slugDoProjeto = (await pergunta(`Identificador curto (slug) [${slugSugerido}]: `)) || slugSugerido;
+    const resultadoProjeto = await criaProjeto(process.cwd(), slugDoProjeto, nome, {
+        tenant,
+        api: API_PADRAO,
+    });
+    console.log(resultadoProjeto.jaExistia
+        ? `\nProjeto ${resultadoProjeto.projeto} já existia — usando ele.`
+        : `\nProjeto ${resultadoProjeto.projeto} criado.`);
+    // 4. Config do repositorio — o unico arquivo que `init` tambem escreveria.
+    const r = await init(process.cwd(), { tenant, projeto: resultadoProjeto.projeto, api: API_PADRAO });
+    console.log(r.config === "criada" ? `criado  ${CAMINHO_CONFIG}` : `mantido ${CAMINHO_CONFIG}`);
+    // 5. Hook e MCP — ESCRITOS, com merge. E aqui que `start` diverge de `init`.
+    const hook = await escreveHook(process.cwd());
+    if (!hook.ok) {
+        console.log(`\nAVISO: ${hook.caminho} não é um JSON válido — não toquei nele. ` +
+            "Acrescente manualmente:\n");
+        console.log(SUGESTAO_HOOK);
+    }
+    else {
+        console.log({ criado: "criado  .claude/settings.json (hook adicionado)",
+            "ja-tinha": "mantido .claude/settings.json — hook já estava lá",
+            acrescentado: "atualizado .claude/settings.json (hook adicionado ao que já existia)",
+        }[hook.estado]);
+    }
+    const mcp = await escreveMcp(process.cwd());
+    if (!mcp.ok) {
+        console.log(`\nAVISO: ${mcp.caminho} não é um JSON válido — não toquei nele. ` +
+            "Acrescente manualmente:\n");
+        console.log(SUGESTAO_MCP);
+    }
+    else {
+        console.log({ criado: "criado  .mcp.json (servidor dd-harness adicionado)",
+            "ja-tinha": "mantido .mcp.json — servidor já estava declarado",
+            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 instalou = 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. 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]: ");
+    if (/^s/i.test(outraFerramenta)) {
+        const agents = await escreveAgents(process.cwd());
+        console.log({ criado: "criado  AGENTS.md",
+            "ja-tinha": "mantido AGENTS.md — já apontava para a política",
+            acrescentado: "atualizado AGENTS.md (instrução acrescentada ao que já existia)",
+        }[agents.estado]);
+    }
+    // 7. Onde esta o monorepo do worker nesta maquina? So pergunta uma vez, e so importa
+    // se houver memoria na fila agora — pular aqui nao trava nada, so avisa mais vezes.
+    const semWorkerConfigurado = !(await temWorkerConfigurado());
+    if (semWorkerConfigurado) {
+        const caminho = await pergunta("\nO worker de embeddings roda local (não hospedado). Onde está o repositório " +
+            "`dd-harness_new` clonado nesta máquina? (Enter para pular — o hook vai " +
+            "avisar quando precisar): ");
+        if (caminho)
+            await guardaConfigDaMaquina({ workerRepo: caminho });
+    }
+    fechaPerguntas();
+    console.log("\nPronto. Abra uma sessão do Claude Code nesta pasta — a política vai ser o " +
+        "primeiro assunto.");
+}
+async function temWorkerConfigurado() {
+    const { workerRepo } = await leConfigDaMaquina();
+    return Boolean(workerRepo);
+}
 async function comandoInit(argv) {
     const tenant = argumento(argv, "tenant");
     const projeto = argumento(argv, "projeto");
@@ -527,6 +694,8 @@ async function principal() {
         return;
     }
     switch (comando) {
+        case "start":
+            return comandoStart();
         case "init":
             return comandoInit(resto);
         case "login":

package/dist/pergunta.d.ts

@@ -0,0 +1,7 @@
+export declare function pergunta(texto: string): Promise<string>;
+export declare function fechaPerguntas(): void;
+/** Numera as opcoes, pede um numero, devolve o item escolhido. Sem loop de retry: erra, recomeca o comando — start nao e ambiente para validar input ao infinito. */
+export declare function escolha<T>(titulo: string, itens: {
+    rotulo: string;
+    valor: T;
+}[]): Promise<T>;

package/dist/pergunta.js

@@ -0,0 +1,31 @@
+import { createInterface } from "node:readline/promises";
+/**
+ * Leitura de terminal, so para `dd-harness start`.
+ *
+ * O resto do CLI e puramente por flag — nao interativo de proposito, porque script e
+ * gancho (`post-commit`, CI) nao tem ninguem para responder um prompt. `start` e a
+ * excecao deliberada: e o comando de quem esta sentado no terminal, comecando um
+ * projeto do zero, sem saber os slugs de memoria.
+ */
+let rl = null;
+function interfaceAtual() {
+    return (rl ??= createInterface({ input: process.stdin, output: process.stdout }));
+}
+export async function pergunta(texto) {
+    return (await interfaceAtual().question(texto)).trim();
+}
+export function fechaPerguntas() {
+    rl?.close();
+    rl = null;
+}
+/** Numera as opcoes, pede um numero, devolve o item escolhido. Sem loop de retry: erra, recomeca o comando — start nao e ambiente para validar input ao infinito. */
+export async function escolha(titulo, itens) {
+    console.log(titulo);
+    itens.forEach((item, i) => console.log(`  ${i + 1}) ${item.rotulo}`));
+    const resposta = await pergunta("> ");
+    const indice = Number(resposta) - 1;
+    const escolhido = itens[indice];
+    if (!escolhido)
+        throw new Error(`escolha um número entre 1 e ${itens.length}.`);
+    return escolhido.valor;
+}

package/dist/projeto.d.ts

@@ -17,3 +17,11 @@ export declare function criaProjeto(raiz: string, slug: string, nome: string, ex
     projeto: string;
     jaExistia: boolean;
 }>;
+/**
+ * Os espacos (tenants) que este token alcanca — para `dd-harness start` deixar escolher
+ * em vez de exigir o slug de memoria.
+ */
+export declare function listaTenants(api: string, token: string): Promise<{
+    slug: string;
+    nome: string;
+}[]>;

package/dist/projeto.js

@@ -37,3 +37,14 @@ export async function criaProjeto(raiz, slug, nome, explicito = {}) {
     const { projeto } = (await resposta.json());
     return { projeto, jaExistia: false };
 }
+/**
+ * Os espacos (tenants) que este token alcanca — para `dd-harness start` deixar escolher
+ * em vez de exigir o slug de memoria.
+ */
+export async function listaTenants(api, token) {
+    const resposta = await pede(`${api}/api/v1/tenants`, { headers: cabecalhos(token) });
+    if (!resposta.ok)
+        await recusa(resposta);
+    const { tenants } = (await resposta.json());
+    return tenants;
+}

package/dist/worker.d.ts

@@ -1,21 +1,12 @@
 /**
- * Subir o worker de embeddings quando ha fila esperando.
+ * Onde rodar o worker, se soubermos.
  *
- * 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.
+ * Prioridade: `~/.dd-harness/config.json` (`workerRepo`, salvo por `dd-harness start` ou
+ * `dd-harness worker --configurar`) primeiro — e o caminho que vale em qualquer pasta que
+ * o CLI rode. Cai para `raiz` so por compatibilidade com quem já roda de dentro do
+ * monorepo sem ter configurado nada.
  */
-/** O worker vive aqui dentro. Noutro repositorio, nao ha o que subir. */
-export declare function temWorkerLocal(raiz: string): Promise<boolean>;
+export declare function achaOWorker(raiz: string): Promise<string | null>;
 export type Subida = {
     subiu: true;
 } | {

package/dist/worker.js

@@ -1,6 +1,7 @@
 import { spawn } from "node:child_process";
 import { access } from "node:fs/promises";
 import { join } from "node:path";
+import { leConfigDaMaquina } from "./config.js";
 /**
  * Subir o worker de embeddings quando ha fila esperando.
  *
@@ -14,19 +15,38 @@ import { join } from "node:path";
  *
  * - **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.
+ * - **So quando sabemos ONDE esta o worker.** Ele vive no monorepo `dd-harness_new`, nao
+ *   no repositorio consumidor — que e onde este hook roda na pratica. Achar o monorepo
+ *   custou uma medicao real: a primeira versao so checava `raiz` (o cwd de quem chamou),
+ *   entao so funcionava quando o dd-harness era executado de DENTRO do proprio monorepo
+ *   — nunca no caso real, que e o projeto do usuario noutra pasta.
  */
-/** O worker vive aqui dentro. Noutro repositorio, nao ha o que subir. */
-export async function temWorkerLocal(raiz) {
+/** O worker existe nesta pasta especifica? */
+async function ehOMonorepo(caminho) {
     try {
-        await access(join(raiz, "src", "worker", "indexador.ts"));
+        await access(join(caminho, "src", "worker", "indexador.ts"));
         return true;
     }
     catch {
         return false;
     }
 }
+/**
+ * Onde rodar o worker, se soubermos.
+ *
+ * Prioridade: `~/.dd-harness/config.json` (`workerRepo`, salvo por `dd-harness start` ou
+ * `dd-harness worker --configurar`) primeiro — e o caminho que vale em qualquer pasta que
+ * o CLI rode. Cai para `raiz` so por compatibilidade com quem já roda de dentro do
+ * monorepo sem ter configurado nada.
+ */
+export async function achaOWorker(raiz) {
+    const { workerRepo } = await leConfigDaMaquina();
+    if (workerRepo && (await ehOMonorepo(workerRepo)))
+        return workerRepo;
+    if (await ehOMonorepo(raiz))
+        return raiz;
+    return null;
+}
 /**
  * Dispara um lote e devolve na hora — nao espera terminar.
  *
@@ -41,12 +61,12 @@ export async function temWorkerLocal(raiz) {
 export async function subiuOWorker(raiz, esperando) {
     if (esperando <= 0)
         return { subiu: false, motivo: "sem-fila" };
-    if (!(await temWorkerLocal(raiz))) {
+    const repo = await achaOWorker(raiz);
+    if (!repo)
         return { subiu: false, motivo: "sem-worker" };
-    }
     try {
         const filho = spawn("npx", ["pnpm@latest", "worker", "--uma-vez"], {
-            cwd: raiz,
+            cwd: repo,
             detached: true,
             stdio: "ignore",
             shell: process.platform === "win32",

package/package.json

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