akm-cli 0.9.0-rc.0 → 0.9.0-rc.13

package/dist/cli/shared.js

@@ -10,12 +10,16 @@
 import { defineCommand } from "citty";
 import { stringify as yamlStringify } from "yaml";
 import { assertNever } from "../core/assert.js";
-import { AkmError } from "../core/errors.js";
+import { AkmError, UsageError } from "../core/errors.js";
 import { getOutputMode } from "../output/context.js";
-import { DEFAULT_TEMPLATE, deliverRendered, escapeHtml, renderHtml, resolveTemplatePath } from "../output/html-render.js";
+import { renderGenericHtml, renderGenericMarkdown, renderGenericText } from "../output/generic-render.js";
+import { deliverRendered } from "../output/html-render.js";
+import { getHtmlRendererHandler, getMdRendererHandler } from "../output/render-registry.js";
 import { shapeForCommand } from "../output/shapes.js";
 import { formatPlain, outputJsonl } from "../output/text.js";
+import { parseAllFlagValues } from "./invocation.js";
 import { hasSubcommand } from "./parse-args.js";
+export { parseAllFlagValues };
 // ── Exit codes ───────────────────────────────────────────────────────────────
 /**
  * Canonical process exit-code table for the akm CLI. Single source of truth —
@@ -71,8 +75,26 @@ function extractHint(error) {
     return undefined;
 }
 /**
- * Serialize an error to the standard JSON envelope and exit.
- * Used in both the startup try/catch and `runWithJsonErrors`.
+ * Serialize an error to the standard JSON envelope and record the mapped
+ * exit code. Used in both the startup try/catch and `runWithJsonErrors`.
+ *
+ * R-067: this used to call `process.exit(exitCode)` directly, which
+ * terminates the process synchronously and skips every pending `finally`
+ * block up the call stack — including `src/cli.ts`'s own
+ * `disposeDispatchResources()` cleanup and citty's per-command `cleanup`
+ * hooks. `process.exitCode = exitCode; return;` is equivalent for every
+ * caller here: Node/Bun exits with that code once the event loop drains
+ * naturally, but cleanup on the way there still runs.
+ * `src/commands/improve/extract-cli.ts` already uses this exact pattern for
+ * its own non-throw failure signal.
+ *
+ * Because this no longer throws or exits, it no longer terminates control
+ * flow on its own — every call site MUST treat it like a normal return and
+ * stop doing further work itself (an explicit `return;` right after the
+ * call, same as any other caller of a fallible function). `runWithJsonErrors`
+ * below satisfies this for free (this call is its catch block's last
+ * statement); `src/cli.ts`'s three direct call sites add the `return;`
+ * explicitly.
  */
 export function emitJsonError(error) {
     const message = error instanceof Error ? error.message : String(error);
@@ -82,7 +104,7 @@ export function emitJsonError(error) {
     // 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);
+    process.exitCode = exitCode;
 }
 /**
  * Run an async function and route any thrown error through the standard JSON
@@ -96,25 +118,126 @@ export async function runWithJsonErrors(fn) {
         emitJsonError(error);
     }
 }
+/**
+ * The global output flags, redeclared on every leaf command.
+ *
+ * citty parses each command level against only that command's own args, so a
+ * flag declared on the root command is UNKNOWN at the leaf — and an unknown
+ * flag does not consume its space-separated value, which then falls through as
+ * a positional. `akm sync --format json` once synced a bundle named "json",
+ * and `akm env unset env:x KEY --format json` once tried to unset a key named
+ * "json"; both grew bespoke argv-inspection workarounds. Declaring the flags
+ * at the leaf lets the parser consume the value, which is the root-cause fix.
+ *
+ * These declarations exist for PARSING only. The output mode is still read
+ * exactly once, from the invocation singleton at startup — no command body may
+ * read these args (that is the same one-parse rule `cli/invocation.ts`
+ * documents).
+ *
+ * These are also the canonical descriptions for the root command's own args
+ * (`main.args` in src/cli.ts) — the root spreads this same object rather than
+ * redeclaring the text, so root help and leaf help can never drift apart.
+ * `format`/`detail` need per-site `default` overrides (root has one, leaves
+ * don't — see the one-parse rule above), so those two keys get shallow
+ * overrides at the root; the description text itself is never duplicated.
+ */
+export const GLOBAL_OUTPUT_ARGS = {
+    format: { type: "string", description: "Output format: json|jsonl|yaml|text|md|html (global flag)" },
+    detail: {
+        type: "string",
+        description: "Detail level (verbosity): brief|normal|full (global flag).",
+    },
+    // R-050(c): single-sourced with the root command's own `--shape` help
+    // (`main.args.shape` in src/cli.ts, which spreads this object) so the
+    // caveat is visible from every leaf's own `--help`, not only the top-level
+    // one. `summary` outside `show` is a hard usage error (exit 2,
+    // INVALID_SHAPE_VALUE), enforced at startup in src/cli.ts before any
+    // command body runs.
+    shape: {
+        type: "string",
+        description: "Output projection: human|agent|summary (global flag). 'agent' trims to agent-essential fields; " +
+            "'summary' is only valid on 'akm show' (a usage error, exit 2, everywhere else). Default: human.",
+    },
+    output: {
+        type: "string",
+        description: "Write rendered output to a file instead of stdout (all formats except jsonl) (global flag)",
+    },
+    // S11: surfaced at every leaf (not just the root) so `akm <command> --help`
+    // documents them too — they already apply globally, parsed from raw argv
+    // by `applyEarlyStderrFlags` in src/cli.ts before citty ever sees them, so
+    // declaring them here is documentation, not new parsing behavior. A
+    // command with its own same-named arg (e.g. `env path --quiet`) wins the
+    // merge in `defineJsonCommand` as usual.
+    quiet: {
+        type: "boolean",
+        alias: "q",
+        description: "Suppress non-essential stderr output (banners, spinners, progress info) (global flag). " +
+            "Safety-critical output is never suppressed: errors, destructive-action confirmation prompts, " +
+            "and auto-migration banners always appear regardless of --quiet.",
+        default: false,
+    },
+    verbose: {
+        type: "boolean",
+        description: "Print per-spec diagnostics to stderr (global flag; also honours AKM_VERBOSE env var).",
+        default: false,
+    },
+};
 /**
  * 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.
+ *
+ * Every command defined here also accepts the {@link GLOBAL_OUTPUT_ARGS} so
+ * their values are parsed rather than mis-captured as positionals; a command
+ * declaring its own arg of the same name wins (e.g. `env path` has its own
+ * `quiet`).
  */
 export function defineJsonCommand(def) {
     const { run, ...rest } = def;
+    const withGlobals = { ...rest, args: { ...GLOBAL_OUTPUT_ARGS, ...rest.args } };
     if (!run)
-        return defineCommand({ ...rest });
+        return defineCommand(withGlobals);
     return defineCommand({
-        ...rest,
+        ...withGlobals,
         run: (context) => runWithJsonErrors(() => run(context)),
     });
 }
+/**
+ * Canonical bare-group behavior (0.9.0 breaking change, owner ruling 12).
+ *
+ * Before 0.9.0 the twelve `akm <group>` command groups did three different
+ * things when invoked with no subcommand: some printed help and exited 1,
+ * some ran an implicit default action and exited 0 (e.g. bare `akm graph`
+ * silently rendering `graph summary`), and one already raised a structured
+ * usage error and exited 2. None of that is discoverable from the exit code
+ * alone, and a script that greps stdout for a specific default action broke
+ * silently the moment someone reordered subcommands.
+ *
+ * The canonical choice, applied uniformly: a bare group invocation is a
+ * USAGE ERROR — exit 2, the same structured JSON envelope every other usage
+ * mistake in this CLI produces (not citty's raw help banner, and not a
+ * silent default action). This matches STABILITY.md's documented exit-code
+ * table (2 = usage) and the exit code the CLI already used for "unknown
+ * command" / "missing required argument" as of the companion 0.9.0 fix.
+ *
+ * `defaultRun` is now OPTIONAL for exactly this reason: omitting it opts a
+ * group into the shared, canonical error below. Passing an explicit
+ * `defaultRun` is a deliberate opt-out and should not be added to new groups
+ * without a documented reason — see CHANGELOG for the migration note.
+ */
+function bareGroupUsageError(meta, subcommandSet) {
+    const name = typeof meta === "object" && meta !== null && "name" in meta && typeof meta.name === "string"
+        ? meta.name
+        : undefined;
+    const usage = name ? `\`akm ${name}\`` : "This command";
+    const subcommands = [...subcommandSet].sort().join(", ");
+    throw new UsageError(`${usage} requires a subcommand. Available: ${subcommands}.`, "MISSING_REQUIRED_ARGUMENT", `Run \`akm ${name ?? "<command>"} --help\` to see usage for each subcommand.`);
+}
 /**
  * Define a citty subcommand-group command (env, secret, proposal, tasks, wiki,
- * graph, …) that shares one wiring shape: a `subCommands` map, a routing set
+ * …) that shares one wiring shape: a `subCommands` map, a routing set
  * DERIVED from that map's keys (so the set can never silently desync from the
  * registered subcommands), and a default body that fires ONLY for the bare
  * group invocation — citty still runs the group body after dispatching a
@@ -128,6 +251,7 @@ export function defineJsonCommand(def) {
  */
 export function defineGroupCommand(def) {
     const subcommandSet = new Set(Object.keys(def.subCommands));
+    const defaultRun = def.defaultRun ?? (() => bareGroupUsageError(def.meta, subcommandSet));
     return defineCommand({
         meta: def.meta,
         ...(def.args ? { args: def.args } : {}),
@@ -135,7 +259,7 @@ export function defineGroupCommand(def) {
         run: (context) => runWithJsonErrors(() => {
             if (hasSubcommand(context.args, subcommandSet))
                 return;
-            return def.defaultRun(context);
+            return defaultRun(context);
         }),
     });
 }
@@ -160,51 +284,37 @@ export function output(command, result) {
             deliverRendered(yamlStringify(shaped), mode.outputPath);
             return;
         case "text": {
+            // D7 — registry first, generic rendering of the shaped envelope second.
+            // Mirrors the md/html fallback immediately below: a command with no
+            // registered text formatter used to fall through to
+            // `JSON.stringify(shaped, null, 2)`, i.e. silently hand back JSON while
+            // claiming `--format text` — the same "wrong format wearing the right
+            // flag" bug D7 already closed for md/html. `renderGenericText` (a
+            // DISTINCT function from `renderGenericMarkdown` — see its doc comment
+            // in src/output/generic-render.ts for why reusing the md renderer here
+            // was itself a version of the same bug) renders flat `key=value` text
+            // matching the house style already established by registered text
+            // formatters like `config list`.
             const plain = formatPlain(command, shaped, mode.detail);
-            deliverRendered(plain ?? JSON.stringify(shaped, null, 2), mode.outputPath);
+            deliverRendered(plain ?? renderGenericText(command, shaped), mode.outputPath);
             return;
         }
-        case "md":
-            // `--format md` is currently only consumed by `akm health` for the
-            // per-run / window-compare table renderings. Commands that don't
-            // implement an md renderer fall back to the JSON envelope so
-            // pipelines never get an empty stdout.
-            deliverRendered(JSON.stringify(shaped, null, 2), mode.outputPath);
+        case "md": {
+            // D7 — registry first, generic rendering of the shaped envelope second.
+            // No command emits JSON under `--format md` any more: silently handing
+            // back the wrong format was the worst of the three behaviours this
+            // replaced.
+            const rendered = getMdRendererHandler(command)?.(shaped, mode.detail);
+            deliverRendered(rendered ?? renderGenericMarkdown(command, shaped), mode.outputPath);
             return;
+        }
         case "html": {
-            // Generic fallback: render the JSON envelope inside the dark-mode
-            // default template. Commands with a bespoke HTML template (`akm health`)
-            // intercept before reaching output(), same as the `md` intercept.
-            const html = renderHtml(resolveTemplatePath(DEFAULT_TEMPLATE), {
-                "%%COMMAND%%": escapeHtml(command),
-                "%%CONTENT_JSON%%": escapeHtml(JSON.stringify(shaped, null, 2)),
-                "%%GENERATED_AT%%": new Date().toISOString(),
-            });
-            deliverRendered(html, mode.outputPath);
+            const rendered = getHtmlRendererHandler(command)?.(shaped, mode.detail);
+            deliverRendered(rendered ?? renderGenericHtml(command, shaped), mode.outputPath);
             return;
         }
     }
 }
-/**
- * Collect all occurrences of a repeatable flag from process.argv.
- * Citty's StringArgDef only exposes the last value when a flag is repeated,
- * so for repeatable CLI args (like `--tag foo --tag bar`) we read argv directly.
- * Supports both `--flag value` and `--flag=value` forms.
- */
-export function parseAllFlagValues(flag) {
-    const values = [];
-    for (let i = 0; i < process.argv.length; i++) {
-        const arg = process.argv[i];
-        if (arg === flag && i + 1 < process.argv.length) {
-            values.push(process.argv[i + 1]);
-            // BUG-M4: skip the value index so `--tag --tag` (literal `--tag`
-            // value) does not double-count the second `--tag` as a separate
-            // flag occurrence.
-            i++;
-        }
-        else if (arg.startsWith(`${flag}=`)) {
-            values.push(arg.slice(flag.length + 1));
-        }
-    }
-    return values;
-}
+// parseAllFlagValues moved to ./invocation (chunk-9 WI-9.9 argv-normalization
+// fold); re-exported above so every existing importer of this module is
+// unaffected.

package/dist/cli-node.mjs

@@ -20,7 +20,8 @@ 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`.
+// `import()` it here. Opt in explicitly so the CLI actually runs its startup
+// block (dispatch, `runCli`).
 process.env.AKM_NODE_ENTRY = "1";
 
 await import("./cli.js");