akm-cli 0.7.5 → 0.8.0-rc.3

package/.github/CHANGELOG.md

@@ -83,7 +83,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 - **Proposal queue (`akm proposal *`)** (#225, #226, #233) — durable queue for proposal-producing commands. New verbs `akm proposal {list, show, diff, accept, reject}`. Promotion runs full validation before routing through `writeAssetToSource()`. Multiple proposals for the same `ref` coexist without filesystem collisions. Auto-accept is gated per-source via `autoAcceptProposals: true` (default off; requires a writable source). See v1 spec §11.
 - **`akm reflect`, `akm propose`, `akm distill`** (#225, #226, #227) — three new commands that write **only** to the proposal queue. `reflect` and `propose` shell out via the agent CLI (`agent.*` config); `distill` is the canonical bounded in-tree LLM call gated behind `llm.features.feedback_distillation`. Usage events `reflect_invoked`, `propose_invoked`, `distill_invoked`.
 - **`lesson` asset type** (#227) — first-class well-known type with required frontmatter `description` and `when_to_use`, stored under `lessons/<name>.md`. Normally produced by `akm distill <ref>` as a `proposed`-quality proposal and promoted via `akm proposal accept`.
-- **`llm.features.*` map with default-false gates** (#227, #284) — every bounded in-tree LLM call site is gated behind exactly one feature flag. Four keys ship: `curate_rerank`, `feedback_distillation`, `memory_inference`, `graph_extraction`. All defaults are `false`. Wrapper `tryLlmFeature(feature, config, fn, fallback)` in `src/llm/feature-gate.ts` guarantees disabled/throw/timeout fall back without crashing the call site. See v1 spec §14.
+- **`llm.features.*` map with mixed defaults** (#227, #284) — every bounded in-tree LLM call site is gated behind exactly one feature flag. Four keys ship: `curate_rerank`, `feedback_distillation`, `memory_inference`, `graph_extraction`. `memory_inference` and `graph_extraction` default to `true`; the others default to `false`. Wrapper `tryLlmFeature(feature, config, fn, fallback)` in `src/llm/feature-gate.ts` guarantees disabled/throw/timeout fall back without crashing the call site. See v1 spec §14.
 - **`quality: "proposed"` and `--include-proposed`** — `SearchHit.quality` open string set; `proposed` is excluded from default search and surfaces only via `akm search ... --include-proposed` or `akm proposal *`. Unknown values parse-warn-include. `SearchHit` gains optional `quality?` and `warnings?` fields.
 - **`akm-bench` v1** (#234, PRs #266, #268, #269) — paired-utility benchmark framework. Track A runs each task with and without akm available and emits a comparable score pair; `akm-bench compare` aggregates paired runs into a delta report; `akm-bench attribute` maps utility deltas back to specific `[origin//]type:name` refs (Track B); `akm-bench evolve` is a stub for the closed-loop workflow that lands in 0.8.
 - **Operator env-var documentation** (#284 Wave B, PR #285) — `docs/configuration.md` now documents `AKM_NPM_REGISTRY`, `AKM_REGISTRY_URL`, `AKM_CACHE_DIR`, `HF_HOME`, and `GH_TOKEN`.

package/dist/cli/parse-args.js

@@ -0,0 +1,86 @@
+/**
+ * Shared argument-parsing utilities for the AKM CLI entry point.
+ *
+ * These were extracted from `src/cli.ts` to eliminate repetition and keep the
+ * main CLI file focused on command definitions and routing.
+ */
+import { UsageError } from "../core/errors";
+// ── Subcommand detection ─────────────────────────────────────────────────────
+/**
+ * Return true when `args._[0]` is a member of `validSet`.
+ *
+ * Citty exposes unknown subcommands as `args._[0]` (the first positional).
+ * Several top-level commands (config, vault, wiki, workflow, tasks) need to
+ * detect whether a recognised subcommand was supplied so they can show a help
+ * banner rather than an unhelpful "unknown command" error.
+ *
+ * @param args     Parsed citty argument object (must have an `_` array).
+ * @param validSet The set of recognised subcommand names for this command.
+ */
+export function hasSubcommand(args, validSet) {
+    const command = Array.isArray(args._) ? args._[0] : undefined;
+    return typeof command === "string" && validSet.has(command);
+}
+// ── Numeric flag parsing ─────────────────────────────────────────────────────
+/**
+ * Parse a `--limit`-style flag value into a positive integer.
+ *
+ * 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.
+ *
+ * @param raw       The raw string value from citty (may be undefined).
+ * @param flagName  The flag name to include in the error message (e.g. `"--limit"`).
+ */
+export function parsePositiveIntFlag(raw, flagName = "--limit") {
+    if (raw === undefined)
+        return undefined;
+    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.`, "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);
+}
+// ── 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;
+}