akm-cli 0.8.1 → 0.9.0-beta.0

package/dist/commands/{init.js → sources/init.js}

@@ -10,11 +10,12 @@
 import { spawnSync } from "node:child_process";
 import fs from "node:fs";
 import path from "node:path";
-import { TYPE_DIRS } from "../core/asset-spec";
-import { loadUserConfig, saveConfig } from "../core/config";
-import { ConfigError } from "../core/errors";
-import { assertSafeStashDir, getBinDir, getConfigPath, getDefaultStashDir } from "../core/paths";
-import { ensureRg } from "../setup/ripgrep-install";
+import { TYPE_DIRS } from "../../core/asset/asset-spec.js";
+import { loadUserConfig, saveConfig } from "../../core/config/config.js";
+import { ConfigError } from "../../core/errors.js";
+import { assertSafeStashDir, getBinDir, getConfigPath, getDefaultStashDir } from "../../core/paths.js";
+import { ensureRg } from "../../core/ripgrep/install.js";
+import { copyStashSkeleton, scaffoldStashMeta } from "./stash-skeleton.js";
 /**
  * Refuse to persist a temporary-directory stashDir to the user's config when
  * running under a test runner AND `--dir <tempdir>` was passed explicitly.
@@ -74,6 +75,10 @@ export async function akmInit(options) {
     }
     // Ensure the default stash is a local git repo (no remote required)
     ensureGitRepo(stashDir);
+    if (created) {
+        copyStashSkeleton(stashDir);
+        scaffoldStashMeta(stashDir);
+    }
     // Persist stashDir in config.json
     const configPath = getConfigPath();
     const existing = loadUserConfig();

package/dist/commands/{installed-stashes.js → sources/installed-stashes.js}

@@ -9,18 +9,18 @@
  */
 import fs from "node:fs";
 import path from "node:path";
-import { isWithin, resolveStashDir } from "../core/common";
-import { getSources, loadConfig } from "../core/config";
-import { NotFoundError, UsageError } from "../core/errors";
-import { akmIndex } from "../indexer/indexer";
-import { removeLockEntry, upsertLockEntry } from "../integrations/lockfile";
-import { parseRegistryRef } from "../registry/resolve";
-import { parseGitRepoUrl, syncMirroredRepo } from "../sources/providers/git";
-import { syncFromRef } from "../sources/providers/sync-from-ref";
-import { ensureWebsiteMirror } from "../sources/website-ingest";
-import { listWikis, resolveWikisRoot } from "../wiki/wiki";
-import { removeInstalledRegistryEntry, upsertInstalledRegistryEntry } from "./source-add";
-import { removeStash } from "./source-manage";
+import { isWithin, resolveStashDir } from "../../core/common.js";
+import { getSources, loadConfig } from "../../core/config/config.js";
+import { NotFoundError, UsageError } from "../../core/errors.js";
+import { akmIndex } from "../../indexer/indexer.js";
+import { removeLockEntry, upsertLockEntry } from "../../integrations/lockfile.js";
+import { parseRegistryRef } from "../../registry/resolve.js";
+import { parseGitRepoUrl, syncMirroredRepo } from "../../sources/providers/git.js";
+import { syncFromRef } from "../../sources/providers/sync-from-ref.js";
+import { ensureWebsiteMirror } from "../../sources/website-ingest.js";
+import { listWikis, resolveWikisRoot } from "../../wiki/wiki.js";
+import { removeInstalledRegistryEntry, upsertInstalledRegistryEntry } from "./source-add.js";
+import { removeStash } from "./source-manage.js";
 export async function akmListSources(input) {
     const stashDir = input?.stashDir ?? resolveStashDir();
     const config = loadConfig();

package/dist/commands/{migration-help.js → sources/migration-help.js}

@@ -3,6 +3,7 @@
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
 import fs from "node:fs";
 import path from "node:path";
+import { getDirname } from "../../runtime.js";
 const CHANGELOG_URL = "https://github.com/itlackey/akm/blob/main/CHANGELOG.md";
 const MIGRATION_DOC_URL = "https://github.com/itlackey/akm/blob/main/docs/migration/v0.5-to-v0.6.md";
 /**
@@ -13,11 +14,11 @@ const MIGRATION_DOC_URL = "https://github.com/itlackey/akm/blob/main/docs/migrat
  * `files[]` array in `package.json`.
  */
 function releaseNotesDir() {
-    return path.resolve(import.meta.dir, "../../docs/migration/release-notes");
+    return path.resolve(getDirname(import.meta.url), "../../../docs/migration/release-notes");
 }
 function loadChangelog() {
     try {
-        const changelogPath = path.resolve(import.meta.dir, "../../CHANGELOG.md");
+        const changelogPath = path.resolve(getDirname(import.meta.url), "../../../CHANGELOG.md");
         if (fs.existsSync(changelogPath)) {
             return fs.readFileSync(changelogPath, "utf8");
         }

package/dist/commands/{schema-repair.js → sources/schema-repair.js}

@@ -14,14 +14,14 @@
  */
 import fs from "node:fs";
 import path from "node:path";
-import { parseAssetRef } from "../core/asset-ref";
-import { assembleAsset } from "../core/asset-serialize";
-import { appendEvent, readEvents } from "../core/events";
-import { parseFrontmatter } from "../core/frontmatter";
-import { createProposal, isProposalSkipped } from "../core/proposals";
-import { info, warn } from "../core/warn";
-import { resolveAssetPath } from "../indexer/path-resolver";
-import { chatCompletion, parseEmbeddedJsonResponse } from "../llm/client";
+import { parseAssetRef } from "../../core/asset/asset-ref.js";
+import { assembleAsset } from "../../core/asset/asset-serialize.js";
+import { parseFrontmatter } from "../../core/asset/frontmatter.js";
+import { appendEvent, readEvents } from "../../core/events.js";
+import { info, warn } from "../../core/warn.js";
+import { resolveAssetPath } from "../../indexer/walk/path-resolver.js";
+import { chatCompletion, parseEmbeddedJsonResponse } from "../../llm/client.js";
+import { createProposal, isProposalSkipped } from "../proposal/validators/proposals.js";
 // ── Constants ────────────────────────────────────────────────────────────────
 /** Minimum gap between schema-repair attempts on the same asset. */
 const SCHEMA_REPAIR_COOLDOWN_MS = 7 * 24 * 60 * 60 * 1000; // 7 days

package/dist/commands/{self-update.js → sources/self-update.js}

@@ -5,9 +5,10 @@ import * as childProcess from "node:child_process";
 import { createHash } from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
-import { fetchWithRetry, IS_WINDOWS } from "../core/common";
-import { warn } from "../core/warn";
-import { githubHeaders } from "../integrations/github";
+import { fetchWithRetry, IS_WINDOWS } from "../../core/common.js";
+import { warn } from "../../core/warn.js";
+import { githubHeaders } from "../../integrations/github.js";
+import { getDirname, mainPath, semverOrder } from "../../runtime.js";
 const REPO = "itlackey/akm";
 const DEFAULT_PACKAGE_NAME = "akm-cli";
 const NODE_MODULES_SEGMENT = "/node_modules/";
@@ -16,8 +17,8 @@ const PNPM_GLOBAL_INSTALL_PATTERN = /(^|\/)(?:pnpm\/global|\.pnpm-global)(?:\/\d
 /** Read live runtime signals. */
 export function getInstallSignals() {
     return {
-        bunMain: typeof Bun !== "undefined" ? Bun.main : undefined,
-        importMetaDir: import.meta.dir ?? undefined,
+        bunMain: mainPath,
+        importMetaDir: getDirname(import.meta.url),
         hasAkmVersion: typeof AKM_VERSION !== "undefined",
     };
 }
@@ -34,8 +35,8 @@ export function detectInstallMethod(signals) {
         }
         return "npm";
     }
-    // Bun-compiled binaries: Bun.main points to a virtual /$bunfs/ path,
-    // NOT process.execPath. The old check (Bun.main === process.execPath) was
+    // Bun-compiled binaries: mainPath points to a virtual /$bunfs/
+    // path, NOT process.execPath. The old check (mainPath === process.execPath) was
     // always false for compiled binaries, causing "unknown" for every binary user.
     if (s.bunMain !== undefined) {
         // Primary check: compiled binaries embed sources under /$bunfs/
@@ -77,7 +78,7 @@ export async function checkForUpdate(currentVersion) {
     return {
         currentVersion,
         latestVersion,
-        updateAvailable: latestVersion !== "" && Bun.semver.order(currentVersion, latestVersion) < 0,
+        updateAvailable: latestVersion !== "" && semverOrder(currentVersion, latestVersion) < 0,
         installMethod,
     };
 }
@@ -373,7 +374,7 @@ function normalizePathSeparators(value) {
 }
 function getInstalledPackageName() {
     try {
-        const pkgPath = path.resolve(import.meta.dir ?? __dirname, "../../package.json");
+        const pkgPath = path.resolve(getDirname(import.meta.url), "../../../package.json");
         if (fs.existsSync(pkgPath)) {
             const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf-8"));
             if (typeof pkg.name === "string" && pkg.name.trim()) {

package/dist/commands/{source-add.js → sources/source-add.js}

@@ -3,16 +3,16 @@
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
 import fs from "node:fs";
 import path from "node:path";
-import { isHttpUrl, resolveStashDir } from "../core/common";
-import { getSources, loadConfig, loadUserConfig, saveConfig } from "../core/config";
-import { ConfigError, UsageError } from "../core/errors";
-import { akmIndex } from "../indexer/indexer";
-import { upsertLockEntry } from "../integrations/lockfile";
-import { parseRegistryRef } from "../registry/resolve";
-import { detectStashRoot } from "../sources/providers/provider-utils";
-import { syncFromRef } from "../sources/providers/sync-from-ref";
-import { ensureWebsiteMirror, validateWebsiteInputUrl } from "../sources/website-ingest";
-import { ensureWikiNameAvailable, validateWikiName } from "../wiki/wiki";
+import { isHttpUrl, resolveStashDir } from "../../core/common.js";
+import { getSources, loadConfig, loadUserConfig, saveConfig } from "../../core/config/config.js";
+import { ConfigError, UsageError } from "../../core/errors.js";
+import { akmIndex } from "../../indexer/indexer.js";
+import { upsertLockEntry } from "../../integrations/lockfile.js";
+import { parseRegistryRef } from "../../registry/resolve.js";
+import { detectStashRoot } from "../../sources/providers/provider-utils.js";
+import { syncFromRef } from "../../sources/providers/sync-from-ref.js";
+import { ensureWebsiteMirror, validateWebsiteInputUrl } from "../../sources/website-ingest.js";
+import { ensureWikiNameAvailable, validateWikiName } from "../../wiki/wiki.js";
 const VALID_OVERRIDE_TYPES = new Set(["wiki"]);
 export async function akmAdd(input) {
     const ref = input.ref.trim();

package/dist/commands/{source-clone.js → sources/source-clone.js}

@@ -3,13 +3,13 @@
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
 import fs from "node:fs";
 import path from "node:path";
-import { makeAssetRef, parseAssetRef } from "../core/asset-ref";
-import { TYPE_DIRS } from "../core/asset-spec";
-import { NotFoundError, UsageError } from "../core/errors";
-import { findSourceForPath, getPrimarySource, resolveSourceEntries } from "../indexer/search-source";
-import { isRemoteOrigin, resolveSourcesForOrigin } from "../registry/origin-resolve";
-import { syncFromRef } from "../sources/providers/sync-from-ref";
-import { resolveAssetPath } from "../sources/resolve";
+import { makeAssetRef, parseAssetRef } from "../../core/asset/asset-ref.js";
+import { TYPE_DIRS } from "../../core/asset/asset-spec.js";
+import { NotFoundError, UsageError } from "../../core/errors.js";
+import { findSourceForPath, getPrimarySource, resolveSourceEntries, } from "../../indexer/search/search-source.js";
+import { isRemoteOrigin, resolveSourcesForOrigin } from "../../registry/origin-resolve.js";
+import { syncFromRef } from "../../sources/providers/sync-from-ref.js";
+import { resolveAssetPath } from "../../sources/resolve.js";
 export async function akmClone(options) {
     const parsed = parseAssetRef(options.sourceRef);
     // When --dest is provided, the working stash is optional

package/dist/commands/{source-manage.js → sources/source-manage.js}

@@ -2,10 +2,10 @@
 // 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/.
 import path from "node:path";
-import { isRemoteUrl } from "../core/common";
-import { getSources, loadConfig, loadUserConfig, saveConfig } from "../core/config";
-import { ConfigError, UsageError } from "../core/errors";
-import { resolveSourceEntries } from "../indexer/search-source";
+import { isRemoteUrl } from "../../core/common.js";
+import { getSources, loadConfig, loadUserConfig, saveConfig } from "../../core/config/config.js";
+import { ConfigError, UsageError } from "../../core/errors.js";
+import { resolveSourceEntries } from "../../indexer/search/search-source.js";
 // ── Operations ──────────────────────────────────────────────────────────────
 /**
  * Add a stash source (filesystem path or remote provider URL) to config.

package/dist/commands/sources/sources-cli.js

@@ -0,0 +1,305 @@
+// 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/.
+/**
+ * Source-management CLI commands — `akm list/remove/update/upgrade/sync/clone/history`.
+ *
+ * Extracted verbatim from src/cli.ts (WS6). Each `main.subCommands.<key>`
+ * registration line stays byte-identical; the args/output shape of every
+ * subcommand is unchanged. The `--kind` filter helper (`parseKindFilter` +
+ * `VALID_SOURCE_KINDS`), the `runSyncBody` git-commit/push body, and the
+ * `wasFormatValueConsumedAsName` citty-mis-parse workaround are used ONLY by
+ * this cluster, so they move with it.
+ *
+ * Leaf handlers whose body is a plain `runWithJsonErrors(async () => { … })`
+ * are migrated to `defineJsonCommand`, which emits the same JSON envelope
+ * (stdout/stderr/exit-code) as the inline form. `sync` keeps `defineCommand`
+ * because its `run` delegates to `runSyncBody` (which owns the
+ * `runWithJsonErrors` wrapper) rather than wrapping inline.
+ */
+import { defineCommand } from "citty";
+import { defineJsonCommand, output, runWithJsonErrors } from "../../cli/shared.js";
+import { loadConfig } from "../../core/config/config.js";
+import { UsageError } from "../../core/errors.js";
+import { appendEvent } from "../../core/events.js";
+import { resolveSourceEntries } from "../../indexer/search/search-source.js";
+import { getHyphenatedBoolean, parseFlagValue } from "../../output/context.js";
+import { resolveWritableOverride, saveGitStash } from "../../sources/providers/git.js";
+import { pkgVersion } from "../../version.js";
+import { akmHistory } from "./history.js";
+import { akmListSources, akmRemove, akmUpdate } from "./installed-stashes.js";
+import { checkForUpdate, performUpgrade } from "./self-update.js";
+import { akmClone } from "./source-clone.js";
+const VALID_SOURCE_KINDS = new Set(["local", "managed", "remote"]);
+function parseKindFilter(raw) {
+    if (!raw)
+        return undefined;
+    const kinds = raw.split(",").map((s) => s.trim());
+    for (const k of kinds) {
+        if (!VALID_SOURCE_KINDS.has(k)) {
+            throw new UsageError(`Invalid --kind value: "${k}". Expected one of: local, managed, remote`);
+        }
+    }
+    return kinds;
+}
+export const listCommand = defineJsonCommand({
+    meta: { name: "list", description: "List all sources (local directories, managed packages, remote providers)" },
+    args: {
+        kind: { type: "string", description: "Filter by source kind (local, managed, remote). Comma-separated." },
+    },
+    async run({ args }) {
+        const kind = parseKindFilter(args.kind);
+        const result = await akmListSources({ kind });
+        output("list", result);
+    },
+});
+export const removeCommand = defineJsonCommand({
+    meta: { name: "remove", description: "Remove a source by id, ref, path, URL, or name" },
+    args: {
+        target: { type: "positional", description: "Source to remove (id, ref, path, URL, or name)", required: true },
+        yes: { type: "boolean", alias: "y", description: "Skip confirmation prompt", default: false },
+    },
+    async run({ args }) {
+        const { confirmDestructive } = await import("../../cli/confirm.js");
+        const confirmed = await confirmDestructive(`Remove source "${args.target}"? This cannot be undone.`, {
+            yes: args.yes === true,
+        });
+        if (!confirmed) {
+            process.stderr.write("Aborted.\n");
+            return;
+        }
+        const result = await akmRemove({ target: args.target });
+        appendEvent({
+            eventType: "remove",
+            metadata: {
+                target: args.target,
+                ref: typeof result.removed?.ref === "string" ? result.removed.ref : null,
+                id: typeof result.removed?.id === "string" ? result.removed.id : null,
+            },
+        });
+        output("remove", result);
+    },
+});
+export const updateCommand = defineJsonCommand({
+    meta: { name: "update", description: "Update one or all managed sources" },
+    args: {
+        target: { type: "positional", description: "Source to update (id or ref)", required: false },
+        all: { type: "boolean", description: "Update all installed entries", default: false },
+        force: { type: "boolean", description: "Force fresh download even if version is unchanged", default: false },
+    },
+    async run({ args }) {
+        const result = await akmUpdate({ target: args.target, all: args.all, force: args.force });
+        appendEvent({
+            eventType: "update",
+            metadata: {
+                target: args.target ?? null,
+                all: args.all === true,
+                force: args.force === true,
+                processed: Array.isArray(result.processed)
+                    ? result.processed.length
+                    : 0,
+            },
+        });
+        output("update", result);
+    },
+});
+export const upgradeCommand = defineJsonCommand({
+    meta: { name: "upgrade", description: "Upgrade akm to the latest release" },
+    args: {
+        check: { type: "boolean", description: "Check for updates without installing", default: false },
+        force: { type: "boolean", description: "Force upgrade even if on latest", default: false },
+        "skip-checksum": {
+            type: "boolean",
+            description: "Skip checksum verification (not recommended)",
+            default: false,
+        },
+        "skip-post-upgrade": {
+            type: "boolean",
+            description: "Skip the post-upgrade `akm index` rebuild (config auto-migration still runs on next `akm` invocation)",
+            default: false,
+        },
+    },
+    async run({ args }) {
+        const check = await checkForUpdate(pkgVersion);
+        if (args.check) {
+            output("upgrade", check);
+            return;
+        }
+        const skipChecksum = getHyphenatedBoolean(args, "skip-checksum");
+        const skipPostUpgrade = getHyphenatedBoolean(args, "skip-post-upgrade");
+        const result = await performUpgrade(check, { force: args.force, skipChecksum, skipPostUpgrade });
+        output("upgrade", result);
+    },
+});
+// `sync` body. Kept as a standalone function so the git-commit/push logic and
+// the `--format`-as-name workaround stay in one place.
+async function runSyncBody(args, verb) {
+    await runWithJsonErrors(async () => {
+        // Fix: citty can consume `--format json` (space-separated) as the
+        // positional `name` argument (e.g. `akm sync --format json` parses
+        // name="json"). Detect the mis-parse by checking argv order — only
+        // treat the positional as consumed by --format when --format appears
+        // before any standalone occurrence of the same value in the sync
+        // subcommand's argv slice. This preserves legitimate invocations
+        // like `akm sync json --format json`.
+        const parsedFormat = parseFlagValue(process.argv, "--format");
+        const effectiveName = args.name !== undefined &&
+            parsedFormat !== undefined &&
+            args.name === parsedFormat &&
+            wasFormatValueConsumedAsName(args.name, parsedFormat, verb)
+            ? undefined
+            : args.name;
+        let writable;
+        if (effectiveName === undefined) {
+            // Primary stash — honour the root-level writable flag from config.
+            writable = resolveWritableOverride(loadConfig());
+        }
+        const result = saveGitStash(effectiveName, args.message, writable, { push: args.push !== false });
+        appendEvent({
+            eventType: "save",
+            metadata: {
+                name: effectiveName ?? null,
+                message: args.message ?? null,
+                ok: result.ok !== false,
+            },
+        });
+        output("save", result);
+    });
+}
+export const syncCommand = defineCommand({
+    meta: {
+        name: "sync",
+        description: "Sync changes in a git-backed stash: commits (and pushes when writable + remote is configured). No-op for non-git stashes.",
+    },
+    args: {
+        name: {
+            type: "positional",
+            description: "Name of the git stash to sync (default: primary stash directory)",
+            required: false,
+        },
+        message: {
+            type: "string",
+            alias: "m",
+            description: "Commit message (default: timestamp)",
+        },
+        push: {
+            type: "boolean",
+            description: "Push after commit when writable + remote configured (use --no-push to commit only). Default: true.",
+            default: true,
+        },
+    },
+    async run({ args }) {
+        await runSyncBody(args, "sync");
+    },
+});
+/**
+ * Detect whether `--format <value>` was consumed by citty as the optional
+ * `name` positional of `akm sync`. Returns true only when `--format` appears
+ * in the sync subcommand's argv slice AND the candidate name does NOT
+ * appear as a standalone positional elsewhere (before or after the flag).
+ *
+ * This keeps `akm sync json --format json` routing `json` as the stash name,
+ * while `akm sync --format json` (no separate positional) is treated as a
+ * primary-stash sync. `verb` is the subcommand token to anchor on.
+ */
+function wasFormatValueConsumedAsName(name, formatValue, verb) {
+    const argv = process.argv.slice(2);
+    const verbIndex = argv.indexOf(verb);
+    const tokens = verbIndex >= 0 ? argv.slice(verbIndex + 1) : argv;
+    let formatIndex = -1;
+    let formatConsumesNextToken = false;
+    for (let i = 0; i < tokens.length; i += 1) {
+        const token = tokens[i];
+        if (token === "--format") {
+            formatIndex = i;
+            formatConsumesNextToken = true;
+            break;
+        }
+        if (token === `--format=${formatValue}`) {
+            formatIndex = i;
+            break;
+        }
+    }
+    if (formatIndex === -1)
+        return false;
+    // If the name appears as a standalone token before --format, it's the
+    // real positional and --format did not consume it.
+    if (tokens.slice(0, formatIndex).includes(name))
+        return false;
+    // If --format has a space-separated value, skip past the value token
+    // when scanning after the flag; otherwise start right after the flag.
+    const firstTokenAfterFormat = formatIndex + (formatConsumesNextToken ? 2 : 1);
+    if (tokens.slice(firstTokenAfterFormat).includes(name))
+        return false;
+    return true;
+}
+export const cloneCommand = defineJsonCommand({
+    meta: {
+        name: "clone",
+        description: "Clone an asset from any source into the working stash or a custom destination",
+    },
+    args: {
+        ref: { type: "positional", description: "Asset ref (e.g. npm:@scope/pkg//script:deploy.sh)", required: true },
+        name: { type: "string", description: "New name for the cloned asset" },
+        force: { type: "boolean", description: "Overwrite if asset already exists in working stash", default: false },
+        dest: { type: "string", description: "Destination directory (default: working stash)" },
+    },
+    async run({ args }) {
+        const result = await akmClone({
+            sourceRef: args.ref,
+            newName: args.name,
+            force: args.force,
+            dest: args.dest,
+        });
+        output("clone", result);
+    },
+});
+export const historyCommand = defineJsonCommand({
+    meta: {
+        name: "history",
+        description: "Show mutation/usage history for a single asset (--ref) or stash-wide.\n\n" +
+            "Event sources:\n" +
+            "  usage_events (default): search, show, and feedback events from the local index.\n" +
+            "  state.db events (--include-proposals): proposal lifecycle events (promoted, rejected)\n" +
+            "    emitted by `akm accept` / `akm reject`.\n\n" +
+            "Results from all active sources are merged and sorted chronologically.",
+    },
+    args: {
+        ref: { type: "string", description: "Asset ref (type:name). Omit for stash-wide history." },
+        since: { type: "string", description: "ISO timestamp or epoch ms — only events on/after this time" },
+        generator: {
+            type: "string",
+            description: 'Filter by event generator: "user" (default) or "improve" (akm improve operations).',
+        },
+        "include-proposals": {
+            type: "boolean",
+            description: "Also include proposal lifecycle events (promoted, rejected) from state.db events. " +
+                "Default: false (usage_events only).",
+            default: false,
+        },
+        "accept-rate-by-source": {
+            type: "boolean",
+            description: "Compute accept-rate-per-source metrics from the proposal store and include them in the output (F-4 / #385). " +
+                "Useful for measuring which generators (reflect, distill, …) produce the most accepted proposals.",
+            default: false,
+        },
+        format: { type: "string", description: "Output format (json|jsonl|text|yaml)" },
+    },
+    async run({ args }) {
+        const generatorFlag = args.generator;
+        if (generatorFlag !== undefined && generatorFlag !== "user" && generatorFlag !== "improve") {
+            throw new UsageError(`Invalid --generator value: "${generatorFlag}". Must be "user" or "improve".`, "INVALID_FLAG_VALUE");
+        }
+        const sources = resolveSourceEntries();
+        const stashDir = sources[0]?.path;
+        const result = await akmHistory({
+            ref: args.ref,
+            since: args.since,
+            source: generatorFlag,
+            includeProposals: args["include-proposals"],
+            acceptRateBySource: args["accept-rate-by-source"],
+            stashDir,
+        });
+        output("history", result);
+    },
+});