akm-cli 0.9.30 → 0.10.261001-beta

package/dist/commands/sources/plugin-upgrade.js

@@ -13,13 +13,14 @@ import * as childProcess from "node:child_process";
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
-import { IS_WINDOWS, stripJsonComments } from "../../core/common.js";
+import { IS_WINDOWS, parseJsonc } from "../../core/common.js";
 import { moveToTrash } from "../../core/trash.js";
+import { OPENCODE_SDK_SERVER_BIN } from "../../integrations/agent/profiles.js";
+import { OPENCODE_V1, OPENCODE_V2, readPackageVersion, } from "../../integrations/harnesses/opencode/plugin-layout.js";
+import { detectOpencodeMajor, resolveOpencodeBin } from "../../integrations/harnesses/opencode/version.js";
 import { semverOrder } from "../../runtime.js";
 const MARKETPLACE = "akm-plugins";
 const PLUGIN_ID = `akm@${MARKETPLACE}`;
-const OPENCODE_PACKAGE = "akm-opencode";
-const OPENCODE_NEXT_SPEC = `${OPENCODE_PACKAGE}@next`;
 const READ_TIMEOUT_MS = 30_000;
 const REFRESH_TIMEOUT_MS = 120_000;
 const PREFETCH_TIMEOUT_MS = 180_000;
@@ -137,20 +138,33 @@ function upgradeCodex(dryRun) {
     const after = codexPluginVersion();
     return refreshed("codex", before.version, "version" in after ? after.version : undefined);
 }
+// ── OpenCode ────────────────────────────────────────────────────────────────
+const nextSpec = (flavor) => `${flavor.pkg}@next`;
 function homeDir() {
     return process.env.HOME?.trim() || process.env.USERPROFILE?.trim() || os.homedir();
 }
+function openCodeCacheHome() {
+    const cacheHome = process.env.XDG_CACHE_HOME?.trim() || path.join(homeDir(), ".cache");
+    return path.join(cacheHome, "opencode");
+}
+/** The spec in a config's plugin entry (a spec string or a `[spec, options]` pair). */
+function entrySpec(entry) {
+    const spec = Array.isArray(entry) ? entry[0] : entry;
+    return typeof spec === "string" ? spec : undefined;
+}
+const namesPackage = (spec, pkg) => spec === pkg || spec.startsWith(`${pkg}@`);
 /**
- * The `akm-opencode` spec the user's global OpenCode config names (bare,
- * `@latest`, `@next`, an exact version, ...), or undefined when none does.
- * OpenCode caches each spec in its own folder, so this says which cache it
- * loads. The config is only read, never written; project configs are not
- * looked at (akm does not know which project OpenCode runs in).
+ * The plugin spec the user's global OpenCode config names for this flavor's
+ * package (bare, `@latest`, `@next`, an exact version, ...), with the config key
+ * it sits under, or undefined when none does. OpenCode caches each spec in its
+ * own folder, so this says which cache it loads. The config is only read, never
+ * written; project configs are not looked at (akm does not know which project
+ * OpenCode runs in).
  */
-export function openCodeConfigSpec() {
+export function openCodeConfigSpec(flavor) {
     const configHome = process.env.XDG_CONFIG_HOME?.trim() || path.join(homeDir(), ".config");
     const files = [
-        process.env.OPENCODE_CONFIG?.trim(),
+        flavor.globalConfigOnly ? undefined : process.env.OPENCODE_CONFIG?.trim(),
         path.join(configHome, "opencode", "opencode.json"),
         path.join(configHome, "opencode", "opencode.jsonc"),
     ];
@@ -158,14 +172,15 @@ export function openCodeConfigSpec() {
         if (!file)
             continue;
         try {
-            const config = JSON.parse(stripJsonComments(fs.readFileSync(file, "utf8")));
-            if (!Array.isArray(config.plugin))
-                continue;
-            // An entry is a spec string or a `[spec, options]` pair.
-            for (const entry of config.plugin) {
-                const spec = Array.isArray(entry) ? entry[0] : entry;
-                if (typeof spec === "string" && (spec === OPENCODE_PACKAGE || spec.startsWith(`${OPENCODE_PACKAGE}@`))) {
-                    return spec;
+            const config = parseJsonc(fs.readFileSync(file, "utf8"));
+            for (const key of flavor.configKeys) {
+                const entries = config[key];
+                if (!Array.isArray(entries))
+                    continue;
+                for (const entry of entries) {
+                    const spec = entrySpec(entry);
+                    if (spec !== undefined && namesPackage(spec, flavor.pkg))
+                        return { spec, key };
                 }
             }
         }
@@ -175,30 +190,32 @@ export function openCodeConfigSpec() {
     }
     return undefined;
 }
+/** Whether OpenCode 2 has ever cached `akm-opencode-v2` on this host. */
+function openCodeV2Cached() {
+    try {
+        return fs
+            .readdirSync(path.join(openCodeCacheHome(), OPENCODE_V2.cacheFolder("")))
+            .some((name) => name.startsWith(`${OPENCODE_V2.pkg}@`));
+    }
+    catch {
+        return false;
+    }
+}
 /**
- * The cached `akm-opencode` OpenCode installed on first use, or undefined when
- * there is none. OpenCode names the folder after the spec it resolved, so a
- * bare `akm-opencode` lands in `@latest` and `akm-opencode@next` in `@next`.
+ * The cached plugin OpenCode installed on first use, or undefined when there is
+ * none. OpenCode names the folder after the spec it resolved, so a bare package
+ * lands in `@latest` and `<pkg>@next` in `@next`.
  */
-export function detectOpenCodeCache(tag = "latest") {
-    const cacheHome = process.env.XDG_CACHE_HOME?.trim() || path.join(homeDir(), ".cache");
-    const dir = path.join(cacheHome, "opencode", "packages", `${OPENCODE_PACKAGE}@${tag}`);
+export function detectOpenCodeCache(tag, flavor) {
+    const dir = path.join(openCodeCacheHome(), flavor.cacheFolder(`${flavor.pkg}@${tag}`));
     if (!fs.existsSync(dir))
         return undefined;
-    const readVersion = (file) => {
-        try {
-            const pkg = JSON.parse(fs.readFileSync(file, "utf8"));
-            return typeof pkg.version === "string" ? pkg.version : undefined;
-        }
-        catch {
-            return undefined;
-        }
-    };
-    return { dir, version: readVersion(path.join(dir, "node_modules", OPENCODE_PACKAGE, "package.json")) };
+    const nodeModules = flavor.nodeModulesDir(dir);
+    return { dir, version: nodeModules && readPackageVersion(path.join(nodeModules, flavor.pkg, "package.json")) };
 }
-/** What npm's `akm-opencode@<tag>` is, and which akm-cli it pins. */
-export function lookupOpenCodeLatest(tag = "latest") {
-    const spec = `${OPENCODE_PACKAGE}@${tag}`;
+/** What npm's `<pkg>@<tag>` is, and which akm-cli it pins. */
+export function lookupOpenCodeLatest(tag, flavor) {
+    const spec = `${flavor.pkg}@${tag}`;
     const view = runCommand(IS_WINDOWS ? "npm.cmd" : "npm", ["view", spec, "version", "dependencies.akm-cli", "--json"], READ_TIMEOUT_MS);
     if (!view.ok)
         return { error: view.error };
@@ -209,7 +226,7 @@ export function lookupOpenCodeLatest(tag = "latest") {
     return { version: parsed.version, akmCli: typeof akmCli === "string" ? akmCli : undefined };
 }
 /**
- * `akm-opencode@next`, which must exist and pin an akm-cli no older than the one
+ * `<pkg>@next`, which must exist and pin an akm-cli no older than the one
  * `@latest` pins: a prerelease channel that trails the stable one is not a target.
  *
  * The two builds are compared by their akm-cli pins, never by their own
@@ -220,23 +237,23 @@ export function lookupOpenCodeLatest(tag = "latest") {
  * (#1089). For the same reason plugin versions are only ever tested for
  * equality (is the cache already this build?), never ordered.
  */
-export function lookupOpenCodeNext() {
-    const next = lookupOpenCodeLatest("next");
+export function lookupOpenCodeNext(flavor) {
+    const next = lookupOpenCodeLatest("next", flavor);
     if ("error" in next)
         return next;
-    const latest = lookupOpenCodeLatest("latest");
+    const latest = lookupOpenCodeLatest("latest", flavor);
     if ("error" in latest)
-        return { error: `could not compare with ${OPENCODE_PACKAGE}@latest: ${latest.error}` };
+        return { error: `could not compare with ${flavor.pkg}@latest: ${latest.error}` };
     // No pin on @next: returned as is, and the lockstep holds the CLI and says why.
     if (!next.akmCli)
         return next;
     if (!latest.akmCli) {
-        return { error: `could not compare with ${OPENCODE_PACKAGE}@latest: it declares no akm-cli dependency` };
+        return { error: `could not compare with ${flavor.pkg}@latest: it declares no akm-cli dependency` };
     }
     if (semverOrder(next.akmCli, latest.akmCli) < 0) {
         return {
-            error: `${OPENCODE_NEXT_SPEC} (${next.version}) pins akm-cli ${next.akmCli}, older than the ` +
-                `${latest.akmCli} that ${OPENCODE_PACKAGE}@latest (${latest.version}) pins`,
+            error: `${nextSpec(flavor)} (${next.version}) pins akm-cli ${next.akmCli}, older than the ` +
+                `${latest.akmCli} that ${flavor.pkg}@latest (${latest.version}) pins`,
         };
     }
     return next;
@@ -296,28 +313,31 @@ function openCodeRunning() {
         return undefined;
     }
 }
-const NOT_FOLLOWING_NEXT = `--next: OpenCode resolves a bare "${OPENCODE_PACKAGE}" to @latest, so it is not updated to a prerelease; ` +
-    `set "plugin": ["${OPENCODE_NEXT_SPEC}"] in your OpenCode config to follow prereleases`;
+const notFollowingNext = (flavor) => `--next: OpenCode resolves a bare "${flavor.pkg}" to @latest, so it is not updated to a prerelease; ` +
+    `set "${flavor.configKeys[0]}": ["${nextSpec(flavor)}"] in your OpenCode config to follow prereleases`;
 /** Why a run leaves alone an OpenCode whose config names a spec this run does not refresh (#1115, #1117). */
-function otherSpecNote(spec) {
+function otherSpecNote(flavor, spec) {
     const loads = `OpenCode loads "${spec}" (your OpenCode config), so this upgrade leaves it alone`;
-    return spec === OPENCODE_NEXT_SPEC
-        ? `${loads}; run \`akm upgrade --next\` to update it, or set "plugin": ["${OPENCODE_PACKAGE}"] to follow stable releases`
-        : `${loads}; set "plugin": ["${OPENCODE_PACKAGE}"] to have \`akm upgrade\` keep it current`;
+    const key = flavor.configKeys[0];
+    return spec === nextSpec(flavor)
+        ? `${loads}; run \`akm upgrade --next\` to update it, or set "${key}": ["${flavor.pkg}"] to follow stable releases`
+        : `${loads}; set "${key}": ["${flavor.pkg}"] to have \`akm upgrade\` keep it current`;
 }
-function upgradeOpenCode(dryRun, cache, latest, tag, notFollowingNext, otherSpec) {
+function upgradeOpenCode(dryRun, target) {
+    const { flavor, cache, latest, tag, skip } = target;
+    const harness = flavor.harness;
     // Refreshing a cache OpenCode does not load would trash one it never re-creates (#1115, #1117).
-    if (otherSpec)
-        return skipped("opencode", otherSpecNote(otherSpec));
+    if (skip)
+        return skipped(harness, skip);
     if (!cache || !latest)
-        return skipped("opencode", `no cached ${OPENCODE_PACKAGE}@${tag} plugin`);
+        return skipped(harness, `no cached ${flavor.pkg}@${tag} plugin`);
     if ("error" in latest)
-        return failed("opencode", latest.error);
-    if (notFollowingNext)
-        return skipped("opencode", NOT_FOLLOWING_NEXT);
+        return failed(harness, latest.error);
+    if (target.notFollowingNext)
+        return skipped(harness, notFollowingNext(flavor));
     if (cache.version === latest.version)
-        return { harness: "opencode", outcome: "current", from: cache.version, to: latest.version };
-    const base = { harness: "opencode", from: cache.version, to: latest.version };
+        return { harness, outcome: "current", from: cache.version, to: latest.version };
+    const base = { harness, from: cache.version, to: latest.version };
     const running = openCodeRunning();
     if (running !== false) {
         return {
@@ -330,30 +350,39 @@ function upgradeOpenCode(dryRun, cache, latest, tag, notFollowingNext, otherSpec
     }
     if (dryRun)
         return { ...base, outcome: "pending" };
-    // OpenCode must be runnable before the cache goes: it does the prefetch.
-    const probe = runCommand("opencode", ["--version"], READ_TIMEOUT_MS);
-    if (!probe.ok)
-        return skipped("opencode", probe.missing ? "opencode is not on PATH" : probe.error);
+    // OpenCode must be runnable before the cache goes: it does the prefetch, and only the major
+    // that owns this plugin's cache can re-create it. akm never installs or replaces the binary.
+    // OpenCode 2 may sit beside an OpenCode 1 `opencode` as `opencode2`; OpenCode 1 is only ever `opencode`.
+    const bin = flavor.major === 2 ? resolveOpencodeBin() : OPENCODE_SDK_SERVER_BIN;
+    const detected = detectOpencodeMajor(bin);
+    if (!detected.runnable)
+        return skipped(harness, `${bin} is not on PATH or \`${bin} --version\` failed`);
+    const major = detected.reportedMajor;
+    // OpenCode 1 keeps its long-standing behavior when the version cannot be read; OpenCode 2's
+    // refresh needs a command only OpenCode 2 has, so it must be sure.
+    if (major === undefined ? flavor.major === 2 : major !== flavor.major) {
+        return skipped(harness, `\`${bin}\` on PATH is ${major === undefined ? "of an unknown version" : `OpenCode ${major}`}, ` +
+            `not OpenCode ${flavor.major}, so it cannot re-create the ${flavor.pkg} cache; the cache is left alone`);
+    }
     try {
         moveToTrash(cache.dir);
     }
     catch (error) {
-        return failed("opencode", `could not move ${cache.dir} to the trash: ${error instanceof Error ? error.message : String(error)}`);
+        return failed(harness, `could not move ${cache.dir} to the trash: ${error instanceof Error ? error.message : String(error)}`);
     }
-    // Any OpenCode command that resolves the config installs the plugin again;
-    // from a temp dir, so no project's opencode.json is read.
+    // From a temp dir, so no project's opencode.json is read.
     const workDir = fs.mkdtempSync(path.join(os.tmpdir(), "akm-opencode-prefetch-"));
     try {
-        const prefetch = runCommand("opencode", ["debug", "config"], PREFETCH_TIMEOUT_MS, { cwd: workDir });
+        const prefetch = runCommand(bin, flavor.prefetch(target.spec), PREFETCH_TIMEOUT_MS, { cwd: workDir });
         if (!prefetch.ok)
-            return failed("opencode", `${prefetch.error} (the old cache is in the trash)`);
+            return failed(harness, `${prefetch.error} (the old cache is in the trash)`);
     }
     finally {
         fs.rmSync(workDir, { recursive: true, force: true });
     }
-    const after = detectOpenCodeCache(tag);
+    const after = detectOpenCodeCache(tag, flavor);
     if (!after)
-        return failed("opencode", "opencode did not re-create the plugin cache (the old cache is in the trash)");
+        return failed(harness, "opencode did not re-create the plugin cache (the old cache is in the trash)");
     return { ...base, outcome: "updated", to: after.version ?? latest.version };
 }
 // ── Orchestration ───────────────────────────────────────────────────────────
@@ -365,18 +394,17 @@ function withNextNote(entry) {
     return { ...entry, message: entry.message ? `${entry.message}; ${NO_PRERELEASE_CHANNEL}` : NO_PRERELEASE_CHANNEL };
 }
 export function upgradePlugins(opts) {
-    const { cache, latest, tag, notFollowingNext, otherSpec } = opts.openCode;
     const claude = upgradeClaudeCode(opts.dryRun);
     const codex = upgradeCodex(opts.dryRun);
     return [
         opts.next ? withNextNote(claude) : claude,
         opts.next ? withNextNote(codex) : codex,
-        upgradeOpenCode(opts.dryRun, cache, latest, tag, notFollowingNext, otherSpec),
+        ...opts.openCode.map((target) => upgradeOpenCode(opts.dryRun, target)),
     ];
 }
 /**
- * When the OpenCode plugin is present the CLI target is the akm-cli that
- * `akm-opencode@latest` pins, not the newest release: the plugin runs that
+ * When an OpenCode plugin is present the CLI target is the akm-cli that
+ * `<pkg>@latest` pins, not the newest release: the plugin runs that
  * exact akm in-process, against databases a newer CLI may already have
  * migrated. The CLI never moves backwards to meet the pin.
  *
@@ -386,7 +414,7 @@ export function upgradePlugins(opts) {
  * `lockstep.reason` says why. Moving the CLI ahead of a pin nobody could read is
  * what lockstep exists to prevent; the OpenCode entry reports the failure.
  */
-export function applyLockstep(check, latest, tag = "latest") {
+export function applyLockstep(check, latest, tag, pkg) {
     if (!latest)
         return check;
     // Held back only when there is a release this upgrade would otherwise install.
@@ -394,14 +422,14 @@ export function applyLockstep(check, latest, tag = "latest") {
     const pinned = "error" in latest ? undefined : latest.akmCli;
     if (!pinned) {
         const reason = "error" in latest
-            ? `could not read the akm-cli pin of ${OPENCODE_PACKAGE}@${tag}: ${latest.error}`
-            : `${OPENCODE_PACKAGE}@${tag} declares no akm-cli dependency`;
+            ? `could not read the akm-cli pin of ${pkg}@${tag}: ${latest.error}`
+            : `${pkg}@${tag} declares no akm-cli dependency`;
         return {
             ...check,
             latestVersion: check.currentVersion,
             updateAvailable: false,
             lockstep: {
-                plugin: OPENCODE_PACKAGE,
+                plugin: pkg,
                 pinnedVersion: null,
                 newestVersion: check.latestVersion,
                 heldBack: wouldInstall,
@@ -411,7 +439,7 @@ export function applyLockstep(check, latest, tag = "latest") {
     }
     const heldBack = semverOrder(pinned, check.latestVersion) < 0 && wouldInstall;
     const lockstep = {
-        plugin: OPENCODE_PACKAGE,
+        plugin: pkg,
         pinnedVersion: pinned,
         newestVersion: check.latestVersion,
         heldBack,
@@ -426,40 +454,75 @@ export function applyLockstep(check, latest, tag = "latest") {
     };
 }
 /**
- * Which OpenCode plugin build the CLI is held to, and which cache refreshes.
- * Under `--next` that is `akm-opencode@next`, but only when the user's OpenCode
+ * The plugin the CLI is held to when several are present: one whose pin could not be read (the
+ * CLI stays put), else the one pinning the oldest akm-cli, since every plugin runs the CLI that is installed.
+ */
+function lockstepSource(targets) {
+    const readable = (t) => t.latest !== undefined && !("error" in t.latest) && typeof t.latest.akmCli === "string";
+    const pinned = targets.filter((t) => t.latest);
+    return (pinned.find((t) => !readable(t)) ??
+        pinned.filter(readable).sort((a, b) => semverOrder(a.latest.akmCli, b.latest.akmCli))[0]);
+}
+/**
+ * Which build of one OpenCode plugin the CLI is held to, and which cache refreshes.
+ * Under `--next` that is `<pkg>@next`, but only when the user's OpenCode
  * config names that tag: a bare one keeps resolving `@latest`, so the lockstep
  * stays against the `@latest` pin and the entry is reported as skipped. A config
  * naming any other spec (an exact version, or `@next` on a plain run) is left
  * alone, with no lockstep.
  */
-function resolveOpenCodeTarget(next) {
-    // No config entry behaves like a bare one: OpenCode would resolve @latest.
-    const spec = openCodeConfigSpec() ?? OPENCODE_PACKAGE;
-    const followsLatest = spec === OPENCODE_PACKAGE || spec === `${OPENCODE_PACKAGE}@latest`;
-    const followNext = next && spec === OPENCODE_NEXT_SPEC;
-    // Any other spec loads a cache this run does not refresh, and pins no akm-cli it should be held to.
-    if (!followsLatest && !followNext) {
-        return {
-            cache: undefined,
-            latest: undefined,
-            tag: next ? "next" : "latest",
-            notFollowingNext: false,
-            otherSpec: spec,
-        };
+function resolveOpenCodeTarget(next, flavor, configured) {
+    // OpenCode 1 with no config entry behaves like a bare one: it would resolve @latest. OpenCode 2's
+    // re-fetch writes the config, so its plugin is only refreshed where the config already names it.
+    const spec = configured?.spec ?? flavor.pkg;
+    const leftAlone = (skip) => ({
+        flavor,
+        cache: undefined,
+        latest: undefined,
+        tag: next ? "next" : "latest",
+        spec,
+        notFollowingNext: false,
+        skip,
+    });
+    if (flavor.globalConfigOnly) {
+        if (!configured) {
+            return leftAlone(`OpenCode's global config does not name ${flavor.pkg}; this upgrade only refreshes a plugin it names`);
+        }
+        if (configured.key !== flavor.configKeys[0]) {
+            return leftAlone(`OpenCode loads "${spec}" from the "${configured.key}" key of your config; move it to "${flavor.configKeys[0]}" ` +
+                "to have `akm upgrade` keep it current");
+        }
     }
+    const followsLatest = spec === flavor.pkg || spec === `${flavor.pkg}@latest`;
+    const followNext = next && spec === nextSpec(flavor);
+    // Any other spec loads a cache this run does not refresh, and pins no akm-cli it should be held to.
+    if (!followsLatest && !followNext)
+        return leftAlone(otherSpecNote(flavor, spec));
     const tag = followNext ? "next" : "latest";
-    const cache = detectOpenCodeCache(tag);
-    const latest = cache ? (followNext ? lookupOpenCodeNext() : lookupOpenCodeLatest()) : undefined;
-    return { cache, latest, tag, notFollowingNext: next && !followNext };
+    const cache = detectOpenCodeCache(tag, flavor);
+    const latest = cache ? (followNext ? lookupOpenCodeNext(flavor) : lookupOpenCodeLatest("latest", flavor)) : undefined;
+    return { flavor, cache, latest, tag, spec, notFollowingNext: next && !followNext };
+}
+/**
+ * The OpenCode plugins this host has: OpenCode 1's always, OpenCode 2's only when the global config
+ * names `akm-opencode-v2` or OpenCode 2 has cached it, so a host with just OpenCode 1 sees the same
+ * output as before.
+ */
+function resolveOpenCodeTargets(next) {
+    const targets = [resolveOpenCodeTarget(next, OPENCODE_V1, openCodeConfigSpec(OPENCODE_V1))];
+    const v2 = openCodeConfigSpec(OPENCODE_V2);
+    if (v2 || openCodeV2Cached())
+        targets.push(resolveOpenCodeTarget(next, OPENCODE_V2, v2));
+    return targets;
 }
 /** `akm upgrade`: the CLI step (held to the OpenCode plugin's akm), then the plugins. */
 export async function runUpgrade(args, currentVersion, deps) {
     const next = args.next === true;
     const channel = next ? "next" : "latest";
-    const openCode = resolveOpenCodeTarget(next);
+    const openCode = resolveOpenCodeTargets(next);
+    const held = lockstepSource(openCode);
     const check = {
-        ...applyLockstep(await deps.checkForUpdate(currentVersion, channel), openCode.latest, openCode.tag),
+        ...applyLockstep(await deps.checkForUpdate(currentVersion, channel), held?.latest, held?.tag ?? "latest", held?.flavor.pkg ?? OPENCODE_V1.pkg),
         channel,
     };
     if (args.check) {

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

@@ -26,10 +26,8 @@
  * `akm sync` directly).
  */
 import { defineCommand } from "citty";
-import { getParsedInvocation } from "../../cli/invocation.js";
 import { defineJsonCommand, EXIT_CODES, GLOBAL_OUTPUT_ARGS, output, outputWithExitCode, 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 { resolveWritableOverride, saveGitStash } from "../../sources/providers/git.js";
 import { pkgVersion } from "../../version.js";
@@ -40,7 +38,7 @@ export const upgradeCommand = defineJsonCommand({
     meta: {
         name: "upgrade",
         description: "Upgrade akm to the latest release, then update the akm plugin of each installed harness " +
-            "(Claude Code, Codex, OpenCode). With the OpenCode plugin installed, akm moves to the version that plugin pins.",
+            "(Claude Code, Codex, OpenCode 1 and 2). With an OpenCode plugin installed, akm moves to the version that plugin pins.",
     },
     args: {
         check: {
@@ -126,17 +124,6 @@ export const syncCommand = defineCommand({
         await runSyncBody(args);
     },
 });
-/**
- * `--target` was renamed to `--bundle` on `clone` in 0.9 (S8). citty is
- * non-strict, so the retired spelling is silently absorbed rather than
- * rejected — the asset then lands in the default bundle instead of the one
- * the caller named, with exit 0 and no error. Reject it explicitly instead.
- */
-function rejectRetiredCloneTargetFlag() {
-    if (!getParsedInvocation().hasFlag("--target"))
-        return;
-    throw new UsageError("`akm clone --target` was renamed to `--bundle` in 0.9. Use `--bundle <name>` instead.", "INVALID_FLAG_VALUE");
-}
 export const cloneCommand = defineJsonCommand({
     meta: {
         name: "clone",
@@ -153,7 +140,6 @@ export const cloneCommand = defineJsonCommand({
         dest: { type: "string", description: "Unmanaged destination directory (cannot be combined with --bundle)" },
     },
     async run({ args }) {
-        rejectRetiredCloneTargetFlag();
         const result = await akmClone({
             sourceRef: args.ref,
             newName: args.name,

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

@@ -30,22 +30,20 @@
 import path from "node:path";
 import { defineCommand } from "citty";
 import * as p from "../../cli/clack.js";
-import { getParsedInvocation } from "../../cli/invocation.js";
 import { defineJsonCommand, GLOBAL_OUTPUT_ARGS, output, parseAllFlagValues, runWithJsonErrors } from "../../cli/shared.js";
 import { assertFlatAssetName } from "../../core/asset/asset-create.js";
 import { placementTypes } from "../../core/asset/asset-placement.js";
 import { parseFrontmatter } from "../../core/asset/frontmatter.js";
 import { isHttpUrl, resolveStashDir } from "../../core/common.js";
 import { loadConfig } from "../../core/config/config.js";
-import { UsageError } from "../../core/errors.js";
 import { appendEvent } from "../../core/events.js";
 import { resolveBundleWriteTarget } from "../../core/mutation-target.js";
-import { getCacheDir } from "../../core/paths.js";
+import { getRunLogDir } from "../../core/paths.js";
 import { clearLogFile, info, isVerbose, setLogFile } from "../../core/warn.js";
 import { resolveWriteTarget } from "../../core/write-source.js";
 import { releaseIndexRebuildLock, tryAcquireIndexRebuildLock } from "../../indexer/index-rebuild-lock.js";
 import { akmIndex } from "../../indexer/indexer.js";
-import { getHyphenatedBoolean, getOutputMode } from "../../output/context.js";
+import { getOutputMode } from "../../output/context.js";
 import { pkgVersion } from "../../version.js";
 import { inferAssetName, mergeXrefsIntoContent, readKnowledgeInput, resolveSupersedesForWrite, resolveSupersedesWriteTarget, resolveXrefsForWrite, writeMarkdownAsset, } from "../read/knowledge.js";
 import { assembleInfo } from "./info.js";
@@ -56,7 +54,7 @@ export const indexCommand = defineCommand({
     args: {
         // R-051: `index` is a raw `defineCommand` (not `defineJsonCommand`), so it
         // does not get `GLOBAL_OUTPUT_ARGS` for free. `--format`/`--detail`/
-        // `--shape`/`--output` already parsed correctly here (this command has no
+        // `--output` already parsed correctly here (this command has no
         // extra positional for a stray value to fall into), so this is purely a
         // `--help` visibility / consistency fix, not a behavior change.
         ...GLOBAL_OUTPUT_ARGS,
@@ -84,12 +82,6 @@ export const indexCommand = defineCommand({
     },
     async run({ args }) {
         await runWithJsonErrors(async () => {
-            if (getHyphenatedBoolean(args, "enrich") || getParsedInvocation().getFlagValue("--enrich") !== undefined) {
-                throw new UsageError("`akm index --enrich` has been removed. Metadata enrichment during indexing is retired; it never runs.");
-            }
-            if (getHyphenatedBoolean(args, "re-enrich") || getParsedInvocation().getFlagValue("--re-enrich") !== undefined) {
-                throw new UsageError("`akm index --re-enrich` has been removed. Metadata enrichment during indexing is retired; there is nothing to re-enrich.");
-            }
             // #956: opt-in, non-blocking rebuild lock — never gates a human-typed
             // `akm index` (it only warns and contends), but a scheduled/opportunistic
             // caller can pass --skip-if-locked to step aside instead of piling up
@@ -116,7 +108,7 @@ export const indexCommand = defineCommand({
             const abort = () => controller.abort(new Error("index interrupted"));
             process.once("SIGINT", abort);
             process.once("SIGTERM", abort);
-            const indexLogFile = path.join(getCacheDir(), "logs", "index", `${new Date().toISOString().replace(/[:.]/g, "-")}.log`);
+            const indexLogFile = path.join(getRunLogDir("index"), `${new Date().toISOString().replace(/[:.]/g, "-")}.log`);
             setLogFile(indexLogFile);
             const verbose = isVerbose();
             const spin = !verbose && outputMode.format === "text" ? p.spinner() : null;
@@ -229,7 +221,7 @@ export const importKnowledgeCommand = defineJsonCommand({
             description: "Overwrite an existing knowledge document with the same name",
             default: false,
         },
-        target: {
+        bundle: {
             type: "string",
             description: "Override the write destination. Accepts a source name from your config; falls back to defaultWriteTarget then the working bundle.",
         },
@@ -250,7 +242,7 @@ export const importKnowledgeCommand = defineJsonCommand({
         // read/write so an unresolvable ref (UsageError → exit 2) leaves the
         // stash untouched.
         const rawSupersedes = parseAllFlagValues("--supersedes");
-        const writeTarget = resolveSupersedesWriteTarget(rawSupersedes, args.target);
+        const writeTarget = resolveSupersedesWriteTarget(rawSupersedes, args.bundle);
         const xrefs = resolveXrefsForWrite(parseAllFlagValues("--xref"), writeTarget);
         // Collect and validate --supersedes occurrences (repeatable). Same
         // before-any-read/write contract: an unresolvable ref exits 2 with nothing