@h1veframework/cli 0.2.0 → 0.5.0

package/README.md

@@ -9,9 +9,7 @@ Parte do tooling do H1VE junto com o **[servidor MCP](https://www.npmjs.com/pack
 ## Pré-requisitos
 
 - **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.
+- Uma conta no H1VE Flow. **Não precisa criar/colar token** — o `nf login` cuida disso.
 
 ## Instalação
 
@@ -20,21 +18,40 @@ npm i -g @h1veframework/cli
 nf --version
 ```
 
-## Configuração
+## Login (recomendado — sem colar nada)
 
 ```bash
-export H1VE_API_URL="https://app.h1ve.org"
-export H1VE_API_KEY="nf_pat_..."      # seu PAT
-nf health                              # testa a conexão
+nf login       # abre o navegador → você autoriza → pronto
+nf health      # já funciona
 ```
 
-> Coloque os `export` no seu `~/.zshrc` / `~/.bashrc` para não repetir a cada sessão.
+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`.
+
 > "Nenhum snapshot registrado" no `nf health` é **sucesso** (conectou; projeto sem métricas ainda).
 
+## Alternativa: variáveis de ambiente (CI / headless)
+
+Sem navegador (ex.: CI), configure por env — tem **precedência** sobre o `nf login`:
+
+```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
+```
+
+> **`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).
+
 ## 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 |

package/dist/index.js

@@ -4,6 +4,53 @@
 import { parseArgs } from "util";
 import { readFile } from "fs/promises";
 
+// ../core/src/branch.ts
+import { execFile } from "child_process";
+import { promisify } from "util";
+var execFileAsync = promisify(execFile);
+var defaultGitRunner = async (args) => {
+  const { stdout } = await execFileAsync("git", args, { cwd: process.cwd() });
+  return stdout;
+};
+async function currentBranch(runner = defaultGitRunner) {
+  let out;
+  try {
+    out = await runner(["rev-parse", "--abbrev-ref", "HEAD"]);
+  } catch {
+    throw new Error("NOT_A_GIT_BRANCH");
+  }
+  const branch = out.trim();
+  if (!branch || branch === "HEAD") throw new Error("NOT_A_GIT_BRANCH");
+  return branch;
+}
+async function gitRemoteRepo(runner = defaultGitRunner) {
+  let out;
+  try {
+    out = await runner(["remote", "get-url", "origin"]);
+  } catch {
+    throw new Error("NO_GIT_REMOTE");
+  }
+  const m = out.trim().match(/[:/]([^/:]+)\/([^/]+?)(?:\.git)?\/?$/);
+  if (!m) throw new Error("NO_GIT_REMOTE");
+  return `${m[1]}/${m[2]}`;
+}
+function gitErrText(err) {
+  if (err && typeof err === "object" && "stderr" in err) {
+    return String(err.stderr ?? "");
+  }
+  return err instanceof Error ? err.message : "";
+}
+async function createBranch(name, runner = defaultGitRunner) {
+  try {
+    await runner(["switch", "-c", name]);
+  } catch (err) {
+    const text = gitErrText(err);
+    if (/already exists/i.test(text)) throw new Error("BRANCH_EXISTS");
+    if (/not a git repository/i.test(text)) throw new Error("NOT_A_GIT_REPO");
+    throw new Error("GIT_BRANCH_FAILED");
+  }
+}
+
 // ../core/src/client.ts
 var NexusApiError = class extends Error {
   constructor(code, message) {
@@ -13,7 +60,13 @@ var NexusApiError = class extends Error {
   }
   code;
 };
-function errorForStatus(status2) {
+function errorForStatus(status2, code) {
+  if (code === "NO_PROJECT") {
+    return new NexusApiError(
+      "NO_PROJECT",
+      "Voc\xEA tem mais de um projeto. Defina H1VE_PROJECT_ID (o id do projeto) na config do CLI/MCP."
+    );
+  }
   switch (status2) {
     case 401:
       return new NexusApiError("UNAUTHENTICATED", "H1VE_API_KEY ausente ou inv\xE1lida.");
@@ -68,7 +121,13 @@ function rootUrl(baseUrl) {
 }
 function createClient(config) {
   const doFetch = config.fetchImpl ?? fetch;
-  const authHeaders = { "x-api-key": config.apiKey, accept: "application/json" };
+  const authHeaders = {
+    "x-api-key": config.apiKey,
+    accept: "application/json",
+    // SPEC-076: envia o projeto ativo quando configurado. O servidor valida a membership
+    // 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) {
     const url = `${rootUrl(config.baseUrl)}/api/features/${encodeURIComponent(featureId)}/${action}`;
     const res = await doFetch(url, {
@@ -83,19 +142,19 @@ function createClient(config) {
     async getContext(branch) {
       const url = `${rootUrl(config.baseUrl)}/api/context?branch=${encodeURIComponent(branch)}`;
       const res = await doFetch(url, { headers: authHeaders });
-      if (!res.ok) throw errorForStatus(res.status);
+      if (!res.ok) throw errorForStatus(res.status, await readErrorCode(res));
       return await res.json();
     },
     async listHealth() {
       const url = `${rootUrl(config.baseUrl)}/api/health`;
       const res = await doFetch(url, { headers: authHeaders });
-      if (!res.ok) throw errorForStatus(res.status);
+      if (!res.ok) throw errorForStatus(res.status, await readErrorCode(res));
       return await res.json();
     },
     async listFeatures() {
       const url = `${rootUrl(config.baseUrl)}/api/features`;
       const res = await doFetch(url, { headers: authHeaders });
-      if (!res.ok) throw errorForStatus(res.status);
+      if (!res.ok) throw errorForStatus(res.status, await readErrorCode(res));
       return await res.json();
     },
     startFeature(featureId, slug) {
@@ -113,7 +172,7 @@ function createClient(config) {
     async listProjects() {
       const url = `${rootUrl(config.baseUrl)}/api/projects`;
       const res = await doFetch(url, { headers: authHeaders });
-      if (!res.ok) throw errorForStatus(res.status);
+      if (!res.ok) throw errorForStatus(res.status, await readErrorCode(res));
       return await res.json();
     },
     async createConnection(projectId, input) {
@@ -128,42 +187,38 @@ function createClient(config) {
     }
   };
 }
-
-// ../core/src/branch.ts
-import { execFile } from "child_process";
-import { promisify } from "util";
-var execFileAsync = promisify(execFile);
-var defaultGitRunner = async (args) => {
-  const { stdout } = await execFileAsync("git", args, { cwd: process.cwd() });
-  return stdout;
-};
-async function currentBranch(runner = defaultGitRunner) {
-  let out;
+async function resolveProjectId(config, repo) {
+  const doFetch = config.fetchImpl ?? fetch;
   try {
-    out = await runner(["rev-parse", "--abbrev-ref", "HEAD"]);
+    const url = `${rootUrl(config.baseUrl)}/api/projects/resolve-by-repo?repo=${encodeURIComponent(repo)}`;
+    const res = await doFetch(url, { headers: { "x-api-key": config.apiKey, accept: "application/json" } });
+    if (!res.ok) return null;
+    const body = await res.json();
+    return body.project_id ?? null;
   } catch {
-    throw new Error("NOT_A_GIT_BRANCH");
-  }
-  const branch = out.trim();
-  if (!branch || branch === "HEAD") throw new Error("NOT_A_GIT_BRANCH");
-  return branch;
-}
-function gitErrText(err) {
-  if (err && typeof err === "object" && "stderr" in err) {
-    return String(err.stderr ?? "");
+    return null;
   }
-  return err instanceof Error ? err.message : "";
 }
-async function createBranch(name, runner = defaultGitRunner) {
+async function autoResolveProjectId(config, runner) {
   try {
-    await runner(["switch", "-c", name]);
-  } catch (err) {
-    const text = gitErrText(err);
-    if (/already exists/i.test(text)) throw new Error("BRANCH_EXISTS");
-    if (/not a git repository/i.test(text)) throw new Error("NOT_A_GIT_REPO");
-    throw new Error("GIT_BRANCH_FAILED");
+    return await resolveProjectId(config, await gitRemoteRepo(runner));
+  } catch {
+    return null;
   }
 }
+async function exchangeCliLoginCode(config, code) {
+  const doFetch = config.fetchImpl ?? fetch;
+  const url = `${rootUrl(config.baseUrl)}/api/cli-login/exchange`;
+  const res = await doFetch(url, {
+    method: "POST",
+    headers: { "content-type": "application/json", accept: "application/json" },
+    body: JSON.stringify({ code })
+  });
+  if (!res.ok) throw errorForStatus(res.status, await readErrorCode(res));
+  const body = await res.json();
+  if (!body.api_key) throw new NexusApiError("LOGIN_FAILED", "Resposta de login inv\xE1lida do servidor.");
+  return { apiKey: body.api_key };
+}
 
 // ../core/src/env.ts
 import { readFile as fsReadFile, writeFile as fsWriteFile } from "fs/promises";
@@ -246,6 +301,60 @@ async function writeEnvVars(pairs, opts = {}) {
   return { file, keys: Object.keys(pairs) };
 }
 
+// ../core/src/credentials.ts
+import {
+  readFile as fsReadFile2,
+  writeFile as fsWriteFile2,
+  mkdir as fsMkdir,
+  rm as fsRm,
+  chmod as fsChmod
+} from "fs/promises";
+import { homedir } from "os";
+import { join as join2 } from "path";
+function credentialDir(home = homedir()) {
+  return join2(home, ".config", "h1ve");
+}
+function credentialPath(home = homedir()) {
+  return join2(credentialDir(home), "credentials.json");
+}
+function parseCredential(raw) {
+  try {
+    const v = JSON.parse(raw);
+    if (v && typeof v === "object") {
+      const o = v;
+      if (typeof o.apiKey === "string" && o.apiKey && typeof o.baseUrl === "string" && o.baseUrl) {
+        return { apiKey: o.apiKey, baseUrl: o.baseUrl };
+      }
+    }
+  } catch {
+  }
+  return null;
+}
+function serializeCredential(cred) {
+  return JSON.stringify({ apiKey: cred.apiKey, baseUrl: cred.baseUrl }, null, 2) + "\n";
+}
+var defaultCredentialStore = {
+  read: async () => {
+    try {
+      return parseCredential(await fsReadFile2(credentialPath(), "utf8"));
+    } catch {
+      return null;
+    }
+  },
+  write: async (cred) => {
+    const path = credentialPath();
+    await fsMkdir(credentialDir(), { recursive: true, mode: 448 });
+    await fsWriteFile2(path, serializeCredential(cred), { mode: 384 });
+    await fsChmod(path, 384);
+  },
+  clear: async () => {
+    try {
+      await fsRm(credentialPath());
+    } catch {
+    }
+  }
+};
+
 // src/errors.ts
 var CliError = class extends Error {
   constructor(message, exitCode = 1) {
@@ -257,19 +366,35 @@ var CliError = class extends Error {
 };
 
 // src/config.ts
-function readConfig(env = process.env) {
-  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) {
+var DEFAULT_BASE_URL = "https://app.h1ve.org";
+function resolveBaseUrl(env = process.env) {
+  return env.H1VE_API_URL?.trim() || env.NEXUS_FLOW_API_URL?.trim() || DEFAULT_BASE_URL;
+}
+async function resolveConfig(env = process.env, store = defaultCredentialStore) {
+  const projectId = env.H1VE_PROJECT_ID?.trim() || env.NEXUS_FLOW_PROJECT_ID?.trim();
+  const envKey = env.H1VE_API_KEY?.trim() || env.NEXUS_FLOW_API_KEY?.trim();
+  const envUrl = env.H1VE_API_URL?.trim() || env.NEXUS_FLOW_API_URL?.trim();
+  let apiKey;
+  let baseUrl;
+  if (envKey) {
+    apiKey = envKey;
+    baseUrl = envUrl || DEFAULT_BASE_URL;
+  } else {
+    const stored = await store.read();
+    apiKey = stored?.apiKey;
+    baseUrl = stored?.baseUrl || DEFAULT_BASE_URL;
+  }
+  if (!apiKey) {
     throw new CliError(
-      "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)",
+      "Voc\xEA n\xE3o est\xE1 logado. Rode `nf login` (abre o navegador) \u2014 ou defina H1VE_API_KEY.\n  (o nome legado NEXUS_FLOW_API_KEY tamb\xE9m \xE9 aceito)",
       2
     );
   }
-  return { baseUrl, apiKey };
+  return { baseUrl, apiKey, projectId };
 }
-function clientFromConfig(cfg) {
-  return createClient({ baseUrl: cfg.baseUrl, apiKey: cfg.apiKey });
+async function clientFromConfig(cfg) {
+  const projectId = cfg.projectId ?? await autoResolveProjectId({ baseUrl: cfg.baseUrl, apiKey: cfg.apiKey }) ?? void 0;
+  return createClient({ baseUrl: cfg.baseUrl, apiKey: cfg.apiKey, projectId });
 }
 
 // src/format.ts
@@ -992,11 +1117,127 @@ Cole o c\xF3digo no painel /connections. Ctrl+C para parar.
   return { human: "", data: null };
 }
 
+// src/commands/login.ts
+import { createServer as createServer2 } from "http";
+import { randomBytes as randomBytes2 } from "crypto";
+import { execFile as execFile2 } from "child_process";
+var LOGIN_TIMEOUT_MS = 3 * 60 * 1e3;
+function buildAuthorizeUrl(baseUrl, port, state) {
+  const base = baseUrl.replace(/\/+$/, "");
+  return `${base}/cli-login?port=${port}&state=${encodeURIComponent(state)}`;
+}
+function parseCallbackUrl(reqUrl, expectedState) {
+  let u;
+  try {
+    u = new URL(reqUrl, "http://127.0.0.1");
+  } catch {
+    return { error: "bad_url" };
+  }
+  if (u.pathname !== "/cb") return { error: "not_cb" };
+  const code = u.searchParams.get("code");
+  const state = u.searchParams.get("state");
+  if (!code || !state) return { error: "missing" };
+  if (state !== expectedState) return { error: "state_mismatch" };
+  return { code };
+}
+var SUCCESS_HTML = `<!doctype html><html><head><meta charset="utf-8"><title>H1VE</title></head>
+<body style="font-family:system-ui;background:#0f1115;color:#e7e9ee;display:flex;min-height:100vh;align-items:center;justify-content:center;margin:0">
+<div style="text-align:center"><div style="font-size:22px;font-weight:800;letter-spacing:.12em">H<span style="color:#f5a623">1</span>VE</div>
+<p style="color:#9aa0aa;margin-top:12px">\u2713 Autorizado. Pode fechar esta aba e voltar ao terminal.</p></div></body></html>`;
+function openBrowser(url) {
+  const platform = process.platform;
+  const cmd = platform === "darwin" ? "open" : platform === "win32" ? "cmd" : "xdg-open";
+  const args = platform === "win32" ? ["/c", "start", "", url] : [url];
+  try {
+    const child = execFile2(cmd, args, () => {
+    });
+    child.on("error", () => {
+    });
+    child.unref();
+  } catch {
+  }
+}
+async function startCallbackServer(expectedState) {
+  let resolveCode;
+  const codePromise = new Promise((resolve) => {
+    resolveCode = resolve;
+  });
+  const server = createServer2((req, res) => {
+    const parsed = parseCallbackUrl(req.url ?? "/", expectedState);
+    if ("code" in parsed) {
+      res.writeHead(200, { "content-type": "text/html; charset=utf-8" });
+      res.end(SUCCESS_HTML);
+      resolveCode(parsed.code);
+    } else {
+      res.writeHead(400, { "content-type": "text/plain; charset=utf-8" });
+      res.end("aguardando autorizacao");
+    }
+  });
+  await new Promise((resolve, reject) => {
+    server.on("error", reject);
+    server.listen(0, "127.0.0.1", resolve);
+  });
+  const addr = server.address();
+  const port = addr ? addr.port : 0;
+  const waitForCode = () => new Promise((resolve, reject) => {
+    const timer = setTimeout(() => {
+      server.close();
+      reject(new CliError("Tempo esgotado esperando a autoriza\xE7\xE3o. Rode `nf login` de novo."));
+    }, LOGIN_TIMEOUT_MS);
+    void codePromise.then((code) => {
+      clearTimeout(timer);
+      server.close();
+      resolve(code);
+    });
+  });
+  return { port, waitForCode, close: () => server.close() };
+}
+async function login(io, _args) {
+  const baseUrl = resolveBaseUrl();
+  const state = randomBytes2(18).toString("base64url");
+  const cb = await startCallbackServer(state);
+  const authorizeUrl = buildAuthorizeUrl(baseUrl, cb.port, state);
+  openBrowser(authorizeUrl);
+  process.stderr.write(
+    `Abrindo o navegador para autorizar em ${baseUrl} \u2026
+Se n\xE3o abrir, acesse:
+  ${authorizeUrl}
+
+Aguardando autoriza\xE7\xE3o\u2026
+`
+  );
+  let code;
+  try {
+    code = await cb.waitForCode();
+  } catch (err) {
+    cb.close();
+    throw err;
+  }
+  const { apiKey } = await exchangeCliLoginCode({ baseUrl }, code);
+  await io.credentials.write({ apiKey, baseUrl });
+  return {
+    human: `\u2713 Logado. Credencial salva em ${credentialPath()} (o CLI e o MCP j\xE1 a usam).`,
+    data: { baseUrl, saved: true }
+  };
+}
+
+// src/commands/logout.ts
+async function logout(io, _args) {
+  await io.credentials.clear();
+  return {
+    human: `\u2713 Deslogado localmente (credencial removida de ${credentialPath()}).
+  O token segue v\xE1lido no servidor at\xE9 expirar (90 dias) \u2014 revogue j\xE1 em /api-tokens se precisar.`,
+    data: { ok: true }
+  };
+}
+
 // src/index.ts
-var VERSION = "0.2.0";
+var VERSION = "0.5.0";
 var HELP = `nf \u2014 CLI do Nexus Flow
 
 Uso:
+  nf login                  autoriza no navegador e salva a credencial local (sem colar nada)
+  nf logout                 remove a credencial local
   nf start [<n\xBA|id>] [--slug <s>]
                             inicia uma feature atribu\xEDda: cria a branch e grava o slug
   nf status                 estado da feature da branch atual
@@ -1024,12 +1265,13 @@ Flags:
   -h, --help        esta ajuda
   -v, --version     vers\xE3o do CLI
 
-Ambiente:
-  H1VE_API_URL   URL do H1VE Flow (ex.: https://app.h1ve.org)
+Ambiente (opcional \u2014 'nf login' dispensa):
+  H1VE_API_URL   URL do H1VE Flow (default 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 };
+var COMMANDS = { start, status, spec, move, blocker, done, health, connect, serve, login, logout };
+var NO_CONFIG = /* @__PURE__ */ new Set(["serve", "login", "logout"]);
 async function readStdin() {
   if (process.stdin.isTTY) return "";
   const chunks = [];
@@ -1085,15 +1327,17 @@ async function main(argv) {
 ${HELP}`);
     return 1;
   }
-  const cfg = command === "serve" ? void 0 : readConfig();
+  const cfg = NO_CONFIG.has(command) ? void 0 : await resolveConfig();
+  const client = cfg ? await clientFromConfig(cfg) : {};
   const io = {
-    client: cfg ? clientFromConfig(cfg) : {},
+    client,
     resolveBranch: () => currentBranch(defaultGitRunner),
     createBranch: (name) => createBranch(name, defaultGitRunner),
     readFile: (path) => readFile(path, "utf8"),
     readStdin,
     writeEnvVars: (pairs, opts) => writeEnvVars(pairs, { file: opts?.file }),
-    removeEnvVars: (keys, opts) => removeEnvVars(keys, { file: opts?.file })
+    removeEnvVars: (keys, opts) => removeEnvVars(keys, { file: opts?.file }),
+    credentials: defaultCredentialStore
   };
   const args = {
     positional: positionals[1],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@h1veframework/cli",
-  "version": "0.2.0",
+  "version": "0.5.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",