@nodii/dev 0.4.1 → 0.6.1

package/dist/cli.js

@@ -0,0 +1,607 @@
+import { readFile } from "node:fs/promises";
+import { stdin, stdout } from "node:process";
+import {
+  CliError,
+  VERSION,
+  deleteCredentials,
+  devRawRequest,
+  devRequest,
+  encode,
+  parseArgs,
+  query,
+  readConfig,
+  requestHash,
+  requireFlag,
+  writeConfig,
+} from "./core.js";
+import {
+  DEFAULT_AUTH_URL,
+  DEFAULT_CLIENT_ID,
+  DEFAULT_EDGE_URL,
+  PLATFORM_TENANT,
+  deviceLogin,
+  revokeOAuth,
+} from "./oauth.js";
+import { heartbeatCurrentLane, postHook, preHook, settingsSnippet, workflowSuggestion } from "./hooks.js";
+import { setupCommand } from "./setup.js";
+import { harnessCommand } from "./harness.js";
+import { docsCommand, rulebookCommand } from "./upload.js";
+import {
+  ALIASES,
+  GROUPS,
+  buildOperationRequest,
+  callOperation,
+  findFirstClass,
+  flagsToOperation,
+  loadOpenApi,
+  operationsFrom,
+  parseParams,
+  readBody,
+} from "./api.js";
+import {
+  agentWorkflowCommand,
+  builtCommand,
+  laneCommand,
+  machineCommand,
+  nextCommand,
+  peopleCommand,
+} from "./lanes.js";
+
+const HELP = `nodii-dev ${VERSION}
+
+Usage: nodii-dev <command> [options] [--json]
+
+  login | logout | whoami | config show
+  agent register --name NAME | agent heartbeat
+  issues list|show|create|update|claim|release
+  inbox list|show
+  drift file | request file
+  decisions list|get|search
+  design entries|entry|guide
+  figma lock|check|log-write|submit|apply|published|abandon|release
+  hook claude-figma-pre|claude-figma-post|print-settings
+  setup [--yes|--check]                 # dry-run by default
+  harness install|update [--include-drafts[=false]] [--adopt PATH,...] [--dry-run]
+  harness update --check                # exit 1 when Dev would write anything different
+  docs check|validate|upload <path...> --class ruling|conformance|editorial
+       [--base CODE=VERSION] [--decision FILE] [--conformance-ref REF]
+       [--meaning-unchanged REASON] [--wait]
+  docs ratify --domain KEY [--domain KEY ...] --decision FILE [--wait]
+  docs parked [CODE] [--status pending|acknowledged]
+  rulebook list|show CODE [--version V]|diff CODE
+
+  lane start <key> --title TEXT --kind KIND --side SIDE [--repo REPO] [--issue ISSUE]
+  lane step <key> --side SIDE --start|--done|--block <step>
+  lane evidence <key> --pr|--commit|--figma|--deploy|--dev-check REF
+  lane heartbeat|review|land|verify|prioritize|deprioritize|stop <key>
+  lane list [--kind KIND] [--status STATUS] [--mine] [--cursor CURSOR]
+  lane show <key> | next <key>
+  built list | built ack <key...>
+  machine list|show|set-coordinator|assign|report
+  agent lane-limit|grant|revoke
+  people reveal <id> --reason TEXT | people refresh-names
+
+  api list [--tag TAG]
+  api <operationId> [--param k=v] [--body @file|-|JSON]
+  <resource> <action> [ID ...] [--field VALUE]
+
+Resource commands cover every OpenAPI tag, including services, feature-docs,
+contracts, sagas, outbox-topics, tables, libraries, workers, projects, issues,
+backlogs, builds, changes, deploy-reports, runtime, people, agents, inbox,
+gate, design, runbooks, doctrine, changelog, health-verdicts, approval-kinds,
+notification-registry, skills, open-questions, decisions, drift, requests,
+rulebook, ad-decisions, domains, standardizations, archive, and harness.
+
+Run a command with --help or see the package README for all flags.`;
+
+// Verbs of the local-stack CLI, which shared this name until it became
+// ./nodii-stack (operator G3-6, no alias). Named here only to point there.
+const STACK_VERBS = new Set(["up", "down", "doctor", "sync", "seed", "wipe", "reset", "rebuild", "restart", "smoke", "urls", "peek", "trace", "stats", "bootstrap", "provenance", "stale", "status", "logs", "world", "totp", "token", "bench"]);
+
+async function stdinText() {
+  let value = "";
+  for await (const chunk of stdin) value += chunk;
+  return value;
+}
+const bodyFlag = async (f, name = "body") =>
+  f[`${name}-file`] ? readFile(f[`${name}-file`], "utf8") : f[name];
+function emit(payload, json, human) {
+  if (json) console.log(JSON.stringify(payload));
+  else
+    console.log(
+      typeof human === "function"
+        ? human(payload)
+        : (human ?? JSON.stringify(payload.data ?? payload, null, 2)),
+    );
+}
+const qsFlags = (f, mapping) =>
+  Object.fromEntries(
+    Object.entries(mapping).map(([to, from]) => [to, f[from]]),
+  );
+
+// Flags of the shared-secret login removed in 0.5.0.
+const REMOVED_LOGIN_FLAGS = ["hmac", "person", "secret-stdin", "from-aws", "hub-url", "agent-id"];
+
+async function login(flags, json) {
+  const removed = REMOVED_LOGIN_FLAGS.filter((name) => flags[name] !== undefined);
+  if (removed.length)
+    throw new CliError(
+      "USAGE",
+      `${removed.map((x) => `--${x}`).join(", ")}: shared-secret login was removed in 0.5.0. ` +
+        "nodii-dev talks only to Dev, through the platform edge, signed in as the platform tenant's OAuth app. Run `nodii-dev login`.",
+      2,
+    );
+  const previous = await readConfig(false);
+  const result = await deviceLogin({
+    clientId: flags["client-id"] ?? process.env.NODII_DEV_OAUTH_CLIENT_ID ?? previous?.clientId ?? DEFAULT_CLIENT_ID,
+    authUrl: flags["auth-url"] ?? process.env.NODII_DEV_AUTH_URL ?? DEFAULT_AUTH_URL,
+    edgeUrl: flags["edge-url"] ?? process.env.NODII_DEV_EDGE_URL ?? DEFAULT_EDGE_URL,
+    tenantHint: flags["tenant-hint"] ?? process.env.NODII_DEV_PLATFORM_TENANT_ID ?? PLATFORM_TENANT,
+    noBrowser: Boolean(flags["no-browser"]),
+    scope: flags.scope,
+    output: json ? console.error : console.log,
+  });
+  return emit({ loggedIn: true, provider: "oauth", credentialStorage: result.storage }, json,
+    `OAuth login complete; refresh credential stored in ${result.storage}. Run \`nodii-dev agent register --name NAME\` next.`);
+}
+
+async function issues(action, args, f, json) {
+  if (action === "list") {
+    const payload = await devRequest(
+      "GET",
+      `/api/v1/issues${query(qsFlags(f, { serviceId: "service", project: "project", status: "status", kind: "kind", priority: "priority", claimed: "claimed", limit: "limit", cursor: "cursor" }))}`,
+    );
+    return emit(
+      payload,
+      json,
+      (p) =>
+        p.data
+          .map((x) => `${x.key}\t${x.status}\t${x.priority}\t${x.title}`)
+          .join("\n") || "No issues.",
+    );
+  }
+  const ref = args[0];
+  if (!ref && action !== "create")
+    throw new CliError("USAGE", `${action} needs an issue key or id`, 2);
+  if (action === "show")
+    return emit(await devRequest("GET", `/api/v1/issues/${encode(ref)}`), json);
+  const config = await readConfig();
+  if (action === "create" || action === "update") {
+    const bodyMd = await bodyFlag(f);
+    const payload = {
+      ...(action === "create"
+        ? {
+            serviceId: requireFlag(f, "service"),
+            title: requireFlag(f, "title"),
+          }
+        : {}),
+      ...Object.fromEntries(
+        [
+          ["title", f.title],
+          ["kind", f.kind],
+          ["priority", f.priority],
+          ["project", f.project],
+          ["bodyMd", bodyMd],
+          ["onBehalfOf", config.person],
+        ].filter(([, v]) => v !== undefined),
+      ),
+    };
+    const result = await devRequest(
+      action === "create" ? "POST" : "PATCH",
+      action === "create" ? "/api/v1/issues" : `/api/v1/issues/${encode(ref)}`,
+      payload,
+    );
+    return emit(
+      result,
+      json,
+      (p) => `${p.data.key} ${p.data.status} — ${p.data.title}`,
+    );
+  }
+  if (action === "claim")
+    return emit(
+      await devRequest("POST", `/api/v1/issues/${encode(ref)}/claim`, {
+        onBehalfOf: config.person,
+        ...(f.ttl ? { ttlMinutes: Number(f.ttl) } : {}),
+      }),
+      json,
+    );
+  if (action === "release")
+    return emit(
+      await devRequest("POST", `/api/v1/issues/${encode(ref)}/release`, {
+        onBehalfOf: config.person,
+        ...(f.note ? { note: f.note } : {}),
+      }),
+      json,
+    );
+  throw new CliError("USAGE", `Unknown issues action: ${action}`, 2);
+}
+
+export async function main(argv = process.argv.slice(2)) {
+  if (argv.length === 1 && ["--version", "-v"].includes(argv[0]))
+    return console.log(VERSION);
+  if (argv.length === 1 && ["--help", "-h"].includes(argv[0]))
+    return console.log(HELP);
+  const { args, flags: f } = parseArgs(argv);
+  const json = Boolean(f.json);
+  const [command, action, ...rest] = args;
+  if (!command || f.help || command === "help") return console.log(HELP);
+  if (command === "api") {
+    const operations = operationsFrom(await loadOpenApi());
+    if (action === "list") {
+      const selected = f.tag === undefined || f.tag === true
+        ? operations
+        : operations.filter((x) => x.tags.some((t) => t.toLowerCase() === String(f.tag).toLowerCase()));
+      return emit(selected.map(({ operationId, method, path, tags }) => ({ operationId, method, path, tags })), json,
+        (rows) => rows.map((x) => `${x.operationId}\t${x.method}\t${x.path}\t${x.tags.join(",")}`).join("\n"));
+    }
+    if (!action) throw new CliError("USAGE", "api needs an operationId or list", 2);
+    const entry = operations.find((x) => x.operationId === action);
+    if (!entry) throw new CliError("UNKNOWN_OPERATION", `No OpenAPI operationId: ${action}`, 2);
+    const parsed = await readBody(f.body);
+    const request = buildOperationRequest(entry, parseParams(f.param), parsed?.value);
+    return emit(await devRawRequest(request.method, request.path, parsed?.text), json);
+  }
+  if (command === "login") return login(f, json);
+  if (command === "logout") {
+    const c = await readConfig(false);
+    if (c) {
+      try { await revokeOAuth(c); } finally { await deleteCredentials(); }
+    } else await deleteCredentials();
+    return emit({ loggedOut: true }, json, "Logged out.");
+  }
+  if (command === "config" && action === "show") {
+    const c = await readConfig();
+    return emit({ provider: "oauth", authUrl: c.authUrl, edgeUrl: c.edgeUrl, clientId: c.clientId, tenantHint: c.tenantHint, agentId: c.agentId }, json,
+      `${c.edgeUrl}/devops\nprovider: oauth\napp: ${c.clientId}\nagent: ${c.agentId ?? "not registered"}`);
+  }
+  if (command === "whoami") {
+    // Dev has no whoami route at the edge: the identity is the OAuth login
+    // itself, plus the registered agent read back from Dev.
+    const c = await readConfig();
+    const agent = c.agentId ? (await devRequest("GET", `/api/v1/agents/${encode(c.agentId)}`)).data : null;
+    return emit({ data: { person: c.person, app: c.clientId, installation: c.installationId, edge: c.edgeUrl, agent } }, json);
+  }
+  const emitCommand = async (result) => emit(result.payload, json, result.human);
+  if (command === "setup") return emitCommand(await setupCommand(f));
+  if (command === "harness" && ["install", "update"].includes(action)) {
+    // `--include-drafts` is a switch: `--include-drafts false` would leave `false` here and turn drafts on.
+    if (rest.length) throw new CliError("USAGE", `harness ${action} takes no arguments, got: ${rest.join(" ")}. Write a flag value as --include-drafts=false.`, 2);
+    return emitCommand(await harnessCommand(action, f));
+  }
+  if (command === "docs") return emitCommand(await docsCommand(action, rest, f));
+  if (command === "rulebook" && ["list", "show", "diff"].includes(action)) return emitCommand(await rulebookCommand(action, rest, f));
+  if (command === "lane") return emitCommand(await laneCommand(action, rest, f));
+  if (command === "next") return emitCommand(await nextCommand(action, f));
+  if (command === "built") return emitCommand(await builtCommand(action, rest, f));
+  if (command === "machine") return emitCommand(await machineCommand(action, rest, f));
+  if (command === "people" && ["reveal", "refresh-names"].includes(action))
+    return emitCommand(await peopleCommand(action, rest, f));
+  if (command === "state" && action === "diff") {
+    const [health, services, decisions, docs, requests, drift] = await Promise.all([
+      devRequest("GET", "/api/v1/health"), devRequest("GET", "/api/v1/services"),
+      devRequest("GET", "/api/v1/decisions"), devRequest("GET", "/api/v1/feature-docs"),
+      devRequest("GET", "/api/v1/requests"), devRequest("GET", "/api/v1/drift"),
+    ]);
+    const count = (x) => Array.isArray(x.data) ? x.data.length : undefined;
+    return emit({ data: { health: health.data ?? health, counts: { services: count(services), decisions: count(decisions), featureDocs: count(docs), requests: count(requests), drift: count(drift) } } }, json);
+  }
+  if (command === "heartbeat" && action === "audit") {
+    const ids = rest[0] ? [rest[0]] : (await devRequest("GET", "/api/v1/services?limit=1000")).data.map((x) => x.id);
+    const rows = await Promise.all(ids.map(async (id) => ({ serviceId: id, ...(await devRequest("GET", `/api/v1/services/${encode(id)}/unblock-surface`)).data })));
+    const failed = rows.some((x) => (x.openDriftCount ?? 0) > 0 || (x.openInboxRequestCount ?? 0) > 0);
+    emit({ data: rows, clean: !failed }, json, (p) => p.data.map((x) => `${x.serviceId}\t${(x.openDriftCount ?? 0) || (x.openInboxRequestCount ?? 0) ? "ATTENTION" : "PASS"}\tdrift=${x.openDriftCount ?? 0}\tinbox=${x.openInboxRequestCount ?? 0}`).join("\n"));
+    if (failed) process.exitCode = 1;
+    return;
+  }
+  if (command === "agents" && action === "spawn") {
+    const serviceId = rest[0] ?? requireFlag(f, "service");
+    const docs = await devRequest("GET", `/api/v1/feature-docs${query({ serviceId, status: "approved", limit: 200 })}`);
+    if (!docs.data?.length) throw new CliError("NO_APPROVED_WORK", `No approved feature docs for ${serviceId}`, 1);
+    const repo = `${f["repo-root"] ?? `${process.env.HOME}/Projects`}/${serviceId}`;
+    return emit({ data: { serviceId, repo, approvedFeatureDocs: docs.data.length, next: `cd ${repo} && nodii-dev agent register --name <name>` } }, json);
+  }
+  if (command === "agents" && action === "cowork-tick") {
+    if (f.plist) {
+      const interval = Number(f.interval ?? 1800);
+      return console.log(`<?xml version="1.0" encoding="UTF-8"?>\n<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">\n<plist version="1.0"><dict><key>Label</key><string>com.nodii.cowork</string><key>ProgramArguments</key><array><string>nodii-dev</string><string>agents</string><string>cowork-tick</string></array><key>StartInterval</key><integer>${interval}</integer><key>RunAtLoad</key><true/></dict></plist>`);
+    }
+    const docs = await devRequest("GET", "/api/v1/feature-docs?status=implementing&limit=1000");
+    const claims = docs.data.filter((x) => x.claimedByAgentId && (!x.claimExpiresAt || Date.parse(x.claimExpiresAt) > Date.now()));
+    return emit({ data: claims, dryRun: true, note: "Wakeup execution is workstation-local and has no Dev endpoint; this tick reports eligible claims without invoking an external agent runtime." }, json,
+      (p) => p.data.map((x) => `${x.serviceId}/${x.docKey}\t${x.claimedByAgentId}`).join("\n") || "No active claims.");
+  }
+  if (command === "agent") {
+    if (["lane-limit", "grant", "revoke"].includes(action))
+      return emitCommand(await agentWorkflowCommand(action, rest, f));
+    const c = await readConfig();
+    if (action === "register") {
+      // POST /api/v1/agents is the registration route the edge exposes; Dev
+      // binds the agent to the OAuth person, app and installation itself.
+      const result = await devRequest("POST", "/api/v1/agents", {
+        sessionId: f.session ?? crypto.randomUUID(),
+        name: requireFlag(f, "name"),
+      });
+      await writeConfig({ ...c, agentId: result.data.id });
+      // Dev ignores a self-claimed service: staff bind agents to services
+      // on the Dev Agents page (devops.agents.bind).
+      if (f.service)
+        process.stderr.write(
+          "--service is ignored: staff bind agents to a service on the Dev Agents page.\n",
+        );
+      await devRequest(
+        "POST",
+        `/api/v1/agents/${encode(result.data.id)}/heartbeat`,
+        {},
+      );
+      return emit(
+        result,
+        json,
+        `Registered ${result.data.name}: ${result.data.id}`,
+      );
+    }
+    if (action === "heartbeat")
+      return emit(
+        await devRequest(
+          "POST",
+          `/api/v1/agents/${encode(c.agentId)}/heartbeat`,
+          {},
+        ),
+        json,
+        "Heartbeat recorded.",
+      );
+  }
+  if (command === "issues") return issues(action, rest, f, json);
+  if (command === "inbox") {
+    if (action === "list")
+      return emit(
+        await devRequest(
+          "GET",
+          `/api/v1/inbox${query({ serviceId: f.service, kind: f.kind, limit: f.limit, cursor: f.cursor })}`,
+        ),
+        json,
+      );
+    if (action === "show") {
+      const [kind, id] = rest;
+      if (!kind || !id)
+        throw new CliError(
+          "USAGE",
+          "inbox show needs <drift|request|question> <id>",
+          2,
+        );
+      return emit(
+        await devRequest(
+          "GET",
+          `/api/v1/${kind === "question" ? "open-questions" : `${kind}s`}/${encode(id)}`,
+        ),
+        json,
+      );
+    }
+  }
+  if (command === "drift" && action === "file") {
+    const service = requireFlag(f, "service");
+    const bodyMd = await bodyFlag(f);
+    return emit(
+      await devRequest("POST", `/api/v1/services/${encode(service)}/drift`, {
+        severity: requireFlag(f, "severity"),
+        summary: requireFlag(f, "summary"),
+        bodyMd: bodyMd ?? "",
+        relatedArtifactType: f["related-artifact-type"] ?? null,
+        relatedArtifactId: f["related-artifact-id"] ?? null,
+      }),
+      json,
+    );
+  }
+  if (command === "request" && action === "file") {
+    const specMd = f["spec-file"]
+      ? await readFile(f["spec-file"], "utf8")
+      : requireFlag(f, "spec");
+    const body = {
+      fromService: requireFlag(f, "from"),
+      toService: requireFlag(f, "to"),
+      kind: requireFlag(f, "kind"),
+      specMd,
+      requestHash: requestHash({ toService: f.to, kind: f.kind, specMd }),
+      ...(f["required-capability"]
+        ? { requiredCapability: f["required-capability"] }
+        : {}),
+      targetArtifactType: f["target-artifact-type"] ?? null,
+      targetArtifactId: f["target-artifact-id"] ?? null,
+    };
+    return emit(await devRequest("POST", "/api/v1/requests", body), json);
+  }
+  if (command === "requests" && action === "file") {
+    const specMd = f["spec-file"] ? await readFile(f["spec-file"], "utf8") : requireFlag(f, "spec");
+    f.fromService = requireFlag(f, "from"); f.toService = requireFlag(f, "to"); f.specMd = specMd;
+    f.requestHash = requestHash({ toService: f.toService, kind: requireFlag(f, "kind"), specMd });
+  }
+  if (command === "decisions") {
+    if (action === "get")
+      return emit(
+        await devRequest("GET", `/api/v1/decisions/${encode(rest[0])}`),
+        json,
+      );
+    const q = action === "search" ? rest.join(" ") || f.q : undefined;
+    const payload = await devRequest(
+      "GET",
+      `/api/v1/decisions${query({ status: f.status, module: f.module, tag: f.tag, limit: f.limit ?? 200 })}`,
+    );
+    if (q)
+      payload.data = payload.data.filter((x) =>
+        `${x.id} ${x.title} ${(x.topicTags ?? []).join(" ")}`
+          .toLowerCase()
+          .includes(q.toLowerCase()),
+      );
+    return emit(
+      payload,
+      json,
+      (p) =>
+        p.data.map((x) => `${x.id}\t${x.status}\t${x.title}`).join("\n") ||
+        "No decisions.",
+    );
+  }
+  if (command === "design") {
+    if (action === "entries")
+      return emit(
+        await devRequest(
+          "GET",
+          `/api/v1/design/entries${query({ kind: f.kind, group: f.group, q: f.q, limit: f.limit })}`,
+        ),
+        json,
+      );
+    if (action === "entry")
+      return emit(
+        await devRequest("GET", `/api/v1/design/entries/${encode(rest[0])}`),
+        json,
+      );
+    if (action === "guide")
+      return emit(
+        await devRequest("GET", `/api/v1/design/guides/${encode(rest[0])}`),
+        json,
+      );
+  }
+  if (command === "figma") {
+    if (action === "lock")
+      return emit(
+        await devRequest(
+          "POST",
+          `/api/v1/design/files/${encode(rest[0])}/lock`,
+          { changeSetTitle: requireFlag(f, "title") },
+        ),
+        json,
+      );
+    if (action === "check") {
+      const c = await readConfig();
+      const result = await devRequest(
+        "GET",
+        `/api/v1/design/files/${encode(rest[0])}/lock/check?agentId=${encode(c.agentId)}`,
+      );
+      emit(
+        result,
+        json,
+        (p) =>
+          `${p.data.allowed ? "allowed" : "denied"}: ${p.data.reason ?? "lock held"}`,
+      );
+      if (!result.data.allowed) process.exitCode = 3;
+      return;
+    }
+    if (action === "log-write")
+      return emit(
+        await devRequest(
+          "POST",
+          `/api/v1/design/change-sets/${encode(rest[0])}/writes`,
+          {
+            tool: requireFlag(f, "tool"),
+            nodeIds: requireFlag(f, "nodes").split(",").filter(Boolean),
+          },
+        ),
+        json,
+      );
+    if (["submit", "apply", "published", "abandon"].includes(action)) {
+      const payload = f.file
+        ? JSON.parse(await readFile(f.file, "utf8"))
+        : action === "abandon"
+          ? {}
+          : { figmaVersion: requireFlag(f, "figma-version") };
+      return emit(
+        await devRequest(
+          "POST",
+          `/api/v1/design/change-sets/${encode(rest[0])}/${action}`,
+          payload,
+        ),
+        json,
+      );
+    }
+    if (action === "release")
+      return emit(
+        await devRequest(
+          "POST",
+          `/api/v1/design/files/${encode(rest[0])}/lock/release`,
+          {},
+        ),
+        json,
+      );
+  }
+  if (command === "hook") {
+    if (action === "print-settings")
+      return console.log(JSON.stringify(settingsSnippet(), null, 2));
+    if (action === "claude-figma-pre") {
+      // Fail closed: Claude Code only blocks a tool call on exit code 2, and
+      // treats any other non-zero exit as a non-blocking error that lets the
+      // write through. Every failure here (bad stdin, missing config, Dev
+      // error, lock denied) must therefore exit 2.
+      try {
+        const payload = JSON.parse(await stdinText());
+        return emit(await preHook(payload), json, "allowed");
+      } catch (error) {
+        throw new CliError(
+          error?.code ?? "FIGMA_HOOK_FAILED",
+          `Blocked Figma write: ${error?.message ?? String(error)}`,
+          2,
+          error?.details,
+        );
+      }
+    }
+    if (action === "lane-heartbeat") {
+      const result = await heartbeatCurrentLane();
+      return emit(result, json, result.heartbeated ? `Heartbeat recorded for ${result.key}.` : "No current-branch lane; no heartbeat sent.");
+    }
+    const payload = JSON.parse(await stdinText());
+    if (action === "workflow-post") {
+      const suggestion = workflowSuggestion(payload);
+      if (suggestion) console.log(suggestion);
+      return;
+    }
+    if (action === "claude-figma-post") {
+      try {
+        return emit(await postHook(payload), json, "logged");
+      } catch (error) {
+        console.error(
+          `nodii-dev post hook: ${error.code ?? "ERROR"}: ${error.message}`,
+        );
+        return;
+      }
+    }
+  }
+  if (Object.hasOwn(GROUPS, command)) {
+    const operations = operationsFrom(await loadOpenApi());
+    let entry = findFirstClass(operations, command, action);
+    if (command === "drift" && action === "resolve" && f.status === "accepted-as-canonical")
+      entry = operations.find((x) => x.operationId === "acceptDrift");
+    if (command === "contracts") {
+      const [kind, verb, ...ids] = [action, ...rest];
+      const type = { grpc: "GrpcInterface", rest: "RestInterface", outbox: "OutboxTopic", saga: "Saga", table: "Table" }[kind];
+      const op = verb === "publish" ? `create${type}` : verb === "status" && f.status === "implemented" ? `implement${type}` : null;
+      if (!op) throw new CliError("USAGE", "contracts: use <grpc|rest|outbox|saga|table> publish|status; status currently supports --status implemented", 2);
+      entry = operations.find((x) => x.operationId === op);
+      rest.splice(0, rest.length, ...ids);
+    }
+    if (!entry) {
+      const tags = Array.isArray(GROUPS[command]) ? GROUPS[command] : [GROUPS[command]];
+      const available = operations.filter((x) => x.tags.some((t) => tags.includes(t))).map((x) => x.operationId).join(", ");
+      throw new CliError("USAGE", `Unknown ${command} action: ${action}. OpenAPI operations: ${available}`, 2);
+    }
+    const built = flagsToOperation(entry, rest, f);
+    if (command === "requests" && action === "answer")
+      Object.assign(built.params, { kind: "request", id: rest[0] });
+    if (command === "drift" && entry.operationId === "acceptDrift" && !built.body?.relatedDecisionId && !built.body?.newDecision)
+      throw new CliError("USAGE", "accepted-as-canonical drift requires --related-decision-id or --new-decision JSON", 2);
+    const explicit = await readBody(f.body);
+    return emit(await callOperation(entry, built.params, explicit?.value ?? built.body), json);
+  }
+  throw new CliError(
+    "USAGE",
+    `Unknown command: ${[command, action].filter(Boolean).join(" ")}${STACK_VERBS.has(command) ? `. The local-stack CLI is \`./nodii-stack ${command}\`, run from the nodii-local-stack checkout.` : ""}`,
+    2,
+  );
+}
+
+export function fail(error) {
+  const e =
+    error instanceof CliError
+      ? error
+      : new CliError("UNEXPECTED", error?.message ?? String(error));
+  console.error(
+    `${e.code}: ${e.message}${e.details ? `\n${JSON.stringify(e.details)}` : ""}`,
+  );
+  process.exitCode = e.exitCode ?? 1;
+}