@stigmer/cli 3.0.8

package/src/config/resolve.test.ts

@@ -0,0 +1,103 @@
+import { afterEach, describe, expect, it } from "vitest";
+import { CliExitError } from "../errors/index.js";
+import type { Config } from "./config.js";
+import {
+  ensureAuthenticated,
+  resolveContextOrganization,
+  resolveEndpoint,
+  resolveOrganization,
+  resolveToken,
+} from "./resolve.js";
+
+const ENV_KEYS = ["STIGMER_SERVER_ADDRESS", "STIGMER_API_KEY", "STIGMER_ORG_ID"] as const;
+
+afterEach(() => {
+  for (const key of ENV_KEYS) delete process.env[key];
+});
+
+function cloudConfig(overrides: Partial<Config["backend"]["cloud"]> = {}): Config {
+  return { backend: { type: "cloud", cloud: { endpoint: "cloud.example:443", ...overrides } } };
+}
+
+describe("resolveEndpoint", () => {
+  it("defaults to the local daemon address in local mode", () => {
+    expect(resolveEndpoint({ backend: { type: "local" } })).toBe("localhost:7234");
+  });
+
+  it("uses the cloud default when no endpoint is configured", () => {
+    expect(resolveEndpoint({ backend: { type: "cloud" } })).toBe("api.stigmer.ai:443");
+  });
+
+  it("prefers the configured cloud endpoint", () => {
+    expect(resolveEndpoint(cloudConfig())).toBe("cloud.example:443");
+  });
+
+  it("lets STIGMER_SERVER_ADDRESS override everything", () => {
+    process.env.STIGMER_SERVER_ADDRESS = "override:7234";
+    expect(resolveEndpoint(cloudConfig())).toBe("override:7234");
+  });
+});
+
+describe("resolveToken", () => {
+  it("prefers STIGMER_API_KEY over the config token", () => {
+    process.env.STIGMER_API_KEY = "env-key";
+    expect(resolveToken(cloudConfig({ token: "config-token" }))).toBe("env-key");
+  });
+
+  it("falls back to the config token", () => {
+    expect(resolveToken(cloudConfig({ token: "config-token" }))).toBe("config-token");
+  });
+
+  it("returns empty string when unauthenticated", () => {
+    expect(resolveToken({ backend: { type: "cloud" } })).toBe("");
+  });
+});
+
+describe("resolveOrganization", () => {
+  it("prefers the --org flag override", () => {
+    process.env.STIGMER_ORG_ID = "env-org";
+    const config = cloudConfig({ org_id: "config-org" });
+    expect(resolveOrganization(config, "flag-org")).toBe("flag-org");
+  });
+
+  it("falls back to STIGMER_ORG_ID, then context, then cloud org_id", () => {
+    process.env.STIGMER_ORG_ID = "env-org";
+    expect(resolveOrganization(cloudConfig({ org_id: "config-org" }))).toBe("env-org");
+  });
+
+  it("uses context organization when no flag/env is set", () => {
+    const config: Config = {
+      backend: { type: "cloud", cloud: { org_id: "legacy" } },
+      context: { organization: "ctx-org" },
+    };
+    expect(resolveOrganization(config)).toBe("ctx-org");
+    expect(resolveContextOrganization(config)).toBe("ctx-org");
+  });
+
+  it("falls back to legacy cloud org_id", () => {
+    expect(resolveContextOrganization(cloudConfig({ org_id: "legacy" }))).toBe("legacy");
+  });
+});
+
+describe("ensureAuthenticated", () => {
+  it("never requires auth in local mode", () => {
+    expect(() => ensureAuthenticated({ backend: { type: "local" } })).not.toThrow();
+  });
+
+  it("throws in cloud mode with no credentials", () => {
+    expect(() => ensureAuthenticated(cloudConfig())).toThrow(CliExitError);
+  });
+
+  it("passes with a stored access token", () => {
+    expect(() => ensureAuthenticated(cloudConfig({ token: "t" }))).not.toThrow();
+  });
+
+  it("passes with only a refresh token", () => {
+    expect(() => ensureAuthenticated(cloudConfig({ refresh_token: "r" }))).not.toThrow();
+  });
+
+  it("passes with STIGMER_API_KEY set", () => {
+    process.env.STIGMER_API_KEY = "env-key";
+    expect(() => ensureAuthenticated(cloudConfig())).not.toThrow();
+  });
+});

package/src/config/resolve.ts

@@ -0,0 +1,80 @@
+// Effective-value resolution with env > config > default precedence. These are
+// the settings the backend client and read verbs depend on; centralizing the
+// precedence keeps every call site consistent (mirrors the Go CLI's Resolve*).
+
+import { CliExitError, ExitCode } from "../errors/index.js";
+import { type Config, isCloudMode } from "./config.js";
+
+const DEFAULT_CLOUD_ENDPOINT = "api.stigmer.ai:443";
+const DEFAULT_LOCAL_ENDPOINT = "localhost:7234";
+
+/**
+ * Resolve the server endpoint.
+ *   STIGMER_SERVER_ADDRESS  (explicit override, either backend)
+ *   > cloud.endpoint        (cloud mode)
+ *   > api.stigmer.ai:443    (cloud default) / localhost:7234 (local default)
+ */
+export function resolveEndpoint(config: Config): string {
+  const override = process.env.STIGMER_SERVER_ADDRESS;
+  if (override !== undefined && override !== "") {
+    return override;
+  }
+  if (isCloudMode(config)) {
+    return config.backend.cloud?.endpoint || DEFAULT_CLOUD_ENDPOINT;
+  }
+  return DEFAULT_LOCAL_ENDPOINT;
+}
+
+/**
+ * Resolve the auth token.
+ *   STIGMER_API_KEY  (env, also where the --api-key global is bridged)
+ *   > cloud.token    (persisted login token)
+ *   > ""             (unauthenticated)
+ */
+export function resolveToken(config: Config): string {
+  const env = process.env.STIGMER_API_KEY;
+  if (env !== undefined && env !== "") {
+    return env;
+  }
+  return config.backend.cloud?.token ?? "";
+}
+
+/**
+ * Resolve the active organization.
+ *   --org flag override > STIGMER_ORG_ID env > context.organization
+ *   > cloud.org_id (legacy fallback)
+ */
+export function resolveOrganization(config: Config, flagOrg?: string): string {
+  if (flagOrg !== undefined && flagOrg !== "") {
+    return flagOrg;
+  }
+  const env = process.env.STIGMER_ORG_ID;
+  if (env !== undefined && env !== "") {
+    return env;
+  }
+  return resolveContextOrganization(config);
+}
+
+/** The configured organization, with the legacy cloud.org_id fallback. */
+export function resolveContextOrganization(config: Config): string {
+  if (config.context?.organization !== undefined && config.context.organization !== "") {
+    return config.context.organization;
+  }
+  return config.backend.cloud?.org_id ?? "";
+}
+
+/**
+ * Fail fast with a clear "please log in" error when a cloud command has no
+ * usable credential. Local mode never requires auth. A credential is any of:
+ * the STIGMER_API_KEY env (or bridged --api-key), a persisted access token, or
+ * a refresh token (which the token provider can exchange for a fresh access
+ * token). This lives in the config layer — not the client façade — because it
+ * is purely a question of which credentials are configured.
+ */
+export function ensureAuthenticated(config: Config): void {
+  if (!isCloudMode(config)) return;
+  if (process.env.STIGMER_API_KEY) return;
+  const cloud = config.backend.cloud;
+  if (cloud?.token || cloud?.refresh_token) return;
+  throw new CliExitError("Not authenticated", ExitCode.Auth, ["Please sign in:", "  stigmer auth login"]);
+}

package/src/errors/classify.ts

@@ -0,0 +1,199 @@
+// Classifies any thrown value into a CliError: an exit code, a user-facing
+// message, and optional remediation hints. Mirrors the Go CLI's
+// clierr.Classify, including walking the error chain so wrapped RPC errors
+// still map to the right exit code.
+
+import { Code, ConnectError } from "@connectrpc/connect";
+import { StigmerError } from "@stigmer/sdk";
+import { CliExitError } from "./cli-exit-error.js";
+import { ExitCode } from "./exit-codes.js";
+
+/**
+ * Structured result of classifying a raw error. `classify` produces these and
+ * `handle` consumes them. `message === ""` signals a clean, silent outcome
+ * (local cancellation) for which nothing should be printed.
+ */
+export interface CliError {
+  readonly exitCode: number;
+  readonly message: string;
+  readonly hints?: readonly string[];
+  readonly cause?: Error;
+  /** Numeric Connect/gRPC code, present when the error originated from an RPC. */
+  readonly code?: number;
+}
+
+// Guards against pathological/circular `cause` chains.
+const MAX_CHAIN_DEPTH = 20;
+
+export function classify(err: unknown): CliError | null {
+  if (err === null || err === undefined) {
+    return null;
+  }
+
+  // Local cancellation (Ctrl-C / AbortController) is a clean outcome, not a
+  // failure — exit 0 silently. A *remote* Canceled status is a genuine failure
+  // and falls through to classifyConnectCode (exit 1). This is the one place
+  // the TS CLI deliberately improves on the Go CLI, which exits 1 for both.
+  if (isLocalAbort(err)) {
+    return { exitCode: ExitCode.Success, message: "", cause: toError(err) };
+  }
+
+  // Local errors that carry their own exit code (UsageError, auth-required,
+  // etc.) are passed through verbatim, including any remediation hints.
+  if (err instanceof CliExitError) {
+    return { exitCode: err.exitCode, message: err.message, hints: err.hints, cause: err };
+  }
+
+  const coded = extractCoded(err);
+  if (coded !== undefined) {
+    return classifyConnectCode(coded.code, coded.message, toError(err));
+  }
+
+  return { exitCode: ExitCode.General, message: messageOf(err), cause: toError(err) };
+}
+
+interface CodedError {
+  readonly code: number;
+  readonly message: string;
+}
+
+// Walks the cause chain for the first SDK StigmerError or raw ConnectError.
+// status.FromError in Go only checks the outermost error; this mirrors the Go
+// CLI's extractGRPCStatus which walks Unwrap to handle wrapped RPC errors.
+function extractCoded(err: unknown): CodedError | undefined {
+  let depth = 0;
+  for (let current: unknown = err; current != null && depth < MAX_CHAIN_DEPTH; current = causeOf(current), depth++) {
+    if (current instanceof StigmerError) {
+      return { code: current.connectCode, message: current.message };
+    }
+    if (current instanceof ConnectError) {
+      return { code: current.code, message: current.rawMessage };
+    }
+  }
+  return undefined;
+}
+
+function isLocalAbort(err: unknown): boolean {
+  let depth = 0;
+  for (let current: unknown = err; current != null && depth < MAX_CHAIN_DEPTH; current = causeOf(current), depth++) {
+    if (current instanceof Error && current.name === "AbortError") {
+      return true;
+    }
+  }
+  return false;
+}
+
+function classifyConnectCode(code: number, message: string, cause: Error): CliError {
+  switch (code) {
+    case Code.Unavailable:
+      return {
+        exitCode: ExitCode.Connection,
+        code,
+        cause,
+        message: "Cannot connect to the Stigmer server",
+        hints: ["Make sure the Stigmer server is running and reachable."],
+      };
+
+    case Code.DeadlineExceeded:
+      return {
+        exitCode: ExitCode.Connection,
+        code,
+        cause,
+        message: "Operation timed out",
+        hints: ["The server took too long to respond. Try again in a moment."],
+      };
+
+    case Code.ResourceExhausted:
+      return {
+        exitCode: ExitCode.Connection,
+        code,
+        cause,
+        message: "Rate limit exceeded",
+        hints: ["Too many requests. Wait a moment and try again."],
+      };
+
+    case Code.NotFound:
+      return { exitCode: ExitCode.NotFound, code, cause, message };
+
+    case Code.InvalidArgument:
+      return { exitCode: ExitCode.Usage, code, cause, message };
+
+    case Code.FailedPrecondition:
+      return { exitCode: ExitCode.Usage, code, cause, message: `Precondition failed: ${message}` };
+
+    case Code.AlreadyExists:
+      return { exitCode: ExitCode.Usage, code, cause, message: `Already exists: ${message}` };
+
+    case Code.Unauthenticated:
+      return {
+        exitCode: ExitCode.Auth,
+        code,
+        cause,
+        message: "Not authenticated",
+        hints: ["Please sign in:", "  stigmer auth login"],
+      };
+
+    case Code.PermissionDenied:
+      return {
+        exitCode: ExitCode.Auth,
+        code,
+        cause,
+        message: `Permission denied: ${message}`,
+        hints: ["Check your permissions, or re-authenticate:", "  stigmer auth login"],
+      };
+
+    case Code.Internal:
+      return {
+        exitCode: ExitCode.General,
+        code,
+        cause,
+        message: "Internal server error",
+        hints: [
+          "This is unexpected. If the problem persists, check the server logs.",
+          "Run with --debug for more details.",
+        ],
+      };
+
+    case Code.Aborted:
+      return {
+        exitCode: ExitCode.General,
+        code,
+        cause,
+        message: `Operation aborted: ${message}`,
+        hints: ["The operation was interrupted. You can safely retry."],
+      };
+
+    case Code.Canceled:
+      return { exitCode: ExitCode.General, code, cause, message: "Operation cancelled" };
+
+    default:
+      return {
+        exitCode: ExitCode.General,
+        code,
+        cause,
+        message: `${codeName(code)}: ${message}`,
+      };
+  }
+}
+
+function causeOf(value: unknown): unknown {
+  return value !== null && typeof value === "object"
+    ? (value as { cause?: unknown }).cause
+    : undefined;
+}
+
+function toError(value: unknown): Error {
+  if (value instanceof Error) return value;
+  return new Error(messageOf(value));
+}
+
+function messageOf(value: unknown): string {
+  if (value instanceof Error) return value.message;
+  if (typeof value === "string") return value;
+  return String(value);
+}
+
+/** Human-readable Connect/gRPC code name, e.g. 12 -> "Unimplemented". */
+export function codeName(code: number): string {
+  return Code[code] ?? "Unknown";
+}

package/src/errors/cli-exit-error.ts

@@ -0,0 +1,16 @@
+// A local error that carries its own exit code and optional remediation hints.
+// classify() passes these through verbatim, so command code can fail fast with
+// a precise exit code (e.g. "auth required" -> 4) without round-tripping to the
+// server. UsageError is the common specialization (exit 2).
+
+export class CliExitError extends Error {
+  readonly exitCode: number;
+  readonly hints?: readonly string[];
+
+  constructor(message: string, exitCode: number, hints?: readonly string[]) {
+    super(message);
+    this.name = "CliExitError";
+    this.exitCode = exitCode;
+    this.hints = hints;
+  }
+}

package/src/errors/clierr.test.ts

@@ -0,0 +1,172 @@
+import { Code, ConnectError } from "@connectrpc/connect";
+import { StigmerError } from "@stigmer/sdk";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { setDebug } from "../runtime.js";
+import { classify } from "./classify.js";
+import { ExitCode } from "./exit-codes.js";
+import { formatError, handle } from "./handle.js";
+import { UsageError } from "./usage-error.js";
+
+afterEach(() => {
+  setDebug(false);
+  vi.restoreAllMocks();
+});
+
+describe("classify — gRPC code to exit code", () => {
+  // Drives both error sources: a raw ConnectError (direct transport usage) and
+  // an SDK StigmerError (typed client usage). Both must classify identically.
+  const cases: ReadonlyArray<{ code: number; exit: number; messageContains?: string }> = [
+    { code: Code.Unavailable, exit: ExitCode.Connection },
+    { code: Code.DeadlineExceeded, exit: ExitCode.Connection },
+    { code: Code.ResourceExhausted, exit: ExitCode.Connection },
+    { code: Code.NotFound, exit: ExitCode.NotFound },
+    { code: Code.InvalidArgument, exit: ExitCode.Usage },
+    { code: Code.FailedPrecondition, exit: ExitCode.Usage, messageContains: "Precondition failed" },
+    { code: Code.AlreadyExists, exit: ExitCode.Usage, messageContains: "Already exists" },
+    { code: Code.Unauthenticated, exit: ExitCode.Auth },
+    { code: Code.PermissionDenied, exit: ExitCode.Auth, messageContains: "Permission denied" },
+    { code: Code.Internal, exit: ExitCode.General },
+    { code: Code.Aborted, exit: ExitCode.General, messageContains: "Operation aborted" },
+    { code: Code.Canceled, exit: ExitCode.General },
+    { code: Code.Unimplemented, exit: ExitCode.General, messageContains: "Unimplemented" },
+    { code: Code.OutOfRange, exit: ExitCode.General, messageContains: "OutOfRange" },
+    { code: Code.DataLoss, exit: ExitCode.General, messageContains: "DataLoss" },
+  ];
+
+  for (const { code, exit, messageContains } of cases) {
+    it(`maps ConnectError ${Code[code]} -> exit ${exit}`, () => {
+      const result = classify(new ConnectError("boom", code));
+      expect(result?.exitCode).toBe(exit);
+      expect(result?.code).toBe(code);
+      if (messageContains) expect(result?.message).toContain(messageContains);
+    });
+
+    it(`maps StigmerError ${Code[code]} -> exit ${exit}`, () => {
+      const result = classify(new StigmerError("unknown", "boom", code));
+      expect(result?.exitCode).toBe(exit);
+    });
+  }
+
+  it("preserves the server message verbatim for NotFound", () => {
+    const result = classify(new ConnectError("agent 'foo' not found", Code.NotFound));
+    expect(result?.message).toBe("agent 'foo' not found");
+  });
+
+  it("attaches remediation hints for auth failures", () => {
+    const result = classify(new ConnectError("nope", Code.Unauthenticated));
+    expect(result?.hints).toEqual(["Please sign in:", "  stigmer auth login"]);
+  });
+});
+
+describe("classify — non-RPC and edge cases", () => {
+  it("returns null for null/undefined", () => {
+    expect(classify(null)).toBeNull();
+    expect(classify(undefined)).toBeNull();
+  });
+
+  it("classifies a plain Error as a general failure", () => {
+    const result = classify(new Error("disk full"));
+    expect(result?.exitCode).toBe(ExitCode.General);
+    expect(result?.message).toBe("disk full");
+    expect(result?.code).toBeUndefined();
+  });
+
+  it("unwraps a wrapped RPC error via the cause chain", () => {
+    const inner = new ConnectError("not found", Code.NotFound);
+    const wrapped = new Error("while fetching agent", { cause: inner });
+    const result = classify(wrapped);
+    expect(result?.exitCode).toBe(ExitCode.NotFound);
+  });
+
+  it("maps a local UsageError to the usage exit code", () => {
+    const result = classify(new UsageError("invalid --output value"));
+    expect(result?.exitCode).toBe(ExitCode.Usage);
+    expect(result?.message).toBe("invalid --output value");
+  });
+});
+
+describe("classify — local abort vs remote cancel", () => {
+  it("treats a local AbortError as a clean exit 0 with no message", () => {
+    const abort = new Error("aborted");
+    abort.name = "AbortError";
+    const result = classify(abort);
+    expect(result?.exitCode).toBe(ExitCode.Success);
+    expect(result?.message).toBe("");
+  });
+
+  it("treats an aborted RPC (Canceled wrapping AbortError) as exit 0", () => {
+    const abort = new Error("aborted");
+    abort.name = "AbortError";
+    const cancelled = new ConnectError("canceled", Code.Canceled, undefined, undefined, abort);
+    const result = classify(cancelled);
+    expect(result?.exitCode).toBe(ExitCode.Success);
+  });
+
+  it("treats a remote Canceled (no local abort) as exit 1", () => {
+    const result = classify(new ConnectError("server canceled", Code.Canceled));
+    expect(result?.exitCode).toBe(ExitCode.General);
+    expect(result?.message).toBe("Operation cancelled");
+  });
+});
+
+describe("formatError", () => {
+  it("renders message and hints", () => {
+    const out = formatError(
+      { exitCode: ExitCode.Auth, message: "Not authenticated", hints: ["Please sign in:", "  stigmer auth login"] },
+      false,
+    );
+    expect(out).toBe("Error: Not authenticated\n\nPlease sign in:\n  stigmer auth login\n");
+  });
+
+  it("returns empty string for a silent (empty message) error", () => {
+    expect(formatError({ exitCode: ExitCode.Success, message: "" }, false)).toBe("");
+  });
+
+  it("appends the raw chain and numeric code in debug mode", () => {
+    const cause = new ConnectError("boom", Code.NotFound);
+    const out = formatError(
+      { exitCode: ExitCode.NotFound, message: "missing", cause, code: Code.NotFound },
+      true,
+    );
+    expect(out).toContain("--- debug ---");
+    expect(out).toContain(`gRPC code: NotFound (${Code.NotFound})`);
+  });
+
+  it("omits the debug block when debug mode is off", () => {
+    const cause = new Error("boom");
+    const out = formatError({ exitCode: ExitCode.General, message: "x", cause }, false);
+    expect(out).not.toContain("--- debug ---");
+  });
+});
+
+describe("handle", () => {
+  it("exits with the mapped code and writes to stderr", () => {
+    const exitSpy = vi.spyOn(process, "exit").mockImplementation(((code?: number) => {
+      throw new Error(`__exit__:${code}`);
+    }) as never);
+    const stderrSpy = vi.spyOn(process.stderr, "write").mockReturnValue(true);
+
+    expect(() => handle(new ConnectError("agent missing", Code.NotFound))).toThrow("__exit__:5");
+    expect(stderrSpy).toHaveBeenCalledWith(expect.stringContaining("Error: agent missing"));
+    expect(exitSpy).toHaveBeenCalledWith(ExitCode.NotFound);
+  });
+
+  it("exits 0 silently for a local abort", () => {
+    const exitSpy = vi.spyOn(process, "exit").mockImplementation(((code?: number) => {
+      throw new Error(`__exit__:${code}`);
+    }) as never);
+    const stderrSpy = vi.spyOn(process.stderr, "write").mockReturnValue(true);
+
+    const abort = new Error("aborted");
+    abort.name = "AbortError";
+    expect(() => handle(abort)).toThrow("__exit__:0");
+    expect(stderrSpy).not.toHaveBeenCalled();
+  });
+
+  it("exits 0 when there is no error", () => {
+    vi.spyOn(process, "exit").mockImplementation(((code?: number) => {
+      throw new Error(`__exit__:${code}`);
+    }) as never);
+    expect(() => handle(null)).toThrow("__exit__:0");
+  });
+});

package/src/errors/exit-codes.ts

@@ -0,0 +1,14 @@
+// Exit codes returned by the CLI. The convention mirrors the Go CLI
+// (internal/cli/clierr/exit_codes.go) so scripts and CI can branch on `$?`
+// without parsing stderr. classify() maps gRPC/Connect status codes onto these.
+
+export const ExitCode = {
+  Success: 0,
+  General: 1, // Internal, Aborted, remote Canceled, Unknown, non-gRPC errors
+  Usage: 2, // InvalidArgument, FailedPrecondition, AlreadyExists
+  Connection: 3, // Unavailable, DeadlineExceeded, ResourceExhausted
+  Auth: 4, // Unauthenticated, PermissionDenied
+  NotFound: 5, // NotFound
+} as const;
+
+export type ExitCode = (typeof ExitCode)[keyof typeof ExitCode];

package/src/errors/handle.ts

@@ -0,0 +1,53 @@
+// The single exit point for command-level errors: classify, print to stderr,
+// and exit with the mapped code. Mirrors the Go CLI's clierr.Handle.
+
+import { isDebug } from "../runtime.js";
+import { type CliError, classify, codeName } from "./classify.js";
+import { ExitCode } from "./exit-codes.js";
+
+/**
+ * Render a CliError for stderr. In debug mode it appends the raw error chain
+ * and numeric gRPC code. Returns "" when there is nothing to print (a clean
+ * local cancellation), so the caller writes nothing.
+ */
+export function formatError(error: CliError, debugMode: boolean): string {
+  const lines: string[] = [];
+
+  if (error.message !== "") {
+    lines.push(`Error: ${error.message}`);
+  }
+
+  if (error.hints !== undefined && error.hints.length > 0) {
+    lines.push("");
+    lines.push(...error.hints);
+  }
+
+  if (debugMode && error.cause !== undefined) {
+    lines.push("");
+    lines.push("--- debug ---");
+    if (error.code !== undefined) {
+      lines.push(`gRPC code: ${codeName(error.code)} (${error.code})`);
+    }
+    lines.push(`Raw error: ${error.cause.stack ?? error.cause.message}`);
+  }
+
+  return lines.length > 0 ? lines.join("\n") + "\n" : "";
+}
+
+/**
+ * Classify the error, print a user-facing message to stderr, and exit with the
+ * appropriate code. The debug flag is read from process-global runtime state
+ * (set from `--debug`), so callers never thread it through.
+ */
+export function handle(error: unknown): never {
+  const classified = classify(error);
+  if (classified === null) {
+    process.exit(ExitCode.Success);
+  }
+
+  const rendered = formatError(classified, isDebug());
+  if (rendered !== "") {
+    process.stderr.write(rendered);
+  }
+  process.exit(classified.exitCode);
+}

package/src/errors/index.ts

@@ -0,0 +1,7 @@
+// Public surface of the CLI error-handling module.
+
+export { ExitCode } from "./exit-codes.js";
+export { type CliError, classify, codeName } from "./classify.js";
+export { CliExitError } from "./cli-exit-error.js";
+export { formatError, handle } from "./handle.js";
+export { UsageError } from "./usage-error.js";

package/src/errors/usage-error.ts

@@ -0,0 +1,14 @@
+// A local (client-side) validation failure — bad flags, an unknown output
+// format, a malformed resource reference, etc. Maps to ExitCode.Usage (2), the
+// same code the server's InvalidArgument produces, so scripts see a consistent
+// "usage" exit regardless of where validation happened.
+
+import { CliExitError } from "./cli-exit-error.js";
+import { ExitCode } from "./exit-codes.js";
+
+export class UsageError extends CliExitError {
+  constructor(message: string) {
+    super(message, ExitCode.Usage);
+    this.name = "UsageError";
+  }
+}

package/src/index.ts

@@ -0,0 +1,8 @@
+// Public surface of @stigmer/cli.
+//
+// The CLI is primarily consumed as the `stigmer` bin, but exposing the program
+// builder lets tests drive the full command tree in-process and lets embedders
+// compose it.
+
+export { buildProgram } from "./program.js";
+export { VERSION } from "./version.js";