@nodii/dev 0.0.0-stage → 0.3.1

package/README.md

@@ -1,3 +1,132 @@
-# Temporary Holding Version
+# `@nodii/dev`
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Install with `npm i -g @nodii/dev` (or `bun add -g @nodii/dev`), or run without
+installing using `bunx @nodii/dev --help`. The `nodii-dev` command runs on
+**Bun when it's installed** (about 40% faster start-up, which matters for the
+Figma hook that runs on every Figma call) and falls back to Node 20+. macOS and
+Linux only (the launcher is a POSIX shell script).
+
+## Authentication
+
+```sh
+nodii-dev login                      # opens the approval page in your browser
+nodii-dev login --no-browser         # prints the link and code instead
+nodii-dev login --scope devops.issues.read,devops.issues.write   # narrower grant
+nodii-dev agent register --name my-agent --service nodii-planning-hub
+
+# Temporary compatibility path:
+printf '%s' "$PLANNING_HUB_HMAC_SECRET" | nodii-dev login --person PERSON_ID --secret-stdin
+nodii-dev login --hmac --person PERSON_ID --from-aws
+```
+
+OAuth is the default: the CLI signs in as the platform tenant's nodii-dev app
+(`NODII_DEV_OAUTH_CLIENT_ID` or `--client-id` overrides the built-in public
+client id). With no `--scope`, auth grants the app's full ceiling: every live
+`devops.*` key except `devops.releases.promote`, which is never granted. Pass
+`--hmac` to keep the interim path. Login uses RFC 8628 and
+opens the verification page on an interactive terminal unless `--no-browser`
+is passed. Refresh tokens are stored only in macOS Keychain or Linux Secret
+Service (`secret-tool`); the CLI refuses plaintext fallback. Access tokens stay
+in memory. OAuth API calls use the platform edge `/devops` route and send the
+registered `x-agent-id`. `logout` revokes the refresh chain before erasing local
+credentials. `--auth-url`, `--edge-url`, and `--tenant-hint` select another real
+deployment.
+
+Every command accepts `--json`; without it, output is formatted for humans.
+Hub failures print the hub error code to stderr and exit non-zero.
+
+## Commands
+
+```text
+nodii-dev login [--no-browser]
+nodii-dev login --hmac --person ID (--secret-stdin | --from-aws)
+nodii-dev logout
+nodii-dev whoami
+nodii-dev config show
+
+nodii-dev api list [--tag TAG] [--json]
+nodii-dev api OPERATION_ID [--param name=value ...] [--body @file|-|JSON]
+
+nodii-dev agent register --name NAME [--service SERVICE] [--session ID]
+nodii-dev agent heartbeat
+nodii-dev agents spawn SERVICE [--repo-root DIR]
+nodii-dev agents cowork-tick [--json]
+nodii-dev agents cowork-tick --plist [--interval SECONDS]
+
+nodii-dev issues list [--service ID] [--project KEY] [--status STATUS]
+                       [--kind KIND] [--priority PRIORITY] [--claimed true|false]
+nodii-dev issues show ISSUE
+nodii-dev issues create --service ID --title TEXT [--body TEXT|--body-file FILE]
+                        [--kind KIND] [--priority PRIORITY] [--project KEY]
+nodii-dev issues update ISSUE [the same mutable fields]
+nodii-dev issues claim ISSUE [--ttl MINUTES]
+nodii-dev issues release ISSUE [--note TEXT]
+
+nodii-dev inbox list [--service ID] [--kind drift|request|question]
+nodii-dev inbox show drift|request|question ID
+
+nodii-dev drift file --service ID --severity local|consumer-visible|breaking
+                     --summary TEXT (--body TEXT|--body-file FILE)
+                     [--related-artifact-type TYPE --related-artifact-id ID]
+nodii-dev drift list|show|resolve|triage
+nodii-dev request file --from ID --to ID --kind KIND (--spec TEXT|--spec-file FILE)
+                       [--required-capability NAME]
+                       [--target-artifact-type TYPE --target-artifact-id ID]
+nodii-dev requests list|show|claim|answer|resolve|reject|file
+
+nodii-dev decisions list [--status STATUS] [--module NAME] [--tag TAG]
+nodii-dev decisions get D123
+nodii-dev decisions search WORDS
+nodii-dev decisions create|lock|supersede|amend
+
+nodii-dev open-questions list|show|answer
+nodii-dev feature-docs list|show|claim|release|status
+nodii-dev contracts grpc|rest|outbox|saga|table publish|status
+nodii-dev backlog list|show|add|move       # `backlogs` is also accepted
+nodii-dev libraries register-version LIBRARY_ID --version VERSION
+nodii-dev state diff
+nodii-dev heartbeat audit [SERVICE]
+
+nodii-dev design entries [--kind KIND] [--group GROUP] [--q TEXT]
+nodii-dev design entry KEY
+nodii-dev design guide PAGE_TYPE
+
+nodii-dev figma lock FILE_KEY --title TEXT
+nodii-dev figma check FILE_KEY
+nodii-dev figma log-write CHANGE_SET --tool TOOL --nodes NODE[,NODE]
+nodii-dev figma submit CHANGE_SET --file SUBMISSION.json
+nodii-dev figma apply CHANGE_SET --figma-version VERSION
+nodii-dev figma published CHANGE_SET --figma-version VERSION
+nodii-dev figma abandon CHANGE_SET
+nodii-dev figma release FILE_KEY
+
+nodii-dev hook claude-figma-pre       # reads Claude Code hook JSON on stdin
+nodii-dev hook claude-figma-post      # reads Claude Code hook JSON on stdin
+nodii-dev hook print-settings         # prints managed-settings JSON; writes nothing
+```
+
+Every first-class resource command accepts positional path identifiers and
+OpenAPI property names as kebab-case flags. For example:
+
+```sh
+nodii-dev feature-docs status UUID --status implemented --completion-pct 100
+nodii-dev requests resolve UUID --commit-sha abc1234 --resolution-md "shipped"
+nodii-dev open-questions answer UUID --decision-id D1420
+```
+
+The first-class resource families cover every live OpenAPI tag: services,
+feature docs, contracts (gRPC, REST, outbox, sagas, tables), libraries,
+workers, projects, slices, SQL lookups, issues, backlogs, builds, changes,
+deploy reports, runtime, people, agents, inbox/gates, design, runbooks,
+doctrine and exceptions, changelog, health verdicts, approval kinds,
+notification registry, skills, questions, decisions, drift, requests,
+pipelines, runners, routing, usage, audit, reconciliation, cron, composite
+surfaces, and service edges. `api list` is the authoritative discovery view;
+`api OPERATION_ID` makes every operation callable even without an alias.
+
+`figma check` exits `0` when allowed and `3` when denied. The pre-hook permits
+non-Figma tools and allowlisted Figma reads, but defaults to denying every
+Figma write if the file key is absent, the hub cannot be reached, or the lock
+is denied. It exits `2`, which makes Claude Code block the call. The post-hook
+best-effort logs the write and never blocks. Per D1433, Codex remains read-only
+for Figma; this package does not write to Figma itself.

package/bin/nodii-dev

@@ -0,0 +1,12 @@
+#!/bin/sh
+# nodii-dev launcher: run on Bun when it's installed (about 40% faster
+# start-up, which matters because the Figma hook runs on every Figma call),
+# otherwise on Node 20+.
+self="$0"
+while [ -L "$self" ]; do
+  link=$(readlink "$self")
+  case "$link" in /*) self="$link" ;; *) self="$(dirname "$self")/$link" ;; esac
+done
+entry="$(cd "$(dirname "$self")/.." && pwd)/dist/nodii-dev.js"
+if command -v bun >/dev/null 2>&1; then exec bun "$entry" "$@"; fi
+exec node "$entry" "$@"

package/dist/api.js

@@ -0,0 +1,151 @@
+import { readFile } from "node:fs/promises";
+import { stdin } from "node:process";
+import { CliError, encode, hubRawRequest, readConfig } from "./core.js";
+
+const methods = new Set(["get", "post", "put", "patch", "delete", "head", "options"]);
+export async function loadOpenApi(fetcher = fetch) {
+  const { hubUrl } = await readConfig();
+  const response = await fetcher(`${hubUrl.replace(/\/$/, "")}/openapi.json`, { headers: { accept: "application/json" } });
+  if (!response.ok) throw new CliError("OPENAPI_UNAVAILABLE", `Cannot load OpenAPI: HTTP ${response.status}`);
+  return response.json();
+}
+
+export function operationsFrom(spec) {
+  const out = [];
+  for (const [path, item] of Object.entries(spec.paths ?? {}))
+    for (const [method, operation] of Object.entries(item))
+      if (methods.has(method) && operation.operationId)
+        out.push({ operationId: operation.operationId, method: method.toUpperCase(), path, tags: operation.tags ?? [], operation });
+  return out.sort((a, b) => a.operationId.localeCompare(b.operationId));
+}
+
+export function parseParams(value) {
+  const values = value === undefined ? [] : Array.isArray(value) ? value : [value];
+  const result = {};
+  for (const entry of values) {
+    const at = String(entry).indexOf("=");
+    if (at < 1) throw new CliError("USAGE", `--param needs k=v, got: ${entry}`, 2);
+    const key = entry.slice(0, at), raw = entry.slice(at + 1);
+    result[key] = raw;
+  }
+  return result;
+}
+
+const coerce = (raw, schema = {}) => {
+  if (schema.type === "boolean") return raw === true || raw === "true";
+  if (schema.type === "integer" || schema.type === "number") return Number(raw);
+  if (schema.type === "array") return Array.isArray(raw) ? raw : String(raw).split(",").filter(Boolean);
+  if (schema.type === "object" || raw?.startsWith?.("{") || raw?.startsWith?.("[")) {
+    try { return JSON.parse(raw); } catch { return raw; }
+  }
+  return raw;
+};
+const camel = (s) => s.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+
+async function stdinText() { let text = ""; for await (const chunk of stdin) text += chunk; return text; }
+export async function readBody(bodyArg) {
+  if (bodyArg === undefined) return undefined;
+  const text = bodyArg === "-" ? await stdinText() : bodyArg.startsWith("@") ? await readFile(bodyArg.slice(1), "utf8") : bodyArg;
+  try { return { value: JSON.parse(text), text }; }
+  catch { throw new CliError("INVALID_BODY", "--body must contain valid JSON", 2); }
+}
+
+export function buildOperationRequest(entry, params = {}, bodyValue) {
+  let path = entry.path;
+  const query = new URLSearchParams();
+  const definitions = entry.operation.parameters ?? [];
+  for (const parameter of definitions) {
+    const raw = params[parameter.name];
+    if (parameter.in === "path") {
+      if (raw === undefined) throw new CliError("USAGE", `Missing --param ${parameter.name}=...`, 2);
+      path = path.replace(`{${parameter.name}}`, encode(raw));
+    } else if (parameter.in === "query" && raw !== undefined) {
+      for (const value of Array.isArray(raw) ? raw : [raw]) query.append(parameter.name, String(value));
+    }
+  }
+  const suffix = query.toString();
+  return { method: entry.method, path: `${path}${suffix ? `?${suffix}` : ""}`, body: bodyValue };
+}
+
+export function flagsToOperation(entry, positional, flags) {
+  const params = {};
+  let pos = 0;
+  for (const p of entry.operation.parameters ?? []) {
+    const flag = flags[p.name] ?? flags[p.name.replace(/[A-Z]/g, c => `-${c.toLowerCase()}`)];
+    if (p.in === "path") params[p.name] = flag ?? positional[pos++];
+    else if (flag !== undefined) params[p.name] = flag;
+  }
+  const schema = entry.operation.requestBody?.content?.["application/json"]?.schema;
+  const body = {};
+  for (const [name, property] of Object.entries(schema?.properties ?? {})) {
+    const raw = flags[name] ?? flags[name.replace(/[A-Z]/g, c => `-${c.toLowerCase()}`)];
+    if (raw !== undefined) body[name] = coerce(raw, property);
+  }
+  return { params, body: schema ? body : undefined, consumed: pos };
+}
+
+export async function callOperation(entry, params, body) {
+  const request = buildOperationRequest(entry, params, body);
+  return hubRawRequest(request.method, request.path, body === undefined ? undefined : JSON.stringify(body));
+}
+
+export const GROUPS = {
+  services: "Services", "feature-docs": "FeatureDocs", contracts: ["GrpcInterfaces", "RestInterfaces", "Outbox", "OutboxTopics", "Sagas", "Tables"],
+  sagas: "Sagas", "outbox-topics": ["Outbox", "OutboxTopics"], tables: "Tables", libraries: "Libraries", workers: "Workers",
+  projects: "Projects", issues: "Issues", backlog: "Backlogs", backlogs: "Backlogs", builds: "Delivery", changes: "Delivery", "deploy-reports": "Runtime",
+  runtime: "Runtime", people: "People", agents: "Agents", inbox: "Inbox", gate: "Inbox", design: "Design", runbooks: "Runbooks",
+  doctrine: ["Doctrine", "DoctrineExceptions"], rulebook: "Doctrine", changelog: "Changelog", "health-verdicts": "HealthVerdicts",
+  "approval-kinds": "ApprovalKinds", "notification-registry": "Notification registry", skills: "Skills", "open-questions": "OpenQuestions",
+  decisions: "Decisions", drift: "Drift", requests: "Requests", pipelines: "Pipelines", slices: "Slices", "sql-lookups": "SqlLookups",
+  runners: "Runners", routing: "Routing", usage: "Usage", audit: "AuditLog", reconciliation: "Reconciliation", cron: "Cron", health: "Health",
+  composite: "Composite", "service-edges": "ServiceEdges",
+};
+
+export const ALIASES = {
+  "requests:show": "getRequest", "requests:list": "listRequests", "requests:claim": "claimRequest", "requests:answer": "answerInboxItem",
+  "requests:resolve": "resolveRequest", "requests:reject": "rejectRequest", "requests:file": "fileRequest",
+  "drift:list": "listDrift", "drift:show": "getDrift", "drift:file": "fileDrift", "drift:resolve": "operatorResolveDrift", "drift:triage": "acceptDrift",
+  "decisions:get": "getDecision", "decisions:list": "listDecisions", "decisions:create": "createDecision", "decisions:lock": "lockDecision",
+  "decisions:supersede": "supersedeDecision", "decisions:amend": "createDecisionAmendment",
+  "open-questions:list": "listOpenQuestions", "open-questions:show": "getOpenQuestion", "open-questions:answer": "answerOpenQuestion",
+  "feature-docs:list": "listFeatureDocs", "feature-docs:show": "getFeatureDoc", "feature-docs:claim": "claimFeatureDoc",
+  "feature-docs:release": "releaseFeatureDocClaim", "feature-docs:status": "patchFeatureDocStatus",
+  "backlogs:list": "listBacklogs", "backlogs:show": "getBacklog", "backlogs:add": "addBacklogItem", "backlogs:move": "moveBacklogItem",
+  "backlog:list": "listBacklogs", "backlog:show": "getBacklog", "backlog:add": "addBacklogItem", "backlog:move": "moveBacklogItem",
+  "libraries:register-version": "registerLibraryVersion",
+  "services:list": "listServices", "services:show": "getService", "services:create": "createService", "services:update": "updateService",
+  "sagas:list": "listSagas", "sagas:show": "getSaga", "sagas:create": "createSaga", "sagas:update": "updateSaga",
+  "outbox-topics:list": "listOutboxTopics", "outbox-topics:show": "getOutboxTopic", "outbox-topics:create": "createOutboxTopic",
+  "tables:list": "listServiceTables", "tables:show": "getTable", "tables:create": "createTable", "tables:update": "updateTable",
+  "libraries:list": "listLibraries", "libraries:show": "getLibrary", "libraries:create": "createLibrary", "libraries:update": "updateLibrary",
+  "workers:list": "listWorkers", "workers:show": "getWorker", "workers:create": "createWorker", "workers:update": "updateWorker",
+  "projects:list": "listServiceProjects", "projects:show": "getProject", "projects:create": "createProject", "projects:update": "updateProject",
+  "builds:list": "listBuilds", "builds:show": "getBuild", "builds:report": "reportBuild",
+  "changes:list": "listChanges", "changes:show": "getChange", "changes:mark": "markChange",
+  "deploy-reports:report": "reportDeployment", "runtime:list": "listRuntimeInventory", "runtime:show": "getServiceRuntime",
+  "people:list": "listPeople", "people:show": "getPerson", "agents:list": "listAgents", "agents:show": "getAgent",
+  "gate:fleet": "getFleetGate", "gate:service": "getServiceGate", "gate:dry-run": "getGateDryRun",
+  "runbooks:list": "listRunbooks", "runbooks:show": "getRunbook", "runbooks:create": "registerRunbook", "runbooks:update": "updateRunbook",
+  "doctrine:list": "listDoctrine", "doctrine:show": "getDoctrine", "doctrine:create": "createDoctrine", "doctrine:revise": "reviseDoctrine",
+  "rulebook:list": "listDoctrine", "rulebook:show": "getDoctrine", "changelog:list": "listChangelog", "changelog:append": "appendChangelog",
+  "health-verdicts:list": "listHealthVerdicts", "health-verdicts:post": "postHealthVerdict",
+  "approval-kinds:list": "listApprovalKinds", "approval-kinds:show": "getApprovalKind", "approval-kinds:create": "createApprovalKind",
+  "notification-registry:list": "listNotificationEvents", "notification-registry:show": "getNotificationEvent", "notification-registry:propose": "proposeNotificationEvent",
+  "skills:list": "listSkills", "skills:show": "getSkillBySlug", "skills:create": "createSkill", "skills:revise": "reviseSkill",
+  "pipelines:list": "listPipelines", "pipelines:show": "getPipeline", "pipelines:create": "createPipeline",
+  "slices:list": "listServiceSlices", "slices:show": "getSlice", "slices:create": "createServiceSlice",
+  "sql-lookups:list": "listServiceSqlLookups", "sql-lookups:show": "getSqlLookup", "sql-lookups:create": "createSqlLookup",
+  "runners:list": "listRunners", "runners:register": "registerRunner", "routing:lookup": "routingLookup", "usage:show": "getUsageFanIn",
+  "audit:list": "listAuditLog", "health:show": "getHealth",
+  "composite:refresher": "getServiceRefresher", "composite:impact": "getImpact", "composite:search": "search",
+  "service-edges:list": "listServiceEdges", "service-edges:show": "getServiceEdgesForService",
+};
+
+export function findFirstClass(operations, group, action) {
+  const aliased = ALIASES[`${group}:${action}`];
+  if (aliased) return operations.find(x => x.operationId === aliased);
+  const tags = Array.isArray(GROUPS[group]) ? GROUPS[group] : [GROUPS[group]];
+  const candidates = operations.filter(x => x.tags.some(t => tags.includes(t)));
+  const normalized = action?.replace(/-([a-z])/g, (_, c) => c.toUpperCase()).toLowerCase();
+  return candidates.find(x => x.operationId.toLowerCase() === normalized || x.operationId.toLowerCase().endsWith(normalized));
+}

package/dist/core.js

@@ -0,0 +1,339 @@
+import { spawn } from "node:child_process";
+import { createHash, createHmac } from "node:crypto";
+import { chmod, mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { homedir, platform } from "node:os";
+import { dirname, join } from "node:path";
+
+export const VERSION = "0.3.1";
+export const DEFAULT_HUB_URL = "https://planning.dev.nucleus-cloud.in";
+export const OPERATOR_AGENT_ID = "00000000-0000-0000-0000-000000000001";
+export const configPath = () =>
+  process.env.NODII_DEV_CONFIG_PATH ??
+  join(homedir(), ".config/nodii-dev/config.json");
+export const secretPath = () =>
+  process.env.NODII_DEV_SECRET_PATH ??
+  join(dirname(configPath()), "hmac-secret");
+
+export function signRequest({
+  secret,
+  agentId,
+  method,
+  path,
+  body = "",
+  timestamp = Math.floor(Date.now() / 1000),
+}) {
+  const upper = method.toUpperCase();
+  const bodyHash = createHash("sha256").update(body).digest("hex");
+  const payload = `${timestamp}.${upper}.${new URL(path, "http://local").pathname}.${bodyHash}`;
+  return {
+    "x-agent-id": agentId,
+    "x-timestamp": String(timestamp),
+    "x-signature": createHmac("sha256", secret).update(payload).digest("hex"),
+  };
+}
+
+export function requestHash({ toService, kind, specMd, at = new Date() }) {
+  const minute = at.toISOString().slice(0, 16);
+  return createHash("sha256")
+    .update(`${toService}|${kind}|${specMd}|${minute}`)
+    .digest("hex")
+    .slice(0, 16);
+}
+
+export async function readConfig(required = true) {
+  try {
+    return JSON.parse(await readFile(configPath(), "utf8"));
+  } catch (error) {
+    if (!required && error?.code === "ENOENT") return null;
+    throw new CliError("NOT_LOGGED_IN", "Run `nodii-dev login` first.", 2);
+  }
+}
+
+export async function writeConfig(value) {
+  const file = configPath();
+  await mkdir(dirname(file), { recursive: true, mode: 0o700 });
+  await writeFile(file, `${JSON.stringify(value, null, 2)}\n`, { mode: 0o600 });
+  await chmod(file, 0o600);
+}
+
+function run(command, args, options = {}) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, args, {
+      ...options,
+      stdio: options.stdio ?? ["ignore", "pipe", "pipe"],
+    });
+    let stdout = "";
+    let stderr = "";
+    child.stdout?.on("data", (x) => {
+      stdout += x;
+    });
+    child.stderr?.on("data", (x) => {
+      stderr += x;
+    });
+    child.on("error", reject);
+    child.on("close", (code) =>
+      code === 0
+        ? resolve(stdout)
+        : reject(new Error(stderr.trim() || `${command} exited ${code}`)),
+    );
+  });
+}
+
+const keychainService = "dev.nodii.cli";
+export async function storeSecret(secret) {
+  if (
+    platform() === "darwin" &&
+    process.env.NODII_DEV_DISABLE_KEYCHAIN !== "1"
+  ) {
+    try {
+      await run("security", [
+        "add-generic-password",
+        "-U",
+        "-a",
+        "hmac",
+        "-s",
+        keychainService,
+        "-w",
+        secret,
+      ]);
+      await rm(secretPath(), { force: true });
+      return "keychain";
+    } catch {
+      /* fall through for minimal/non-interactive macOS images */
+    }
+  }
+  const file = secretPath();
+  await mkdir(dirname(file), { recursive: true, mode: 0o700 });
+  await writeFile(file, secret, { mode: 0o600 });
+  await chmod(file, 0o600);
+  return "file";
+}
+
+export async function loadSecret() {
+  if (process.env.PLANNING_HUB_HMAC_SECRET)
+    return process.env.PLANNING_HUB_HMAC_SECRET;
+  if (
+    platform() === "darwin" &&
+    process.env.NODII_DEV_DISABLE_KEYCHAIN !== "1"
+  ) {
+    try {
+      return (
+        await run("security", [
+          "find-generic-password",
+          "-a",
+          "hmac",
+          "-s",
+          keychainService,
+          "-w",
+        ])
+      ).trim();
+    } catch {
+      /* try fallback file */
+    }
+  }
+  try {
+    return (await readFile(secretPath(), "utf8")).trim();
+  } catch {
+    throw new CliError(
+      "SECRET_NOT_FOUND",
+      "No HMAC credential is stored; run `nodii-dev login`.",
+      2,
+    );
+  }
+}
+
+export async function deleteCredentials() {
+  if (
+    platform() === "darwin" &&
+    process.env.NODII_DEV_DISABLE_KEYCHAIN !== "1"
+  ) {
+    try {
+      await run("security", [
+        "delete-generic-password",
+        "-a",
+        "hmac",
+        "-s",
+        keychainService,
+      ]);
+    } catch {}
+  }
+  await Promise.all([
+    rm(configPath(), { force: true }),
+    rm(secretPath(), { force: true }),
+  ]);
+}
+
+export async function secretFromAws() {
+  const raw = await run("aws", [
+    "secretsmanager",
+    "get-secret-value",
+    "--secret-id",
+    "nodii/dev/app/planning_hub",
+    "--region",
+    "ap-south-1",
+    "--query",
+    "SecretString",
+    "--output",
+    "text",
+  ]);
+  const value = JSON.parse(raw);
+  if (!value.PLANNING_HUB_HMAC_SECRET)
+    throw new CliError(
+      "AWS_SECRET_KEY_MISSING",
+      "The AWS secret does not contain PLANNING_HUB_HMAC_SECRET.",
+    );
+  return value.PLANNING_HUB_HMAC_SECRET;
+}
+
+export class CliError extends Error {
+  constructor(code, message, exitCode, details) {
+    super(message);
+    this.code = code;
+    this.exitCode = exitCode;
+    this.details = details;
+  }
+}
+
+/** @typedef {{headers(input: {method:string, path:string, body:string}): Promise<Record<string,string>>}} AuthProvider */
+/** HMAC v1 provider. A nodii-auth OAuth provider can implement the same boundary. */
+export class HmacAuthProvider {
+  async headers({ method, path, body }) {
+    const config = await readConfig();
+    return signRequest({
+      secret: await loadSecret(),
+      agentId: config.agentId,
+      method,
+      path,
+      body,
+    });
+  }
+}
+
+let oauthAuthProvider;
+export async function authProvider(config) {
+  config ??= await readConfig();
+  if (config.authProvider === "oauth") {
+    const { OAuthAuthProvider } = await import("./oauth.js");
+    oauthAuthProvider ??= new OAuthAuthProvider();
+    return oauthAuthProvider;
+  }
+  return new HmacAuthProvider();
+}
+
+export function requestUrl(config, path) {
+  if (config.authProvider === "oauth")
+    return `${config.edgeUrl.replace(/\/$/, "")}/devops${path}`;
+  return `${config.hubUrl.replace(/\/$/, "")}${path}`;
+}
+
+export async function hubRequest(
+  method,
+  path,
+  body,
+  { auth } = {},
+) {
+  const config = await readConfig();
+  auth ??= await authProvider(config);
+  const text = body === undefined ? "" : JSON.stringify(body);
+  const headers = { accept: "application/json" };
+  if (body !== undefined) headers["content-type"] = "application/json";
+  if (config.authProvider === "oauth" || !["GET", "HEAD", "OPTIONS"].includes(method))
+    Object.assign(headers, await auth.headers({ method, path, body: text }));
+  let response;
+  try {
+    response = await fetch(requestUrl(config, path), {
+      method,
+      headers,
+      body: body === undefined ? undefined : text,
+    });
+  } catch (error) {
+    throw new CliError(
+      "HUB_UNREACHABLE",
+      `Cannot reach the hub: ${error.message}`,
+    );
+  }
+  const raw = await response.text();
+  let payload;
+  try {
+    payload = raw ? JSON.parse(raw) : {};
+  } catch {
+    payload = { message: raw };
+  }
+  if (!response.ok)
+    throw new CliError(
+      payload.code ?? `HTTP_${response.status}`,
+      payload.message ?? `Hub returned HTTP ${response.status}`,
+      1,
+      payload.details,
+    );
+  return payload;
+}
+
+export async function hubRawRequest(method, path, bodyText, contentType = "application/json") {
+  const config = await readConfig();
+  const auth = await authProvider(config);
+  const headers = { accept: "application/json" };
+  if (bodyText !== undefined) headers["content-type"] = contentType;
+  if (config.authProvider === "oauth" || !["GET", "HEAD", "OPTIONS"].includes(method))
+    Object.assign(headers, await auth.headers({ method, path, body: bodyText ?? "" }));
+  let response;
+  try {
+    response = await fetch(requestUrl(config, path), {
+      method,
+      headers,
+      body: bodyText === undefined ? undefined : bodyText,
+    });
+  } catch (error) {
+    throw new CliError("HUB_UNREACHABLE", `Cannot reach the hub: ${error.message}`);
+  }
+  const raw = await response.text();
+  let payload;
+  try { payload = raw ? JSON.parse(raw) : {}; } catch { payload = { message: raw }; }
+  if (!response.ok)
+    throw new CliError(payload.code ?? `HTTP_${response.status}`, payload.message ?? `Hub returned HTTP ${response.status}`, 1, payload.details);
+  return payload;
+}
+
+export const encode = (value) => encodeURIComponent(value);
+export function parseArgs(argv) {
+  const flags = {};
+  const args = [];
+  for (let i = 0; i < argv.length; i++) {
+    const token = argv[i];
+    if (!token.startsWith("--")) {
+      args.push(token);
+      continue;
+    }
+    const [key, inline] = token.slice(2).split("=", 2);
+    const value =
+      inline !== undefined
+        ? inline
+        : argv[i + 1] && !argv[i + 1].startsWith("--")
+          ? argv[++i]
+          : true;
+    flags[key] =
+      flags[key] === undefined
+        ? value
+        : Array.isArray(flags[key])
+          ? [...flags[key], value]
+          : [flags[key], value];
+  }
+  return { args, flags };
+}
+
+export function requireFlag(flags, name) {
+  const value = flags[name];
+  if (value === undefined || value === true || value === "")
+    throw new CliError("USAGE", `Missing --${name}`, 2);
+  return value;
+}
+
+export const query = (pairs) => {
+  const p = new URLSearchParams();
+  for (const [key, value] of Object.entries(pairs))
+    if (value !== undefined && value !== false)
+      for (const item of Array.isArray(value) ? value : [value])
+        p.append(key, String(item));
+  const value = p.toString();
+  return value ? `?${value}` : "";
+};