akm-cli 0.8.1 → 0.9.0-beta.0

package/dist/cli/shared.js

@@ -7,11 +7,13 @@
  *
  * Exported: output, runWithJsonErrors, parseAllFlagValues, emitJsonError
  */
+import { defineCommand } from "citty";
 import { stringify as yamlStringify } from "yaml";
-import { ConfigError, NotFoundError, UsageError } from "../core/errors";
-import { getOutputMode } from "../output/context";
-import { shapeForCommand } from "../output/shapes";
-import { formatPlain, outputJsonl } from "../output/text";
+import { assertNever } from "../core/assert.js";
+import { AkmError } from "../core/errors.js";
+import { getOutputMode } from "../output/context.js";
+import { shapeForCommand } from "../output/shapes.js";
+import { formatPlain, outputJsonl } from "../output/text.js";
 // ── Exit codes ───────────────────────────────────────────────────────────────
 /**
  * Canonical process exit-code table for the akm CLI. Single source of truth —
@@ -22,6 +24,7 @@ import { formatPlain, outputJsonl } from "../output/text";
  *   1  general / not-found
  *   2  usage error
  *   4  health warn (health command only)
+ *  70  internal / unclassified (sysexits EX_SOFTWARE — akm threw unexpectedly)
  *  78  config error
  */
 export const EXIT_CODES = {
@@ -29,17 +32,35 @@ export const EXIT_CODES = {
     GENERAL: 1,
     USAGE: 2,
     HEALTH_WARN: 4,
+    // sysexits.h EX_SOFTWARE. Distinct from GENERAL(1) so scripts can tell an
+    // expected "not found" outcome from akm itself throwing an unexpected error.
+    INTERNAL: 70,
     CONFIG: 78,
 };
 // ── Helpers ──────────────────────────────────────────────────────────────────
+/**
+ * Map a thrown value to a process exit code.
+ *
+ * Known, classified errors (instances of `AkmError`) are dispatched through an
+ * exhaustive switch on the `kind` discriminant — `assertNever` makes a missing
+ * case a compile-time error, so adding a new error class can't silently inherit
+ * the wrong code. Anything that is NOT an `AkmError` is treated as a genuinely
+ * unexpected internal failure and maps to INTERNAL(70) rather than GENERAL(1),
+ * so callers can distinguish "akm threw" from a normal not-found outcome.
+ */
 function classifyExitCode(error) {
-    if (error instanceof UsageError)
-        return EXIT_CODES.USAGE;
-    if (error instanceof ConfigError)
-        return EXIT_CODES.CONFIG;
-    if (error instanceof NotFoundError)
-        return EXIT_CODES.GENERAL;
-    return EXIT_CODES.GENERAL;
+    if (!(error instanceof AkmError))
+        return EXIT_CODES.INTERNAL;
+    switch (error.kind) {
+        case "usage":
+            return EXIT_CODES.USAGE;
+        case "config":
+            return EXIT_CODES.CONFIG;
+        case "not-found":
+            return EXIT_CODES.GENERAL;
+        default:
+            return assertNever(error.kind, "classifyExitCode");
+    }
 }
 function extractHint(error) {
     if (error instanceof Error && "hint" in error && typeof error.hint === "function") {
@@ -55,9 +76,9 @@ export function emitJsonError(error) {
     const message = error instanceof Error ? error.message : String(error);
     const hint = extractHint(error);
     const exitCode = classifyExitCode(error);
-    const code = error instanceof UsageError || error instanceof ConfigError || error instanceof NotFoundError
-        ? error.code
-        : undefined;
+    // Classified akm errors carry a stable machine-readable `code`; unexpected
+    // internal errors have none.
+    const code = error instanceof AkmError ? error.code : undefined;
     console.error(JSON.stringify({ ok: false, error: message, ...(code ? { code } : {}), hint }, null, 2));
     process.exit(exitCode);
 }
@@ -73,6 +94,22 @@ export async function runWithJsonErrors(fn) {
         emitJsonError(error);
     }
 }
+/**
+ * Define a citty command whose `run` body is automatically wrapped in
+ * `runWithJsonErrors`, so the handler emits a byte-identical JSON error
+ * envelope (stdout/stderr/exit-code) on throw without the boilerplate. A
+ * command without a `run` (a pure subcommand group) is passed through
+ * unchanged.
+ */
+export function defineJsonCommand(def) {
+    const { run, ...rest } = def;
+    if (!run)
+        return defineCommand({ ...rest });
+    return defineCommand({
+        ...rest,
+        run: (context) => runWithJsonErrors(() => run(context)),
+    });
+}
 /**
  * Render a command result according to the active output mode (json/jsonl/yaml/text).
  */

package/dist/cli-node.mjs

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+
+// Node entry wrapper for akm.
+//
+// The primary entry `dist/cli.js` carries a `#!/usr/bin/env bun` shebang and,
+// when run under Node, relies on a text-import loader hook for its embedded
+// `.md`/`.xml` assets (Bun loads those natively; Node needs a hook). Those
+// imports are static and hoisted, so the hook MUST be registered before the
+// module graph is evaluated — i.e. before `cli.js` is imported. This wrapper
+// does exactly that: register the hook, then dynamically import the real CLI.
+//
+// Bun users never touch this file; it exists solely so `node dist/cli-node.mjs`
+// (and the `test:node-smoke` script / Node CI matrix) can run akm end-to-end.
+
+import { register } from "node:module";
+
+register("./text-import-hook.mjs", import.meta.url);
+
+// cli.js gates its startup block on `import.meta.main`, which is false when we
+// `import()` it here. Opt in explicitly so the CLI actually runs `runMain`.
+process.env.AKM_NODE_ENTRY = "1";
+
+await import("./cli.js");