@h1veframework/cli 0.13.0 → 0.14.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) {
@@ -554,10 +557,30 @@ function formatStartList(list) {
   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}`;
+    const dep = f.depends_on && f.depends_on.length > 0 ? `  \u26A0 depende de ${f.depends_on.map((d) => d.name).join(", ")}` : "";
+    return `  ${String(i + 1).padStart(2)}. ${f.name}  [${stageLabel(f.stage)}]${tag}${dep}`;
   });
   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) {
   const stage = r.landed_stage ?? r.feature.stage;
@@ -781,7 +804,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 +822,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

package/package.json

@@ -1,61 +1,61 @@
-{
-  "name": "@h1veframework/cli",
-  "version": "0.13.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": [
-    "dist",
-    "README.md"
-  ],
-  "engines": {
-    "node": ">=18.18"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/GusHartz/nexus-flow.git",
-    "directory": "packages/cli"
-  },
-  "homepage": "https://h1ve.org",
-  "bugs": {
-    "url": "https://github.com/GusHartz/nexus-flow/issues"
-  },
-  "keywords": [
-    "h1ve",
-    "cli",
-    "nf",
-    "ai",
-    "claude-code",
-    "cursor",
-    "copilot",
-    "ai-coding",
-    "ai-agents",
-    "memory",
-    "anti-drift",
-    "context",
-    "governance",
-    "developer-tools",
-    "dev-workflow",
-    "mcp"
-  ],
-  "publishConfig": {
-    "access": "public"
-  },
-  "scripts": {
-    "build": "tsup",
-    "typecheck": "tsc --noEmit",
-    "test": "vitest run",
-    "prepublishOnly": "npm run build"
-  },
-  "devDependencies": {
-    "@nexus-flow/core": "*",
-    "@types/node": "^20.19.43",
-    "tsup": "^8.3.0",
-    "typescript": "^5.6.0",
-    "vitest": "^2.1.0"
-  }
-}
+{
+  "name": "@h1veframework/cli",
+  "version": "0.14.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": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18.18"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/GusHartz/nexus-flow.git",
+    "directory": "packages/cli"
+  },
+  "homepage": "https://h1ve.org",
+  "bugs": {
+    "url": "https://github.com/GusHartz/nexus-flow/issues"
+  },
+  "keywords": [
+    "h1ve",
+    "cli",
+    "nf",
+    "ai",
+    "claude-code",
+    "cursor",
+    "copilot",
+    "ai-coding",
+    "ai-agents",
+    "memory",
+    "anti-drift",
+    "context",
+    "governance",
+    "developer-tools",
+    "dev-workflow",
+    "mcp"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "prepublishOnly": "npm run build"
+  },
+  "devDependencies": {
+    "@nexus-flow/core": "*",
+    "@types/node": "^20.19.43",
+    "tsup": "^8.3.0",
+    "typescript": "^5.6.0",
+    "vitest": "^2.1.0"
+  }
+}