@h1veframework/cli 0.1.0 → 0.2.0

package/README.md

@@ -1,87 +1,76 @@
-# @h1veframework/cli — `nf`
+# @h1veframework/cli
 
-CLI de terminal do **H1VE Flow**. Opera o fluxo da feature **da própria branch**, sem abrir o painel: ver estado, mover stage, abrir blocker, ler a spec, enviar a AI declaration e consultar a saúde técnica.
+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.
 
-É um **cliente fino**: toda regra (transições, ownership, papéis) é decidida no servidor. O `nf` resolve a branch (via `git`), chama a API e formata a saída. O bundle é **auto-contido** (sem dependências de runtime além do Node).
+Parte do tooling do H1VE junto com o **[servidor MCP](https://www.npmjs.com/package/@h1veframework/mcp)**
+(para o Claude Code).
 
-## Instalação
+## Pré-requisitos
 
-```bash
-npm install -g @h1veframework/cli   # disponibiliza o comando `nf` globalmente
-```
+- **Node.js 18.18+** (`node --version`).
+- Uma conta no H1VE Flow e um **PAT** (`nf_pat_…`), criado em **`app.h1ve.org/api-tokens`**.
+  - PAT autentica **como você**: leitura **e escrita**. A chave de serviço é **só leitura**.
+  - Guarde o PAT com cuidado — é um segredo, mostrado uma vez.
 
-> Requer Node ≥ 18.18 e `git` no PATH.
-
-<details><summary>A partir do código-fonte (contribuidores)</summary>
+## Instalação
 
 ```bash
-npm install                              # na raiz do monorepo
-npm run build -w @h1veframework/cli
-node packages/cli/dist/index.js --help   # ou: npm i -g ./packages/cli
+npm i -g @h1veframework/cli
+nf --version
 ```
-</details>
 
 ## Configuração
 
-Duas variáveis de ambiente:
-
-| Variável | Descrição |
-|---|---|
-| `NEXUS_FLOW_API_URL` | URL do H1VE Flow (ex.: `https://app.h1ve.org`) |
-| `NEXUS_FLOW_API_KEY` | Um **PAT** (`nf_pat_…`, criado em `/api-tokens`) **ou** a chave de serviço |
-
 ```bash
-export NEXUS_FLOW_API_URL=https://app.h1ve.org
-export NEXUS_FLOW_API_KEY=nf_pat_xxxxxxxx
+export H1VE_API_URL="https://app.h1ve.org"
+export H1VE_API_KEY="nf_pat_..."      # seu PAT
+nf health                              # testa a conexão
 ```
 
-> Nota: os nomes das env vars ainda usam o prefixo `NEXUS_FLOW_` (nome interno original). O rebrand desses nomes p/ `H1VE_` toca código de servidor + config de deploy — fica p/ uma fatia futura.
-
-- **PAT** (`nf_pat_…`): age com a **sua identidade e papel** — habilita escrita (`move`, `blocker`, `done`).
-- **Chave de serviço**: **só leitura** — `move`/`blocker`/`done` respondem `SERVICE_CANNOT_WRITE`. `status`/`spec`/`health` funcionam.
+> Coloque os `export` no seu `~/.zshrc` / `~/.bashrc` para não repetir a cada sessão.
+> "Nenhum snapshot registrado" no `nf health` é **sucesso** (conectou; projeto sem métricas ainda).
 
 ## Comandos
 
-```bash
-nf status                  # estado da feature da branch (stage, dias ativos, blockers, sign-offs)
-nf spec                    # imprime a spec (spec_content) da feature
-nf move <stage> [--note "..."]   # move a feature de stage
-nf blocker "<descrição>"   # abre um blocker
-nf done [--from <arq>] [--no-move]   # envia a AI declaration (JSON) e move dev → pr
-nf health                  # últimos snapshots de saúde técnica (founder/architect, ou serviço)
-```
-
-Flags globais: `--json` (saída crua), `-h/--help`, `-v/--version`.
+| Comando | O que faz |
+|---|---|
+| `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 |
 
-### `nf done`
+Flags: `--json` (saída crua p/ scripts) · `--project <nome\|id>` (se você é membro de +1 projeto) · `-h` (ajuda completa).
 
-Recebe a AI declaration como **JSON** — de um arquivo ou do stdin:
+## Exemplo de uso
 
 ```bash
-nf done --from ai-declaration.json
-nf done < ai-declaration.json
+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
 ```
 
-Formato do JSON (validado no servidor):
+## Troubleshooting
 
-```json
-{
-  "generated_files": [{ "file": "src/x.ts", "pct_generated": 80 }],
-  "reviewed_files":  [{ "file": "src/x.ts", "reviewed_by_human": true }],
-  "github_pr_number": 42,
-  "out_of_scope": "nenhum"
-}
-```
-
-`nf done` **envia a declaration e depois move `dev → pr`**. Com `--no-move`, só envia. Se o move falhar (ex.: a feature não está em `dev`), a declaration **já foi enviada** — o CLI reporta o parcial e sai com código ≠ 0.
+| Sintoma | Solução |
+|---|---|
+| `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. |
 
-## Saída e exit codes
+## Compatibilidade de nomes
 
-- Sucesso → **stdout**, exit `0`.
-- Erro → **stderr** (mensagem amigável, sem stack), exit `≠ 0` (config faltando = `2`).
+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.
 
-Compõe bem em scripts/CI:
+---
 
-```bash
-nf status --json | jq .stage
-```
+MIT · [H1VE Flow](https://app.h1ve.org)

package/dist/index.js

@@ -16,7 +16,7 @@ var NexusApiError = class extends Error {
 function errorForStatus(status2) {
   switch (status2) {
     case 401:
-      return new NexusApiError("UNAUTHENTICATED", "NEXUS_FLOW_API_KEY ausente ou inv\xE1lida.");
+      return new NexusApiError("UNAUTHENTICATED", "H1VE_API_KEY ausente ou inv\xE1lida.");
     case 403:
       return new NexusApiError("FORBIDDEN", "Sem permiss\xE3o para ver esta feature.");
     case 404:
@@ -45,7 +45,7 @@ function mapWriteError(status2, code) {
   }
   switch (status2) {
     case 401:
-      return new NexusApiError("UNAUTHENTICATED", "NEXUS_FLOW_API_KEY ausente ou inv\xE1lida.");
+      return new NexusApiError("UNAUTHENTICATED", "H1VE_API_KEY ausente ou inv\xE1lida.");
     case 403:
       return new NexusApiError(code ?? "FORBIDDEN", "Sem permiss\xE3o para esta a\xE7\xE3o (papel ou ownership).");
     case 404:
@@ -258,11 +258,11 @@ var CliError = class extends Error {
 
 // src/config.ts
 function readConfig(env = process.env) {
-  const baseUrl = env.NEXUS_FLOW_API_URL?.trim();
-  const apiKey = env.NEXUS_FLOW_API_KEY?.trim();
+  const baseUrl = env.H1VE_API_URL?.trim() || env.NEXUS_FLOW_API_URL?.trim();
+  const apiKey = env.H1VE_API_KEY?.trim() || env.NEXUS_FLOW_API_KEY?.trim();
   if (!baseUrl || !apiKey) {
     throw new CliError(
-      "Defina NEXUS_FLOW_API_URL e NEXUS_FLOW_API_KEY no ambiente.\n  export NEXUS_FLOW_API_URL=https://seu-nexus.example.com\n  export NEXUS_FLOW_API_KEY=nf_pat_...   (crie um token em /api-tokens)",
+      "Defina H1VE_API_URL e H1VE_API_KEY no ambiente.\n  export H1VE_API_URL=https://app.h1ve.org\n  export H1VE_API_KEY=nf_pat_...   (crie um token em /api-tokens)\n  (os nomes legados NEXUS_FLOW_API_URL/KEY ainda s\xE3o aceitos)",
       2
     );
   }
@@ -993,7 +993,7 @@ Cole o c\xF3digo no painel /connections. Ctrl+C para parar.
 }
 
 // src/index.ts
-var VERSION = "0.1.0";
+var VERSION = "0.2.0";
 var HELP = `nf \u2014 CLI do Nexus Flow
 
 Uso:
@@ -1025,8 +1025,9 @@ Flags:
   -v, --version     vers\xE3o do CLI
 
 Ambiente:
-  NEXUS_FLOW_API_URL   URL do Nexus Flow
-  NEXUS_FLOW_API_KEY   PAT (nf_pat_\u2026) p/ escrever, ou a chave de servi\xE7o (s\xF3 leitura)
+  H1VE_API_URL   URL do H1VE Flow (ex.: https://app.h1ve.org)
+  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 };
 async function readStdin() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@h1veframework/cli",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "CLI `nf` do H1VE Flow: opera o fluxo da feature (status/move/blocker/spec/done/health/start) da própria branch, via PAT.",
   "license": "MIT",
   "type": "module",