akm-cli 0.10.261018-beta → 0.10.261020-beta

package/CHANGELOG.md

@@ -6,6 +6,31 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [0.10.261020] - 2026-10-29
+
+### Added
+
+- `akm upgrade --channel latest|next` switches the CLI and installed Claude,
+  Codex and OpenCode plugins together, preserving unrelated native settings and
+  writing backups. `--check` shows channel mismatches; an older target requires
+  `--allow-downgrade` (#1285).
+
+### Fixed
+
+- Claude plugin health uses native installation, scope and enabled metadata
+  instead of choosing the highest cached version. It reads `AKM_MIN_VERSION`
+  as well as the legacy range, and reports uncertain selections as unknown (#1286).
+- Repeated fenced identifiers contribute once per document to search content,
+  reducing repetition bias while retaining distinct code names. Existing
+  content projections and embedding inputs refresh on the next index pass (#1284).
+
+## [0.10.261019] - 2026-10-29
+
+The first stable release of the 0.10 line, published to npm `latest`. Its
+changes are in the 0.10 sections below; the upgrade from 0.9 is in
+[the 0.9 to 0.10 migration guide](docs/migration/v0.9-to-v0.10.md) and
+`akm help migrate 0.10.261019`.
+
 ## [0.10.261018] - 2026-10-29
 
 ### Fixed

package/dist/commands/health/plugin-staleness.js

@@ -2,51 +2,11 @@
 // 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/.
 /**
- * `plugin-version` advisory for `akm health` (itlackey/akm#832).
- *
- * #828 was filed as a CLI bug — session extraction failing on 232/234 runs —
- * and took a full investigation to resolve. The actual cause: the harness
- * plugin (`akm@akm-plugins`, installed in Claude Code's plugin cache) was
- * three days stale relative to the fix, and its own `AKM_VERSION_RANGE` gate
- * had nothing to do with it — the plugin was simply running old code. Every
- * fact needed to reach that conclusion in one step was already on disk:
- *
- *   - installed plugin version: `~/.claude/plugins/cache/<marketplace>/akm/<version>/.claude-plugin/plugin.json`
- *   - the plugin's own akm-cli compatibility contract: `<pluginDir>/shared/akm-version.ts`'s `AKM_VERSION_RANGE`
- *   - the running CLI's version: `../../version.ts`'s `pkgVersion`
- *
- * Nothing correlated them, so a stale plugin was indistinguishable from a
- * broken CLI. This module closes that gap with three checks, one per
- * detected plugin:
- *
- *   1. report the installed version;
- *   2. compare it against the newest tag published to the plugin's git
- *      remote, and warn (naming the update command) when behind;
- *   3. the sharp one — check whether the *installed plugin's* declared
- *      `AKM_VERSION_RANGE` admits the *running* CLI version. When it does
- *      not, the plugin has silently disabled itself (both surfaces log
- *      `version_out_of_range` / `akm_version_mismatch` and degrade quietly)
- *      and there was previously no way to know that from the CLI side.
- *
- * Read-only: this never fetches, writes, or mutates the plugin cache or
- * marketplace clone. Check 2 is one of two deliberate exceptions to "`akm
- * health` makes no network call" (see `./health-advisories.md`; the other is
- * the `cli-version` advisory in `./version-drift.ts`, #950): a plugin's
- * local marketplace clone is not proof of what is newest upstream — the
- * incident above involved a clone that hadn't seen the fix's tag at all — so
- * the only way to ever detect drift is to ask the remote what tags exist.
- * That query is a `git ls-remote --symref` (lists refs; fetches nothing,
- * writes nothing) with a short timeout, and any failure (offline, no
- * remote, timeout) degrades to "installed version reported, no staleness
- * claim" rather than a false positive or a hang. Like `cli-version`, this
- * check is gated behind `--probe`/`--no-probe`: with probing off the remote is
- * not asked, the row reports `unknown` ("not probed") and only the local range
- * check (3) runs.
- *
- * Every collector here is best-effort and silent on missing/unreadable
- * input: no Claude plugin installed, no marketplace clone, an unreadable
- * manifest, or a malformed version range must never crash `akm health` and
- * must never produce a false "stale" or "inactive" warning.
+ * Report the installations Claude's native listing selects, not the versions
+ * left in its cache. The listing owns scope and merged enabled settings; it
+ * cannot prove what an already-running session has loaded. Ambiguous scoped
+ * installations and unavailable compatibility contracts are reported as unknown.
+ * Remote release checks remain optional under --no-probe.
  */
 import { spawnSync } from "node:child_process";
 import fs from "node:fs";
@@ -64,7 +24,9 @@ import { openCodeConfigSpec } from "../sources/plugin-upgrade.js";
  * `AKM_CLAUDE_PROJECTS_DIR` in `../../integrations/harnesses/claude/session-log.ts`.
  */
 function claudePluginsDir() {
-    return process.env.AKM_CLAUDE_PLUGINS_DIR ?? path.join(os.homedir(), ".claude", "plugins");
+    return (process.env.AKM_CLAUDE_PLUGINS_DIR ??
+        process.env.CLAUDE_CODE_PLUGIN_CACHE_DIR ??
+        path.join(process.env.CLAUDE_CONFIG_DIR ?? path.join(os.homedir(), ".claude"), "plugins"));
 }
 /**
  * Root of OpenCode's package cache, same override pattern as
@@ -159,74 +121,90 @@ function buildOpencodeBundledAdvisory(plugin, bundled, cliVersion) {
         evidence: bundled.spec ? { bundledVersion, cliVersion, spec: bundled.spec } : { bundledVersion, cliVersion },
     };
 }
-/**
- * Scan `<pluginsRoot>/cache/<marketplace>/akm/<version>/` for every
- * `akm` plugin cache entry, picking the highest cached version per
- * marketplace when more than one is present. Returns `[]` (never throws)
- * when the cache directory is absent, empty, or unreadable — that is the
- * ordinary "no Claude plugin installed" case, not an error.
- */
 function detectInstalledPlugins(pluginsRoot) {
-    const cacheDir = path.join(pluginsRoot, "cache");
-    let marketplaces;
+    if (!fs.existsSync(path.join(pluginsRoot, "installed_plugins.json")) &&
+        !fs.existsSync(path.join(pluginsRoot, "cache")))
+        return [];
     try {
-        marketplaces = fs.readdirSync(cacheDir);
+        const listed = spawnSync("claude", ["plugin", "list", "--json"], {
+            encoding: "utf8",
+            timeout: 30_000,
+            env: {
+                ...process.env,
+                ...(process.env.AKM_CLAUDE_PLUGINS_DIR
+                    ? { CLAUDE_CONFIG_DIR: process.env.CLAUDE_CONFIG_DIR ?? path.dirname(pluginsRoot) }
+                    : {}),
+                CLAUDE_CODE_PLUGIN_CACHE_DIR: pluginsRoot,
+            },
+        });
+        if (listed.status !== 0)
+            return undefined;
+        const rows = JSON.parse(listed.stdout);
+        if (!Array.isArray(rows))
+            return undefined;
+        const detected = rows.flatMap((row) => {
+            if (typeof row?.id !== "string" || !row.id.startsWith("akm@"))
+                return [];
+            const applicable = typeof row.projectPath !== "string" ||
+                path.resolve(process.cwd()) === path.resolve(row.projectPath) ||
+                path.resolve(process.cwd()).startsWith(`${path.resolve(row.projectPath)}${path.sep}`);
+            return [
+                {
+                    harness: "claude",
+                    marketplace: row.id.slice(4),
+                    pluginName: "akm",
+                    version: typeof row.folderVersion === "string"
+                        ? row.folderVersion
+                        : typeof row.version === "string"
+                            ? row.version
+                            : "unknown",
+                    pluginDir: typeof row.readFromFolder === "string"
+                        ? row.readFromFolder
+                        : typeof row.installPath === "string"
+                            ? row.installPath
+                            : "",
+                    applicable,
+                    selectionKnown: false,
+                    scope: typeof row.scope === "string" ? row.scope : "unknown",
+                    enabled: typeof row.enabled === "boolean" ? row.enabled : undefined,
+                    ...(typeof row.projectPath === "string" ? { projectPath: row.projectPath } : {}),
+                },
+            ];
+        });
+        for (const plugin of detected) {
+            const applicable = detected.filter((p) => p.marketplace === plugin.marketplace && p.applicable);
+            plugin.selectionKnown =
+                plugin.applicable &&
+                    isExactSemver(plugin.version) &&
+                    plugin.scope !== "unknown" &&
+                    plugin.pluginDir !== "" &&
+                    new Set(applicable.map((p) => `${p.version}:${p.pluginDir}`)).size === 1;
+        }
+        return detected;
     }
     catch {
-        return [];
-    }
-    const detected = [];
-    for (const marketplace of marketplaces) {
-        const pluginDir = path.join(cacheDir, marketplace, "akm");
-        let versions;
-        try {
-            versions = fs.readdirSync(pluginDir).filter(isExactSemver);
-        }
-        catch {
-            continue;
-        }
-        if (versions.length === 0)
-            continue;
-        const latest = highestVersion(versions);
-        if (!latest)
-            continue;
-        const versionDir = path.join(pluginDir, latest);
-        const manifestPath = path.join(versionDir, ".claude-plugin", "plugin.json");
-        try {
-            const manifest = JSON.parse(fs.readFileSync(manifestPath, "utf8"));
-            if (typeof manifest.version !== "string")
-                continue;
-            detected.push({
-                harness: "claude",
-                marketplace,
-                pluginName: "akm",
-                version: manifest.version,
-                pluginDir: versionDir,
-            });
-        }
-        catch {
-            // Unreadable/malformed manifest — skip this entry rather than crash.
-        }
+        return undefined;
     }
-    return detected;
 }
-/**
- * Extract `AKM_VERSION_RANGE` from the installed plugin's vendored
- * `shared/akm-version.ts`. Returns `undefined` when the file is missing,
- * unreadable, or does not contain the expected declaration — callers must
- * treat that as "compatibility unknown", never as a mismatch.
- */
-function readVersionRange(pluginDir) {
-    const versionFilePath = path.join(pluginDir, "shared", "akm-version.ts");
+/** Read the contract, never execute plugin source. A minimum admits later prereleases too. */
+function readCompatibility(pluginDir, cliVersion) {
     let text;
     try {
-        text = fs.readFileSync(versionFilePath, "utf8");
+        text = fs.readFileSync(path.join(pluginDir, "shared", "akm-version.ts"), "utf8");
     }
     catch {
-        return undefined;
+        return {};
+    }
+    const minimum = text.match(/export\s+const\s+AKM_MIN_VERSION\s*=\s*["']([^"']+)["']/)?.[1];
+    if (minimum !== undefined) {
+        if (!isExactSemver(minimum) || !isExactSemver(cliVersion))
+            return {};
+        return { versionRange: `>=${minimum}`, admitted: highestVersion([minimum, cliVersion]) === cliVersion };
     }
-    const match = text.match(/export\s+const\s+AKM_VERSION_RANGE\s*=\s*["']([^"']+)["']/);
-    return match?.[1];
+    const range = text.match(/export\s+const\s+AKM_VERSION_RANGE\s*=\s*["']([^"']+)["']/)?.[1];
+    if (!range || !isSemverRange(range) || !isExactSemver(cliVersion))
+        return {};
+    return { versionRange: range, admitted: satisfiesRange(cliVersion, range) };
 }
 const LS_REMOTE_TIMEOUT_MS = 5_000;
 /**
@@ -311,7 +289,17 @@ export function collectPluginStalenessAdvisories(options) {
     const listRemoteTags = options.listRemoteTags ?? realListRemoteTags;
     const plugins = detectInstalledPlugins(pluginsRoot);
     const probe = options.probe ?? true;
-    const results = plugins.map((plugin) => buildAdvisory(plugin, options.cliVersion, pluginsRoot, listRemoteTags, probe));
+    const results = (plugins ?? []).map((plugin) => buildAdvisory(plugin, options.cliVersion, pluginsRoot, listRemoteTags, probe));
+    if (plugins === undefined && fs.existsSync(pluginsRoot)) {
+        results.push({
+            name: "plugin-version",
+            kind: "deterministic",
+            status: "unknown",
+            confidence: "high",
+            message: "Claude plugin installation and enabled state could not be resolved with `claude plugin list --json`; cached versions do not establish the selected installation.",
+            evidence: { harness: "claude", installedVersion: null, enabled: null, admitted: null },
+        });
+    }
     const opencodeCacheRoot = options.opencodeCacheRoot ?? defaultOpencodeCacheRoot();
     for (const plugin of OPENCODE_PLUGIN_LOCATIONS) {
         for (const bundled of findBundledAkm(plugin, opencodeCacheRoot)) {
@@ -326,7 +314,9 @@ function buildAdvisory(plugin, cliVersion, pluginsRoot, listRemoteTags, probe) {
     const marketplaceDir = path.join(pluginsRoot, "marketplaces", plugin.marketplace);
     let availableVersion;
     try {
-        const tags = probe && fs.existsSync(marketplaceDir) ? listRemoteTags(marketplaceDir) : undefined;
+        const tags = probe && plugin.selectionKnown && plugin.enabled !== false && fs.existsSync(marketplaceDir)
+            ? listRemoteTags(marketplaceDir)
+            : undefined;
         availableVersion = tags && tags.length > 0 ? highestVersion(tags) : undefined;
     }
     catch {
@@ -336,10 +326,20 @@ function buildAdvisory(plugin, cliVersion, pluginsRoot, listRemoteTags, probe) {
         plugin.version !== availableVersion &&
         highestVersion([plugin.version, availableVersion]) === availableVersion;
     // Point 3: does the plugin's own declared range admit the running CLI?
-    const versionRange = readVersionRange(plugin.pluginDir);
-    const rangeKnown = versionRange !== undefined && isSemverRange(versionRange);
-    const admitted = rangeKnown ? satisfiesRange(cliVersion, versionRange) : undefined;
-    const messageParts = [`${pluginRef}: installed ${plugin.version}`];
+    const { versionRange, admitted } = readCompatibility(plugin.pluginDir, cliVersion);
+    const messageParts = [
+        `${pluginRef}: installed ${plugin.version} (${plugin.scope}${plugin.projectPath ? `: ${plugin.projectPath}` : ""})`,
+    ];
+    if (!plugin.applicable)
+        messageParts.push("installed for another project; not selected in this directory");
+    else if (!plugin.selectionKnown)
+        messageParts.push("effective selection unknown across native installations");
+    if (plugin.enabled === false)
+        messageParts.push("disabled in Claude settings");
+    else if (plugin.enabled === undefined)
+        messageParts.push("enabled state unknown");
+    if (admitted === undefined)
+        messageParts.push("CLI compatibility unknown");
     if (!probe)
         messageParts.push("newest tag was not probed");
     if (availableVersion !== undefined) {
@@ -347,15 +347,23 @@ function buildAdvisory(plugin, cliVersion, pluginsRoot, listRemoteTags, probe) {
     }
     if (stale)
         messageParts.push(`-> claude plugin update ${pluginRef}`);
-    if (rangeKnown && admitted === false) {
-        messageParts.push(`installed plugin requires akm-cli ${versionRange}; running ${cliVersion} -> NOT ADMITTED (plugin is inactive)`);
+    if (plugin.selectionKnown && plugin.enabled === true && admitted === false) {
+        messageParts.push(`installed plugin requires akm-cli ${versionRange}; running ${cliVersion} -> NOT ADMITTED by the plugin compatibility contract`);
     }
     return {
         name: "plugin-version",
         kind: "deterministic",
         // Not probed => staleness is unknown, not "up to date"; only the local
         // range check can still warn.
-        status: stale || admitted === false ? "warn" : probe ? "pass" : "unknown",
+        status: plugin.enabled === false || !plugin.applicable
+            ? "pass"
+            : !plugin.selectionKnown || plugin.enabled === undefined
+                ? "unknown"
+                : stale || admitted === false
+                    ? "warn"
+                    : probe && availableVersion !== undefined && admitted !== undefined && plugin.enabled === true
+                        ? "pass"
+                        : "unknown",
         confidence: "high",
         message: messageParts.join(" — "),
         evidence: {
@@ -363,6 +371,12 @@ function buildAdvisory(plugin, cliVersion, pluginsRoot, listRemoteTags, probe) {
             marketplace: plugin.marketplace,
             plugin: plugin.pluginName,
             installedVersion: plugin.version,
+            scope: plugin.scope,
+            applicable: plugin.applicable,
+            selectionKnown: plugin.selectionKnown,
+            projectPath: plugin.projectPath ?? null,
+            enabled: plugin.enabled ?? null,
+            installPath: plugin.pluginDir,
             availableVersion: availableVersion ?? null,
             ...(probe ? {} : { probed: false }),
             stale,

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

@@ -0,0 +1,147 @@
+// 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/.
+import fs from "node:fs";
+import path from "node:path";
+import { isDeepStrictEqual } from "node:util";
+import { applyEdits, modify } from "jsonc-parser";
+import { parse as parseToml } from "smol-toml";
+import { existingFileMode, parseJsonc, timestampForFilename, writeFileAtomic } from "../../core/common.js";
+/** Preserve unrelated settings and comments; only the named native key changes. */
+export function editChannelJson(file, keys, value, content) {
+    const before = content ?? fs.readFileSync(file, "utf8");
+    parseJsonc(before);
+    const after = applyEdits(before, modify(before, keys, value, { formattingOptions: { insertSpaces: true, tabSize: 2 } }));
+    parseJsonc(after);
+    return { file, content: after };
+}
+export function backupChannelFile(file) {
+    const backup = `${file}.akm-channel-${timestampForFilename()}-${process.pid}.bak`;
+    fs.copyFileSync(file, backup, fs.constants.COPYFILE_EXCL);
+    fs.chmodSync(backup, existingFileMode(file) ?? 0o600);
+    return backup;
+}
+export class ChannelWriteError extends Error {
+    backups;
+    writtenFiles;
+    constructor(cause, backups, writtenFiles) {
+        super(`Channel settings could not all be written: ${String(cause)}. Backups: ${backups.join(", ") || "none"}`);
+        this.backups = backups;
+        this.writtenFiles = writtenFiles;
+    }
+}
+export function writeChannelEdits(edits) {
+    const backups = [];
+    const writtenFiles = [];
+    try {
+        const changed = edits.filter(({ file, content }) => fs.readFileSync(file, "utf8") !== content);
+        for (const { file } of changed)
+            backups.push(backupChannelFile(file));
+        for (const { file, content } of changed) {
+            writeFileAtomic(file, content, existingFileMode(file));
+            writtenFiles.push(file);
+        }
+        return backups;
+    }
+    catch (error) {
+        throw new ChannelWriteError(error, backups, writtenFiles);
+    }
+}
+/** Claude has no command to change a registered marketplace's ref in place. Never remove the marketplace. */
+export function claudeChannelEdits(configDir, pluginsRoot, channel, projectPaths = []) {
+    const ref = channel === "next" ? "next" : undefined;
+    const knownFile = path.join(pluginsRoot, "known_marketplaces.json");
+    const known = parseJsonc(fs.readFileSync(knownFile, "utf8"));
+    const source = known["akm-plugins"]?.source;
+    if (!source || !["github", "git"].includes(source.source ?? "")) {
+        throw new Error("the akm-plugins marketplace has no Git source whose channel can be switched");
+    }
+    const edits = [editChannelJson(knownFile, ["akm-plugins", "source", "ref"], ref)];
+    const settingsFiles = [
+        path.join(configDir, "settings.json"),
+        ...[process.cwd(), ...projectPaths].flatMap((project) => [
+            path.join(project, ".claude", "settings.json"),
+            path.join(project, ".claude", "settings.local.json"),
+        ]),
+    ];
+    for (const file of new Set(settingsFiles)) {
+        if (!fs.existsSync(file))
+            continue;
+        const settings = parseJsonc(fs.readFileSync(file, "utf8"));
+        if (!settings.extraKnownMarketplaces?.["akm-plugins"])
+            continue;
+        edits.push(editChannelJson(file, ["extraKnownMarketplaces", "akm-plugins", "source", "ref"], ref));
+    }
+    return edits;
+}
+/** Read native TOML, including quoted keys and inline tables. */
+export function codexMarketplace(file) {
+    const config = parseToml(fs.readFileSync(file, "utf8"));
+    const marketplaces = config.marketplaces;
+    const marketplace = marketplaces?.["akm-plugins"];
+    return marketplace && typeof marketplace === "object" ? marketplace : undefined;
+}
+/** Codex's add refuses a changed ref on an existing source; preserve the installed plugin and edit only its ref. */
+export function codexChannelEdit(file, channel) {
+    const before = fs.readFileSync(file, "utf8");
+    const expected = parseToml(before);
+    const entry = expected.marketplaces?.["akm-plugins"];
+    if (!entry || entry.source_type !== "git")
+        throw new Error("the akm-plugins marketplace has no Git source whose channel can be switched");
+    if (channel === "next")
+        entry.ref = "next";
+    else
+        delete entry.ref;
+    const headers = [...before.matchAll(/^[ \t]*\[(?!\[)([^\]\r\n]+)\][ \t]*(?:#[^\r\n]*)?\r?$/gm)];
+    let after = before;
+    let edited = false;
+    for (const [index, header] of headers.entries()) {
+        let parsed;
+        try {
+            parsed = parseToml(`[${header[1]}]`);
+        }
+        catch {
+            continue;
+        }
+        const target = parsed.marketplaces?.["akm-plugins"];
+        if (!target || Object.keys(target).length !== 0)
+            continue;
+        const start = header.index + header[0].length;
+        const end = headers[index + 1]?.index ?? before.length;
+        const section = before.slice(start, end);
+        const refLine = /^[ \t]*(?:ref|"ref"|'ref')[ \t]*=[ \t]*(?:"(?:\\.|[^"\\])*"|'[^']*')([ \t]*(?:#[^\r\n]*)?)(\r?\n|$)/m;
+        const newline = before.includes("\r\n") ? "\r\n" : "\n";
+        const nextSection = refLine.test(section)
+            ? section.replace(refLine, (_line, comment, end) => channel === "next" ? `ref = "next"${comment}${end}` : comment.trim() ? `${comment.trimStart()}${end}` : "")
+            : channel === "next"
+                ? `${newline}ref = "next"${section}`
+                : section;
+        after = before.slice(0, start) + nextSection + before.slice(end);
+        edited = true;
+        break;
+    }
+    if (!edited) {
+        // Inline tables have no section to insert into. Change just this table's ref and retain every other byte.
+        const inline = /((?:"akm-plugins"|'akm-plugins'|akm-plugins)\s*=\s*\{)([^\n]*?)(\})/g;
+        for (const match of before.matchAll(inline)) {
+            const [, open, body, close] = match;
+            const ref = /(?:^|,)\s*(?:ref|"ref"|'ref')\s*=\s*(?:"(?:\\.|[^"\\])*"|'[^']*')\s*/;
+            const stripped = body.replace(ref, "").replace(/^\s*,/, "");
+            const next = channel === "next" ? `${stripped.trimEnd()}${stripped.trim() ? ", " : ""}ref = "next" ` : stripped;
+            const candidate = before.slice(0, match.index) + `${open}${next}${close}` + before.slice(match.index + match[0].length);
+            try {
+                if (isDeepStrictEqual(parseToml(candidate), expected)) {
+                    after = candidate;
+                    break;
+                }
+            }
+            catch {
+                /* Try the next table with this name. */
+            }
+        }
+    }
+    // Validate the whole semantic document: an unusual layout is never partially rewritten.
+    if (!isDeepStrictEqual(parseToml(after), expected))
+        throw new Error("could not locate only the akm-plugins ref in Codex config.toml; no settings were changed");
+    return { file, content: after };
+}