@h1veframework/cli 0.5.1 → 0.5.2

package/README.md

@@ -1,93 +1,79 @@
-# @h1veframework/cli
+# @h1veframework/cli · `nf`
 
-CLI `nf` do **H1VE Flow** — opera o fluxo da feature da sua branch direto do terminal
-(status, start, move, spec, done, blocker, health, connect), autenticado por um token pessoal.
+**The command-line companion for [H1VE](https://h1ve.org) — the governance & memory layer for teams building with AI.**
 
-Parte do tooling do H1VE junto com o **[servidor MCP](https://www.npmjs.com/package/@h1veframework/mcp)**
-(para o Claude Code).
+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.
 
-## Pré-requisitos
+Part of the H1VE toolchain, alongside the **[MCP server](https://www.npmjs.com/package/@h1veframework/mcp)** for
+Claude Code / Cursor.
 
-- **Node.js 18.18+** (`node --version`).
-- Uma conta no H1VE Flow. **Não precisa criar/colar token** — o `nf login` cuida disso.
+→ **[h1ve.org](https://h1ve.org)** · **[app.h1ve.org](https://app.h1ve.org)**
 
-## Instalação
+## Quickstart (zero paste)
 
 ```bash
 npm i -g @h1veframework/cli
-nf --version
+nf login     # opens your browser → you click Authorize → done
+nf status    # state of the current branch's feature
 ```
 
-## Login (recomendado — sem colar nada)
+`nf 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.
 
-```bash
-nf login       # abre o navegador → você autoriza → pronto
-nf health      # já funciona
-```
+> `nf health` saying "no snapshots yet" is **success** (you're connected; the project just has no metrics yet).
 
-O `nf login` abre o navegador (onde você já está logado no H1VE), você clica **Autorizar**, e o CLI **guarda
-a credencial sozinho** em `~/.config/h1ve/credentials.json` (permissão 600). O **[MCP](https://www.npmjs.com/package/@h1veframework/mcp)**
-lê a mesma credencial — um `nf login` configura os dois. `nf logout` remove. **100% automático** (SPEC-078):
-o projeto também é resolvido sozinho pelo repo (SPEC-077), então nada de `H1VE_PROJECT_ID`.
+## Commands
 
-> "Nenhum snapshot registrado" no `nf health` é **sucesso** (conectou; projeto sem métricas ainda).
+| 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 |
 
-## Alternativa: variáveis de ambiente (CI / headless)
+Flags: `--json` (raw output for scripts) · `--project <name\|id>` (if you belong to more than one project) · `-h`.
 
-Sem navegador (ex.: CI), configure por env — tem **precedência** sobre o `nf login`:
+## Example
 
 ```bash
-export H1VE_API_URL="https://app.h1ve.org"   # opcional (default já é este)
-export H1VE_API_KEY="nf_pat_..."             # PAT criado em app.h1ve.org/api-tokens
-# export H1VE_PROJECT_ID="..."               # OPCIONAL — o CLI resolve o projeto pelo repo; use só p/ forçar
+nf 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_PROJECT_ID`** (SPEC-076/077): **opcional**. Rodando dentro de um repo conectado a um projeto, o
-> CLI **resolve o projeto sozinho** pelo `git remote` — zero config, mesmo com 2+ projetos. Use só pra
-> **forçar** um projeto (override).
+## CI / headless (env vars)
 
-## Comandos
-
-| Comando | O que faz |
-|---|---|
-| `nf login` | Autoriza no navegador e salva a credencial local (sem colar nada) |
-| `nf logout` | Remove a credencial local |
-| `nf health` | Últimos snapshots de saúde técnica do projeto |
-| `nf status` | Estado da feature da branch atual (stage, dias ativo, blockers, sign-offs) |
-| `nf start [<nº\|id>] [--slug <s>]` | Inicia uma feature atribuída: cria a branch `feat/{você}/{slug}` e grava o slug |
-| `nf spec` | Imprime a spec (markdown) da feature da branch |
-| `nf move <stage> [--note]` | Move a feature para outro stage |
-| `nf done [--from <arq>] [--no-move]` | Envia a AI declaration (JSON) e move `dev → pr` |
-| `nf blocker "<desc>"` | Abre um blocker na feature (você vira o dono) |
-| `nf connect --kind <k> --label <l> --env KEY=VAL` | Aplica uma credencial no `.env.local` **local** (nunca ao servidor) e registra o inventário (Jeito B) |
-| `nf serve [--port 7391]` | Sobe o agente local (`127.0.0.1`) p/ o menu visual do painel aplicar credenciais pelo navegador |
-
-Flags: `--json` (saída crua p/ scripts) · `--project <nome\|id>` (se você é membro de +1 projeto) · `-h` (ajuda completa).
-
-## Exemplo de uso
+No browser? Configure by env (takes **precedence** over `nf login`):
 
 ```bash
-nf start                                  # inicia a feature atribuída (cria a branch)
-# ... trabalha (git, código, commits) ...
-nf status                                 # estado a qualquer momento
-nf blocker "aguardando credencial do Neon" # trava? abre blocker
-nf done --from ai-declaration.json        # envia a AI declaration + move dev → pr
+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
 
-| Sintoma | Solução |
+| Symptom | Fix |
 |---|---|
-| `nf: command not found` | Node ausente ou terminal errado. Confira `node --version`. No Windows, o PowerShell pode não ter o bin do npm no PATH — use o terminal do VS Code ou reabra o shell. |
-| `404` ao instalar | Propagação do npm logo após publicação. Espere alguns minutos. |
-| `NO_PROJECT` | Você é membro de +1 projeto — passe `--project <nome\|id>`. |
-| `401` / `403` | Token errado/ausente/sem permissão. Confira que `H1VE_API_KEY` é um PAT (`nf_pat_…`). `403 SERVICE_CANNOT_WRITE` = chave de serviço (só leitura) numa escrita → use um PAT. |
-
-## Compatibilidade de nomes
+| `nf: 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. |
 
-Use **`H1VE_API_URL`** e **`H1VE_API_KEY`**. Os nomes legados `NEXUS_FLOW_API_URL` / `NEXUS_FLOW_API_KEY`
-**ainda são aceitos** por compatibilidade — se você já configurou com eles, não precisa mudar nada.
+Requires **Node.js 18.18+**. Legacy env names `NEXUS_FLOW_API_URL` / `NEXUS_FLOW_API_KEY` are still accepted.
 
 ---
 
-MIT · [H1VE Flow](https://app.h1ve.org)
+MIT · built with H1VE, by [H1VE](https://h1ve.org) 🐝

package/dist/index.js

@@ -128,16 +128,17 @@ function createClient(config) {
     // do id e ignora o header onde não escopa — então mandar sempre é simples e seguro.
     ...config.projectId ? { "x-project-id": config.projectId } : {}
   };
-  async function postAction(featureId, action, body) {
+  async function writeAction(method, featureId, action, body) {
     const url = `${rootUrl(config.baseUrl)}/api/features/${encodeURIComponent(featureId)}/${action}`;
     const res = await doFetch(url, {
-      method: "POST",
+      method,
       headers: { ...authHeaders, "content-type": "application/json" },
       body: JSON.stringify(body)
     });
     if (!res.ok) throw mapWriteError(res.status, await readErrorCode(res));
     return await res.json();
   }
+  const postAction = (featureId, action, body) => writeAction("POST", featureId, action, body);
   return {
     async getContext(branch) {
       const url = `${rootUrl(config.baseUrl)}/api/context?branch=${encodeURIComponent(branch)}`;
@@ -157,9 +158,38 @@ function createClient(config) {
       if (!res.ok) throw errorForStatus(res.status, await readErrorCode(res));
       return await res.json();
     },
+    async recallMemory(query) {
+      const params = new URLSearchParams();
+      if (query.entities?.length) params.set("entities", query.entities.join(","));
+      if (query.text) params.set("q", query.text);
+      if (query.limit) params.set("limit", String(query.limit));
+      const url = `${rootUrl(config.baseUrl)}/api/memory/recall?${params.toString()}`;
+      const res = await doFetch(url, { headers: authHeaders });
+      if (!res.ok) throw errorForStatus(res.status, await readErrorCode(res));
+      return await res.json();
+    },
     startFeature(featureId, slug) {
       return postAction(featureId, "start", slug ? { slug } : {});
     },
+    setSpec(featureId, specContent) {
+      return writeAction("PATCH", featureId, "spec", { spec_content: specContent });
+    },
+    // 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) {
+      try {
+        const url = `${rootUrl(config.baseUrl)}/api/features/${encodeURIComponent(featureId)}/spec/alignment`;
+        const res = await doFetch(url, {
+          method: "POST",
+          headers: { ...authHeaders, "content-type": "application/json" },
+          body: "{}"
+        });
+        if (!res.ok) return { checked: false };
+        return await res.json();
+      } catch {
+        return { checked: false };
+      }
+    },
     moveStage(featureId, toStage, note) {
       return postAction(featureId, "move", { to_stage: toStage, note });
     },

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@h1veframework/cli",
-  "version": "0.5.1",
-  "description": "CLI `nf` do H1VE Flow: opera o fluxo da feature (status/move/blocker/spec/done/health/start) da própria branch, via PAT.",
+  "version": "0.5.2",
+  "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": {
@@ -19,17 +19,27 @@
     "url": "git+https://github.com/GusHartz/nexus-flow.git",
     "directory": "packages/cli"
   },
-  "homepage": "https://github.com/GusHartz/nexus-flow/tree/main/packages/cli#readme",
+  "homepage": "https://h1ve.org",
   "bugs": {
     "url": "https://github.com/GusHartz/nexus-flow/issues"
   },
   "keywords": [
     "h1ve",
-    "h1ve-flow",
     "cli",
     "nf",
+    "ai",
+    "claude-code",
+    "cursor",
+    "copilot",
+    "ai-coding",
+    "ai-agents",
+    "memory",
+    "anti-drift",
+    "context",
+    "governance",
+    "developer-tools",
     "dev-workflow",
-    "governance"
+    "mcp"
   ],
   "publishConfig": {
     "access": "public"