akm-cli 0.9.0-rc.1 → 0.9.0-rc.3

package/dist/cli/config-validate.js

@@ -8,27 +8,29 @@
  * prints "All checks passed." or a list of structured errors (path + message).
  * Exits non-zero on errors so it composes well in CI hooks.
  */
-import fs from "node:fs";
-import { parseConfigText } from "../core/config/config-io.js";
-import { validateConfigShape } from "../core/config/config-schema.js";
+import { parseConfigText, readConfigText } from "../core/config/config-io.js";
+import { CURRENT_CONFIG_VERSION, validateConfigShape } from "../core/config/config-schema.js";
 import { ConfigError } from "../core/errors.js";
 import { getConfigPath } from "../core/paths.js";
 export async function runConfigValidate() {
     const configPath = getConfigPath();
-    if (!fs.existsSync(configPath)) {
-        console.log(`No config file at ${configPath} — nothing to validate.`);
-        return;
-    }
     let text;
     try {
-        text = fs.readFileSync(configPath, "utf8");
+        text = readConfigText(configPath);
     }
     catch (err) {
         const detail = err instanceof Error ? err.message : String(err);
         throw new ConfigError(`Could not read config at ${configPath}: ${detail}`, "INVALID_CONFIG_FILE");
     }
+    if (text === undefined) {
+        console.log(`No config file at ${configPath} — nothing to validate.`);
+        return;
+    }
     // parseConfigText throws ConfigError on malformed JSON (#458). Surface as-is.
     const raw = parseConfigText(text, configPath);
+    if (raw.configVersion !== CURRENT_CONFIG_VERSION) {
+        throw new ConfigError(`Unsupported configVersion at ${configPath}: expected "${CURRENT_CONFIG_VERSION}".`, "UNSUPPORTED_CONFIG_VERSION", "Recreate engines and improve.strategies manually; AKM 0.9 never translates profile-based configuration.");
+    }
     const result = validateConfigShape(raw);
     if (result.ok) {
         console.log(`All checks passed. (${configPath})`);

package/dist/cli.js

@@ -63,6 +63,7 @@ import { defineCommand, runMain } from "citty";
 import { findCittyTopLevelCommand } from "./cli/parse-args.js";
 import { EXIT_CODES, emitJsonError, output, parseAllFlagValues, runWithJsonErrors } from "./cli/shared.js";
 import { agentCommand, lintCommand, proposeCommand } from "./commands/agent/contribute-cli.js";
+import { backupCommand } from "./commands/backup-cli.js";
 import { generateBashCompletions, installBashCompletions } from "./commands/completions.js";
 import { configCommand } from "./commands/config-cli.js";
 import { envCommand } from "./commands/env/env-cli.js";
@@ -74,6 +75,8 @@ import { renderRunsDetailMd, renderWindowCompareMd } from "./commands/health/md-
 import { parseWindowSpec } from "./commands/health/windows.js";
 import { extractCommand } from "./commands/improve/extract-cli.js";
 import { improveCommand } from "./commands/improve/improve-cli.js";
+import { migrateCommand } from "./commands/migrate-cli.js";
+import { mvCommand } from "./commands/mv-cli.js";
 import { hintsCommand, lessonsCommand, logCommand } from "./commands/observability-cli.js";
 import { proposalCommand } from "./commands/proposal/proposal-cli.js";
 import { rememberCommand } from "./commands/read/remember-cli.js";
@@ -88,11 +91,12 @@ import { tasksCommand } from "./commands/tasks/tasks-cli.js";
 import { wikiCommand } from "./commands/wiki-cli.js";
 import { workflowCommand } from "./commands/workflow-cli.js";
 import { bestEffort } from "./core/best-effort.js";
-import { loadConfig } from "./core/config/config.js";
+import { DEFAULT_CONFIG, loadConfig } from "./core/config/config.js";
 import { UsageError } from "./core/errors.js";
 import { getCacheDir, getConfigPath, getDbPath } from "./core/paths.js";
 import { plainize } from "./core/tty.js";
 import { info, isQuiet, setQuiet, setVerbose, warn } from "./core/warn.js";
+import { disposeDispatchResources } from "./integrations/agent/runner-dispatch.js";
 import { getHyphenatedBoolean, getOutputMode, initOutputMode, parseFlagValue } from "./output/context.js";
 import { deliverRendered, renderHtml, resolveTemplatePath } from "./output/html-render.js";
 import { pkgVersion } from "./version.js";
@@ -195,10 +199,15 @@ const setupCommand = defineCommand({
             type: "string",
             description: "Stash directory path (overrides stashDir in config or --config JSON)",
         },
+        "no-init": {
+            type: "boolean",
+            default: false,
+            description: "Write configuration without scaffolding the stash directory",
+        },
         probe: {
             type: "boolean",
             default: false,
-            description: "Probe LLM/embedding endpoints after writing config to verify connectivity",
+            description: "Probe LLM/embedding endpoints before writing config to verify connectivity",
         },
         "detect-only": {
             type: "boolean",
@@ -213,7 +222,9 @@ const setupCommand = defineCommand({
     },
     async run({ args }) {
         await runWithJsonErrors(async () => {
-            const noInit = getHyphenatedBoolean(args, "no-init");
+            // citty treats a leading `no-` as boolean negation on some parse paths,
+            // so retain the raw argv spelling as the authoritative compatibility form.
+            const noInit = getHyphenatedBoolean(args, "no-init") || process.argv.includes("--no-init");
             const detectOnly = args["detect-only"];
             const resetRecommended = args["reset-recommended"];
             if (detectOnly) {
@@ -505,7 +516,10 @@ export const main = defineCommand({
         import: importKnowledgeCommand,
         sync: syncCommand,
         clone: cloneCommand,
+        mv: mvCommand,
         registry: registryCommand,
+        migrate: migrateCommand,
+        backup: backupCommand,
         config: configCommand,
         feedback: feedbackCommand,
         history: historyCommand,
@@ -527,6 +541,20 @@ export const main = defineCommand({
     },
 });
 const MAIN_TOP_LEVEL_ARGS = main.args;
+/** Recovery/setup surfaces must remain reachable when config.json is invalid. */
+export function shouldBypassConfigStartup(argv) {
+    const args = argv.slice(2);
+    if (args.includes("--help") || args.includes("-h") || args.includes("--version") || args.includes("-v"))
+        return true;
+    const command = findCittyTopLevelCommand([...args], MAIN_TOP_LEVEL_ARGS);
+    if (command === "setup" || command === "backup" || command === "migrate")
+        return true;
+    if (command !== "config")
+        return false;
+    const configIndex = args.indexOf("config");
+    const subcommand = args.slice(configIndex + 1).find((arg) => !arg.startsWith("-"));
+    return subcommand === "path" || subcommand === "validate" || subcommand === "migrate";
+}
 // ── Exit codes ──────────────────────────────────────────────────────────────
 // Canonical table lives in `src/cli/shared.ts` (EXIT_CODES). These aliases keep
 // the local call sites terse. EXIT_HEALTH_WARN (4) is the `akm health` "warn"
@@ -556,7 +584,8 @@ if (import.meta.main || process.env.AKM_NODE_ENTRY === "1") {
     // rather than letting the raw exception escape with a stack trace.
     try {
         applyEarlyStderrFlags(process.argv);
-        initOutputMode(process.argv, loadConfig().output ?? {});
+        const bypassConfig = shouldBypassConfigStartup(process.argv);
+        initOutputMode(process.argv, bypassConfig ? (DEFAULT_CONFIG.output ?? {}) : (loadConfig().output ?? {}));
     }
     catch (error) {
         emitJsonError(error);
@@ -575,15 +604,17 @@ if (import.meta.main || process.env.AKM_NODE_ENTRY === "1") {
     // 0.8.0 moved the index to $XDG_DATA_HOME/akm/index.db (getDataDir()).
     // If the old file exists at $XDG_CACHE_HOME/akm/index.db, remove it so the
     // user isn't confused by a phantom DB. Best-effort; never fatal.
-    bestEffort(() => {
-        const oldIndexPath = path.join(getCacheDir(), "index.db");
-        if (fs.existsSync(oldIndexPath)) {
-            fs.rmSync(oldIndexPath, { force: true });
-            fs.rmSync(`${oldIndexPath}-shm`, { force: true });
-            fs.rmSync(`${oldIndexPath}-wal`, { force: true });
-            warn(`Cleaned up stale 0.7.x index from ${oldIndexPath}. Canonical path is now ${getDbPath()}.`);
-        }
-    }, "stale 0.7.x index cleanup is non-fatal");
+    if (!shouldBypassConfigStartup(process.argv)) {
+        bestEffort(() => {
+            const oldIndexPath = path.join(getCacheDir(), "index.db");
+            if (fs.existsSync(oldIndexPath)) {
+                fs.rmSync(oldIndexPath, { force: true });
+                fs.rmSync(`${oldIndexPath}-shm`, { force: true });
+                fs.rmSync(`${oldIndexPath}-wal`, { force: true });
+                warn(`Cleaned up stale 0.7.x index from ${oldIndexPath}. Canonical path is now ${getDbPath()}.`);
+            }
+        }, "stale 0.7.x index cleanup is non-fatal");
+    }
     // First-time-user breadcrumb: when run with no subcommand AND no config
     // exists yet AND stderr is a TTY, print a friendly pointer to `akm setup`
     // above citty's auto-generated usage block. Triggers only when stdin/stderr
@@ -608,5 +639,10 @@ if (import.meta.main || process.env.AKM_NODE_ENTRY === "1") {
         }
         console.error(plainize("👋 First time with akm? Run `akm setup` to get started.\n   Docs: https://github.com/itlackey/akm#readme\n"));
     })();
-    runMain(main);
+    try {
+        await runMain(main);
+    }
+    finally {
+        await disposeDispatchResources();
+    }
 }

package/dist/commands/agent/agent-dispatch.js

@@ -2,9 +2,9 @@
 // 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/.
 /**
- * `akm agent <profile> [--prompt <text>] [--command <ref>] [--workflow <ref>] [args...]`
+ * `akm agent [--engine <name>] [--prompt <text>] [--command <ref>] [--workflow <ref>] [args...]`
  *
- * Dispatch an agent by named profile, optionally injecting a prompt from
+ * Dispatch an agent by named engine, optionally injecting a prompt from
  * inline text, a stash command: asset, or a stash workflow: asset.
  *
  * When none of --prompt, --command, or --workflow are given, the agent is
@@ -16,9 +16,8 @@
 import fs from "node:fs";
 import { parseAssetRef } from "../../core/asset/asset-ref.js";
 import { NotFoundError, UsageError } from "../../core/errors.js";
-import { requireAgentProfile } from "../../integrations/agent/config.js";
-import { runAgent } from "../../integrations/agent/spawn.js";
-import { runOpencodeSdk } from "../../integrations/harnesses/opencode-sdk/index.js";
+import { resolveEngine } from "../../integrations/agent/engine-resolution.js";
+import { executeRunner } from "../../integrations/agent/runner-dispatch.js";
 /**
  * Fill `{{0}}`, `{{1}}`, ... placeholders in `template` with the
  * corresponding entries in `args`. Any placeholder index that exceeds the
@@ -59,12 +58,16 @@ async function resolveAssetBody(ref) {
     }
 }
 export async function akmAgentDispatch(options) {
-    if (!options.profileName?.trim()) {
-        throw new UsageError("agent: <profile> is required.", "MISSING_REQUIRED_ARGUMENT");
+    if (!options.agentConfig)
+        throw new UsageError("agent requires a valid config with an agent engine.", "MISSING_REQUIRED_ARGUMENT");
+    const engineName = options.engine ?? options.agentConfig.defaults?.engine;
+    if (!engineName)
+        throw new UsageError("agent requires --engine or defaults.engine.", "MISSING_REQUIRED_ARGUMENT");
+    const runner = resolveEngine(engineName, options.agentConfig);
+    if (runner.kind === "llm") {
+        throw new UsageError(`Engine "${engineName}" is an LLM engine; akm agent requires an agent engine.`, "INVALID_FLAG_VALUE");
     }
-    // Resolve the profile — throws ConfigError with an actionable hint when
-    // agent config is absent or the profile is not found.
-    const profile = requireAgentProfile(options.agentConfig, options.profileName.trim());
+    const profile = runner.profile;
     // Resolve the prompt text from whichever source was provided.
     let prompt;
     if (options.commandRef) {
@@ -79,7 +82,7 @@ export async function akmAgentDispatch(options) {
         prompt = options.prompt;
     }
     // When prompt is undefined, the agent is launched interactively.
-    const stdio = prompt === undefined && profile.sdkMode !== true ? "interactive" : profile.stdio;
+    const stdio = prompt === undefined && runner.kind !== "sdk" ? "interactive" : profile.stdio;
     // Build the final dispatch request: merge the caller-supplied dispatch with
     // the resolved prompt so the builder has all context in one place.
     const dispatchRequest = options.dispatch
@@ -93,14 +96,12 @@ export async function akmAgentDispatch(options) {
         ...(options.cwd ? { cwd: options.cwd } : {}),
         ...(dispatchRequest !== undefined ? { dispatch: dispatchRequest } : {}),
     };
-    const result = profile.sdkMode
-        ? await runOpencodeSdk(profile, prompt ?? "", runOptions, options.llmConfig)
-        : await runAgent(profile, prompt, runOptions);
+    const result = await executeRunner(runner, prompt ?? "", runOptions);
     return {
-        schemaVersion: 1,
+        schemaVersion: 2,
         ok: result.ok,
         shape: "agent-result",
-        profileName: profile.name,
+        engine: engineName,
         exitCode: result.exitCode,
         stdout: result.stdout ?? "",
         stderr: result.stderr ?? "",

package/dist/commands/agent/agent-support.js

@@ -1,30 +1,6 @@
 // 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 { loadConfig } from "../../core/config/config.js";
-import { requireAgentProfile, } from "../../integrations/agent/index.js";
-// ── Config helpers ───────────────────────────────────────────────────────────
-/**
- * Load the loaded AkmConfig from disk.
- *
- * After 0.8.0, the legacy `agent` top-level block was removed — the agent
- * profile data now lives on the unified `AkmConfig` (via `profiles.agent` and
- * `defaults.agent`). This helper remains for source-compat with callers that
- * still expect an "AgentConfig"; it now returns the loaded `AkmConfig`.
- */
-export function loadAgentConfigFromDisk() {
-    return loadConfig();
-}
-/**
- * Resolve the agent profile for a command's options.
- * Prefers an injected `agentProfile` (test seam) over the on-disk config.
- */
-export function resolveAgentProfile(options) {
-    if (options.agentProfile)
-        return options.agentProfile;
-    const agent = options.agentConfig ?? loadAgentConfigFromDisk();
-    return requireAgentProfile(agent, options.profile);
-}
 // ── Failure helpers ──────────────────────────────────────────────────────────
 /**
  * Base failure envelope shared by all agent command failures.

package/dist/commands/agent/contribute-cli.js

@@ -38,17 +38,13 @@ export const agentCommand = defineCommand({
         description: "Dispatch an agent CLI (opencode, claude, …) with an optional agent asset that provides the system prompt, model, and tool policy. Use <agent-ref> to embody a stash agent, --model to override the model, and --prompt/--command/--workflow to provide the task.",
     },
     args: {
-        profile: {
-            type: "positional",
-            description: "Agent profile / platform to use (opencode, claude, …)",
-            required: false,
-        },
         "agent-ref": {
             type: "positional",
             description: "Optional agent asset ref (e.g. agent:code-reviewer). Loads system prompt, model, and tool policy from the stash asset.",
             required: false,
         },
         prompt: { type: "string", description: "Task prompt to pass to the agent" },
+        engine: { type: "string", description: "Agent engine to use (default: defaults.engine)" },
         command: { type: "string", description: "Load prompt from a command: asset" },
         workflow: { type: "string", description: "Load prompt from a workflow: asset" },
         model: {
@@ -63,13 +59,8 @@ export const agentCommand = defineCommand({
     },
     async run({ args }) {
         await runWithJsonErrors(async () => {
-            if (!args.profile) {
-                throw new UsageError("Usage: akm agent <profile> [<agent-ref>] [--prompt <text>] [--model <model>]", "MISSING_REQUIRED_ARGUMENT", "Provide the agent profile name. Available profiles are listed in profiles.agent.");
-            }
             const timeoutMs = parsePositiveIntFlag(args["timeout-ms"], "--timeout-ms");
             const config = loadConfig();
-            const { getDefaultLlmConfig } = await import("../../core/config/config.js");
-            // After 0.8.0 the agent block IS the loaded AkmConfig.
             const agentConfig = config;
             // Resolve agent asset ref → extract system prompt, model, and tool policy.
             const agentRef = getStringArg(args, "agent-ref");
@@ -95,12 +86,11 @@ export const agentCommand = defineCommand({
             // platform-specific flags beyond the profile's base args).
             const hasDispatchContent = !!(promptText ?? commandRef ?? workflowRef ?? systemPrompt ?? model ?? assetTools);
             const result = await akmAgentDispatch({
-                profileName: String(args.profile),
+                engine: getStringArg(args, "engine"),
                 prompt: promptText,
                 commandRef,
                 workflowRef,
                 agentConfig,
-                llmConfig: getDefaultLlmConfig(config),
                 ...(hasDispatchContent
                     ? {
                         dispatch: {
@@ -125,7 +115,7 @@ export const agentCommand = defineCommand({
 export const lintCommand = defineCommand({
     meta: {
         name: "lint",
-        description: "Scan stash .md files for structural issues (unquoted colons, missing updated field, orphaned stubs, placeholder stubs, missing name/type, stale paths). Use --fix to auto-fix Tier 1 issues. Exits 0 on success regardless of findings; use --fail-on-flagged for CI fail-on-finding behavior.",
+        description: "Scan stash .md files for structural issues (unquoted colons, missing updated field, orphaned stubs, placeholder stubs, missing name/type, stale paths, broken refs in body text and in refs/xrefs/supersededBy/contradictedBy frontmatter). Use --fix to auto-fix Tier 1 issues. Exits 0 on success regardless of findings; use --fail-on-flagged for CI fail-on-finding behavior.",
     },
     args: {
         fix: {
@@ -182,7 +172,7 @@ export const proposeCommand = defineCommand({
         },
         task: { type: "string", description: "Task description for the agent (what should the asset do?)" },
         file: { type: "string", description: "Read the task or prompt text from a UTF-8 file" },
-        profile: { type: "string", description: "Override the agent profile (defaults to agent.default)" },
+        engine: { type: "string", description: "Engine to use (defaults to defaults.engine)" },
         "timeout-ms": { type: "string", description: "Override the agent CLI timeout in milliseconds" },
     },
     async run({ args }) {
@@ -207,7 +197,7 @@ export const proposeCommand = defineCommand({
                 type: String(args.type),
                 name: proposedName,
                 task: taskText,
-                profile: getStringArg(args, "profile"),
+                engine: getStringArg(args, "engine"),
                 ...(timeoutMs !== undefined ? { timeoutMs } : {}),
             });
             output("propose", result);

package/dist/commands/backup-cli.js

@@ -0,0 +1,56 @@
+// 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 { defineGroupCommand, defineJsonCommand, output } from "../cli/shared.js";
+import { UsageError } from "../core/errors.js";
+import { createMigrationBackup, MIGRATION_BACKUP_VERSION, restoreMigrationBackup } from "../core/migration-backup.js";
+function requireVersion(value) {
+    if (value !== MIGRATION_BACKUP_VERSION) {
+        throw new UsageError(`Unsupported migration backup target ${JSON.stringify(value)}; expected ${MIGRATION_BACKUP_VERSION}.`, "INVALID_FLAG_VALUE");
+    }
+}
+export const backupCommand = defineGroupCommand({
+    meta: { name: "backup", description: "Create or restore a verified migration recovery run" },
+    subCommands: {
+        create: defineJsonCommand({
+            meta: { name: "create", description: "Create a unique installation-scoped migration recovery run" },
+            args: {
+                for: { type: "string", required: true, description: "Migration target version (0.9.0)" },
+            },
+            run({ args }) {
+                requireVersion(args.for);
+                const result = createMigrationBackup();
+                output("backup", {
+                    action: "create",
+                    for: MIGRATION_BACKUP_VERSION,
+                    path: result.path,
+                    created: result.created,
+                    manifest: result.manifest,
+                });
+            },
+        }),
+        restore: defineJsonCommand({
+            meta: { name: "restore", description: "Restore a recovery run after preserving a rescue snapshot" },
+            args: {
+                for: { type: "string", required: true, description: "Migration target version (0.9.0)" },
+                run: { type: "string", description: "Backup run ID (defaults to the newest applicable run)" },
+                confirm: { type: "boolean", default: false, description: "Confirm destructive restoration" },
+            },
+            run({ args }) {
+                requireVersion(args.for);
+                const result = restoreMigrationBackup(args.confirm, args.run);
+                output("backup", {
+                    action: "restore",
+                    for: MIGRATION_BACKUP_VERSION,
+                    path: result.path,
+                    restored: true,
+                    rescuePath: result.rescuePath,
+                    manifest: result.manifest,
+                });
+            },
+        }),
+    },
+    defaultRun() {
+        throw new UsageError("Choose `backup create` or `backup restore`.", "MISSING_REQUIRED_ARGUMENT");
+    },
+});