@h1veframework/cli 0.5.2 → 0.7.0

package/README.md

@@ -1,11 +1,11 @@
-# @h1veframework/cli · `nf`
+# @h1veframework/cli · `h1ve`
 
 **The command-line companion for [H1VE](https://h1ve.org) — the governance & memory layer for teams building with AI.**
 
 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.
+`h1ve` drives that workflow straight from your terminal.
 
 Part of the H1VE toolchain, alongside the **[MCP server](https://www.npmjs.com/package/@h1veframework/mcp)** for
 Claude Code / Cursor.
@@ -16,46 +16,48 @@ Claude Code / Cursor.
 
 ```bash
 npm i -g @h1veframework/cli
-nf login     # opens your browser → you click Authorize → done
-nf status    # state of the current branch's feature
+h1ve login     # opens your browser → you click Authorize → done
+h1ve status    # state of the current branch's feature
 ```
 
-`nf login` stores the credential locally (`~/.config/h1ve/credentials.json`, `600`) — the MCP server reads the
+`h1ve 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.
+to paste and no `H1VE_PROJECT_ID` to set. `h1ve logout` removes it.
 
-> `nf health` saying "no snapshots yet" is **success** (you're connected; the project just has no metrics yet).
+> The legacy `nf` command still works as an alias — every `h1ve <cmd>` below can be run as `nf <cmd>`.
+
+> `h1ve health` saying "no snapshots yet" is **success** (you're connected; the project just has no metrics yet).
 
 ## Commands
 
 | 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 |
+| `h1ve login` / `h1ve logout` | Authorize in the browser and store the credential locally / remove it |
+| `h1ve status` | State of the current branch's feature (stage, days active, blockers, sign-offs) |
+| `h1ve start [<#\|id>] [--slug <s>]` | Start an assigned feature: create the `feat/{you}/{slug}` branch and record the slug |
+| `h1ve spec` | Print the feature's spec (markdown) |
+| `h1ve move <stage> [--note]` | Move the feature to another stage |
+| `h1ve done [--from <file>] [--no-move]` | Submit the AI declaration (JSON) and move `dev → pr` |
+| `h1ve blocker "<desc>"` | Open a blocker on the feature (you become its owner) |
+| `h1ve health` | Latest technical-health snapshots for the project |
+| `h1ve 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) |
+| `h1ve serve [--port 7391]` | Run the local agent (`127.0.0.1`) so the dashboard can apply credentials from the browser |
 
 Flags: `--json` (raw output for scripts) · `--project <name\|id>` (if you belong to more than one project) · `-h`.
 
 ## Example
 
 ```bash
-nf start                                    # start your assigned feature (creates the branch)
+h1ve 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 status                                   # check state anytime
+h1ve blocker "waiting on the Neon credential" # blocked? open a blocker
+h1ve done --from ai-declaration.json          # submit the AI declaration + move dev → pr
 ```
 
 ## CI / headless (env vars)
 
-No browser? Configure by env (takes **precedence** over `nf login`):
+No browser? Configure by env (takes **precedence** over `h1ve login`):
 
 ```bash
 export H1VE_API_URL="https://app.h1ve.org"   # optional (this is the default)
@@ -67,12 +69,12 @@ export H1VE_API_KEY="nf_pat_..."             # a PAT from app.h1ve.org/api-token
 
 | Symptom | Fix |
 |---|---|
-| `nf: command not found` | Node missing or wrong terminal. Check `node --version`. On Windows, reopen the shell or use the VS Code terminal. |
+| `h1ve: 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. |
 
-Requires **Node.js 18.18+**. Legacy env names `NEXUS_FLOW_API_URL` / `NEXUS_FLOW_API_KEY` are still accepted.
+Requires **Node.js 18.18+**. The legacy `nf` command and env names `NEXUS_FLOW_API_URL` / `NEXUS_FLOW_API_KEY` are still accepted.
 
 ---
 

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 {
@@ -77,7 +95,7 @@ function errorForStatus(status2, code) {
     case 422:
       return new NexusApiError("INVALID_INPUT", "Branch inv\xE1lida.");
     default:
-      return new NexusApiError("API_ERROR", `Falha ao consultar o Nexus Flow (HTTP ${status2}).`);
+      return new NexusApiError("API_ERROR", `Falha ao consultar o H1VE (HTTP ${status2}).`);
   }
 }
 function mapWriteError(status2, code) {
@@ -106,7 +124,7 @@ function mapWriteError(status2, code) {
     case 422:
       return new NexusApiError(code ?? "INVALID_INPUT", "Entrada inv\xE1lida para esta a\xE7\xE3o.");
     default:
-      return new NexusApiError("API_ERROR", `Falha ao escrever no Nexus Flow (HTTP ${status2}).`);
+      return new NexusApiError("API_ERROR", `Falha ao escrever no H1VE (HTTP ${status2}).`);
   }
 }
 async function readErrorCode(res) {
@@ -416,7 +434,7 @@ async function resolveConfig(env = process.env, store = defaultCredentialStore)
   }
   if (!apiKey) {
     throw new CliError(
-      "Voc\xEA n\xE3o est\xE1 logado. Rode `nf login` (abre o navegador) \u2014 ou defina H1VE_API_KEY.\n  (o nome legado NEXUS_FLOW_API_KEY tamb\xE9m \xE9 aceito)",
+      "Voc\xEA n\xE3o est\xE1 logado. Rode `h1ve login` (abre o navegador) \u2014 ou defina H1VE_API_KEY.\n  (o nome legado NEXUS_FLOW_API_KEY tamb\xE9m \xE9 aceito)",
       2
     );
   }
@@ -472,17 +490,45 @@ 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: h1ve 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) {
+var PRE_DEV_STAGES = /* @__PURE__ */ new Set(["backlog", "spec", "blocked"]);
+function startFlowLines(r) {
+  const stage = r.landed_stage ?? r.feature.stage;
+  if (!PRE_DEV_STAGES.has(stage)) {
+    return [
+      `Fluxo:   card em ${stageLabel(stage)} \u2014 pronto para codar.`,
+      "Pr\xF3ximo: codar \u2192 'h1ve status' \u2192 'h1ve done' (move dev \u2192 pr)"
+    ];
+  }
+  const blocked = r.advance?.blocked_by;
+  if (blocked === "SPEC_REQUIRED" || blocked === "SPEC_MALFORMED") {
+    return [
+      "Fluxo:   card em Spec (aguarda a SPEC \u2014 Modo Estrito).",
+      "Pr\xF3ximo: escreva a SPEC no card \u2192 'h1ve start' de novo para avan\xE7ar at\xE9 Dev."
+    ];
+  }
+  if (blocked === "INVALID_TRANSITION") {
+    return [
+      `Fluxo:   card em ${stageLabel(stage)}.`,
+      "Pr\xF3ximo: pe\xE7a ao arquiteto para mover o card at\xE9 Dev (voc\xEA n\xE3o tem permiss\xE3o)."
+    ];
+  }
+  return [
+    `Fluxo:   card em ${stageLabel(stage)}.`,
+    "Pr\xF3ximo: mova o card at\xE9 Dev no board para come\xE7ar."
+  ];
+}
+function formatStart(r, opts) {
   return [
-    `\u2713 Iniciada: ${r.feature.name}`,
-    `Branch:  ${r.branch_name}  (criada e ativa)`,
-    "Pr\xF3ximo: codar \u2192 'nf status' \u2192 'nf done' (move dev \u2192 pr)"
+    `\u2713 ${opts?.resumed ? "Retomada" : "Iniciada"}: ${r.feature.name}`,
+    `Branch:  ${r.branch_name}  (${opts?.resumed ? "pronta e ativa" : "criada e ativa"})`,
+    ...startFlowLines(r)
   ].join("\n");
 }
 function formatHealth(snaps) {
@@ -538,7 +584,7 @@ function isStage(s) {
 }
 async function move(io, args) {
   const stage = args.positional;
-  if (!stage) throw new CliError("Uso: nf move <stage>");
+  if (!stage) throw new CliError("Uso: h1ve move <stage>");
   if (!isStage(stage)) {
     throw new CliError(`Stage inv\xE1lido: ${stage}. V\xE1lidos: ${STAGES.join(", ")}`);
   }
@@ -551,7 +597,7 @@ async function move(io, args) {
 // src/commands/blocker.ts
 async function blocker(io, args) {
   const description = args.positional;
-  if (!description) throw new CliError('Uso: nf blocker "<descri\xE7\xE3o>"');
+  if (!description) throw new CliError('Uso: h1ve blocker "<descri\xE7\xE3o>"');
   const branch = await io.resolveBranch();
   const digest = await io.client.getContext(branch);
   const result = await io.client.createBlocker(digest.feature.id, description);
@@ -591,7 +637,7 @@ ${movedLine}`, data: { declaration, move: moved } };
     throw new CliError(
       `${sent}
 \u2717 Move dev \u2192 pr falhou: ${reason}
-(a declaration J\xC1 foi enviada \u2014 rode \`nf move pr\` para concluir; N\xC3O repita \`nf done\`, pois enviaria a declaration de novo.)`
+(a declaration J\xC1 foi enviada \u2014 rode \`h1ve move pr\` para concluir; N\xC3O repita \`h1ve done\`, pois enviaria a declaration de novo.)`
     );
   }
 }
@@ -603,8 +649,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;
@@ -612,30 +665,28 @@ function pick(list, arg) {
   if (byId) return byId;
   const idx = Number(arg);
   if (Number.isInteger(idx) && idx >= 1 && idx <= list.length) return list[idx - 1] ?? null;
-  throw new CliError(`Feature n\xE3o encontrada: ${arg}. Rode 'nf start' para ver a lista.`);
+  throw new CliError(`Feature n\xE3o encontrada: ${arg}. Rode 'h1ve 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
@@ -1212,7 +1263,7 @@ async function startCallbackServer(expectedState) {
   const waitForCode = () => new Promise((resolve, reject) => {
     const timer = setTimeout(() => {
       server.close();
-      reject(new CliError("Tempo esgotado esperando a autoriza\xE7\xE3o. Rode `nf login` de novo."));
+      reject(new CliError("Tempo esgotado esperando a autoriza\xE7\xE3o. Rode `h1ve login` de novo."));
     }, LOGIN_TIMEOUT_MS);
     void codePromise.then((code) => {
       clearTimeout(timer);
@@ -1262,31 +1313,32 @@ async function logout(io, _args) {
 }
 
 // src/index.ts
-var VERSION = "0.5.0";
-var HELP = `nf \u2014 CLI do Nexus Flow
+var VERSION = "0.7.0";
+var HELP = `h1ve \u2014 CLI do H1VE
+(o comando legado \`nf\` continua funcionando como alias)
 
 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
-  nf status                 estado da feature da branch atual
-  nf spec                   imprime a spec da feature
-  nf move <stage> [--note]  move a feature de stage
-  nf blocker "<desc>"       abre um blocker na feature
-  nf done [--from <arq>] [--no-move]
+  h1ve login                autoriza no navegador e salva a credencial local (sem colar nada)
+  h1ve logout               remove a credencial local
+  h1ve start [<n\xBA|id>] [--slug <s>]
+                            inicia (ou retoma) uma feature: cria/entra na branch e grava o slug
+  h1ve status               estado da feature da branch atual
+  h1ve spec                 imprime a spec da feature
+  h1ve move <stage> [--note]  move a feature de stage
+  h1ve blocker "<desc>"     abre um blocker na feature
+  h1ve done [--from <arq>] [--no-move]
                             envia a AI declaration (JSON) e move dev \u2192 pr
-  nf health                 \xFAltimos snapshots de sa\xFAde t\xE9cnica
-  nf connect --kind <k> --label <l> --env KEY=VAL [...]
+  h1ve health               \xFAltimos snapshots de sa\xFAde t\xE9cnica
+  h1ve connect --kind <k> --label <l> --env KEY=VAL [...]
                             aplica a credencial no .env.local LOCAL (nunca ao servidor)
                             e registra o invent\xE1rio da conex\xE3o (Jeito B)
-  nf serve [--port 7391] [--origin http://localhost:3000]
+  h1ve serve [--port 7391] [--origin http://localhost:3000]
                             sobe o agente local (127.0.0.1) p/ o menu visual aplicar
                             credenciais pelo navegador \u2014 imprime o c\xF3digo de pareamento
 
 Flags:
   --json            sa\xEDda em JSON cru (comp\xF5e em scripts)
-  --slug <s>        slug custom para 'nf start' (default = derivado do nome)
+  --slug <s>        slug custom para 'h1ve start' (default = derivado do nome)
   --kind <k>        tipo da conex\xE3o (database|deploy|observability|api|auth|other)
   --label <l>       nome da conex\xE3o (ex.: "Neon (prod)")
   --env KEY=VAL     vari\xE1vel a escrever no .env.local (repet\xEDvel)
@@ -1295,7 +1347,7 @@ Flags:
   -h, --help        esta ajuda
   -v, --version     vers\xE3o do CLI
 
-Ambiente (opcional \u2014 'nf login' dispensa):
+Ambiente (opcional \u2014 'h1ve login' dispensa):
   H1VE_API_URL   URL do H1VE Flow (default https://app.h1ve.org)
   H1VE_API_KEY   PAT (nf_pat_\u2026) p/ escrever, ou a chave de servi\xE7o (s\xF3 leitura)
   (nomes legados aceitos: NEXUS_FLOW_API_URL / NEXUS_FLOW_API_KEY)
@@ -1321,7 +1373,7 @@ function parse(argv) {
         json: { type: "boolean" },
         help: { type: "boolean", short: "h" },
         version: { type: "boolean", short: "v" },
-        // nf connect (SPEC-050)
+        // h1ve connect (SPEC-050)
         kind: { type: "string" },
         label: { type: "string" },
         url: { type: "string" },
@@ -1329,13 +1381,13 @@ function parse(argv) {
         project: { type: "string" },
         file: { type: "string" },
         env: { type: "string", multiple: true },
-        // nf serve (SPEC-051)
+        // h1ve serve (SPEC-051)
         port: { type: "string" },
         origin: { type: "string" }
       }
     });
   } catch {
-    throw new CliError("Argumentos inv\xE1lidos. Veja `nf --help`.", 2);
+    throw new CliError("Argumentos inv\xE1lidos. Veja `h1ve --help`.", 2);
   }
 }
 async function main(argv) {
@@ -1363,6 +1415,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 }),
@@ -1397,7 +1451,7 @@ function messageFor(err) {
   if (err instanceof Error && (err.message === "NOT_A_GIT_REPO" || err.message === "GIT_BRANCH_FAILED")) {
     return "N\xE3o consegui criar a branch git. Rode dentro do reposit\xF3rio (git) da feature.";
   }
-  return "Erro inesperado ao falar com o Nexus Flow.";
+  return "Erro inesperado ao falar com o H1VE.";
 }
 main(process.argv.slice(2)).then((code) => {
   process.exitCode = code;

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "@h1veframework/cli",
-  "version": "0.5.2",
+  "version": "0.7.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": {
+    "h1ve": "dist/index.js",
     "nf": "dist/index.js"
   },
   "files": [