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

package/dist/cli/invocation.js

@@ -0,0 +1,279 @@
+// 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/.
+/**
+ * Single-parse argv normalization (plan §10.7, chunk-9 WI-9.9).
+ *
+ * Before this module, ~46 `process.argv` read sites were scattered across
+ * `src/**` (32 outside `src/cli.ts`), each re-scanning the raw argv array for
+ * repeated flags (`parseAllFlagValues`), `--`-passthrough tails (`env run`,
+ * `secret run`), or first-occurrence flag values (`parseFlagValue`). This
+ * module normalizes argv into one typed {@link ParsedInvocation} object,
+ * minted ONCE by `src/cli.ts` at startup, so every downstream reader shares
+ * one parse instead of re-scanning the raw array.
+ *
+ * Deliberately import-free: this module must never join an import cycle
+ * (cycle ratchet, plan §10.7 / chunk-9 D.3), so it depends on nothing but
+ * global `process` — no `output/context`, no `core/errors`. The flag-parsing
+ * primitives below are intentionally small, self-contained re-implementations
+ * of the same algorithms `output/context.ts`'s `parseFlagValue`/
+ * `hasBooleanFlag` and (the now-retired) `cli/shared.ts` `parseAllFlagValues`
+ * used, kept byte-identical so every converted call site is behavior-
+ * preserving — with ONE deliberate exception (R-033a): `getAllFlagValuesFrom`
+ * now stops at a literal `--` separator instead of scanning past it, fixing a
+ * bug where a repeatable flag's value placed after `--` (meant to end flag
+ * parsing) was still read as a real flag occurrence. See that function's
+ * docstring.
+ *
+ * Singleton + fallback semantics (the design decision this module encodes):
+ *  - `setParsedInvocation(argv)` is called exactly once, by `src/cli.ts`, in
+ *    its startup block before any command handler can run. It
+ *    snapshots that argv into an immutable {@link ParsedInvocation} that
+ *    every subsequent `getParsedInvocation()` call returns unchanged for the
+ *    rest of the process lifetime — "normalize argv exactly once at entry".
+ *  - `getParsedInvocation()` is the ONLY way leaf command modules read
+ *    invocation state. When the singleton was never set — the common case
+ *    for unit tests that call command logic directly, and for
+ *    `tests/_helpers/cli.ts`'s in-process CLI harness, which drives citty's
+ *    `runCommand` WITHOUT running `src/cli.ts`'s `import.meta.main` startup
+ *    block (see that file's docstring) — it falls back to parsing the
+ *    CURRENT `process.argv` fresh, on every call, uncached. That harness
+ *    mutates `process.argv` itself per invocation and restores it in
+ *    `finally`, and many suites issue several back-to-back in-process runs
+ *    per test; caching the fallback parse would leak one run's flags into
+ *    the next. So "lazily parses process.argv once" means "once PER CALL",
+ *    not "once for the life of the process" — the fallback is intentionally
+ *    request-scoped, mirroring how every pre-WI-9.9 leaf site read
+ *    `process.argv` fresh at call time. Production code never touches the
+ *    fallback path: the real entry point sets the singleton before any
+ *    command handler can run.
+ *  - `_resetParsedInvocationForTests()` clears an explicitly-set singleton
+ *    (symmetry with `resetOutputMode`/`resetConfigCache` in
+ *    `tests/_helpers/cli.ts`); no suite currently needs it because the
+ *    startup block that calls `setParsedInvocation` never runs under
+ *    `bun test`, but it exists so a test that DOES call
+ *    `setParsedInvocation` directly can clean up after itself.
+ *
+ * Also folds three argv re-scanners that pre-dated this module (plan §10.7):
+ *  - `parseAllFlagValues` (moved from `cli/shared.ts`) — repeated-flag
+ *    collection (`--tag foo --tag bar`), re-exported from `cli/shared.ts` so
+ *    every existing importer (feedback-cli, observability-cli, remember-cli,
+ *    search-cli, stash-cli, cli.ts) is unaffected.
+ *  - `findCittyTopLevelCommand`/`findCittyTopLevelCommandIndex` (moved from
+ *    `cli/parse-args.ts`, which had zero internal imports for this cluster) —
+ *    re-exported from `cli/parse-args.ts` for `tests/tasks-embedded.test.ts`.
+ *  - `resolveHelpMigrateVersionArg` (moved from `cli.ts`, where it was
+ *    private) — the `akm help migrate <version>` positional/flag
+ *    disambiguation guard.
+ */
+// ── Repeated-flag / `--`-passthrough primitives (byte-identical to the
+// pre-WI-9.9 per-site implementations they replace) ─────────────────────────
+function getFlagValueFrom(argv, flag) {
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (arg === "--")
+            break;
+        if (arg === flag)
+            return argv[i + 1];
+        if (arg.startsWith(`${flag}=`))
+            return arg.slice(flag.length + 1);
+    }
+    return undefined;
+}
+function hasFlagIn(argv, flag) {
+    for (const arg of argv) {
+        if (arg === "--")
+            return false;
+        if (arg === flag || arg === `${flag}=true`)
+            return true;
+    }
+    return false;
+}
+/**
+ * Collect every `--flag value` / `--flag=value` occurrence, stopping at a
+ * literal `--` separator (R-033a). `--` conventionally ends flag parsing —
+ * everything after it is positional/passthrough, never a flag akm should
+ * interpret. Before this fix, a token like `--tag leaked:yes` placed AFTER
+ * `--` (e.g. `akm feedback <ref> --positive -- --tag leaked:yes`) was still
+ * picked up as a real `--tag` value, letting argv content past the boundary
+ * leak into structured output. This is a deliberate BEHAVIOR CHANGE from the
+ * pre-WI-9.9 per-site implementation this module otherwise keeps
+ * byte-identical (see the module docstring) — every caller of
+ * `parseAllFlagValues`/`getAllFlagValues` inherits the fix for free.
+ */
+function getAllFlagValuesFrom(argv, flag) {
+    const values = [];
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (arg === "--")
+            break;
+        if (arg === flag && i + 1 < argv.length) {
+            values.push(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;
+}
+/**
+ * Tokens after a literal `--` marker in argv, or `[]` when there is no `--`
+ * OR nothing follows it. Callers that previously threw a "Missing command"
+ * UsageError on `dashIndex < 0 || dashIndex === argv.length - 1` now check
+ * `passthroughArgs().length === 0` — the two conditions are equivalent.
+ */
+function passthroughArgsFrom(argv) {
+    const dashIndex = argv.indexOf("--");
+    if (dashIndex < 0 || dashIndex === argv.length - 1)
+        return [];
+    return argv.slice(dashIndex + 1);
+}
+function createParsedInvocation(argv) {
+    const snapshot = Object.freeze([...argv]);
+    const userArgs = Object.freeze(snapshot.slice(2));
+    return {
+        argv: snapshot,
+        userArgs,
+        getFlagValue: (flag) => getFlagValueFrom(snapshot, flag),
+        hasFlag: (flag) => hasFlagIn(snapshot, flag),
+        getAllFlagValues: (flag) => getAllFlagValuesFrom(snapshot, flag),
+        passthroughArgs: () => passthroughArgsFrom(snapshot),
+    };
+}
+let _invocation;
+/**
+ * Mint the process-wide {@link ParsedInvocation} singleton. Called exactly
+ * once, by `src/cli.ts`, at startup — "normalize argv exactly once at entry"
+ * (plan §10.7).
+ */
+export function setParsedInvocation(argv) {
+    _invocation = createParsedInvocation(argv);
+    return _invocation;
+}
+/**
+ * Read the process-wide {@link ParsedInvocation}. Returns the singleton set
+ * by `setParsedInvocation` when one exists; otherwise falls back to parsing
+ * the CURRENT `process.argv` fresh (uncached — see the module docstring for
+ * why caching the fallback would be wrong). The fallback is what every
+ * leaf-command unit test and `tests/_helpers/cli.ts`'s in-process harness
+ * exercise; production CLI runs always hit the singleton.
+ */
+export function getParsedInvocation() {
+    if (_invocation)
+        return _invocation;
+    return createParsedInvocation(process.argv);
+}
+/** Test-only: clear an explicitly-set singleton. Symmetry with resetOutputMode/resetConfigCache. */
+export function _resetParsedInvocationForTests() {
+    _invocation = undefined;
+}
+// ── Folded re-scanner #1: parseAllFlagValues (moved from cli/shared.ts) ─────
+/**
+ * Collect all occurrences of a repeatable flag from the current invocation's
+ * argv. Citty's StringArgDef only exposes the last value when a flag is
+ * repeated, so for repeatable CLI args (like `--tag foo --tag bar`) callers
+ * read argv directly via this helper. Supports both `--flag value` and
+ * `--flag=value` forms.
+ */
+export function parseAllFlagValues(flag) {
+    return getParsedInvocation().getAllFlagValues(flag);
+}
+function cittyComparableName(name) {
+    return name.replace(/[-_]+([a-zA-Z0-9])/g, (_match, char) => char.toUpperCase());
+}
+function toAliasArray(alias) {
+    if (Array.isArray(alias))
+        return alias;
+    return typeof alias === "string" ? [alias] : [];
+}
+function isCittyValueFlag(flag, argsDef) {
+    const name = flag.replace(/^-{1,2}/, "");
+    const normalized = cittyComparableName(name);
+    for (const [key, def] of Object.entries(argsDef)) {
+        if (def.type !== "string" && def.type !== "enum")
+            continue;
+        if (normalized === cittyComparableName(key))
+            return true;
+        if (toAliasArray(def.alias).includes(name))
+            return true;
+    }
+    return false;
+}
+/**
+ * Match citty's top-level subcommand scan (`findSubCommandIndex`).
+ *
+ * Citty does not assume `rawArgs[0]` is the command: global string flags may
+ * appear first and consume the following token. The CLI startup guard uses this
+ * to classify the requested command before any command handler can run.
+ */
+export function findCittyTopLevelCommandIndex(rawArgs, argsDef) {
+    for (let i = 0; i < rawArgs.length; i += 1) {
+        const arg = rawArgs[i];
+        if (arg === "--")
+            return -1;
+        if (arg.startsWith("-")) {
+            if (!arg.includes("=") && isCittyValueFlag(arg, argsDef))
+                i += 1;
+            continue;
+        }
+        return i;
+    }
+    return -1;
+}
+export function findCittyTopLevelCommand(rawArgs, argsDef) {
+    const index = findCittyTopLevelCommandIndex(rawArgs, argsDef);
+    return index >= 0 ? rawArgs[index] : undefined;
+}
+// ── Folded re-scanner #3: resolveHelpMigrateVersionArg (moved from cli.ts,
+// where it was a private, unexported function) ──────────────────────────────
+/**
+ * Guard against citty consuming a global flag value as the `help migrate`
+ * version positional (mirrors `resolveRememberContentArg` /
+ * `wasFormatValueConsumedAsName` in the read/sources leaf modules).
+ *
+ * When the user runs `akm help migrate --format json` without a version
+ * argument, citty may assign `"json"` to the `version` positional. This
+ * detects that case and returns `undefined` so the caller surfaces the
+ * "missing version" UsageError instead of treating a flag value as a version.
+ */
+export function resolveHelpMigrateVersionArg(version) {
+    if (version === undefined)
+        return undefined;
+    const invocation = getParsedInvocation();
+    const parsedFormat = invocation.getFlagValue("--format");
+    if (parsedFormat !== undefined &&
+        version === parsedFormat &&
+        wasHelpMigrateFlagValueConsumedAsVersion(version, parsedFormat, "--format")) {
+        return undefined;
+    }
+    const parsedDetail = invocation.getFlagValue("--detail");
+    if (parsedDetail !== undefined &&
+        version === parsedDetail &&
+        wasHelpMigrateFlagValueConsumedAsVersion(version, parsedDetail, "--detail")) {
+        return undefined;
+    }
+    return version;
+}
+function wasHelpMigrateFlagValueConsumedAsVersion(version, flagValue, flagName) {
+    const argv = getParsedInvocation().userArgs;
+    const helpIndex = argv.indexOf("help");
+    const tokens = helpIndex >= 0 ? argv.slice(helpIndex + 1) : argv;
+    const migrateIndex = tokens.indexOf("migrate");
+    const relevant = migrateIndex >= 0 ? tokens.slice(migrateIndex + 1) : tokens;
+    let flagIndex = -1;
+    for (let i = 0; i < relevant.length; i += 1) {
+        const token = relevant[i];
+        if (token === flagName || token === `${flagName}=${flagValue}`) {
+            flagIndex = i;
+            break;
+        }
+    }
+    if (flagIndex === -1)
+        return false;
+    if (relevant.slice(0, flagIndex).includes(version))
+        return false;
+    return relevant[flagIndex] === flagName ? relevant[flagIndex + 1] === version : true;
+}

package/dist/cli/parse-args.js

@@ -8,52 +8,11 @@
  * main CLI file focused on command definitions and routing.
  */
 import { UsageError } from "../core/errors.js";
-function cittyComparableName(name) {
-    return name.replace(/[-_]+([a-zA-Z0-9])/g, (_match, char) => char.toUpperCase());
-}
-function toAliasArray(alias) {
-    if (Array.isArray(alias))
-        return alias;
-    return typeof alias === "string" ? [alias] : [];
-}
-function isCittyValueFlag(flag, argsDef) {
-    const name = flag.replace(/^-{1,2}/, "");
-    const normalized = cittyComparableName(name);
-    for (const [key, def] of Object.entries(argsDef)) {
-        if (def.type !== "string" && def.type !== "enum")
-            continue;
-        if (normalized === cittyComparableName(key))
-            return true;
-        if (toAliasArray(def.alias).includes(name))
-            return true;
-    }
-    return false;
-}
-/**
- * Match citty's top-level subcommand scan (`findSubCommandIndex`).
- *
- * Citty does not assume `rawArgs[0]` is the command: global string flags may
- * appear first and consume the following token. The CLI startup guard uses this
- * to classify the requested command before any command handler can run.
- */
-export function findCittyTopLevelCommandIndex(rawArgs, argsDef) {
-    for (let i = 0; i < rawArgs.length; i += 1) {
-        const arg = rawArgs[i];
-        if (arg === "--")
-            return -1;
-        if (arg.startsWith("-")) {
-            if (!arg.includes("=") && isCittyValueFlag(arg, argsDef))
-                i += 1;
-            continue;
-        }
-        return i;
-    }
-    return -1;
-}
-export function findCittyTopLevelCommand(rawArgs, argsDef) {
-    const index = findCittyTopLevelCommandIndex(rawArgs, argsDef);
-    return index >= 0 ? rawArgs[index] : undefined;
-}
+// findCittyTopLevelCommand(Index) + CittyArg(s)DefinitionForScan moved to
+// ./invocation (chunk-9 WI-9.9 argv-normalization fold — that cluster had no
+// internal imports, so it relocated cleanly); re-exported here so existing
+// importers (tests/tasks-embedded.test.ts, commands/read/show.ts) are unaffected.
+export { findCittyTopLevelCommand, findCittyTopLevelCommandIndex, } from "./invocation.js";
 /**
  * Return true when `args._[0]` is a member of `validSet`.
  *
@@ -113,50 +72,6 @@ export function parseNonNegativeIntFlag(raw, flagName) {
     }
     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.

package/dist/cli/retired-commands.js

@@ -0,0 +1,78 @@
+// 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/.
+/**
+ * Replacement hints for command spellings retired by the 0.9 CLI overhaul
+ * (hard break — no aliases). Consulted by the unknown-command error path
+ * BEFORE the edit-distance did-you-mean: distance-based suggestions are
+ * actively misleading for retired spellings (`init` → "did you mean
+ * `info`?", `update` → "did you mean `upgrade`?" — the latter replaces the
+ * BINARY, not the sources), and an agent following them gets steered into
+ * the wrong command instead of the renamed one.
+ *
+ * Keys are either a bare retired top-level token (`"init"`) or a
+ * group-scoped `"<group> <sub>"` pair (`"env set"`). Keep entries one
+ * sentence; the migration pointer is appended by the caller.
+ */
+const RETIRED_COMMAND_HINTS = {
+    // Top-level verbs absorbed by the `bundle` group.
+    init: "`akm init` moved in 0.9 — use `akm bundle create`.",
+    add: "`akm add` moved in 0.9 — use `akm bundle add <source>`.",
+    list: "`akm list` moved in 0.9 — use `akm bundle list`.",
+    remove: "`akm remove` moved in 0.9 — use `akm bundle remove <source>`.",
+    update: "`akm update` moved in 0.9 — use `akm bundle update` (to update akm itself, use `akm upgrade`).",
+    // Group renamed to the singular.
+    tasks: "the `tasks` group was renamed in 0.9 — use `akm task <subcommand>`.",
+    // Verbs absorbed by the `proposal` group.
+    extract: "`akm extract` moved in 0.9 — use `akm proposal extract`.",
+    propose: "`akm propose` moved in 0.9 — use `akm proposal new`.",
+    proposals: "`akm proposals` moved in 0.9 — use `akm proposal list`.",
+    accept: "`akm accept` moved in 0.9 — use `akm proposal accept <id>`.",
+    reject: '`akm reject` moved in 0.9 — use `akm proposal reject <id> --reason "..."`.',
+    diff: "`akm diff` moved in 0.9 — use `akm proposal diff <id>`.",
+    revert: "`akm revert` moved in 0.9 — use `akm proposal revert <id>`.",
+    reflect: "`akm reflect` was folded into 0.9 — use `akm improve <ref>`.",
+    distill: "`akm distill` was folded into 0.9 — use `akm improve <ref>`.",
+    // Renamed persistence and observability verbs.
+    save: "`akm save` moved in 0.9 — use `akm sync`.",
+    events: "`akm events` moved in 0.9 — use `akm log`.",
+    // Removed observability surfaces.
+    history: "`akm history` was removed in 0.9 — use `akm log --ref <ref>` for an asset's event trail.",
+    graph: "`akm graph` was removed in 0.9 — graph counts appear in `akm health`; refresh extraction with `akm improve --strategy graph-refresh`.",
+    lessons: "`akm lessons` was removed in 0.9 — lesson strength is indexed; use `akm search --type lesson`.",
+    lesson: "`akm lesson` was removed in 0.9 — lesson strength is indexed; use `akm search --type lesson`.",
+    // Relocated guidance / removed asset verbs.
+    mv: "`akm mv` was removed in 0.9 — move the file, then run `akm index` and `akm lint` (to carry ranking signal: `bun scripts/rekey-asset-ref.ts <old-ref> <new-ref>`).",
+    // Pre-0.9 removals agents still trip over.
+    wiki: "the `akm wiki` family was removed in 0.9 — wikis are ordinary knowledge assets; ingest with `akm import <url> --path <subdir>`.",
+    backup: "`akm backup` was removed in 0.9 — backups belong to the standalone `akm-migrate backup` tool.",
+    // Group-scoped retirements.
+    "env set": "`akm env set` was removed in 0.9 — edit the `.env` file directly; akm loads it as-is.",
+    "env unset": "`akm env unset` was removed in 0.9 — edit the `.env` file directly; akm loads it as-is.",
+    "registry search": "`akm registry search` was folded into `akm search --from registry` in 0.9.",
+    "registry build-index": "`akm registry build-index` moved in 0.9 — maintainers run `bun scripts/build-registry-index.ts`.",
+    "workflow template": "`akm workflow template` was folded into `akm workflow create --print` in 0.9.",
+    "workflow validate": "`akm workflow validate` was folded into `akm lint --type workflows` in 0.9 (add `--fail-on-flagged` for CI gates).",
+    "workflow watch": "`akm workflow watch` was removed in 0.9 — use `akm log --run <run-id>`.",
+    "config show": "`akm config show` was removed in 0.9 — use `akm config list`.",
+    "config validate": "`akm config validate` was removed in 0.9 — the config file is validated on every load.",
+    "task enable": "`akm task enable` was removed in 0.9 — set `enabled: true` in the task YAML, then `akm task sync`.",
+    "task disable": "`akm task disable` was removed in 0.9 — set `enabled: false` in the task YAML, then `akm task sync`.",
+    "task init": "`akm task init` was removed in 0.9 — `akm setup` seeds the default schedules.",
+    "task list": "there is no `task list` — task files are indexed assets; use `akm search --type task`.",
+    "task remove": "there is no `task remove` — delete the task YAML, then run `akm task sync` to unbind it.",
+    "log tail": "`akm log tail` was removed in 0.9 — poll `akm log --since @offset:<id>` (the durable cursor).",
+    "log list": "`akm log list` was flattened in 0.9 — bare `akm log` is the same surface.",
+};
+const MIGRATION_POINTER = "Full rename table: `akm help migrate 0.9.0`.";
+/**
+ * Replacement hint for a retired spelling, or undefined when the attempted
+ * token isn't a known retirement. `parentPath` is the group path already
+ * resolved before the unknown token (empty at root), so `env set` and a
+ * hypothetical top-level `set` can't collide.
+ */
+export function retiredCommandHint(parentPath, attempted) {
+    const key = parentPath.length === 0 ? attempted : `${parentPath[parentPath.length - 1]} ${attempted}`;
+    const entry = RETIRED_COMMAND_HINTS[key];
+    return entry === undefined ? undefined : `${entry} ${MIGRATION_POINTER}`;
+}