@h1veframework/cli 0.5.1 → 0.6.0

package/README.md

@@ -1,93 +1,79 @@
-# @h1veframework/cli
+# @h1veframework/cli · `nf`
 
-CLI `nf` do **H1VE Flow** — opera o fluxo da feature da sua branch direto do terminal
-(status, start, move, spec, done, blocker, health, connect), autenticado por um token pessoal.
+**The command-line companion for [H1VE](https://h1ve.org) — the governance & memory layer for teams building with AI.**
 
-Parte do tooling do H1VE junto com o **[servidor MCP](https://www.npmjs.com/package/@h1veframework/mcp)**
-(para o Claude Code).
+Your team ships with AI (Claude Code, Cursor, Copilot). As the codebase grows, the AI and your teammates start
+**losing context and drifting from decisions you already made**. H1VE keeps every feature aligned — a shared,
+**eternal project memory** plus an **anti-drift engine** that checks each change against what's been decided.
+`nf` drives that workflow straight from your terminal.
 
-## Pré-requisitos
+Part of the H1VE toolchain, alongside the **[MCP server](https://www.npmjs.com/package/@h1veframework/mcp)** for
+Claude Code / Cursor.
 
-- **Node.js 18.18+** (`node --version`).
-- Uma conta no H1VE Flow. **Não precisa criar/colar token** — o `nf login` cuida disso.
+→ **[h1ve.org](https://h1ve.org)** · **[app.h1ve.org](https://app.h1ve.org)**
 
-## Instalação
+## Quickstart (zero paste)
 
 ```bash
 npm i -g @h1veframework/cli
-nf --version
+nf login     # opens your browser → you click Authorize → done
+nf status    # state of the current branch's feature
 ```
 
-## Login (recomendado — sem colar nada)
+`nf login` stores the credential locally (`~/.config/h1ve/credentials.json`, `600`) — the MCP server reads the
+same one, so **one login sets up both**. The project **auto-resolves from your git remote**, so there's nothing
+to paste and no `H1VE_PROJECT_ID` to set. `nf logout` removes it.
 
-```bash
-nf login       # abre o navegador → você autoriza → pronto
-nf health      # já funciona
-```
+> `nf health` saying "no snapshots yet" is **success** (you're connected; the project just has no metrics yet).
 
-O `nf login` abre o navegador (onde você já está logado no H1VE), você clica **Autorizar**, e o CLI **guarda
-a credencial sozinho** em `~/.config/h1ve/credentials.json` (permissão 600). O **[MCP](https://www.npmjs.com/package/@h1veframework/mcp)**
-lê a mesma credencial — um `nf login` configura os dois. `nf logout` remove. **100% automático** (SPEC-078):
-o projeto também é resolvido sozinho pelo repo (SPEC-077), então nada de `H1VE_PROJECT_ID`.
+## Commands
 
-> "Nenhum snapshot registrado" no `nf health` é **sucesso** (conectou; projeto sem métricas ainda).
+| Command | What it does |
+|---|---|
+| `nf login` / `nf logout` | Authorize in the browser and store the credential locally / remove it |
+| `nf status` | State of the current branch's feature (stage, days active, blockers, sign-offs) |
+| `nf start [<#\|id>] [--slug <s>]` | Start an assigned feature: create the `feat/{you}/{slug}` branch and record the slug |
+| `nf spec` | Print the feature's spec (markdown) |
+| `nf move <stage> [--note]` | Move the feature to another stage |
+| `nf done [--from <file>] [--no-move]` | Submit the AI declaration (JSON) and move `dev → pr` |
+| `nf blocker "<desc>"` | Open a blocker on the feature (you become its owner) |
+| `nf health` | Latest technical-health snapshots for the project |
+| `nf connect --kind <k> --label <l> --env KEY=VAL` | Write a credential to your **local** `.env.local` and register the inventory (never sent to the server) |
+| `nf serve [--port 7391]` | Run the local agent (`127.0.0.1`) so the dashboard can apply credentials from the browser |
 
-## Alternativa: variáveis de ambiente (CI / headless)
+Flags: `--json` (raw output for scripts) · `--project <name\|id>` (if you belong to more than one project) · `-h`.
 
-Sem navegador (ex.: CI), configure por env — tem **precedência** sobre o `nf login`:
+## Example
 
 ```bash
-export H1VE_API_URL="https://app.h1ve.org"   # opcional (default já é este)
-export H1VE_API_KEY="nf_pat_..."             # PAT criado em app.h1ve.org/api-tokens
-# export H1VE_PROJECT_ID="..."               # OPCIONAL — o CLI resolve o projeto pelo repo; use só p/ forçar
+nf start                                    # start your assigned feature (creates the branch)
+# ... work: git, code, commits ...
+nf status                                   # check state anytime
+nf blocker "waiting on the Neon credential" # blocked? open a blocker
+nf done --from ai-declaration.json          # submit the AI declaration + move dev → pr
 ```
 
-> **`H1VE_PROJECT_ID`** (SPEC-076/077): **opcional**. Rodando dentro de um repo conectado a um projeto, o
-> CLI **resolve o projeto sozinho** pelo `git remote` — zero config, mesmo com 2+ projetos. Use só pra
-> **forçar** um projeto (override).
+## CI / headless (env vars)
 
-## Comandos
-
-| Comando | O que faz |
-|---|---|
-| `nf login` | Autoriza no navegador e salva a credencial local (sem colar nada) |
-| `nf logout` | Remove a credencial local |
-| `nf health` | Últimos snapshots de saúde técnica do projeto |
-| `nf status` | Estado da feature da branch atual (stage, dias ativo, blockers, sign-offs) |
-| `nf start [<nº\|id>] [--slug <s>]` | Inicia uma feature atribuída: cria a branch `feat/{você}/{slug}` e grava o slug |
-| `nf spec` | Imprime a spec (markdown) da feature da branch |
-| `nf move <stage> [--note]` | Move a feature para outro stage |
-| `nf done [--from <arq>] [--no-move]` | Envia a AI declaration (JSON) e move `dev → pr` |
-| `nf blocker "<desc>"` | Abre um blocker na feature (você vira o dono) |
-| `nf connect --kind <k> --label <l> --env KEY=VAL` | Aplica uma credencial no `.env.local` **local** (nunca ao servidor) e registra o inventário (Jeito B) |
-| `nf serve [--port 7391]` | Sobe o agente local (`127.0.0.1`) p/ o menu visual do painel aplicar credenciais pelo navegador |
-
-Flags: `--json` (saída crua p/ scripts) · `--project <nome\|id>` (se você é membro de +1 projeto) · `-h` (ajuda completa).
-
-## Exemplo de uso
+No browser? Configure by env (takes **precedence** over `nf login`):
 
 ```bash
-nf start                                  # inicia a feature atribuída (cria a branch)
-# ... trabalha (git, código, commits) ...
-nf status                                 # estado a qualquer momento
-nf blocker "aguardando credencial do Neon" # trava? abre blocker
-nf done --from ai-declaration.json        # envia a AI declaration + move dev → pr
+export H1VE_API_URL="https://app.h1ve.org"   # optional (this is the default)
+export H1VE_API_KEY="nf_pat_..."             # a PAT from app.h1ve.org/api-tokens
+# export H1VE_PROJECT_ID="..."               # OPTIONAL — the CLI resolves the project from the repo
 ```
 
 ## Troubleshooting
 
-| Sintoma | Solução |
+| Symptom | Fix |
 |---|---|
-| `nf: command not found` | Node ausente ou terminal errado. Confira `node --version`. No Windows, o PowerShell pode não ter o bin do npm no PATH — use o terminal do VS Code ou reabra o shell. |
-| `404` ao instalar | Propagação do npm logo após publicação. Espere alguns minutos. |
-| `NO_PROJECT` | Você é membro de +1 projeto — passe `--project <nome\|id>`. |
-| `401` / `403` | Token errado/ausente/sem permissão. Confira que `H1VE_API_KEY` é um PAT (`nf_pat_…`). `403 SERVICE_CANNOT_WRITE` = chave de serviço (só leitura) numa escrita → use um PAT. |
-
-## Compatibilidade de nomes
+| `nf: command not found` | Node missing or wrong terminal. Check `node --version`. On Windows, reopen the shell or use the VS Code terminal. |
+| `404` on install | npm propagation right after a publish — wait a few minutes. |
+| `NO_PROJECT` | You belong to more than one project — pass `--project <name\|id>`. |
+| `401` / `403` | Wrong/missing token. Make sure `H1VE_API_KEY` is a PAT (`nf_pat_…`). `403 SERVICE_CANNOT_WRITE` = a read-only service key used on a write → use a PAT. |
 
-Use **`H1VE_API_URL`** e **`H1VE_API_KEY`**. Os nomes legados `NEXUS_FLOW_API_URL` / `NEXUS_FLOW_API_KEY`
-**ainda são aceitos** por compatibilidade — se você já configurou com eles, não precisa mudar nada.
+Requires **Node.js 18.18+**. Legacy env names `NEXUS_FLOW_API_URL` / `NEXUS_FLOW_API_KEY` are still accepted.
 
 ---
 
-MIT · [H1VE Flow](https://app.h1ve.org)
+MIT · built with H1VE, by [H1VE](https://h1ve.org) 🐝

package/dist/index.js

@@ -50,6 +50,24 @@ async function createBranch(name, runner = defaultGitRunner) {
     throw new Error("GIT_BRANCH_FAILED");
   }
 }
+async function switchBranch(name, runner = defaultGitRunner) {
+  try {
+    await runner(["switch", name]);
+  } catch (err) {
+    const text = gitErrText(err);
+    if (/not a git repository/i.test(text)) throw new Error("NOT_A_GIT_REPO");
+    throw new Error("GIT_SWITCH_FAILED");
+  }
+}
+async function listLocalBranches(runner = defaultGitRunner) {
+  let out;
+  try {
+    out = await runner(["for-each-ref", "--format=%(refname:short)", "refs/heads"]);
+  } catch {
+    return [];
+  }
+  return out.split("\n").map((l) => l.trim()).filter(Boolean);
+}
 
 // ../core/src/client.ts
 var NexusApiError = class extends Error {
@@ -128,16 +146,17 @@ function createClient(config) {
     // do id e ignora o header onde não escopa — então mandar sempre é simples e seguro.
     ...config.projectId ? { "x-project-id": config.projectId } : {}
   };
-  async function postAction(featureId, action, body) {
+  async function writeAction(method, featureId, action, body) {
     const url = `${rootUrl(config.baseUrl)}/api/features/${encodeURIComponent(featureId)}/${action}`;
     const res = await doFetch(url, {
-      method: "POST",
+      method,
       headers: { ...authHeaders, "content-type": "application/json" },
       body: JSON.stringify(body)
     });
     if (!res.ok) throw mapWriteError(res.status, await readErrorCode(res));
     return await res.json();
   }
+  const postAction = (featureId, action, body) => writeAction("POST", featureId, action, body);
   return {
     async getContext(branch) {
       const url = `${rootUrl(config.baseUrl)}/api/context?branch=${encodeURIComponent(branch)}`;
@@ -157,9 +176,38 @@ function createClient(config) {
       if (!res.ok) throw errorForStatus(res.status, await readErrorCode(res));
       return await res.json();
     },
+    async recallMemory(query) {
+      const params = new URLSearchParams();
+      if (query.entities?.length) params.set("entities", query.entities.join(","));
+      if (query.text) params.set("q", query.text);
+      if (query.limit) params.set("limit", String(query.limit));
+      const url = `${rootUrl(config.baseUrl)}/api/memory/recall?${params.toString()}`;
+      const res = await doFetch(url, { headers: authHeaders });
+      if (!res.ok) throw errorForStatus(res.status, await readErrorCode(res));
+      return await res.json();
+    },
     startFeature(featureId, slug) {
       return postAction(featureId, "start", slug ? { slug } : {});
     },
+    setSpec(featureId, specContent) {
+      return writeAction("PATCH", featureId, "spec", { spec_content: specContent });
+    },
+    // SPEC-100 (B2): best-effort — o juiz de drift é ADVISORY; qualquer falha → {checked:false}
+    // (nunca lança, pra não estragar o fluxo de gravar a SPEC no `set_spec` do MCP).
+    async checkSpecAlignment(featureId) {
+      try {
+        const url = `${rootUrl(config.baseUrl)}/api/features/${encodeURIComponent(featureId)}/spec/alignment`;
+        const res = await doFetch(url, {
+          method: "POST",
+          headers: { ...authHeaders, "content-type": "application/json" },
+          body: "{}"
+        });
+        if (!res.ok) return { checked: false };
+        return await res.json();
+      } catch {
+        return { checked: false };
+      }
+    },
     moveStage(featureId, toStage, note) {
       return postAction(featureId, "move", { to_stage: toStage, note });
     },
@@ -442,16 +490,17 @@ function formatBlocker(r) {
   return `\u2713 Blocker aberto: ${r.description}`;
 }
 function formatStartList(list) {
-  const header = "Features atribu\xEDdas a iniciar \u2014 escolha: nf start <n\xBA>";
-  const rows = list.map(
-    (f, i) => `  ${String(i + 1).padStart(2)}. ${f.name}  [${stageLabel(f.stage)}]`
-  );
+  const header = "Features para iniciar ou retomar \u2014 escolha: nf start <n\xBA>";
+  const rows = list.map((f, i) => {
+    const tag = f.branch_slug !== null ? "  (retomar)" : "";
+    return `  ${String(i + 1).padStart(2)}. ${f.name}  [${stageLabel(f.stage)}]${tag}`;
+  });
   return [header, ...rows].join("\n");
 }
-function formatStart(r) {
+function formatStart(r, opts) {
   return [
-    `\u2713 Iniciada: ${r.feature.name}`,
-    `Branch:  ${r.branch_name}  (criada e ativa)`,
+    `\u2713 ${opts?.resumed ? "Retomada" : "Iniciada"}: ${r.feature.name}`,
+    `Branch:  ${r.branch_name}  (${opts?.resumed ? "pronta e ativa" : "criada e ativa"})`,
     "Pr\xF3ximo: codar \u2192 'nf status' \u2192 'nf done' (move dev \u2192 pr)"
   ].join("\n");
 }
@@ -573,8 +622,15 @@ async function health(io) {
 }
 
 // src/commands/start.ts
-function startable(features) {
-  return features.filter((f) => f.branch_slug === null && f.stage !== "main");
+function branchSlugOf(branch) {
+  return branch.match(/^feat\/[^/]+\/(.+)$/)?.[1] ?? null;
+}
+function startable(features, localBranches) {
+  const localSlugs = new Set(
+    localBranches.map(branchSlugOf).filter((s) => s !== null)
+  );
+  const hasLocalBranch = (f) => f.branch_slug !== null && localSlugs.has(f.branch_slug);
+  return features.filter((f) => f.stage !== "main" && !hasLocalBranch(f));
 }
 function pick(list, arg) {
   if (!arg) return list.length === 1 ? list[0] ?? null : null;
@@ -585,27 +641,25 @@ function pick(list, arg) {
   throw new CliError(`Feature n\xE3o encontrada: ${arg}. Rode 'nf start' para ver a lista.`);
 }
 async function start(io, args) {
-  const list = startable(await io.client.listFeatures());
+  const [features, localBranches] = await Promise.all([io.client.listFeatures(), io.listBranches()]);
+  const list = startable(features, localBranches);
   if (list.length === 0) {
-    throw new CliError("Nenhuma feature atribu\xEDda a iniciar (sem branch e fora de main).");
+    throw new CliError("Nenhuma feature para iniciar ou retomar (sem branch local e fora de main).");
   }
   const selected = pick(list, args.positional);
   if (!selected) {
     return { human: formatStartList(list), data: { features: list } };
   }
+  const resuming = selected.branch_slug !== null;
   const result = await io.client.startFeature(selected.id, args.slug);
   try {
     await io.createBranch(result.branch_name);
   } catch (err) {
     const code = err instanceof Error ? err.message : "";
-    if (code === "BRANCH_EXISTS") {
-      throw new CliError(
-        `branch_slug gravado, mas a branch '${result.branch_name}' j\xE1 existe. Rode: git switch ${result.branch_name}`
-      );
-    }
-    throw err;
+    if (code === "BRANCH_EXISTS") await io.switchBranch(result.branch_name);
+    else throw err;
   }
-  return { human: formatStart(result), data: result };
+  return { human: formatStart(result, { resumed: resuming }), data: result };
 }
 
 // src/commands/connect.ts
@@ -1232,14 +1286,14 @@ async function logout(io, _args) {
 }
 
 // src/index.ts
-var VERSION = "0.5.0";
+var VERSION = "0.6.0";
 var HELP = `nf \u2014 CLI do Nexus Flow
 
 Uso:
   nf login                  autoriza no navegador e salva a credencial local (sem colar nada)
   nf logout                 remove a credencial local
   nf start [<n\xBA|id>] [--slug <s>]
-                            inicia uma feature atribu\xEDda: cria a branch e grava o slug
+                            inicia (ou retoma) uma feature: cria/entra na branch e grava o slug
   nf status                 estado da feature da branch atual
   nf spec                   imprime a spec da feature
   nf move <stage> [--note]  move a feature de stage
@@ -1333,6 +1387,8 @@ ${HELP}`);
     client,
     resolveBranch: () => currentBranch(defaultGitRunner),
     createBranch: (name) => createBranch(name, defaultGitRunner),
+    switchBranch: (name) => switchBranch(name, defaultGitRunner),
+    listBranches: () => listLocalBranches(defaultGitRunner),
     readFile: (path) => readFile(path, "utf8"),
     readStdin,
     writeEnvVars: (pairs, opts) => writeEnvVars(pairs, { file: opts?.file }),

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@h1veframework/cli",
-  "version": "0.5.1",
-  "description": "CLI `nf` do H1VE Flow: opera o fluxo da feature (status/move/blocker/spec/done/health/start) da própria branch, via PAT.",
+  "version": "0.6.0",
+  "description": "The CLI for H1VE — the governance & memory layer for teams building with AI. Drive your feature flow (start, status, move, spec, done) from the terminal. Works with Claude Code, Cursor and Copilot.",
   "license": "MIT",
   "type": "module",
   "bin": {
@@ -19,17 +19,27 @@
     "url": "git+https://github.com/GusHartz/nexus-flow.git",
     "directory": "packages/cli"
   },
-  "homepage": "https://github.com/GusHartz/nexus-flow/tree/main/packages/cli#readme",
+  "homepage": "https://h1ve.org",
   "bugs": {
     "url": "https://github.com/GusHartz/nexus-flow/issues"
   },
   "keywords": [
     "h1ve",
-    "h1ve-flow",
     "cli",
     "nf",
+    "ai",
+    "claude-code",
+    "cursor",
+    "copilot",
+    "ai-coding",
+    "ai-agents",
+    "memory",
+    "anti-drift",
+    "context",
+    "governance",
+    "developer-tools",
     "dev-workflow",
-    "governance"
+    "mcp"
   ],
   "publishConfig": {
     "access": "public"