dd-harness 0.14.0 → 0.15.0

package/dist/index.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { spawn } from "node:child_process";
-import { access } from "node:fs/promises";
+import { access, readFile } 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
@@ -19,6 +19,7 @@ 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 { blocoDeSessao, criaFase, editaFase, formataChangelog, formataRoadmap, leFases, } from "./roadmap.js";
 import { busca } from "./buscar.js";
 import { arquiva, edita, le } from "./curar.js";
 import { criaPasta } from "./pasta.js";
@@ -61,6 +62,16 @@ const AJUDA = `dd-harness — a política e o Brain do projeto, no serviço
                                      1 = não consegui buscar
                                      --hook: fala o protocolo do SessionStart do
                                      Claude Code, para pôr a política no contexto
+  dd-harness roadmap                as fases abertas: a atual inteira, as próximas
+                                     por título (opcional — projeto sem fase não tem)
+  dd-harness changelog [--versao <v>]
+                                     o que já foi concluído, agrupado por versão
+  dd-harness fase criar --titulo "<t>" [--conteudo <arquivo.md>] [--versao <v>]
+                     [--status ideia|aberta|concluida] [--slug <s>]
+  dd-harness fase editar <slug> [--titulo "<t>"] [--conteudo <arquivo.md>]
+                     [--versao <v> | --sem-versao] [--status <s>] [--ordem <n>]
+                                     concluir = --status concluida: a fase sai do
+                                     roadmap e entra no changelog, nada migra
   dd-harness --help
   dd-harness --version              qual binário está instalado nesta máquina
 
@@ -88,6 +99,77 @@ function argumento(argv, nome) {
     return i >= 0 ? argv[i + 1] : undefined;
 }
 const API_PADRAO = "https://dd-harness.vercel.app";
+// --- roadmap e changelog ---
+async function comandoRoadmap() {
+    console.log(formataRoadmap(await leFases(process.cwd())));
+}
+async function comandoChangelog(argv) {
+    const versao = argumento(argv, "versao");
+    const fases = await leFases(process.cwd(), { status: "concluida", ...(versao ? { versao } : {}) });
+    console.log(formataChangelog(fases));
+}
+const STATUS_DE_FASE = ["ideia", "aberta", "concluida", "descartada"];
+function statusDoArgv(argv) {
+    const s = argumento(argv, "status");
+    if (s === undefined)
+        return undefined;
+    if (!STATUS_DE_FASE.includes(s)) {
+        throw new Error(`--status: use ${STATUS_DE_FASE.join(", ")}.`);
+    }
+    return s;
+}
+/** `--conteudo` aponta para um .md, como `gravar` e `editar` — markdown de verdade nao cabe em flag. */
+async function conteudoDoArgv(argv) {
+    const caminho = argumento(argv, "conteudo");
+    return caminho === undefined ? undefined : readFile(caminho, "utf8");
+}
+/**
+ * `fase criar` e `fase editar`. Concluir uma fase e `fase editar <slug> --status concluida`
+ * — nao ha verbo proprio de proposito: e uma edicao de status como qualquer outra, e e o
+ * banco que a transforma em changelog.
+ */
+async function comandoFase(argv) {
+    const [acao, ...resto] = argv;
+    if (acao === "criar") {
+        const titulo = argumento(resto, "titulo");
+        if (!titulo)
+            throw new Error('fase criar exige --titulo "<título>".');
+        const status = statusDoArgv(resto);
+        if (status === "descartada")
+            throw new Error("não se cria uma fase já descartada.");
+        const { fase } = await criaFase(process.cwd(), {
+            titulo,
+            conteudo: await conteudoDoArgv(resto),
+            versao: argumento(resto, "versao"),
+            status,
+            slug: argumento(resto, "slug"),
+        });
+        console.log(`Fase ${fase.slug} criada — ordem ${fase.ordem}, ${fase.status}` +
+            (fase.versao ? `, versão ${fase.versao}` : "") +
+            ".");
+        return;
+    }
+    if (acao === "editar") {
+        const [slug, ...opcoes] = resto;
+        if (!slug || slug.startsWith("--"))
+            throw new Error("fase editar exige o slug da fase.");
+        const ordemBruta = argumento(opcoes, "ordem");
+        const status = statusDoArgv(opcoes);
+        const { fase } = await editaFase(process.cwd(), slug, {
+            titulo: argumento(opcoes, "titulo"),
+            conteudo: await conteudoDoArgv(opcoes),
+            versao: opcoes.includes("--sem-versao") ? null : argumento(opcoes, "versao"),
+            status,
+            ordem: ordemBruta === undefined ? undefined : Number(ordemBruta),
+        });
+        console.log(`Fase ${fase.slug} atualizada — ${fase.status}` +
+            (fase.versao ? `, versão ${fase.versao}` : "") +
+            (status === "concluida" ? " (saiu do roadmap, entrou no changelog)" : "") +
+            ".");
+        return;
+    }
+    throw new Error('uso: dd-harness fase criar --titulo "<t>" [...]  |  dd-harness fase editar <slug> [...]');
+}
 /**
  * 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
@@ -588,6 +670,9 @@ function contextoDaSessao(r, worker) {
             additionalContext: "# Política deste projeto (carregada do dd-harness)\n\n" +
                 "As regras abaixo valem para esta sessão inteira.\n\n" +
                 r.conteudo +
+                // Depois da politica, antes dos avisos operacionais: o roadmap e contexto de
+                // trabalho, a fila e ruido de infraestrutura. Vazio quando nao ha fase aberta.
+                blocoDeSessao(r.roadmap) +
                 fila,
         };
     }
@@ -802,6 +887,12 @@ async function principal() {
             return comandoStatus();
         case "politica":
             return comandoPolitica(resto);
+        case "roadmap":
+            return comandoRoadmap();
+        case "changelog":
+            return comandoChangelog(resto);
+        case "fase":
+            return comandoFase(resto);
         case "--version":
         case "-V":
         case "version":

package/dist/politica.d.ts

@@ -1,3 +1,4 @@
+import type { RoadmapDaSessao } from "./roadmap.js";
 /**
  * A politica do projeto, buscada no servico na hora.
  *
@@ -30,5 +31,11 @@ export type ResultadoDaPolitica = ({
      * faz esta chamada, entao saber o estado da fila custa zero requisicao.
      */
     esperandoIndexacao?: number;
+    /**
+     * O roadmap ja fatiado para a sessao (fase atual inteira, proximas por titulo). Tambem de
+     * carona no mesmo payload — e opcional: `agora` nulo e "projeto sem roadmap", e o hook
+     * nao imprime nada.
+     */
+    roadmap?: RoadmapDaSessao;
 };
 export declare function buscaPolitica(raiz: string): Promise<ResultadoDaPolitica>;

package/dist/politica.js

@@ -24,6 +24,7 @@ export async function buscaPolitica(raiz) {
         const payload = (await resposta.json());
         const conteudo = payload.politica?.trim();
         const esperandoIndexacao = payload.esperando_indexacao ?? 0;
+        const roadmap = payload.roadmap;
         // `briefado` e do SERVICO, nao inferido aqui: exige politica E briefing, os dois
         // obrigatorios. So checar `politica` vazia deixava passar o caso de politica
         // existir sem briefing — a sessao seguia como "ok" com metade do briefing faltando,
@@ -31,7 +32,7 @@ export async function buscaPolitica(raiz) {
         if (!conteudo || payload.briefado === false) {
             return { estado: "sem-politica", esperandoIndexacao };
         }
-        return { estado: "ok", conteudo, esperandoIndexacao };
+        return { estado: "ok", conteudo, esperandoIndexacao, roadmap };
     }
     catch (erro) {
         return { estado: "inalcancavel", motivo: mensagem(erro) };

package/dist/roadmap.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Roadmap e changelog: o mesmo dado, lido de dois jeitos.
+ *
+ * Uma fase e uma linha com `status`. Roadmap e o que esta aberto; changelog e o que foi
+ * concluido, agrupado por versao. Concluir e mudar um status — nada migra, e e isso que
+ * impede o roadmap de virar o cemiterio que o ROADMAP.md file-based virou (395 linhas em
+ * "Agora", seis delas ja feitas, porque mover texto e um ato que ninguem lembra de fazer).
+ *
+ * As funcoes de rede falam com `/api/v1/roadmap`. As de formatacao sao puras, para o hook,
+ * o terminal e o MCP imprimirem a mesma coisa — e para serem testadas sem rede.
+ */
+export type StatusDaFase = "ideia" | "aberta" | "concluida" | "descartada";
+export type Fase = {
+    slug: string;
+    titulo: string;
+    conteudo: string;
+    status: StatusDaFase;
+    versao: string | null;
+    ordem: number;
+    concluida_em: string | null;
+    atualizada_em: string;
+};
+/**
+ * O que o payload de `/api/v1/artefatos` traz ja fatiado para a sessao: a fase atual
+ * inteira, os titulos das proximas, e quantas ja foram concluidas. `agora` nulo significa
+ * "este projeto nao tem roadmap" — e o hook cala.
+ */
+export type RoadmapDaSessao = {
+    agora: {
+        slug: string;
+        titulo: string;
+        versao: string | null;
+        conteudo: string;
+    } | null;
+    a_seguir: {
+        slug: string;
+        titulo: string;
+        versao: string | null;
+    }[];
+    concluidas: number;
+};
+export type NovaFase = {
+    titulo: string;
+    conteudo?: string;
+    versao?: string | null;
+    status?: Exclude<StatusDaFase, "descartada">;
+    slug?: string;
+};
+export type EdicaoDeFase = {
+    titulo?: string;
+    conteudo?: string;
+    versao?: string | null;
+    status?: StatusDaFase;
+    ordem?: number;
+};
+export declare function leFases(raiz: string, filtro?: {
+    status?: StatusDaFase;
+    versao?: string;
+}): Promise<Fase[]>;
+export declare function leFase(raiz: string, slug: string): Promise<Fase>;
+export declare function criaFase(raiz: string, dados: NovaFase): Promise<{
+    fase: Fase;
+    criou: boolean;
+}>;
+export declare function editaFase(raiz: string, slug: string, dados: EdicaoDeFase): Promise<{
+    fase: Fase;
+}>;
+/** Rotulo do grupo de fases concluidas sem versao: o "Unreleased" do Keep a Changelog. */
+export declare const SEM_VERSAO = "Sem vers\u00E3o (ainda n\u00E3o lan\u00E7ado)";
+/**
+ * O bloco que entra no contexto da sessao, colado depois da politica. Vazio quando o
+ * projeto nao tem fase aberta: aviso sem motivo em toda sessao e o que ensina a ignorar
+ * aviso — e roadmap e opcional.
+ *
+ * So a fase atual vai em texto integral. As proximas vao por titulo, e as concluidas nem
+ * isso — so a contagem. E a reducao de tokens que o modelo file-based nao tinha como
+ * fazer: la o arquivo entrava inteiro, feito e por fazer.
+ */
+export declare function blocoDeSessao(r: RoadmapDaSessao | null | undefined): string;
+/**
+ * O roadmap para o terminal e para `ler_roadmap`: recebe TODAS as fases do projeto e
+ * separa por status. Concluidas nao aparecem aqui — sao changelog.
+ */
+export declare function formataRoadmap(fases: Fase[]): string;
+/**
+ * O changelog: fases concluidas agrupadas por versao, na ordem em que a API devolveu (mais
+ * recente primeiro). Grupo sem versao recebe `SEM_VERSAO`. A ordem dos grupos e a da
+ * primeira aparicao — versao e rotulo livre, entao nao ha como ordena-la melhor que pelo
+ * tempo em que suas fases foram concluidas.
+ */
+export declare function formataChangelog(concluidas: Fase[]): string;

package/dist/roadmap.js

@@ -0,0 +1,153 @@
+import { cabecalhos, credencial, pede, recusa } from "./api.js";
+// --- rede ---
+export async function leFases(raiz, filtro = {}) {
+    const { config, token } = await credencial(raiz);
+    const url = new URL(`${config.api}/api/v1/roadmap`);
+    url.searchParams.set("tenant", config.tenant);
+    url.searchParams.set("projeto", config.projeto);
+    if (filtro.status)
+        url.searchParams.set("status", filtro.status);
+    if (filtro.versao)
+        url.searchParams.set("versao", filtro.versao);
+    const resposta = await pede(url, { headers: cabecalhos(token) });
+    if (!resposta.ok)
+        await recusa(resposta);
+    return (await resposta.json()).fases;
+}
+export async function leFase(raiz, slug) {
+    const { config, token } = await credencial(raiz);
+    const url = new URL(`${config.api}/api/v1/roadmap/${encodeURIComponent(slug)}`);
+    url.searchParams.set("tenant", config.tenant);
+    url.searchParams.set("projeto", config.projeto);
+    const resposta = await pede(url, { headers: cabecalhos(token) });
+    if (!resposta.ok)
+        await recusa(resposta);
+    return (await resposta.json()).fase;
+}
+export async function criaFase(raiz, dados) {
+    const { config, token } = await credencial(raiz);
+    const resposta = await pede(`${config.api}/api/v1/roadmap`, {
+        method: "POST",
+        headers: cabecalhos(token, true),
+        body: JSON.stringify({ tenant: config.tenant, projeto: config.projeto, ...dados }),
+    });
+    if (!resposta.ok)
+        await recusa(resposta);
+    return (await resposta.json());
+}
+export async function editaFase(raiz, slug, dados) {
+    const { config, token } = await credencial(raiz);
+    const resposta = await pede(`${config.api}/api/v1/roadmap/${encodeURIComponent(slug)}`, {
+        method: "PATCH",
+        headers: cabecalhos(token, true),
+        body: JSON.stringify({ tenant: config.tenant, projeto: config.projeto, ...dados }),
+    });
+    if (!resposta.ok)
+        await recusa(resposta);
+    return (await resposta.json());
+}
+// --- formatacao (pura) ---
+/** Rotulo do grupo de fases concluidas sem versao: o "Unreleased" do Keep a Changelog. */
+export const SEM_VERSAO = "Sem versão (ainda não lançado)";
+const rotuloDeVersao = (versao) => (versao ? ` (${versao})` : "");
+/**
+ * O bloco que entra no contexto da sessao, colado depois da politica. Vazio quando o
+ * projeto nao tem fase aberta: aviso sem motivo em toda sessao e o que ensina a ignorar
+ * aviso — e roadmap e opcional.
+ *
+ * So a fase atual vai em texto integral. As proximas vao por titulo, e as concluidas nem
+ * isso — so a contagem. E a reducao de tokens que o modelo file-based nao tinha como
+ * fazer: la o arquivo entrava inteiro, feito e por fazer.
+ */
+export function blocoDeSessao(r) {
+    if (!r?.agora)
+        return "";
+    const linhas = [
+        "",
+        "",
+        "---",
+        "",
+        "# Roadmap deste projeto (dd-harness)",
+        "",
+        `## Agora — ${r.agora.titulo}${rotuloDeVersao(r.agora.versao)}`,
+        "",
+        r.agora.conteudo.trim() || "_(fase sem descrição — pergunte ao usuário o que ela cobre.)_",
+    ];
+    if (r.a_seguir.length > 0) {
+        linhas.push("", "## A seguir");
+        for (const f of r.a_seguir)
+            linhas.push(`- ${f.titulo}${rotuloDeVersao(f.versao)}`);
+    }
+    linhas.push("", r.concluidas > 0
+        ? `${r.concluidas} fase(s) já concluída(s) — \`ler_changelog\` mostra o que foi entregue.`
+        : "Nenhuma fase concluída ainda.", "", "É da fase **Agora** que saem os passos desta sessão. Quando ela terminar, proponha ao " +
+        "usuário marcá-la concluída (`editar_fase` com `status: \"concluida\"`) — ela sai do " +
+        "roadmap e entra no changelog sozinha. O roadmap guarda o quê e quando; o porquê das " +
+        "decisões vai ao Brain, pelos três filtros, e fase concluída não gera memória por padrão.");
+    return linhas.join("\n");
+}
+/**
+ * O roadmap para o terminal e para `ler_roadmap`: recebe TODAS as fases do projeto e
+ * separa por status. Concluidas nao aparecem aqui — sao changelog.
+ */
+export function formataRoadmap(fases) {
+    const porOrdem = (a, b) => a.ordem - b.ordem;
+    const abertas = fases.filter((f) => f.status === "aberta").sort(porOrdem);
+    const ideias = fases.filter((f) => f.status === "ideia").sort(porOrdem);
+    const concluidas = fases.filter((f) => f.status === "concluida").length;
+    if (abertas.length === 0 && ideias.length === 0) {
+        return ("Este projeto não tem roadmap." +
+            (concluidas > 0 ? ` (${concluidas} fase(s) concluída(s) no changelog.)` : "") +
+            "\nCrie a primeira fase: `dd-harness fase criar --titulo \"...\"`.");
+    }
+    const linhas = [];
+    const [agora, ...aSeguir] = abertas;
+    if (agora) {
+        linhas.push(`## Agora — ${agora.titulo}${rotuloDeVersao(agora.versao)}  [${agora.slug}]`, "");
+        linhas.push(agora.conteudo.trim() || "_(sem descrição)_");
+    }
+    if (aSeguir.length > 0) {
+        linhas.push("", "## A seguir");
+        for (const f of aSeguir)
+            linhas.push(`- ${f.titulo}${rotuloDeVersao(f.versao)}  [${f.slug}]`);
+    }
+    if (ideias.length > 0) {
+        linhas.push("", "## Ideias (não comprometidas)");
+        for (const f of ideias)
+            linhas.push(`- ${f.titulo}${rotuloDeVersao(f.versao)}  [${f.slug}]`);
+    }
+    // Neutro de proposito: este texto sai igual no terminal e na ferramenta MCP, e cada
+    // porta tem o seu jeito de abrir o changelog.
+    linhas.push("", concluidas > 0
+        ? `${concluidas} fase(s) concluída(s) — estão no changelog.`
+        : "Nenhuma fase concluída ainda.");
+    return linhas.join("\n");
+}
+/**
+ * O changelog: fases concluidas agrupadas por versao, na ordem em que a API devolveu (mais
+ * recente primeiro). Grupo sem versao recebe `SEM_VERSAO`. A ordem dos grupos e a da
+ * primeira aparicao — versao e rotulo livre, entao nao ha como ordena-la melhor que pelo
+ * tempo em que suas fases foram concluidas.
+ */
+export function formataChangelog(concluidas) {
+    if (concluidas.length === 0)
+        return "Nenhuma fase concluída ainda.";
+    const grupos = new Map();
+    for (const f of concluidas) {
+        const chave = f.versao ?? SEM_VERSAO;
+        const grupo = grupos.get(chave) ?? [];
+        grupo.push(f);
+        grupos.set(chave, grupo);
+    }
+    const linhas = [];
+    for (const [versao, fases] of grupos) {
+        if (linhas.length > 0)
+            linhas.push("");
+        linhas.push(`## ${versao}`);
+        for (const f of fases) {
+            const data = f.concluida_em ? f.concluida_em.slice(0, 10) : "";
+            linhas.push(`- ${f.titulo}${data ? ` — ${data}` : ""}  [${f.slug}]`);
+        }
+    }
+    return linhas.join("\n");
+}

package/package.json

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