@h1veframework/cli 0.12.1 → 0.13.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

@@ -61,6 +61,21 @@ async function switchBranch(name, runner = defaultGitRunner) {
     throw new Error("GIT_SWITCH_FAILED");
   }
 }
+async function commitsBehindOriginMain(runner = defaultGitRunner) {
+  try {
+    await runner(["fetch", "origin"]);
+  } catch {
+    return null;
+  }
+  let out;
+  try {
+    out = await runner(["rev-list", "--count", "HEAD..origin/main"]);
+  } catch {
+    return null;
+  }
+  const n = Number(out.trim());
+  return Number.isInteger(n) && n >= 0 ? n : null;
+}
 async function listLocalBranches(runner = defaultGitRunner) {
   let out;
   try {
@@ -360,6 +375,26 @@ async function writeEnvVars(pairs, opts = {}) {
   return { file, keys: Object.keys(pairs) };
 }
 
+// ../core/src/format.ts
+var MINUTE_MS = 6e4;
+var HOUR_MS = 36e5;
+var DAY_MS = 864e5;
+function formatDuration(ms) {
+  if (ms < MINUTE_MS) return "<1min";
+  if (ms < HOUR_MS) return `${Math.floor(ms / MINUTE_MS)}min`;
+  if (ms < DAY_MS) {
+    const h2 = Math.floor(ms / HOUR_MS);
+    const m = Math.floor(ms % HOUR_MS / MINUTE_MS);
+    return m > 0 ? `${h2}h ${m}min` : `${h2}h`;
+  }
+  const d = Math.floor(ms / DAY_MS);
+  const h = Math.floor(ms % DAY_MS / HOUR_MS);
+  return h > 0 ? `${d}d ${h}h` : `${d}d`;
+}
+function formatMinutes(minutes) {
+  return formatDuration(minutes * MINUTE_MS);
+}
+
 // ../core/src/credentials.ts
 import {
   readFile as fsReadFile2,
@@ -457,6 +492,9 @@ async function clientFromConfig(cfg) {
 }
 
 // src/format.ts
+function activeTime(d) {
+  return d.elapsed_minutes != null ? formatMinutes(d.elapsed_minutes) : `${d.days_active}d`;
+}
 var STAGE_LABEL = {
   backlog: "Backlog",
   spec: "Spec",
@@ -476,7 +514,7 @@ function formatStatus(d) {
   const lines = [
     `${f.name}  [${f.priority}]`,
     `Stage:        ${stageLabel(d.stage)}`,
-    `Dias ativos:  ${d.days_active}`,
+    `Tempo ativo:  ${activeTime(d)}`,
     `Branch:       ${f.branch_slug ?? "\u2014"}`
   ];
   if (f.github_pr_url) lines.push(`PR:           ${f.github_pr_url}`);
@@ -554,6 +592,13 @@ function formatStart(r, opts) {
     ...startFlowLines(r)
   ].join("\n");
 }
+function formatBehindMainWarning(behind) {
+  const plural = behind === 1 ? "commit" : "commits";
+  return [
+    `\u26A0 Sua base est\xE1 ${behind} ${plural} atr\xE1s de origin/main.`,
+    "  Sincronize antes de codar: git fetch origin && git rebase origin/main"
+  ].join("\n");
+}
 function formatHealth(snaps) {
   if (!snaps.length) return "Nenhum snapshot de sa\xFAde t\xE9cnica registrado.";
   const header = "Semana     CI%  Deploys  Bugs  D\xEDvida";
@@ -705,6 +750,17 @@ async function health(io) {
 }
 
 // src/commands/start.ts
+async function behindMainWarning(io) {
+  if (!io.checkBehindMain) return "";
+  try {
+    const behind = await io.checkBehindMain();
+    return behind && behind > 0 ? `${formatBehindMainWarning(behind)}
+
+` : "";
+  } catch {
+    return "";
+  }
+}
 function branchSlugOf(branch) {
   return branch.match(/^feat\/[^/]+\/(.+)$/)?.[1] ?? null;
 }
@@ -733,6 +789,7 @@ async function start(io, args) {
   if (!selected) {
     return { human: formatStartList(list), data: { features: list } };
   }
+  const warning = await behindMainWarning(io);
   const resuming = selected.branch_slug !== null;
   const result = await io.client.startFeature(selected.id, args.slug);
   try {
@@ -742,7 +799,7 @@ async function start(io, args) {
     if (code === "BRANCH_EXISTS") await io.switchBranch(result.branch_name);
     else throw err;
   }
-  return { human: formatStart(result, { resumed: resuming }), data: result };
+  return { human: `${warning}${formatStart(result, { resumed: resuming })}`, data: result };
 }
 
 // src/commands/connect.ts
@@ -1437,8 +1494,11 @@ async function mcp(io, args) {
   };
 }
 
+// src/version.ts
+import { readFileSync } from "fs";
+var VERSION = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
+
 // src/index.ts
-var VERSION = "0.12.1";
 var HELP = `h1ve \u2014 CLI do H1VE
 (o comando legado \`nf\` continua funcionando como alias)
 
@@ -1562,6 +1622,7 @@ ${HELP}`);
     createBranch: (name) => createBranch(name, defaultGitRunner),
     switchBranch: (name) => switchBranch(name, defaultGitRunner),
     listBranches: () => listLocalBranches(defaultGitRunner),
+    checkBehindMain: () => commitsBehindOriginMain(defaultGitRunner),
     readFile: (path) => readFile(path, "utf8"),
     readStdin,
     writeEnvVars: (pairs, opts) => writeEnvVars(pairs, { file: opts?.file }),

package/package.json

@@ -1,61 +1,61 @@
-{
-  "name": "@h1veframework/cli",
-  "version": "0.12.1",
-  "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.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"
+  }
+}