akm-cli 0.8.0-rc2 → 0.8.0

package/dist/cli/parse-args.js

@@ -1,3 +1,6 @@
+// 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/.
 /**
  * Shared argument-parsing utilities for the AKM CLI entry point.
  *
@@ -25,7 +28,7 @@ export function hasSubcommand(args, validSet) {
 /**
  * Parse a `--limit`-style flag value into a positive integer.
  *
- * Returns `undefined` when `raw` is `undefined` (flag not supplied).
+ * Returns `undefined` when `raw` is `undefined` or empty (flag not supplied).
  * Throws `UsageError` when the raw value is present but not a valid positive
  * integer so the caller gets a structured, machine-readable error response.
  *
@@ -35,9 +38,96 @@ export function hasSubcommand(args, validSet) {
 export function parsePositiveIntFlag(raw, flagName = "--limit") {
     if (raw === undefined)
         return undefined;
-    const parsed = parseInt(raw, 10);
+    const trimmed = raw.trim();
+    if (!trimmed)
+        return undefined;
+    const parsed = parseInt(trimmed, 10);
     if (Number.isNaN(parsed) || parsed <= 0) {
-        throw new UsageError(`Invalid ${flagName} value: "${raw}". Must be a positive integer.`);
+        throw new UsageError(`Invalid ${flagName} value: "${raw}". Must be a positive integer.`, "INVALID_FLAG_VALUE");
     }
     return parsed;
 }
+/**
+ * Parse a non-negative integer flag value (0 is allowed, unlike `parsePositiveIntFlag`).
+ *
+ * Returns `undefined` when `raw` is `undefined` or empty (flag not supplied).
+ * Throws `UsageError` when the raw value is present but not a valid non-negative
+ * integer (e.g. contains decimals, letters, or is negative).
+ *
+ * @param raw       The raw string value (may be undefined).
+ * @param flagName  The flag name to include in the error message.
+ */
+export function parseNonNegativeIntFlag(raw, flagName) {
+    if (raw === undefined)
+        return undefined;
+    const trimmed = raw.trim();
+    if (!trimmed)
+        return undefined;
+    if (!/^\d+$/.test(trimmed)) {
+        throw new UsageError(`Invalid ${flagName} value: "${raw}". Must be a non-negative integer.`, "INVALID_FLAG_VALUE");
+    }
+    return parseInt(trimmed, 10);
+}
+// ── Auto-accept flag parsing ─────────────────────────────────────────────────
+/**
+ * Parse the value of `akm improve --auto-accept` into a confidence threshold.
+ *
+ * Semantics (see docs/migration/v0.7-to-v0.8.md):
+ * - `undefined` (flag absent) → `undefined` (default-OFF; pre-prod flip)
+ * - `""` (bare `--auto-accept`, no value) → `undefined` (treated as flag absent)
+ * - `"false"` (case-insensitive) → `undefined` (explicit disable)
+ * - `"safe"` (case-insensitive) → `90` (permanent back-compat alias)
+ * - integer string `"0".."100"` → that integer
+ * - anything else → throws `UsageError("INVALID_FLAG_VALUE")`
+ *
+ * Citty's `type: "string"` resolves bare flags to `""` and an absent flag to
+ * `undefined`. Both forms now disable auto-accept; users must pass an explicit
+ * threshold (`--auto-accept=N` or `--auto-accept=safe`) to opt in. This is a
+ * deliberate flip from the earlier 0.8.0-RC behaviour, which defaulted to ON
+ * at threshold 90 and surprised users who didn't expect Phase B operations to
+ * apply without confirmation.
+ *
+ * Until proposals expose per-operation confidence scores, any non-`undefined`
+ * threshold causes the consolidate path to auto-accept the whole batch
+ * (legacy "safe" behaviour). The threshold value is preserved for the eventual
+ * per-operation comparison; see the TODO in `consolidate.ts`.
+ */
+export function parseAutoAcceptFlag(raw) {
+    if (raw === undefined)
+        return undefined;
+    const trimmed = raw.trim();
+    if (trimmed === "")
+        return undefined;
+    const lower = trimmed.toLowerCase();
+    if (lower === "false")
+        return undefined;
+    if (lower === "safe")
+        return 90;
+    if (!/^\d+$/.test(trimmed)) {
+        throw new UsageError(`Invalid --auto-accept value: "${raw}". Must be an integer 0-100, 'safe', or 'false'.`, "INVALID_FLAG_VALUE");
+    }
+    const parsed = parseInt(trimmed, 10);
+    if (parsed < 0 || parsed > 100) {
+        throw new UsageError(`Invalid --auto-accept value: "${raw}". Must be an integer 0-100, 'safe', or 'false'.`, "INVALID_FLAG_VALUE");
+    }
+    return parsed;
+}
+// ── String flag parsing ──────────────────────────────────────────────────────
+/**
+ * Extract a string value from a parsed citty argument object by key.
+ *
+ * Returns the trimmed string when present and non-empty, or `undefined`
+ * otherwise. Eliminates the repeated
+ * `typeof args.X === "string" && args.X.trim() ? args.X.trim() : undefined`
+ * pattern throughout the CLI command handlers.
+ *
+ * @param args  The citty argument object (typed as unknown for flexibility).
+ * @param key   The argument key to look up.
+ */
+export function getStringArg(args, key) {
+    const val = args[key];
+    if (typeof val !== "string")
+        return undefined;
+    const trimmed = val.trim();
+    return trimmed || undefined;
+}

package/dist/cli/shared.js

@@ -0,0 +1,129 @@
+// 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/.
+/**
+ * Shared CLI utilities extracted from `src/cli.ts` so that individual
+ * command modules can import them without a circular dependency.
+ *
+ * Exported: output, runWithJsonErrors, parseAllFlagValues, emitJsonError
+ */
+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";
+// ── Exit codes ───────────────────────────────────────────────────────────────
+/**
+ * Canonical process exit-code table for the akm CLI. Single source of truth —
+ * referenced by `classifyExitCode` here and re-imported by `src/cli.ts` so the
+ * health-warn / general-failure paths stay in sync.
+ *
+ *   0  success
+ *   1  general / not-found
+ *   2  usage error
+ *   4  health warn (health command only)
+ *  78  config error
+ */
+export const EXIT_CODES = {
+    SUCCESS: 0,
+    GENERAL: 1,
+    USAGE: 2,
+    HEALTH_WARN: 4,
+    CONFIG: 78,
+};
+// ── Helpers ──────────────────────────────────────────────────────────────────
+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;
+}
+function extractHint(error) {
+    if (error instanceof Error && "hint" in error && typeof error.hint === "function") {
+        return error.hint();
+    }
+    return undefined;
+}
+/**
+ * Serialize an error to the standard JSON envelope and exit.
+ * Used in both the startup try/catch and `runWithJsonErrors`.
+ */
+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;
+    console.error(JSON.stringify({ ok: false, error: message, ...(code ? { code } : {}), hint }, null, 2));
+    process.exit(exitCode);
+}
+/**
+ * Run an async function and route any thrown error through the standard JSON
+ * error envelope so users never see a raw stack trace.
+ */
+export async function runWithJsonErrors(fn) {
+    try {
+        await fn();
+    }
+    catch (error) {
+        emitJsonError(error);
+    }
+}
+/**
+ * Render a command result according to the active output mode (json/jsonl/yaml/text).
+ */
+export function output(command, result) {
+    const mode = getOutputMode();
+    const shaped = shapeForCommand(command, result, mode.detail, mode.shape);
+    if (mode.format === "jsonl") {
+        outputJsonl(command, shaped);
+        return;
+    }
+    switch (mode.format) {
+        case "json":
+            console.log(JSON.stringify(shaped, null, 2));
+            return;
+        case "yaml":
+            console.log(yamlStringify(shaped));
+            return;
+        case "text": {
+            const plain = formatPlain(command, shaped, mode.detail);
+            console.log(plain ?? JSON.stringify(shaped, null, 2));
+            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.
+            console.log(JSON.stringify(shaped, null, 2));
+            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;
+}