akm-cli 0.9.28-alpha.4 → 0.9.28-alpha.5

package/CHANGELOG.md

@@ -6,6 +6,20 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [0.9.28-alpha.5] - 2026-10-08
+
+### Added
+
+- **`akm upgrade --next` installs the `@next` prerelease of akm and its OpenCode plugin.** The CLI target is
+  the `next` dist-tag of `akm-cli` when it is newer than the latest stable release, else the stable release
+  (never a downgrade); npm/Bun/pnpm installs name that exact version and binary installs take its GitHub
+  release. The OpenCode lockstep and cache refresh follow `akm-opencode@next` when the OpenCode config's
+  `plugin` list names it (akm never edits that config); with a bare `"akm-opencode"` the entry is `skipped`
+  with a message saying to set `"plugin": ["akm-opencode@next"]`, and lockstep stays on the `@latest` pin.
+  Missing, older-than-`@latest` or unpinned `@next` fails closed like the stable lockstep. Claude Code and
+  Codex are unchanged (no prerelease channel). The result gains `channel`. Works with `--check`, `--force`
+  and `-q`. See [`akm upgrade`](docs/reference/cli.md#prereleases-next).
+
 ## [0.9.28-alpha.4] - 2026-10-08
 
 ### Added

package/dist/assets/hints/cli-hints-full.md

@@ -331,6 +331,7 @@ akm lint --fix                                # Auto-fix Tier 1 issues
 akm lint --fail-on-flagged                    # Exit non-zero when summary.flagged > 0 (CI-friendly)
 akm upgrade                                   # Upgrade akm using its install method, then update installed harness plugins
 akm upgrade --check                           # Report pending CLI and plugin updates, changing nothing
+akm upgrade --next                            # Follow prereleases (@next); OpenCode needs "akm-opencode@next" in its plugin list
 akm help migrate 0.6.0                        # Print migration notes for a release (or: latest)
 akm help bundle                               # Print options and subcommands for one command
 akm help agents --full                        # Print this reference

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

@@ -13,12 +13,13 @@ 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 } from "../../core/common.js";
+import { IS_WINDOWS, stripJsonComments } from "../../core/common.js";
 import { moveToTrash } from "../../core/trash.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;
@@ -136,11 +137,48 @@ function upgradeCodex(dryRun) {
     const after = codexPluginVersion();
     return refreshed("codex", before.version, "version" in after ? after.version : undefined);
 }
-/** The cached `akm-opencode` OpenCode installed on first use, or undefined when there is none. */
-export function detectOpenCodeCache() {
-    const cacheHome = process.env.XDG_CACHE_HOME?.trim() ||
-        path.join(process.env.HOME?.trim() || process.env.USERPROFILE?.trim() || os.homedir(), ".cache");
-    const dir = path.join(cacheHome, "opencode", "packages", `${OPENCODE_PACKAGE}@latest`);
+function homeDir() {
+    return process.env.HOME?.trim() || process.env.USERPROFILE?.trim() || os.homedir();
+}
+/**
+ * Whether the user's global OpenCode config asks for `akm-opencode@next`.
+ * A bare `akm-opencode` resolves to `@latest` when OpenCode prefetches it, so
+ * only a config that names the tag can follow prereleases. The config is only
+ * read, never written; project configs are not looked at (akm does not know
+ * which project OpenCode runs in).
+ */
+export function openCodeConfigRequestsNext() {
+    const configHome = process.env.XDG_CONFIG_HOME?.trim() || path.join(homeDir(), ".config");
+    const files = [
+        process.env.OPENCODE_CONFIG?.trim(),
+        path.join(configHome, "opencode", "opencode.json"),
+        path.join(configHome, "opencode", "opencode.jsonc"),
+    ];
+    for (const file of files) {
+        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.
+            if (config.plugin.some((entry) => (Array.isArray(entry) ? entry[0] : entry) === OPENCODE_NEXT_SPEC))
+                return true;
+        }
+        catch {
+            // Missing or unparseable: this file does not request it.
+        }
+    }
+    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`.
+ */
+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}`);
     if (!fs.existsSync(dir))
         return undefined;
     const readVersion = (file) => {
@@ -154,17 +192,33 @@ export function detectOpenCodeCache() {
     };
     return { dir, version: readVersion(path.join(dir, "node_modules", OPENCODE_PACKAGE, "package.json")) };
 }
-/** What npm's `akm-opencode@latest` is, and which akm-cli it pins. */
-export function lookupOpenCodeLatest() {
-    const view = runCommand(IS_WINDOWS ? "npm.cmd" : "npm", ["view", `${OPENCODE_PACKAGE}@latest`, "version", "dependencies.akm-cli", "--json"], READ_TIMEOUT_MS);
+/** What npm's `akm-opencode@<tag>` is, and which akm-cli it pins. */
+export function lookupOpenCodeLatest(tag = "latest") {
+    const spec = `${OPENCODE_PACKAGE}@${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 };
     const parsed = parseJson(view.stdout);
     if (typeof parsed?.version !== "string")
-        return { error: "npm did not report a version for akm-opencode@latest" };
+        return { error: `npm did not report a version for ${spec}` };
     const akmCli = parsed["dependencies.akm-cli"];
     return { version: parsed.version, akmCli: typeof akmCli === "string" ? akmCli : undefined };
 }
+/** `akm-opencode@next`, which must exist and be no older than `@latest`: a prerelease channel that trails the stable one is not a target. */
+export function lookupOpenCodeNext() {
+    const next = lookupOpenCodeLatest("next");
+    if ("error" in next)
+        return next;
+    const latest = lookupOpenCodeLatest("latest");
+    if ("error" in latest)
+        return { error: `could not compare with ${OPENCODE_PACKAGE}@latest: ${latest.error}` };
+    if (semverOrder(next.version, latest.version) < 0) {
+        return {
+            error: `${OPENCODE_NEXT_SPEC} (${next.version}) is older than ${OPENCODE_PACKAGE}@latest (${latest.version})`,
+        };
+    }
+    return next;
+}
 /** Whether an OpenCode process is running (its prefetch would be replaced under it). `undefined` when that cannot be told. */
 function openCodeRunning() {
     if (IS_WINDOWS) {
@@ -198,11 +252,15 @@ function openCodeRunning() {
         return undefined;
     }
 }
-function upgradeOpenCode(dryRun, cache, latest) {
+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`;
+function upgradeOpenCode(dryRun, cache, latest, tag, notFollowingNext) {
     if (!cache || !latest)
-        return skipped("opencode", "no cached akm-opencode plugin");
+        return skipped("opencode", `no cached ${OPENCODE_PACKAGE}@${tag} plugin`);
     if ("error" in latest)
         return failed("opencode", latest.error);
+    if (notFollowingNext)
+        return skipped("opencode", NOT_FOLLOWING_NEXT);
     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 };
@@ -239,17 +297,27 @@ function upgradeOpenCode(dryRun, cache, latest) {
     finally {
         fs.rmSync(workDir, { recursive: true, force: true });
     }
-    const after = detectOpenCodeCache();
+    const after = detectOpenCodeCache(tag);
     if (!after)
         return failed("opencode", "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 ───────────────────────────────────────────────────────────
+const NO_PRERELEASE_CHANNEL = "--next: no prerelease channel; the akm-plugins marketplace is followed as usual and works with any 0.9.x akm";
+/** The note `--next` adds to a harness whose plugin has no prerelease channel. */
+function withNextNote(entry) {
+    if (entry.outcome === "skipped")
+        return entry;
+    return { ...entry, message: entry.message ? `${entry.message}; ${NO_PRERELEASE_CHANNEL}` : NO_PRERELEASE_CHANNEL };
+}
 export function upgradePlugins(opts) {
+    const { cache, latest, tag, notFollowingNext } = opts.openCode;
+    const claude = upgradeClaudeCode(opts.dryRun);
+    const codex = upgradeCodex(opts.dryRun);
     return [
-        upgradeClaudeCode(opts.dryRun),
-        upgradeCodex(opts.dryRun),
-        upgradeOpenCode(opts.dryRun, opts.openCode.cache, opts.openCode.latest),
+        opts.next ? withNextNote(claude) : claude,
+        opts.next ? withNextNote(codex) : codex,
+        upgradeOpenCode(opts.dryRun, cache, latest, tag, notFollowingNext),
     ];
 }
 /**
@@ -264,7 +332,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) {
+export function applyLockstep(check, latest, tag = "latest") {
     if (!latest)
         return check;
     // Held back only when there is a release this upgrade would otherwise install.
@@ -272,8 +340,8 @@ export function applyLockstep(check, 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}@latest: ${latest.error}`
-            : `${OPENCODE_PACKAGE}@latest declares no akm-cli dependency`;
+            ? `could not read the akm-cli pin of ${OPENCODE_PACKAGE}@${tag}: ${latest.error}`
+            : `${OPENCODE_PACKAGE}@${tag} declares no akm-cli dependency`;
         return {
             ...check,
             latestVersion: check.currentVersion,
@@ -303,23 +371,40 @@ export function applyLockstep(check, latest) {
         lockstep,
     };
 }
+/**
+ * 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
+ * config names that tag: otherwise OpenCode keeps resolving `@latest`, so the
+ * lockstep stays against the `@latest` pin and the entry is reported as skipped.
+ */
+function resolveOpenCodeTarget(next) {
+    const followNext = next && openCodeConfigRequestsNext();
+    const tag = followNext ? "next" : "latest";
+    const cache = detectOpenCodeCache(tag);
+    const latest = cache ? (followNext ? lookupOpenCodeNext() : lookupOpenCodeLatest()) : undefined;
+    return { cache, latest, tag, notFollowingNext: next && !followNext };
+}
 /** `akm upgrade`: the CLI step (held to the OpenCode plugin's akm), then the plugins. */
 export async function runUpgrade(args, currentVersion, deps) {
-    const cache = detectOpenCodeCache();
-    const latest = cache ? lookupOpenCodeLatest() : undefined;
-    const check = applyLockstep(await deps.checkForUpdate(currentVersion), latest);
-    const openCode = { cache, latest };
+    const next = args.next === true;
+    const channel = next ? "next" : "latest";
+    const openCode = resolveOpenCodeTarget(next);
+    const check = {
+        ...applyLockstep(await deps.checkForUpdate(currentVersion, channel), openCode.latest, openCode.tag),
+        channel,
+    };
     if (args.check) {
-        return { mode: "check", result: { ...check, plugins: upgradePlugins({ dryRun: true, openCode }) } };
+        return { mode: "check", result: { ...check, plugins: upgradePlugins({ dryRun: true, next, openCode }) } };
     }
     const upgraded = await deps.performUpgrade(check, {
         force: args.force,
         skipPostUpgrade: args.skipPostUpgrade,
-        // A package manager install must name the version, or `@latest` goes past the pin.
-        ...(check.lockstep?.heldBack ? { targetVersion: check.latestVersion } : {}),
+        // A package manager install must name the version, or `@latest` goes past the pin
+        // (or past the prerelease that `--next` chose).
+        ...(check.lockstep?.heldBack || (next && check.latestVersion) ? { targetVersion: check.latestVersion } : {}),
     });
-    const plugins = upgradePlugins({ dryRun: false, openCode });
-    const result = { ...upgraded, ...(check.lockstep ? { lockstep: check.lockstep } : {}), plugins };
+    const plugins = upgradePlugins({ dryRun: false, next, openCode });
+    const result = { ...upgraded, channel, ...(check.lockstep ? { lockstep: check.lockstep } : {}), plugins };
     // The install may have succeeded, but an upgrade whose migration is
     // blocked or could not run is not done, and neither is one whose plugin
     // step failed.

package/dist/commands/sources/self-update.js

@@ -174,7 +174,24 @@ export function getAkmBinaryName() {
         return "akm-windows-x64.exe";
     throw new ConfigError(`Unsupported platform for binary upgrade: ${platform}/${arch}`, "UNSUPPORTED_PLATFORM");
 }
-export async function checkForUpdate(currentVersion, fetchOptions) {
+/** The `next` dist-tag of this package on the npm registry, or undefined when none is published. */
+async function lookupNextVersion(fetchOptions) {
+    const url = `https://registry.npmjs.org/-/package/${encodeURIComponent(getInstalledPackageName())}/dist-tags`;
+    const response = await fetchWithRetry(url, { headers: { accept: "application/json" } }, fetchOptions);
+    if (!response.ok) {
+        throw new Error(`Failed to check for the next prerelease: ${response.status} ${response.statusText}`);
+    }
+    const tags = JSON.parse(await readBodyWithByteCap(response, MAX_CHECKSUM_METADATA_BYTES));
+    return typeof tags.next === "string" && tags.next !== "" ? tags.next : undefined;
+}
+/**
+ * The newest release. With `channel: "next"` that includes prereleases: the
+ * `next` dist-tag when it is newer than the latest stable release, else the
+ * stable release (a prerelease older than a stable one is never a target).
+ * A binary install downloads the GitHub release tagged `v<version>`, which a
+ * prerelease has too, so the version is all the install step needs.
+ */
+export async function checkForUpdate(currentVersion, fetchOptions, channel = "latest") {
     const installMethod = detectInstallMethod();
     const url = `https://api.github.com/repos/${REPO}/releases/latest`;
     const response = await fetchWithRetry(url, { headers: githubHeaders() }, fetchOptions);
@@ -183,7 +200,12 @@ export async function checkForUpdate(currentVersion, fetchOptions) {
     }
     const release = JSON.parse(await readBodyWithByteCap(response, MAX_CHECKSUM_METADATA_BYTES));
     const latestTag = release.tag_name ?? "";
-    const latestVersion = latestTag.replace(/^v/, "");
+    let latestVersion = latestTag.replace(/^v/, "");
+    if (channel === "next") {
+        const next = await lookupNextVersion(fetchOptions);
+        if (next && (latestVersion === "" || semverOrder(latestVersion, next) < 0))
+            latestVersion = next;
+    }
     return {
         currentVersion,
         latestVersion,

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

@@ -54,9 +54,17 @@ export const upgradeCommand = defineJsonCommand({
             description: "Skip the post-upgrade index rebuild",
             default: false,
         },
+        next: {
+            type: "boolean",
+            description: "Install the newest prerelease (the @next npm tag) of akm and, if OpenCode's config names akm-opencode@next, of its plugin",
+            default: false,
+        },
     },
     async run({ args }) {
-        const run = await runUpgrade({ check: args.check, force: args.force, skipPostUpgrade: args["skip-post-upgrade"] }, pkgVersion, { checkForUpdate, performUpgrade: (check, opts) => performUpgrade(check, opts) });
+        const run = await runUpgrade({ check: args.check, force: args.force, skipPostUpgrade: args["skip-post-upgrade"], next: args.next }, pkgVersion, {
+            checkForUpdate: (version, channel) => checkForUpdate(version, undefined, channel),
+            performUpgrade: (check, opts) => performUpgrade(check, opts),
+        });
         if (run.mode === "check") {
             output("upgrade", run.result);
             return;

package/dist/output/text/command-format.js

@@ -693,7 +693,7 @@ function formatUpgradeHead(r) {
         return `akm upgraded: v${r.currentVersion} → v${r.newVersion}`;
     }
     if (r.updateAvailable === true) {
-        return `akm v${r.currentVersion} → v${r.latestVersion} available (run 'akm upgrade' to install)`;
+        return `akm v${r.currentVersion} → v${r.latestVersion} available (run 'akm upgrade${r.channel === "next" ? " --next" : ""}' to install)`;
     }
     if (r.updateAvailable === false && r.latestVersion) {
         return `akm v${r.currentVersion} is already the latest version`;

package/dist/scripts/akm-migrate-node.js

@@ -30493,7 +30493,7 @@ function formatUpgradeHead(r) {
     return `akm upgraded: v${r.currentVersion} → v${r.newVersion}`;
   }
   if (r.updateAvailable === true) {
-    return `akm v${r.currentVersion} → v${r.latestVersion} available (run 'akm upgrade' to install)`;
+    return `akm v${r.currentVersion} → v${r.latestVersion} available (run 'akm upgrade${r.channel === "next" ? " --next" : ""}' to install)`;
   }
   if (r.updateAvailable === false && r.latestVersion) {
     return `akm v${r.currentVersion} is already the latest version`;

package/dist/scripts/akm-migrate.js

@@ -29821,7 +29821,7 @@ function formatUpgradeHead(r) {
     return `akm upgraded: v${r.currentVersion} \u2192 v${r.newVersion}`;
   }
   if (r.updateAvailable === true) {
-    return `akm v${r.currentVersion} \u2192 v${r.latestVersion} available (run 'akm upgrade' to install)`;
+    return `akm v${r.currentVersion} \u2192 v${r.latestVersion} available (run 'akm upgrade${r.channel === "next" ? " --next" : ""}' to install)`;
   }
   if (r.updateAvailable === false && r.latestVersion) {
     return `akm v${r.currentVersion} is already the latest version`;

package/docs/reference/cli.md

@@ -1339,6 +1339,7 @@ computed, with a 256 MiB binary limit. Release/checksum metadata is capped at
 akm upgrade              # Install a newer release if there is one, run every pending migration, then update the harness plugins
 akm upgrade --check      # Report pending updates, CLI and plugins, without changing anything (no migration step)
 akm upgrade --force      # Force the install even if already on latest
+akm upgrade --next       # Install the newest prerelease (@next) instead of the latest stable release
 ```
 
 | Flag | Description |
@@ -1346,6 +1347,7 @@ akm upgrade --force      # Force the install even if already on latest
 | `--check` | Report pending updates (CLI and per-harness plugins) without changing anything |
 | `--force` | Force upgrade even if on latest version |
 | `--skip-post-upgrade` | Skip the post-upgrade index rebuild |
+| `--next` | Follow the `next` prerelease channel: install the newest prerelease of akm (and of the OpenCode plugin, see [Prereleases](#prereleases-next)). Works with `--check`, `--force` and `-q` |
 
 Offline, or to migrate without a release check, run `akm migrate apply`
 directly: it is the same step.
@@ -1399,6 +1401,41 @@ be read (the npm lookup failed, or `akm-opencode@latest` declares no
 OpenCode entry is `failed` and the run exits `1`; the next `akm upgrade`
 retries.
 
+#### Prereleases (`--next`)
+
+`akm upgrade --next` means "newest available, prereleases included". The result
+carries `channel: "next"` (`"latest"` otherwise); no other field changes.
+
+- **CLI.** The target is the `next` dist-tag of `akm-cli` (read from the npm
+  registry, so it works for binary installs too) when that is newer than the
+  latest stable release; otherwise the latest stable release. It never moves
+  backwards. npm, Bun and pnpm installs run `<manager> add|install -g akm-cli@<that exact version>`;
+  standalone binaries download the GitHub release tagged `v<that version>`
+  (prereleases are GitHub releases too) and verify its checksum as usual.
+- **OpenCode.** OpenCode resolves a bare `"akm-opencode"` in its `plugin` list
+  to `@latest`, and caches `@next` in its own folder
+  (`$XDG_CACHE_HOME/opencode/packages/akm-opencode@next`). akm does not edit
+  your OpenCode config, so it can only follow `@next` when you ask for it:
+
+  ```json
+  { "plugin": ["akm-opencode@next"] }
+  ```
+
+  With that line in the global OpenCode config (`~/.config/opencode/opencode.json`
+  or `.jsonc`, or the file named by `OPENCODE_CONFIG`), lockstep and the cache
+  refresh use `akm-opencode@next` (its version and its `akm-cli` pin) instead of
+  `@latest`. If `akm-opencode@next` is missing, older than `@latest`, or its
+  `akm-cli` pin is unreadable, the CLI is held where it is and the OpenCode entry
+  is `failed`, exactly as in the stable lockstep above.
+
+  Without that line the OpenCode entry is `skipped`, its message names the line
+  to add, and lockstep stays against the `@latest` pin, so the CLI does not go
+  past what OpenCode will run.
+- **Claude Code and Codex.** Unchanged: their plugin comes from the `akm-plugins`
+  git marketplace, which has no prerelease channel and accepts any 0.9.x akm,
+  prereleases included. Their entries carry a note saying so.
+- `--check --next` reports all of this and changes nothing.
+
 #### Containers
 
 With the plugin step, a container entrypoint needs only:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akm-cli",
-  "version": "0.9.28-alpha.4",
+  "version": "0.9.28-alpha.5",
   "type": "module",
   "description": "akm (Agent Knowledge Manager) — a portable, local-first capability library for AI agents. Discover, load, share, and improve reusable skills, scripts, workflows, and knowledge across any shell-capable coding agent, including Claude Code, OpenCode, and Cursor.",
   "keywords": [