@h1veframework/cli 0.8.0 → 0.9.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

@@ -82,7 +82,7 @@ function errorForStatus(status2, code) {
   if (code === "NO_PROJECT") {
     return new NexusApiError(
       "NO_PROJECT",
-      "Nenhum projeto resolvido para este repo. Conecte-o a um projeto em /settings \u2192 GitHub (o CLI/MCP ent\xE3o auto-resolvem pelo git remote), ou defina H1VE_PROJECT_ID na config."
+      "Nenhum projeto resolvido para este repo. Causas comuns: (1) o repo n\xE3o est\xE1 conectado a um projeto \u2014 conecte em /settings \u2192 GitHub; (2) a conta logada N\xC3O \xE9 membro do projeto do repo \u2014 confira com `h1ve whoami` e logue na conta certa (`h1ve logout && h1ve login`). Ou defina H1VE_PROJECT_ID na config."
     );
   }
   switch (status2) {
@@ -192,6 +192,9 @@ function createClient(config) {
     setSpec(featureId, specContent) {
       return writeAction("PATCH", featureId, "spec", { spec_content: specContent });
     },
+    setDone(featureId, doneContent) {
+      return writeAction("PATCH", featureId, "done", { done_content: doneContent });
+    },
     // 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) {
@@ -217,6 +220,12 @@ function createClient(config) {
     submitAiDeclaration(featureId, input) {
       return postAction(featureId, "ai-declaration", input);
     },
+    async getMe() {
+      const url = `${rootUrl(config.baseUrl)}/api/auth/me`;
+      const res = await doFetch(url, { headers: authHeaders });
+      if (!res.ok) throw errorForStatus(res.status, await readErrorCode(res));
+      return await res.json();
+    },
     async listProjects() {
       const url = `${rootUrl(config.baseUrl)}/api/projects`;
       const res = await doFetch(url, { headers: authHeaders });
@@ -483,6 +492,18 @@ function formatSpec(d) {
   if (!d.spec_content) return `${d.feature.name}: sem spec registrada.`;
   return d.spec_content;
 }
+function formatSpecSet(featureName, path, chars) {
+  return [
+    `\u2713 SPEC publicada no card "${featureName}" (${chars} chars, de ${path}).`,
+    "  Agora ela aparece na Fila de Spec para aprova\xE7\xE3o e nos gates do fluxo."
+  ].join("\n");
+}
+function formatDoneDoc(featureName, path, chars) {
+  return [
+    `\u2713 DONE publicado no card "${featureName}" (${chars} chars, de ${path}).`,
+    "  O documento n\xE3o move o card \u2014 use `h1ve done --from <ai-decl.json>` para o fluxo dev \u2192 pr."
+  ].join("\n");
+}
 function formatMove(prevStage, r) {
   return `\u2713 ${r.name}: ${stageLabel(prevStage)} \u2192 ${stageLabel(r.stage)}`;
 }
@@ -545,6 +566,13 @@ function formatHealth(snaps) {
   );
   return [header, ...rows].join("\n");
 }
+function formatWhoami(me, host, projectId) {
+  return [
+    `conta:   ${me.email}  (${me.role})`,
+    `host:    ${host}`,
+    `projeto: ${projectId ?? "(n\xE3o resolvido para este repo \u2014 a conta pode n\xE3o ser membro do projeto, ou o repo n\xE3o est\xE1 conectado)"}`
+  ].join("\n");
+}
 function formatConnect(r) {
   return [
     `\u2713 Conectado "${r.label}" ao projeto ${r.project}.`,
@@ -561,9 +589,21 @@ async function status(io) {
 }
 
 // src/commands/spec.ts
-async function spec(io) {
+async function spec(io, args) {
   const branch = await io.resolveBranch();
   const digest = await io.client.getContext(branch);
+  if (args.doc || args.from) {
+    const path = args.doc ?? args.from;
+    const content = await io.readFile(path);
+    if (!content.trim()) {
+      throw new CliError(`O arquivo ${path} est\xE1 vazio \u2014 nada para publicar no card.`);
+    }
+    const result = await io.client.setSpec(digest.feature.id, content);
+    return {
+      human: formatSpecSet(digest.feature.name, path, result.spec_content?.length ?? 0),
+      data: { id: result.id, spec_content: result.spec_content }
+    };
+  }
   return { human: formatSpec(digest), data: { spec_content: digest.spec_content } };
 }
 
@@ -616,7 +656,21 @@ async function readDeclaration(io, from) {
     throw new CliError("JSON inv\xE1lido na AI declaration.");
   }
 }
+async function publishDoneDoc(io, path) {
+  const content = await io.readFile(path);
+  if (!content.trim()) {
+    throw new CliError(`O arquivo ${path} est\xE1 vazio \u2014 nada para publicar no card.`);
+  }
+  const branch = await io.resolveBranch();
+  const digest = await io.client.getContext(branch);
+  const result = await io.client.setDone(digest.feature.id, content);
+  return {
+    human: formatDoneDoc(digest.feature.name, path, result.done_content?.length ?? 0),
+    data: { id: result.id, done_content: result.done_content }
+  };
+}
 async function done(io, args) {
+  if (args.doc) return publishDoneDoc(io, args.doc);
   const input = await readDeclaration(io, args.from);
   const branch = await io.resolveBranch();
   const digest = await io.client.getContext(branch);
@@ -1312,20 +1366,39 @@ async function logout(io, _args) {
   };
 }
 
+// src/commands/whoami.ts
+async function whoami(io) {
+  const me = await io.client.getMe();
+  const host = io.host ?? "\u2014";
+  let projectId = null;
+  try {
+    projectId = io.resolveProjectId ? await io.resolveProjectId() : null;
+  } catch {
+    projectId = null;
+  }
+  return {
+    human: formatWhoami(me, host, projectId),
+    data: { id: me.id, name: me.name, email: me.email, role: me.role, host, project_id: projectId }
+  };
+}
+
 // src/index.ts
-var VERSION = "0.7.0";
+var VERSION = "0.9.0";
 var HELP = `h1ve \u2014 CLI do H1VE
 (o comando legado \`nf\` continua funcionando como alias)
 
 Uso:
   h1ve login                autoriza no navegador e salva a credencial local (sem colar nada)
   h1ve logout               remove a credencial local
+  h1ve whoami               conta logada + host + projeto resolvido para este repo
   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 spec --from <arq>    publica o arquivo da SPEC no card (spec_content)
   h1ve move <stage> [--note]  move a feature de stage
   h1ve blocker "<desc>"     abre um blocker na feature
+  h1ve done --doc <arq>     publica o documento DONE no card (n\xE3o move)
   h1ve done [--from <arq>] [--no-move]
                             envia a AI declaration (JSON) e move dev \u2192 pr
   h1ve health               \xFAltimos snapshots de sa\xFAde t\xE9cnica
@@ -1338,6 +1411,8 @@ Uso:
 
 Flags:
   --json            sa\xEDda em JSON cru (comp\xF5e em scripts)
+  --from <arq>      arquivo da SPEC ('h1ve spec') ou da AI declaration JSON ('h1ve done')
+  --doc <arq>       arquivo do documento DONE a publicar no card ('h1ve done --doc')
   --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)")
@@ -1352,7 +1427,7 @@ Ambiente (opcional \u2014 'h1ve login' dispensa):
   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)
 `;
-var COMMANDS = { start, status, spec, move, blocker, done, health, connect, serve, login, logout };
+var COMMANDS = { start, status, spec, move, blocker, done, health, connect, serve, login, logout, whoami };
 var NO_CONFIG = /* @__PURE__ */ new Set(["serve", "login", "logout"]);
 async function readStdin() {
   if (process.stdin.isTTY) return "";
@@ -1368,6 +1443,7 @@ function parse(argv) {
       options: {
         note: { type: "string" },
         from: { type: "string" },
+        doc: { type: "string" },
         slug: { type: "string" },
         "no-move": { type: "boolean" },
         json: { type: "boolean" },
@@ -1421,12 +1497,16 @@ ${HELP}`);
     readStdin,
     writeEnvVars: (pairs, opts) => writeEnvVars(pairs, { file: opts?.file }),
     removeEnvVars: (keys, opts) => removeEnvVars(keys, { file: opts?.file }),
-    credentials: defaultCredentialStore
+    credentials: defaultCredentialStore,
+    // SPEC-173: `h1ve whoami` mostra o host + resolve o projeto do repo (override ou git remote).
+    host: cfg?.baseUrl,
+    resolveProjectId: cfg ? () => cfg.projectId ? Promise.resolve(cfg.projectId) : autoResolveProjectId({ baseUrl: cfg.baseUrl, apiKey: cfg.apiKey }) : void 0
   };
   const args = {
     positional: positionals[1],
     note: values.note,
     from: values.from,
+    doc: values.doc,
     slug: values.slug,
     noMove: values["no-move"] === true,
     kind: values.kind,

package/package.json

@@ -1,60 +1,60 @@
-{
-  "name": "@h1veframework/cli",
-  "version": "0.8.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"
-  },
-  "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.9.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"
+  },
+  "devDependencies": {
+    "@nexus-flow/core": "*",
+    "@types/node": "^20.19.43",
+    "tsup": "^8.3.0",
+    "typescript": "^5.6.0",
+    "vitest": "^2.1.0"
+  }
+}