@h1veframework/cli 0.13.0 → 0.15.0

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 H1VE Framework
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 H1VE Framework
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,81 +1,81 @@
-# @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.
-`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.
-
-→ **[h1ve.org](https://h1ve.org)** · **[app.h1ve.org](https://app.h1ve.org)**
-
-## Quickstart (zero paste)
-
-```bash
-npm i -g @h1veframework/cli
-h1ve login     # opens your browser → you click Authorize → done
-h1ve status    # state of the current branch's feature
-```
-
-`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. `h1ve logout` removes it.
-
-> 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 |
-|---|---|
-| `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
-h1ve start                                    # start your assigned feature (creates the branch)
-# ... work: git, code, commits ...
-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 `h1ve login`):
-
-```bash
-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
-
-| Symptom | Fix |
-|---|---|
-| `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+**. The legacy `nf` command and env names `NEXUS_FLOW_API_URL` / `NEXUS_FLOW_API_KEY` are still accepted.
-
----
-
-MIT · built with H1VE, by [H1VE](https://h1ve.org) 🐝
+# @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.
+`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.
+
+→ **[h1ve.org](https://h1ve.org)** · **[app.h1ve.org](https://app.h1ve.org)**
+
+## Quickstart (zero paste)
+
+```bash
+npm i -g @h1veframework/cli
+h1ve login     # opens your browser → you click Authorize → done
+h1ve status    # state of the current branch's feature
+```
+
+`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. `h1ve logout` removes it.
+
+> 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 |
+|---|---|
+| `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
+h1ve start                                    # start your assigned feature (creates the branch)
+# ... work: git, code, commits ...
+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 `h1ve login`):
+
+```bash
+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
+
+| Symptom | Fix |
+|---|---|
+| `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+**. The legacy `nf` command and env names `NEXUS_FLOW_API_URL` / `NEXUS_FLOW_API_KEY` are still accepted.
+
+---
+
+MIT · built with H1VE, by [H1VE](https://h1ve.org) 🐝

package/dist/index.js

@@ -212,6 +212,9 @@ function createClient(config) {
     setDone(featureId, doneContent) {
       return writeAction("PATCH", featureId, "done", { done_content: doneContent });
     },
+    addDependency(featureId, dependsOnId) {
+      return postAction(featureId, "dependencies", { depends_on_id: dependsOnId });
+    },
     // 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) {
@@ -294,6 +297,26 @@ async function exchangeCliLoginCode(config, code) {
   return { apiKey: body.api_key };
 }
 
+// ../core/src/cli-login.ts
+function buildAuthorizeUrl(baseUrl, port, state) {
+  const base = baseUrl.replace(/\/+$/, "");
+  return `${base}/cli-login?port=${port}&state=${encodeURIComponent(state)}`;
+}
+function parseCallbackUrl(reqUrl, expectedState) {
+  let u;
+  try {
+    u = new URL(reqUrl, "http://127.0.0.1");
+  } catch {
+    return { error: "bad_url" };
+  }
+  if (u.pathname !== "/cb") return { error: "not_cb" };
+  const code = u.searchParams.get("code");
+  const state = u.searchParams.get("state");
+  if (!code || !state) return { error: "missing" };
+  if (state !== expectedState) return { error: "state_mismatch" };
+  return { code };
+}
+
 // ../core/src/env.ts
 import { readFile as fsReadFile, writeFile as fsWriteFile } from "fs/promises";
 import { join } from "path";
@@ -525,6 +548,13 @@ function formatStatus(d) {
   } else {
     lines.push("Blockers ativos: nenhum");
   }
+  if (d.attachments && d.attachments.length) {
+    lines.push(`Anexos (${d.attachments.length}):`);
+    for (const a of d.attachments) {
+      const tag = a.kind === "repo_path" ? "  (arquivo local \u2014 leia)" : "";
+      lines.push(`  \u{1F4CE} ${a.label ? `${a.label} \u2014 ` : ""}${a.value}${tag}`);
+    }
+  }
   if (d.ai_declaration?.submitted) lines.push("AI declaration: enviada");
   return lines.join("\n");
 }
@@ -550,13 +580,47 @@ function formatMove(prevStage, r) {
 function formatBlocker(r) {
   return `\u2713 Blocker aberto: ${r.description}`;
 }
+function suggestionReason(f) {
+  if (f.branch_slug !== null) return "j\xE1 iniciado \u2014 retome antes de abrir outra frente";
+  if (f.blocked_by_dep) return "\xE9 o mais priorit\xE1rio dispon\xEDvel, mas depende de trabalho n\xE3o conclu\xEDdo";
+  if (f.priority === "HIGH") return "prioridade alta e sem depend\xEAncia pendente";
+  if (f.priority === "MEDIUM") return "sem depend\xEAncia pendente; nada de prioridade alta na fila";
+  return "\xE9 o que resta na fila";
+}
+function metaOf(f) {
+  const aposta = f.appetite ? ` \xB7 ${f.appetite}d` : "";
+  return `  ${f.priority}${aposta}`;
+}
 function formatStartList(list) {
   const header = "Features para iniciar ou retomar \u2014 escolha: h1ve start <n\xBA>";
-  const rows = list.map((f, i) => {
+  const rows = list.flatMap((f, i) => {
+    const sugerido = i === 0;
+    const marca = sugerido ? "\u2192" : " ";
     const tag = f.branch_slug !== null ? "  (retomar)" : "";
-    return `  ${String(i + 1).padStart(2)}. ${f.name}  [${stageLabel(f.stage)}]${tag}`;
+    const dep = f.depends_on && f.depends_on.length > 0 ? `  \u26A0 depende de ${f.depends_on.map((d) => d.name).join(", ")}` : "";
+    const linha = `${marca} ${String(i + 1).padStart(2)}. ${f.name}  [${stageLabel(f.stage)}]${metaOf(f)}${tag}${dep}`;
+    return sugerido ? [linha, `       sugerido: ${suggestionReason(f)}`] : [linha];
   });
-  return [header, ...rows].join("\n");
+  return [header, "", ...rows].join("\n");
+}
+var PRIORITY_RANK = { HIGH: 0, MEDIUM: 1, LOW: 2 };
+function rankStartable(list) {
+  return [...list].sort((a, b) => {
+    const resume = (a.branch_slug !== null ? 0 : 1) - (b.branch_slug !== null ? 0 : 1);
+    if (resume !== 0) return resume;
+    const blocked = (a.blocked_by_dep ? 1 : 0) - (b.blocked_by_dep ? 1 : 0);
+    if (blocked !== 0) return blocked;
+    const prio = PRIORITY_RANK[a.priority] - PRIORITY_RANK[b.priority];
+    if (prio !== 0) return prio;
+    return (a.appetite ?? 0) - (b.appetite ?? 0);
+  });
+}
+function formatDepWarning(f) {
+  if (!f.depends_on || f.depends_on.length === 0) return "";
+  const names = f.depends_on.map((d) => d.name).join(", ");
+  return `\u26A0 "${f.name}" depende de ${names} (ainda n\xE3o conclu\xEDdo) \u2014 considere fazer isso primeiro.
+
+`;
 }
 var PRE_DEV_STAGES = /* @__PURE__ */ new Set(["backlog", "spec", "blocked"]);
 function startFlowLines(r) {
@@ -781,7 +845,7 @@ function pick(list, arg) {
 }
 async function start(io, args) {
   const [features, localBranches] = await Promise.all([io.client.listFeatures(), io.listBranches()]);
-  const list = startable(features, localBranches);
+  const list = rankStartable(startable(features, localBranches));
   if (list.length === 0) {
     throw new CliError("Nenhuma feature para iniciar ou retomar (sem branch local e fora de main).");
   }
@@ -799,7 +863,8 @@ async function start(io, args) {
     if (code === "BRANCH_EXISTS") await io.switchBranch(result.branch_name);
     else throw err;
   }
-  return { human: `${warning}${formatStart(result, { resumed: resuming })}`, data: result };
+  const depWarn = formatDepWarning(selected);
+  return { human: `${warning}${depWarn}${formatStart(result, { resumed: resuming })}`, data: result };
 }
 
 // src/commands/connect.ts
@@ -1316,24 +1381,6 @@ import { createServer as createServer2 } from "http";
 import { randomBytes as randomBytes2 } from "crypto";
 import { execFile as execFile2 } from "child_process";
 var LOGIN_TIMEOUT_MS = 3 * 60 * 1e3;
-function buildAuthorizeUrl(baseUrl, port, state) {
-  const base = baseUrl.replace(/\/+$/, "");
-  return `${base}/cli-login?port=${port}&state=${encodeURIComponent(state)}`;
-}
-function parseCallbackUrl(reqUrl, expectedState) {
-  let u;
-  try {
-    u = new URL(reqUrl, "http://127.0.0.1");
-  } catch {
-    return { error: "bad_url" };
-  }
-  if (u.pathname !== "/cb") return { error: "not_cb" };
-  const code = u.searchParams.get("code");
-  const state = u.searchParams.get("state");
-  if (!code || !state) return { error: "missing" };
-  if (state !== expectedState) return { error: "state_mismatch" };
-  return { code };
-}
 var SUCCESS_HTML = `<!doctype html><html><head><meta charset="utf-8"><title>H1VE</title></head>
 <body style="font-family:system-ui;background:#0f1115;color:#e7e9ee;display:flex;min-height:100vh;align-items:center;justify-content:center;margin:0">
 <div style="text-align:center"><div style="font-size:22px;font-weight:800;letter-spacing:.12em">H<span style="color:#f5a623">1</span>VE</div>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@h1veframework/cli",
-  "version": "0.13.0",
+  "version": "0.15.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",