@h1veframework/cli 0.1.0

package/LICENSE

@@ -0,0 +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.

package/README.md

@@ -0,0 +1,87 @@
+# @h1veframework/cli — `nf`
+
+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.
+
+É 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).
+
+## Instalação
+
+```bash
+npm install -g @h1veframework/cli   # disponibiliza o comando `nf` globalmente
+```
+
+> Requer Node ≥ 18.18 e `git` no PATH.
+
+<details><summary>A partir do código-fonte (contribuidores)</summary>
+
+```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
+```
+</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
+```
+
+> 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.
+
+## 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`.
+
+### `nf done`
+
+Recebe a AI declaration como **JSON** — de um arquivo ou do stdin:
+
+```bash
+nf done --from ai-declaration.json
+nf done < ai-declaration.json
+```
+
+Formato do JSON (validado no servidor):
+
+```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.
+
+## Saída e exit codes
+
+- Sucesso → **stdout**, exit `0`.
+- Erro → **stderr** (mensagem amigável, sem stack), exit `≠ 0` (config faltando = `2`).
+
+Compõe bem em scripts/CI:
+
+```bash
+nf status --json | jq .stage
+```

package/dist/index.js

@@ -0,0 +1,1133 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { parseArgs } from "util";
+import { readFile } from "fs/promises";
+
+// ../core/src/client.ts
+var NexusApiError = class extends Error {
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+    this.name = "NexusApiError";
+  }
+  code;
+};
+function errorForStatus(status2) {
+  switch (status2) {
+    case 401:
+      return new NexusApiError("UNAUTHENTICATED", "NEXUS_FLOW_API_KEY ausente ou inv\xE1lida.");
+    case 403:
+      return new NexusApiError("FORBIDDEN", "Sem permiss\xE3o para ver esta feature.");
+    case 404:
+      return new NexusApiError("FEATURE_NOT_FOUND", "Nenhuma feature corresponde a esta branch.");
+    case 422:
+      return new NexusApiError("INVALID_INPUT", "Branch inv\xE1lida.");
+    default:
+      return new NexusApiError("API_ERROR", `Falha ao consultar o Nexus Flow (HTTP ${status2}).`);
+  }
+}
+function mapWriteError(status2, code) {
+  if (code === "SERVICE_CANNOT_WRITE") {
+    return new NexusApiError(
+      code,
+      "A chave de servi\xE7o \xE9 s\xF3-leitura. Use um PAT de usu\xE1rio (crie em /api-tokens)."
+    );
+  }
+  if (code === "INVALID_TRANSITION") {
+    return new NexusApiError(code, "Transi\xE7\xE3o de stage inv\xE1lida a partir do stage atual.");
+  }
+  if (code === "OWNER_REQUIRED") {
+    return new NexusApiError(
+      code,
+      "A feature precisa de um owner antes de iniciar. Pe\xE7a ao arquiteto para atribuir."
+    );
+  }
+  switch (status2) {
+    case 401:
+      return new NexusApiError("UNAUTHENTICATED", "NEXUS_FLOW_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:
+      return new NexusApiError("FEATURE_NOT_FOUND", "Feature n\xE3o encontrada.");
+    case 422:
+      return new NexusApiError(code ?? "INVALID_INPUT", "Entrada inv\xE1lida para esta a\xE7\xE3o.");
+    default:
+      return new NexusApiError("API_ERROR", `Falha ao escrever no Nexus Flow (HTTP ${status2}).`);
+  }
+}
+async function readErrorCode(res) {
+  try {
+    return (await res.json()).code;
+  } catch {
+    return void 0;
+  }
+}
+function rootUrl(baseUrl) {
+  return baseUrl.replace(/\/+$/, "");
+}
+function createClient(config) {
+  const doFetch = config.fetchImpl ?? fetch;
+  const authHeaders = { "x-api-key": config.apiKey, accept: "application/json" };
+  async function postAction(featureId, action, body) {
+    const url = `${rootUrl(config.baseUrl)}/api/features/${encodeURIComponent(featureId)}/${action}`;
+    const res = await doFetch(url, {
+      method: "POST",
+      headers: { ...authHeaders, "content-type": "application/json" },
+      body: JSON.stringify(body)
+    });
+    if (!res.ok) throw mapWriteError(res.status, await readErrorCode(res));
+    return await res.json();
+  }
+  return {
+    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);
+      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);
+      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);
+      return await res.json();
+    },
+    startFeature(featureId, slug) {
+      return postAction(featureId, "start", slug ? { slug } : {});
+    },
+    moveStage(featureId, toStage, note) {
+      return postAction(featureId, "move", { to_stage: toStage, note });
+    },
+    createBlocker(featureId, description) {
+      return postAction(featureId, "blockers", { description });
+    },
+    submitAiDeclaration(featureId, input) {
+      return postAction(featureId, "ai-declaration", input);
+    },
+    async listProjects() {
+      const url = `${rootUrl(config.baseUrl)}/api/projects`;
+      const res = await doFetch(url, { headers: authHeaders });
+      if (!res.ok) throw errorForStatus(res.status);
+      return await res.json();
+    },
+    async createConnection(projectId, input) {
+      const url = `${rootUrl(config.baseUrl)}/api/projects/${encodeURIComponent(projectId)}/connections`;
+      const res = await doFetch(url, {
+        method: "POST",
+        headers: { ...authHeaders, "content-type": "application/json" },
+        body: JSON.stringify(input)
+      });
+      if (!res.ok) throw mapWriteError(res.status, await readErrorCode(res));
+      return await res.json();
+    }
+  };
+}
+
+// ../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;
+}
+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/env.ts
+import { readFile as fsReadFile, writeFile as fsWriteFile } from "fs/promises";
+import { join } from "path";
+var defaultFs = {
+  readFile: (p) => fsReadFile(p, "utf8"),
+  writeFile: (p, c) => fsWriteFile(p, c, "utf8")
+};
+async function isGitIgnored(file, git) {
+  try {
+    await git(["check-ignore", "-q", file]);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function mergeEnv(existing, pairs) {
+  const remaining = new Set(Object.keys(pairs));
+  const body = existing.replace(/\n+$/, "");
+  const lines = body.length ? body.split("\n") : [];
+  const out = lines.map((line) => {
+    const key = line.match(/^([A-Za-z_][A-Za-z0-9_]*)=/)?.[1];
+    if (key !== void 0 && remaining.has(key)) {
+      remaining.delete(key);
+      return `${key}=${pairs[key]}`;
+    }
+    return line;
+  });
+  for (const k of Object.keys(pairs)) if (remaining.has(k)) out.push(`${k}=${pairs[k]}`);
+  return out.join("\n") + "\n";
+}
+function removeEnvKeys(existing, keys) {
+  const drop = new Set(keys);
+  const body = existing.replace(/\n+$/, "");
+  const lines = body.length ? body.split("\n") : [];
+  const out = lines.filter((line) => {
+    const key = line.match(/^([A-Za-z_][A-Za-z0-9_]*)=/)?.[1];
+    return key === void 0 || !drop.has(key);
+  });
+  return out.length ? out.join("\n") + "\n" : "";
+}
+async function removeEnvVars(keys, opts = {}) {
+  const file = opts.file ?? ".env.local";
+  const cwd = opts.cwd ?? process.cwd();
+  const git = opts.git ?? defaultGitRunner;
+  const fs = opts.fs ?? defaultFs;
+  if (keys.length === 0) throw new Error("NO_ENV_VARS");
+  if (!await isGitIgnored(file, git)) throw new Error("ENV_FILE_NOT_GITIGNORED");
+  const path = join(cwd, file);
+  let existing = "";
+  try {
+    existing = await fs.readFile(path);
+  } catch {
+    return { file, removed: [] };
+  }
+  const present = /* @__PURE__ */ new Set();
+  for (const line of existing.split("\n")) {
+    const key = line.match(/^([A-Za-z_][A-Za-z0-9_]*)=/)?.[1];
+    if (key !== void 0) present.add(key);
+  }
+  const removed = keys.filter((k) => present.has(k));
+  await fs.writeFile(path, removeEnvKeys(existing, keys));
+  return { file, removed };
+}
+async function writeEnvVars(pairs, opts = {}) {
+  const file = opts.file ?? ".env.local";
+  const cwd = opts.cwd ?? process.cwd();
+  const git = opts.git ?? defaultGitRunner;
+  const fs = opts.fs ?? defaultFs;
+  if (Object.keys(pairs).length === 0) throw new Error("NO_ENV_VARS");
+  if (!await isGitIgnored(file, git)) throw new Error("ENV_FILE_NOT_GITIGNORED");
+  const path = join(cwd, file);
+  let existing = "";
+  try {
+    existing = await fs.readFile(path);
+  } catch {
+    existing = "";
+  }
+  await fs.writeFile(path, mergeEnv(existing, pairs));
+  return { file, keys: Object.keys(pairs) };
+}
+
+// src/errors.ts
+var CliError = class extends Error {
+  constructor(message, exitCode = 1) {
+    super(message);
+    this.exitCode = exitCode;
+    this.name = "CliError";
+  }
+  exitCode;
+};
+
+// src/config.ts
+function readConfig(env = process.env) {
+  const baseUrl = env.NEXUS_FLOW_API_URL?.trim();
+  const apiKey = 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)",
+      2
+    );
+  }
+  return { baseUrl, apiKey };
+}
+function clientFromConfig(cfg) {
+  return createClient({ baseUrl: cfg.baseUrl, apiKey: cfg.apiKey });
+}
+
+// src/format.ts
+var STAGE_LABEL = {
+  backlog: "Backlog",
+  spec: "Spec",
+  dev: "Dev",
+  pr: "PR",
+  ci: "CI",
+  qa_data: "QA/Data",
+  architect: "Arquiteto",
+  main: "Main",
+  blocked: "Bloqueada"
+};
+function stageLabel(stage) {
+  return STAGE_LABEL[stage] ?? stage;
+}
+function formatStatus(d) {
+  const f = d.feature;
+  const lines = [
+    `${f.name}  [${f.priority}]`,
+    `Stage:        ${stageLabel(d.stage)}`,
+    `Dias ativos:  ${d.days_active}`,
+    `Branch:       ${f.branch_slug ?? "\u2014"}`
+  ];
+  if (f.github_pr_url) lines.push(`PR:           ${f.github_pr_url}`);
+  lines.push(`Sign-offs:    QA ${d.sign_offs.qa} \xB7 Data ${d.sign_offs.data}`);
+  if (d.active_blockers.length) {
+    lines.push(`Blockers ativos (${d.active_blockers.length}):`);
+    for (const b of d.active_blockers) lines.push(`  \u26A0 ${b.description}`);
+  } else {
+    lines.push("Blockers ativos: nenhum");
+  }
+  if (d.ai_declaration?.submitted) lines.push("AI declaration: enviada");
+  return lines.join("\n");
+}
+function formatSpec(d) {
+  if (!d.spec_content) return `${d.feature.name}: sem spec registrada.`;
+  return d.spec_content;
+}
+function formatMove(prevStage, r) {
+  return `\u2713 ${r.name}: ${stageLabel(prevStage)} \u2192 ${stageLabel(r.stage)}`;
+}
+function formatBlocker(r) {
+  return `\u2713 Blocker aberto: ${r.description}`;
+}
+function formatStartList(list) {
+  const header = "Features atribu\xEDdas a iniciar \u2014 escolha: nf start <n\xBA>";
+  const rows = list.map(
+    (f, i) => `  ${String(i + 1).padStart(2)}. ${f.name}  [${stageLabel(f.stage)}]`
+  );
+  return [header, ...rows].join("\n");
+}
+function formatStart(r) {
+  return [
+    `\u2713 Iniciada: ${r.feature.name}`,
+    `Branch:  ${r.branch_name}  (criada e ativa)`,
+    "Pr\xF3ximo: codar \u2192 'nf status' \u2192 'nf done' (move dev \u2192 pr)"
+  ].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";
+  const rows = snaps.slice(0, 8).map(
+    (s) => [
+      s.week.padEnd(9),
+      String(s.ci_pass_rate).padStart(4),
+      String(s.deployments).padStart(8),
+      String(s.open_bugs).padStart(5),
+      String(s.debt_items).padStart(7)
+    ].join(" ")
+  );
+  return [header, ...rows].join("\n");
+}
+function formatConnect(r) {
+  return [
+    `\u2713 Conectado "${r.label}" ao projeto ${r.project}.`,
+    `  ${r.keys.length} vari\xE1vel(is) escrita(s) em ${r.file}: ${r.keys.join(", ")}`,
+    `  A credencial ficou s\xF3 no seu ${r.file} (gitignored) \u2014 o servidor guarda apenas o invent\xE1rio.`
+  ].join("\n");
+}
+
+// src/commands/status.ts
+async function status(io) {
+  const branch = await io.resolveBranch();
+  const digest = await io.client.getContext(branch);
+  return { human: formatStatus(digest), data: digest };
+}
+
+// src/commands/spec.ts
+async function spec(io) {
+  const branch = await io.resolveBranch();
+  const digest = await io.client.getContext(branch);
+  return { human: formatSpec(digest), data: { spec_content: digest.spec_content } };
+}
+
+// src/commands/move.ts
+var STAGES = [
+  "backlog",
+  "spec",
+  "dev",
+  "pr",
+  "ci",
+  "qa_data",
+  "architect",
+  "main",
+  "blocked"
+];
+function isStage(s) {
+  return STAGES.includes(s);
+}
+async function move(io, args) {
+  const stage = args.positional;
+  if (!stage) throw new CliError("Uso: nf move <stage>");
+  if (!isStage(stage)) {
+    throw new CliError(`Stage inv\xE1lido: ${stage}. V\xE1lidos: ${STAGES.join(", ")}`);
+  }
+  const branch = await io.resolveBranch();
+  const digest = await io.client.getContext(branch);
+  const result = await io.client.moveStage(digest.feature.id, stage, args.note);
+  return { human: formatMove(digest.stage, result), data: result };
+}
+
+// src/commands/blocker.ts
+async function blocker(io, args) {
+  const description = args.positional;
+  if (!description) throw new CliError('Uso: nf blocker "<descri\xE7\xE3o>"');
+  const branch = await io.resolveBranch();
+  const digest = await io.client.getContext(branch);
+  const result = await io.client.createBlocker(digest.feature.id, description);
+  return { human: formatBlocker(result), data: result };
+}
+
+// src/commands/done.ts
+async function readDeclaration(io, from) {
+  const raw = from ? await io.readFile(from) : await io.readStdin();
+  if (!raw.trim()) {
+    throw new CliError("Forne\xE7a a AI declaration via --from <arquivo> ou pelo stdin.");
+  }
+  try {
+    return JSON.parse(raw);
+  } catch {
+    throw new CliError("JSON inv\xE1lido na AI declaration.");
+  }
+}
+async function done(io, args) {
+  const input = await readDeclaration(io, args.from);
+  const branch = await io.resolveBranch();
+  const digest = await io.client.getContext(branch);
+  const featureId = digest.feature.id;
+  const declaration = await io.client.submitAiDeclaration(featureId, input);
+  const sent = `\u2713 AI declaration enviada (${declaration.id}).`;
+  if (args.noMove) {
+    return { human: `${sent}
+Move pulado (--no-move).`, data: { declaration } };
+  }
+  try {
+    const moved = await io.client.moveStage(featureId, "pr");
+    const movedLine = `\u2713 ${moved.name}: ${stageLabel(digest.stage)} \u2192 ${stageLabel(moved.stage)}`;
+    return { human: `${sent}
+${movedLine}`, data: { declaration, move: moved } };
+  } catch (err) {
+    const reason = err instanceof Error ? err.message : "erro ao mover";
+    throw new CliError(
+      `${sent}
+\u2717 Move dev \u2192 pr falhou: ${reason}
+(a declaration J\xC1 foi enviada \u2014 rode \`nf move pr\` para concluir; N\xC3O repita \`nf done\`, pois enviaria a declaration de novo.)`
+    );
+  }
+}
+
+// src/commands/health.ts
+async function health(io) {
+  const snapshots = await io.client.listHealth();
+  return { human: formatHealth(snapshots), data: snapshots };
+}
+
+// src/commands/start.ts
+function startable(features) {
+  return features.filter((f) => f.branch_slug === null && f.stage !== "main");
+}
+function pick(list, arg) {
+  if (!arg) return list.length === 1 ? list[0] ?? null : null;
+  const byId = list.find((f) => f.id === arg);
+  if (byId) return byId;
+  const idx = Number(arg);
+  if (Number.isInteger(idx) && idx >= 1 && idx <= list.length) return list[idx - 1] ?? null;
+  throw new CliError(`Feature n\xE3o encontrada: ${arg}. Rode 'nf start' para ver a lista.`);
+}
+async function start(io, args) {
+  const list = startable(await io.client.listFeatures());
+  if (list.length === 0) {
+    throw new CliError("Nenhuma feature atribu\xEDda a iniciar (sem branch e fora de main).");
+  }
+  const selected = pick(list, args.positional);
+  if (!selected) {
+    return { human: formatStartList(list), data: { features: list } };
+  }
+  const result = await io.client.startFeature(selected.id, args.slug);
+  try {
+    await io.createBranch(result.branch_name);
+  } catch (err) {
+    const code = err instanceof Error ? err.message : "";
+    if (code === "BRANCH_EXISTS") {
+      throw new CliError(
+        `branch_slug gravado, mas a branch '${result.branch_name}' j\xE1 existe. Rode: git switch ${result.branch_name}`
+      );
+    }
+    throw err;
+  }
+  return { human: formatStart(result), data: result };
+}
+
+// src/commands/connect.ts
+var KINDS = ["database", "deploy", "observability", "api", "auth", "other"];
+function parseEnvPairs(env) {
+  const pairs = {};
+  for (const item of env ?? []) {
+    const eq = item.indexOf("=");
+    if (eq <= 0) throw new CliError(`--env inv\xE1lido: "${item}" (esperado KEY=valor)`);
+    const key = item.slice(0, eq);
+    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key)) throw new CliError(`Nome de env var inv\xE1lido: "${key}"`);
+    pairs[key] = item.slice(eq + 1);
+  }
+  return pairs;
+}
+function resolveProject(projects, arg) {
+  if (arg) {
+    const found = projects.find((p) => p.id === arg || p.name.toLowerCase() === arg.toLowerCase());
+    if (!found) throw new CliError(`Projeto "${arg}" n\xE3o encontrado. Dispon\xEDveis: ${projects.map((p) => p.name).join(", ") || "(nenhum)"}`);
+    return found;
+  }
+  const [only, ...rest] = projects;
+  if (!only) throw new CliError("Voc\xEA n\xE3o \xE9 membro de nenhum projeto.");
+  if (rest.length > 0) {
+    throw new CliError(`V\xE1rios projetos \u2014 informe --project <nome>. Op\xE7\xF5es: ${projects.map((p) => p.name).join(", ")}`);
+  }
+  return only;
+}
+async function connect(io, args) {
+  const kind = args.kind;
+  if (!kind || !KINDS.includes(kind)) throw new CliError(`--kind \xE9 obrigat\xF3rio (${KINDS.join(" | ")})`);
+  if (!args.label) throw new CliError("--label \xE9 obrigat\xF3rio");
+  const pairs = parseEnvPairs(args.env);
+  if (Object.keys(pairs).length === 0) throw new CliError("Informe ao menos um --env KEY=valor");
+  const project = resolveProject(await io.client.listProjects(), args.project);
+  let written;
+  try {
+    written = await io.writeEnvVars(pairs, { file: args.file });
+  } catch (e) {
+    const msg = e instanceof Error ? e.message : "";
+    if (msg === "ENV_FILE_NOT_GITIGNORED") {
+      throw new CliError(`${args.file ?? ".env.local"} n\xE3o est\xE1 no .gitignore \u2014 adicione-o antes (o segredo n\xE3o pode virar commit).`, 2);
+    }
+    throw new CliError("N\xE3o consegui escrever o arquivo .env local.");
+  }
+  const conn = await io.client.createConnection(project.id, {
+    kind,
+    label: args.label,
+    url: args.url,
+    notes: args.notes
+  });
+  return {
+    human: formatConnect({ project: project.name, file: written.file, keys: written.keys, label: args.label }),
+    data: { id: conn.id, project_id: project.id, file: written.file, keys: written.keys }
+  };
+}
+
+// src/commands/serve.ts
+import { createServer } from "http";
+import { randomBytes } from "crypto";
+
+// src/agent.ts
+import { timingSafeEqual } from "crypto";
+function tokenEq(got, expected) {
+  if (!got) return false;
+  const a = Buffer.from(got);
+  const b = Buffer.from(expected);
+  return a.length === b.length && timingSafeEqual(a, b);
+}
+var ENV_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
+function isLoopbackHost(host) {
+  const name = (host.split(":")[0] ?? "").toLowerCase();
+  return name === "127.0.0.1" || name === "localhost";
+}
+function isSafeFile(file) {
+  return typeof file === "string" && file.length > 0 && !/[/\\]/.test(file) && !file.includes("..") && !file.startsWith("~");
+}
+function normalizeConfig(v) {
+  if (v === void 0 || v === null) return {};
+  if (typeof v !== "object" || Array.isArray(v)) return null;
+  const entries = Object.entries(v);
+  if (entries.length > 20) return null;
+  const out = {};
+  for (const [k, val] of entries) {
+    if (typeof val !== "string" || val.length > 200) return null;
+    out[k] = val;
+  }
+  return out;
+}
+async function handleAgent(req, deps) {
+  if (req.origin !== null && req.origin !== deps.origin) return { status: 403, body: { error: "forbidden_origin" } };
+  if (req.host !== null && !isLoopbackHost(req.host)) return { status: 403, body: { error: "forbidden_host" } };
+  if (req.method === "OPTIONS") return { status: 204, body: null };
+  if (req.method === "GET" && req.path === "/health") return { status: 200, body: { ok: true, agent: "nexus-flow" } };
+  if (req.method === "POST" && req.path === "/apply") {
+    if (!tokenEq(req.token, deps.pairingToken)) return { status: 401, body: { error: "unpaired" } };
+    const b = req.body ?? null;
+    const env = b?.env;
+    if (!env || typeof env !== "object" || Array.isArray(env) || Object.keys(env).length === 0) {
+      return { status: 422, body: { error: "no_env" } };
+    }
+    for (const k of Object.keys(env)) if (!ENV_NAME.test(k)) return { status: 422, body: { error: "bad_env_name" } };
+    if (b?.file !== void 0 && !isSafeFile(b.file)) return { status: 422, body: { error: "bad_file" } };
+    try {
+      const res = await deps.writeEnv(env, { file: b?.file });
+      return { status: 200, body: { file: res.file, keys: res.keys } };
+    } catch (e) {
+      const msg = e instanceof Error ? e.message : "";
+      if (msg === "ENV_FILE_NOT_GITIGNORED") return { status: 409, body: { error: "not_gitignored" } };
+      return { status: 500, body: { error: "write_failed" } };
+    }
+  }
+  if (req.method === "POST" && req.path === "/remove") {
+    if (!tokenEq(req.token, deps.pairingToken)) return { status: 401, body: { error: "unpaired" } };
+    const b = req.body ?? null;
+    const keys = b?.keys;
+    if (!Array.isArray(keys) || keys.length === 0) return { status: 422, body: { error: "no_keys" } };
+    for (const k of keys) if (typeof k !== "string" || !ENV_NAME.test(k)) return { status: 422, body: { error: "bad_env_name" } };
+    if (b?.file !== void 0 && !isSafeFile(b.file)) return { status: 422, body: { error: "bad_file" } };
+    try {
+      const res = await deps.removeEnv(keys, { file: b?.file });
+      return { status: 200, body: { file: res.file, removed: res.removed } };
+    } catch (e) {
+      const msg = e instanceof Error ? e.message : "";
+      if (msg === "ENV_FILE_NOT_GITIGNORED") return { status: 409, body: { error: "not_gitignored" } };
+      return { status: 500, body: { error: "remove_failed" } };
+    }
+  }
+  if (req.method === "POST" && req.path === "/apply-deploy") {
+    if (!tokenEq(req.token, deps.pairingToken)) return { status: 401, body: { error: "unpaired" } };
+    const b = req.body ?? null;
+    if (!b || typeof b.provider !== "string" || !b.provider) return { status: 422, body: { error: "no_provider" } };
+    if (typeof b.token !== "string" || !b.token) return { status: 422, body: { error: "missing_credentials" } };
+    const config = normalizeConfig(b.config);
+    if (config === null) return { status: 422, body: { error: "bad_config" } };
+    const env = b.env;
+    if (!env || typeof env !== "object" || Array.isArray(env) || Object.keys(env).length === 0) {
+      return { status: 422, body: { error: "no_env" } };
+    }
+    for (const k of Object.keys(env)) if (!ENV_NAME.test(k)) return { status: 422, body: { error: "bad_env_name" } };
+    let result;
+    try {
+      result = await deps.deployApply(b.provider, { token: b.token, config, env });
+    } catch {
+      return { status: 502, body: { error: "deploy_failed" } };
+    }
+    if (result.ok) return { status: 200, body: { ok: true } };
+    const status2 = result.code === "unsupported_provider" ? 422 : 502;
+    return { status: status2, body: { error: result.code ?? "deploy_failed" } };
+  }
+  if (req.method === "POST" && req.path === "/remove-deploy") {
+    if (!tokenEq(req.token, deps.pairingToken)) return { status: 401, body: { error: "unpaired" } };
+    const b = req.body ?? null;
+    if (!b || typeof b.provider !== "string" || !b.provider) return { status: 422, body: { error: "no_provider" } };
+    if (typeof b.token !== "string" || !b.token) return { status: 422, body: { error: "missing_credentials" } };
+    const config = normalizeConfig(b.config);
+    if (config === null) return { status: 422, body: { error: "bad_config" } };
+    const keys = b.keys;
+    if (!Array.isArray(keys) || keys.length === 0) return { status: 422, body: { error: "no_keys" } };
+    for (const k of keys) if (typeof k !== "string" || !ENV_NAME.test(k)) return { status: 422, body: { error: "bad_env_name" } };
+    let result;
+    try {
+      result = await deps.deployRemove(b.provider, { token: b.token, config, keys });
+    } catch {
+      return { status: 502, body: { error: "deploy_failed" } };
+    }
+    if (result.ok) return { status: 200, body: { removed: result.removed ?? [], failed: result.failed ?? [] } };
+    const status2 = result.code === "unsupported_provider" ? 422 : 502;
+    return { status: status2, body: { error: result.code ?? "deploy_failed" } };
+  }
+  return { status: 404, body: { error: "not_found" } };
+}
+
+// src/vercel.ts
+var VERCEL_API = "https://api.vercel.com";
+var TIMEOUT_MS = 15e3;
+async function applyVercelEnv(input) {
+  const { project, team, target: cfgTarget } = input.config;
+  if (!project) return { ok: false, code: "missing_config" };
+  const target = cfgTarget ? [cfgTarget] : ["production"];
+  const body = Object.entries(input.env).map(([key, value]) => ({ key, value, type: "encrypted", target }));
+  const query = team ? `?upsert=true&teamId=${encodeURIComponent(team)}` : "?upsert=true";
+  const url = `${VERCEL_API}/v10/projects/${encodeURIComponent(project)}/env${query}`;
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), TIMEOUT_MS);
+  try {
+    const res = await fetch(url, {
+      method: "POST",
+      headers: { Authorization: `Bearer ${input.token}`, "content-type": "application/json" },
+      body: JSON.stringify(body),
+      signal: controller.signal
+    });
+    if (res.status === 401 || res.status === 403) return { ok: false, code: "unauthorized" };
+    if (res.status === 404) return { ok: false, code: "project_not_found" };
+    if (res.status >= 200 && res.status < 300) return { ok: true };
+    return { ok: false, code: "vercel_error" };
+  } catch {
+    return { ok: false, code: "request_failed" };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+function mapVercelError(status2) {
+  if (status2 === 401 || status2 === 403) return "unauthorized";
+  if (status2 === 404) return "project_not_found";
+  return "vercel_error";
+}
+var teamQuery = (teamId) => teamId ? `?teamId=${encodeURIComponent(teamId)}` : "";
+function matchesTarget(env, target) {
+  if (!target) return true;
+  const t = env.target;
+  return Array.isArray(t) ? t.includes(target) : t === target;
+}
+async function vercelReq(url, method, token) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), TIMEOUT_MS);
+  try {
+    return await fetch(url, { method, headers: { Authorization: `Bearer ${token}` }, signal: controller.signal });
+  } catch {
+    return null;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+async function removeVercelEnv(input) {
+  const { project, team, target } = input.config;
+  if (!project) return { ok: false, code: "missing_config" };
+  const base = `${VERCEL_API}/v9/projects/${encodeURIComponent(project)}/env`;
+  const listRes = await vercelReq(`${base}${teamQuery(team)}`, "GET", input.token);
+  if (!listRes) return { ok: false, code: "request_failed" };
+  if (!(listRes.status >= 200 && listRes.status < 300)) return { ok: false, code: mapVercelError(listRes.status) };
+  let envs;
+  try {
+    const data = await listRes.json();
+    envs = Array.isArray(data.envs) ? data.envs : [];
+  } catch {
+    return { ok: false, code: "vercel_error" };
+  }
+  const want = new Set(input.keys);
+  const matches = envs.filter((e) => want.has(e.key) && matchesTarget(e, target));
+  const removed = [];
+  const failed = [];
+  for (const e of matches) {
+    const del = await vercelReq(`${base}/${encodeURIComponent(e.id)}${teamQuery(team)}`, "DELETE", input.token);
+    (del && del.status >= 200 && del.status < 300 ? removed : failed).push(e.key);
+  }
+  return { ok: true, removed, failed };
+}
+
+// src/netlify.ts
+var NETLIFY_API = "https://api.netlify.com";
+var TIMEOUT_MS2 = 15e3;
+function mapNetlifyError(status2) {
+  if (status2 === 401 || status2 === 403) return "unauthorized";
+  if (status2 === 404) return "project_not_found";
+  return "netlify_error";
+}
+var siteQuery = (siteId) => siteId ? `?site_id=${encodeURIComponent(siteId)}` : "";
+async function netlifyReq(url, method, token, body) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), TIMEOUT_MS2);
+  try {
+    return await fetch(url, {
+      method,
+      headers: { Authorization: `Bearer ${token}`, ...body !== void 0 ? { "content-type": "application/json" } : {} },
+      body: body !== void 0 ? JSON.stringify(body) : void 0,
+      signal: controller.signal
+    });
+  } catch {
+    return null;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+async function applyNetlifyEnv(input) {
+  const { account_id, site_id } = input.config;
+  if (!account_id) return { ok: false, code: "missing_config" };
+  const base = `${NETLIFY_API}/api/v1/accounts/${encodeURIComponent(account_id)}/env`;
+  for (const [key, value] of Object.entries(input.env)) {
+    const url = `${base}/${encodeURIComponent(key)}${siteQuery(site_id)}`;
+    const res = await netlifyReq(url, "PATCH", input.token, { context: "all", value });
+    if (!res) return { ok: false, code: "request_failed" };
+    if (!(res.status >= 200 && res.status < 300)) return { ok: false, code: mapNetlifyError(res.status) };
+  }
+  return { ok: true };
+}
+async function removeNetlifyEnv(input) {
+  const { account_id, site_id } = input.config;
+  if (!account_id) return { ok: false, code: "missing_config" };
+  const base = `${NETLIFY_API}/api/v1/accounts/${encodeURIComponent(account_id)}/env`;
+  const removed = [];
+  const failed = [];
+  for (const key of input.keys) {
+    const res = await netlifyReq(`${base}/${encodeURIComponent(key)}${siteQuery(site_id)}`, "DELETE", input.token);
+    if (res && (res.status >= 200 && res.status < 300 || res.status === 404)) removed.push(key);
+    else failed.push(key);
+  }
+  return { ok: true, removed, failed };
+}
+
+// src/gql.ts
+var GQL_TIMEOUT_MS = 15e3;
+async function gqlRequest(url, token, query, variables, errPrefix) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), GQL_TIMEOUT_MS);
+  try {
+    const res = await fetch(url, {
+      method: "POST",
+      headers: { Authorization: `Bearer ${token}`, "content-type": "application/json" },
+      body: JSON.stringify({ query, variables }),
+      signal: controller.signal
+    });
+    if (res.status === 401 || res.status === 403) return { ok: false, code: "unauthorized" };
+    if (!(res.status >= 200 && res.status < 300)) return { ok: false, code: `${errPrefix}_error` };
+    const json = await res.json().catch(() => null);
+    if (!json || Array.isArray(json.errors) && json.errors.length > 0) return { ok: false, code: `${errPrefix}_error` };
+    return { ok: true, data: json.data };
+  } catch {
+    return { ok: false, code: "request_failed" };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+// src/fly.ts
+var FLY_API = "https://api.fly.io/graphql";
+var SET = "mutation($input: SetSecretsInput!) { setSecrets(input: $input) { release { id } } }";
+var UNSET = "mutation($input: UnsetSecretsInput!) { unsetSecrets(input: $input) { release { id } } }";
+async function applyFlyEnv(input) {
+  const { app } = input.config;
+  if (!app) return { ok: false, code: "missing_config" };
+  const secrets = Object.entries(input.env).map(([key, value]) => ({ key, value }));
+  const r = await gqlRequest(FLY_API, input.token, SET, { input: { appId: app, replaceAll: false, secrets } }, "fly");
+  return r.ok ? { ok: true } : { ok: false, code: r.code };
+}
+async function removeFlyEnv(input) {
+  const { app } = input.config;
+  if (!app) return { ok: false, code: "missing_config" };
+  const r = await gqlRequest(FLY_API, input.token, UNSET, { input: { appId: app, keys: input.keys } }, "fly");
+  if (!r.ok) return { ok: false, code: r.code };
+  return { ok: true, removed: input.keys, failed: [] };
+}
+
+// src/railway.ts
+var RAILWAY_API = "https://backboard.railway.com/graphql/v2";
+var UPSERT = "mutation($input: VariableCollectionUpsertInput!) { variableCollectionUpsert(input: $input) }";
+var DELETE = "mutation($input: VariableDeleteInput!) { variableDelete(input: $input) }";
+async function applyRailwayEnv(input) {
+  const { projectId, environmentId, serviceId } = input.config;
+  if (!projectId || !environmentId) return { ok: false, code: "missing_config" };
+  const inp = { projectId, environmentId, ...serviceId ? { serviceId } : {}, variables: input.env, replace: false };
+  const r = await gqlRequest(RAILWAY_API, input.token, UPSERT, { input: inp }, "railway");
+  return r.ok ? { ok: true } : { ok: false, code: r.code };
+}
+async function removeRailwayEnv(input) {
+  const { projectId, environmentId, serviceId } = input.config;
+  if (!projectId || !environmentId) return { ok: false, code: "missing_config" };
+  const removed = [];
+  const failed = [];
+  for (const name of input.keys) {
+    const inp = { projectId, environmentId, ...serviceId ? { serviceId } : {}, name };
+    const r = await gqlRequest(RAILWAY_API, input.token, DELETE, { input: inp }, "railway");
+    (r.ok ? removed : failed).push(name);
+  }
+  return { ok: true, removed, failed };
+}
+
+// src/render.ts
+var RENDER_API = "https://api.render.com";
+var TIMEOUT_MS3 = 15e3;
+function mapRenderError(status2) {
+  if (status2 === 401 || status2 === 403) return "unauthorized";
+  if (status2 === 404) return "project_not_found";
+  return "render_error";
+}
+async function renderReq(url, method, token, body) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), TIMEOUT_MS3);
+  try {
+    return await fetch(url, {
+      method,
+      headers: { Authorization: `Bearer ${token}`, ...body !== void 0 ? { "content-type": "application/json" } : {} },
+      body: body !== void 0 ? JSON.stringify(body) : void 0,
+      signal: controller.signal
+    });
+  } catch {
+    return null;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+async function applyRenderEnv(input) {
+  const { serviceId } = input.config;
+  if (!serviceId) return { ok: false, code: "missing_config" };
+  const base = `${RENDER_API}/v1/services/${encodeURIComponent(serviceId)}/env-vars`;
+  for (const [key, value] of Object.entries(input.env)) {
+    const res = await renderReq(`${base}/${encodeURIComponent(key)}`, "PUT", input.token, { value });
+    if (!res) return { ok: false, code: "request_failed" };
+    if (!(res.status >= 200 && res.status < 300)) return { ok: false, code: mapRenderError(res.status) };
+  }
+  return { ok: true };
+}
+async function removeRenderEnv(input) {
+  const { serviceId } = input.config;
+  if (!serviceId) return { ok: false, code: "missing_config" };
+  const base = `${RENDER_API}/v1/services/${encodeURIComponent(serviceId)}/env-vars`;
+  const removed = [];
+  const failed = [];
+  for (const key of input.keys) {
+    const res = await renderReq(`${base}/${encodeURIComponent(key)}`, "DELETE", input.token);
+    if (res && (res.status >= 200 && res.status < 300 || res.status === 404)) removed.push(key);
+    else failed.push(key);
+  }
+  return { ok: true, removed, failed };
+}
+
+// src/commands/serve.ts
+var DEFAULT_AGENT_PORT = 7391;
+var DEPLOY_REGISTRY = {
+  vercel: applyVercelEnv,
+  netlify: applyNetlifyEnv,
+  fly: applyFlyEnv,
+  railway: applyRailwayEnv,
+  render: applyRenderEnv
+};
+var DEPLOY_REMOVE_REGISTRY = {
+  vercel: removeVercelEnv,
+  netlify: removeNetlifyEnv,
+  fly: removeFlyEnv,
+  railway: removeRailwayEnv,
+  render: removeRenderEnv
+};
+async function deployApply(provider, input) {
+  const adapter = Object.hasOwn(DEPLOY_REGISTRY, provider) ? DEPLOY_REGISTRY[provider] : void 0;
+  if (!adapter) return { ok: false, code: "unsupported_provider" };
+  return adapter(input);
+}
+async function deployRemove(provider, input) {
+  const adapter = Object.hasOwn(DEPLOY_REMOVE_REGISTRY, provider) ? DEPLOY_REMOVE_REGISTRY[provider] : void 0;
+  if (!adapter) return { ok: false, code: "unsupported_provider" };
+  return adapter(input);
+}
+function corsHeaders(origin) {
+  return {
+    "Access-Control-Allow-Origin": origin,
+    "Access-Control-Allow-Methods": "GET, POST, OPTIONS",
+    "Access-Control-Allow-Headers": "content-type, x-pairing-token",
+    "content-type": "application/json"
+  };
+}
+var MAX_BODY = 64 * 1024;
+async function readJsonBody(req) {
+  const chunks = [];
+  let size = 0;
+  for await (const c of req) {
+    size += c.length;
+    if (size > MAX_BODY) {
+      req.destroy();
+      return null;
+    }
+    chunks.push(c);
+  }
+  if (!chunks.length) return null;
+  try {
+    return JSON.parse(Buffer.concat(chunks).toString("utf8"));
+  } catch {
+    return null;
+  }
+}
+async function serve(io, args) {
+  const port = Number(args.port ?? DEFAULT_AGENT_PORT);
+  const origin = args.origin ?? "http://localhost:3000";
+  const pairingToken = randomBytes(18).toString("base64url");
+  const deps = { pairingToken, origin, writeEnv: io.writeEnvVars, removeEnv: io.removeEnvVars, deployApply, deployRemove };
+  const server = createServer((req, res) => {
+    void (async () => {
+      const body = req.method === "POST" ? await readJsonBody(req) : null;
+      const result = await handleAgent(
+        {
+          method: req.method ?? "GET",
+          path: (req.url ?? "/").split("?")[0] ?? "/",
+          origin: req.headers.origin ?? null,
+          host: req.headers.host ?? null,
+          token: req.headers["x-pairing-token"] ?? null,
+          body
+        },
+        deps
+      );
+      res.writeHead(result.status, corsHeaders(origin));
+      res.end(result.body === null ? "" : JSON.stringify(result.body));
+    })().catch(() => {
+      res.writeHead(500, corsHeaders(origin));
+      res.end("{}");
+    });
+  });
+  await new Promise((resolve, reject) => {
+    server.on("error", reject);
+    server.listen(port, "127.0.0.1", resolve);
+  });
+  process.stdout.write(
+    `Agente H1VE ouvindo em http://127.0.0.1:${port}
+Origem permitida: ${origin}
+C\xF3digo de pareamento: ${pairingToken}
+Cole o c\xF3digo no painel /connections. Ctrl+C para parar.
+`
+  );
+  await new Promise(() => {
+  });
+  return { human: "", data: null };
+}
+
+// src/index.ts
+var VERSION = "0.1.0";
+var HELP = `nf \u2014 CLI do Nexus Flow
+
+Uso:
+  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
+  nf spec                   imprime a spec da feature
+  nf move <stage> [--note]  move a feature de stage
+  nf blocker "<desc>"       abre um blocker na feature
+  nf done [--from <arq>] [--no-move]
+                            envia a AI declaration (JSON) e move dev \u2192 pr
+  nf health                 \xFAltimos snapshots de sa\xFAde t\xE9cnica
+  nf connect --kind <k> --label <l> --env KEY=VAL [...]
+                            aplica a credencial no .env.local LOCAL (nunca ao servidor)
+                            e registra o invent\xE1rio da conex\xE3o (Jeito B)
+  nf serve [--port 7391] [--origin http://localhost:3000]
+                            sobe o agente local (127.0.0.1) p/ o menu visual aplicar
+                            credenciais pelo navegador \u2014 imprime o c\xF3digo de pareamento
+
+Flags:
+  --json            sa\xEDda em JSON cru (comp\xF5e em scripts)
+  --slug <s>        slug custom para 'nf 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)")
+  --env KEY=VAL     vari\xE1vel a escrever no .env.local (repet\xEDvel)
+  --project <p>     projeto (nome|id) \u2014 se voc\xEA \xE9 membro de mais de um
+  --url/--notes     metadado opcional da conex\xE3o
+  -h, --help        esta ajuda
+  -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)
+`;
+var COMMANDS = { start, status, spec, move, blocker, done, health, connect, serve };
+async function readStdin() {
+  if (process.stdin.isTTY) return "";
+  const chunks = [];
+  for await (const chunk of process.stdin) chunks.push(chunk);
+  return Buffer.concat(chunks).toString("utf8");
+}
+function parse(argv) {
+  try {
+    return parseArgs({
+      args: argv,
+      allowPositionals: true,
+      options: {
+        note: { type: "string" },
+        from: { type: "string" },
+        slug: { type: "string" },
+        "no-move": { type: "boolean" },
+        json: { type: "boolean" },
+        help: { type: "boolean", short: "h" },
+        version: { type: "boolean", short: "v" },
+        // nf connect (SPEC-050)
+        kind: { type: "string" },
+        label: { type: "string" },
+        url: { type: "string" },
+        notes: { type: "string" },
+        project: { type: "string" },
+        file: { type: "string" },
+        env: { type: "string", multiple: true },
+        // nf serve (SPEC-051)
+        port: { type: "string" },
+        origin: { type: "string" }
+      }
+    });
+  } catch {
+    throw new CliError("Argumentos inv\xE1lidos. Veja `nf --help`.", 2);
+  }
+}
+async function main(argv) {
+  const { values, positionals } = parse(argv);
+  if (values.version) {
+    process.stdout.write(`${VERSION}
+`);
+    return 0;
+  }
+  const command = positionals[0];
+  if (values.help || !command) {
+    process.stdout.write(HELP);
+    return command || values.help ? 0 : 1;
+  }
+  const run = COMMANDS[command];
+  if (!run) {
+    process.stderr.write(`Comando desconhecido: ${command}
+
+${HELP}`);
+    return 1;
+  }
+  const cfg = command === "serve" ? void 0 : readConfig();
+  const io = {
+    client: cfg ? clientFromConfig(cfg) : {},
+    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 })
+  };
+  const args = {
+    positional: positionals[1],
+    note: values.note,
+    from: values.from,
+    slug: values.slug,
+    noMove: values["no-move"] === true,
+    kind: values.kind,
+    label: values.label,
+    url: values.url,
+    notes: values.notes,
+    project: values.project,
+    file: values.file,
+    env: values.env,
+    port: values.port,
+    origin: values.origin
+  };
+  const result = await run(io, args);
+  process.stdout.write((values.json ? JSON.stringify(result.data, null, 2) : result.human) + "\n");
+  return 0;
+}
+function messageFor(err) {
+  if (err instanceof CliError || err instanceof NexusApiError) return err.message;
+  if (err instanceof Error && err.message === "NOT_A_GIT_BRANCH") {
+    return "N\xE3o estou numa branch git. Rode dentro do reposit\xF3rio da feature.";
+  }
+  if (err instanceof Error && (err.message === "NOT_A_GIT_REPO" || err.message === "GIT_BRANCH_FAILED")) {
+    return "N\xE3o consegui criar a branch git. Rode dentro do reposit\xF3rio (git) da feature.";
+  }
+  return "Erro inesperado ao falar com o Nexus Flow.";
+}
+main(process.argv.slice(2)).then((code) => {
+  process.exitCode = code;
+}).catch((err) => {
+  process.stderr.write(`${messageFor(err)}
+`);
+  process.exitCode = err instanceof CliError ? err.exitCode : 1;
+});

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@h1veframework/cli",
+  "version": "0.1.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",
+  "bin": {
+    "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://github.com/GusHartz/nexus-flow/tree/main/packages/cli#readme",
+  "bugs": {
+    "url": "https://github.com/GusHartz/nexus-flow/issues"
+  },
+  "keywords": [
+    "h1ve",
+    "h1ve-flow",
+    "cli",
+    "nf",
+    "dev-workflow",
+    "governance"
+  ],
+  "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"
+  }
+}