@h1veframework/cli 0.6.0 → 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

@@ -95,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) {
@@ -124,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) {
@@ -434,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
     );
   }
@@ -490,18 +490,45 @@ function formatBlocker(r) {
   return `\u2713 Blocker aberto: ${r.description}`;
 }
 function formatStartList(list) {
-  const header = "Features para iniciar ou retomar \u2014 escolha: nf start <n\xBA>";
+  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");
 }
+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 ${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)"
+    ...startFlowLines(r)
   ].join("\n");
 }
 function formatHealth(snaps) {
@@ -557,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(", ")}`);
   }
@@ -570,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);
@@ -610,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.)`
     );
   }
 }
@@ -638,7 +665,7 @@ 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 [features, localBranches] = await Promise.all([io.client.listFeatures(), io.listBranches()]);
@@ -1236,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);
@@ -1286,31 +1313,32 @@ async function logout(io, _args) {
 }
 
 // src/index.ts
-var VERSION = "0.6.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>]
+  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
-  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 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)
@@ -1319,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)
@@ -1345,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" },
@@ -1353,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) {
@@ -1423,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.6.0",
+  "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": [