akm-cli 0.9.0-rc.0 → 0.9.0-rc.13

package/dist/commands/sources/migration-help.js

@@ -116,12 +116,15 @@ export function renderMigrationHelp(versionInput, changelogText = loadChangelog(
     if (changelogText) {
         for (const candidate of candidates) {
             const section = extractChangelogSection(changelogText, candidate);
-            if (section) {
-                const bundled = loadReleaseNote(candidate);
-                if (!bundled)
-                    return `${section.trim()}\n\nFull changelog: ${CHANGELOG_URL}\n`;
+            const bundled = loadReleaseNote(candidate);
+            if (bundled) {
+                if (!section)
+                    return `${bundled.trim()}\n\nFull changelog: ${CHANGELOG_URL}\n`;
                 return `${bundled.trim()}\n\nRelease notes\n-------------\n${section.trim()}\n\nFull changelog: ${CHANGELOG_URL}\n`;
             }
+            if (section) {
+                return `${section.trim()}\n\nFull changelog: ${CHANGELOG_URL}\n`;
+            }
         }
     }
     const fallbackVersion = candidates.find((candidate) => candidate !== "latest") ?? requested;

package/dist/commands/sources/schema-repair.js

@@ -14,15 +14,16 @@
  */
 import fs from "node:fs";
 import path from "node:path";
-import { parseAssetRef } from "../../core/asset/asset-ref.js";
 import { assembleAsset } from "../../core/asset/asset-serialize.js";
 import { parseFrontmatter } from "../../core/asset/frontmatter.js";
+import { parseRefInput } from "../../core/asset/resolve-ref.js";
 import { authoringRulesForType } from "../../core/authoring-rules.js";
 import { appendEvent, readEvents } from "../../core/events.js";
+import { parseEmbeddedJsonResponse } from "../../core/parse.js";
 import { resolveStandardsContext } from "../../core/standards/resolve-standards-context.js";
 import { info } from "../../core/warn.js";
 import { resolveAssetPath } from "../../indexer/walk/path-resolver.js";
-import { chatCompletion, parseEmbeddedJsonResponse } from "../../llm/client.js";
+import { chatCompletion } from "../../llm/client.js";
 import { createProposal, isProposalSkipped } from "../proposal/repository.js";
 // ── Constants ────────────────────────────────────────────────────────────────
 /** Minimum gap between schema-repair attempts on the same asset. */
@@ -39,8 +40,8 @@ const SCHEMA_REPAIR_WINDOW_MS = 30 * 24 * 60 * 60 * 1000; // 30 days
 // ── Main ─────────────────────────────────────────────────────────────────────
 /**
  * Run the schema-repair loop for a batch of validation failures.
- * Returns a list of per-asset outcome records and the set of refs that were
- * successfully repaired (so the caller can exclude them from skip logic).
+ * Returns a list of per-asset outcome records and the set of refs whose live
+ * files were repaired. Queued proposals never count as live repairs.
  */
 export async function runSchemaRepairPass(failures, options) {
     const repairs = [];
@@ -55,7 +56,7 @@ export async function runSchemaRepairPass(failures, options) {
         // Cooldown: skip repair if we ran it successfully recently.
         const recentRepairs = readEvents({ type: "schema_repair_invoked", ref: failure.ref });
         const lastRepair = recentRepairs.events
-            .filter((e) => e.metadata?.outcome === "written")
+            .filter((e) => e.metadata?.outcome === "queued")
             .sort((a, b) => new Date(b.ts ?? 0).getTime() - new Date(a.ts ?? 0).getTime())[0];
         if (lastRepair?.ts && Date.now() - new Date(lastRepair.ts).getTime() < SCHEMA_REPAIR_COOLDOWN_MS) {
             repairs.push({ ref: failure.ref, reason: failure.reason, outcome: "skipped" });
@@ -106,7 +107,7 @@ export async function runSchemaRepairPass(failures, options) {
             const standardsSection = standardsContext.trim()
                 ? `\n\nStandards to follow (the rulebook for this target):\n${standardsContext.trim()}`
                 : "";
-            const assetType = parseAssetRef(failure.ref).type;
+            const assetType = parseRefInput(failure.ref).type;
             const authoringRules = authoringRulesForType(assetType);
             const authoringRulesSection = authoringRules ? `\n\n${authoringRules}` : "";
             const llmResponse = await chatFn(llmConfig, [
@@ -145,6 +146,8 @@ export async function runSchemaRepairPass(failures, options) {
             const proposalResult = createProposal(stashDir, {
                 ref: failure.ref,
                 source: "schema-repair",
+                // §23.6 fingerprint model-id term (WI-6.4).
+                modelId: llmConfig.model,
                 payload: {
                     content: newContent,
                     ...(Object.keys(newFm).length > 0 ? { frontmatter: newFm } : {}),
@@ -167,8 +170,6 @@ export async function runSchemaRepairPass(failures, options) {
                 outcome: "queued",
                 proposalId: proposalResult.id,
             });
-            // Mark as repaired so the caller removes it from the validation-failure set.
-            repairedRefs.add(failure.ref);
         }
         catch (e) {
             appendEvent({
@@ -184,7 +185,7 @@ export async function runSchemaRepairPass(failures, options) {
 // ── Default seam implementations ─────────────────────────────────────────────
 function defaultIsLessonCandidate(ref) {
     try {
-        const parsed = parseAssetRef(ref);
+        const parsed = parseRefInput(ref);
         return parsed.type === "lesson";
     }
     catch {

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

@@ -5,7 +5,8 @@ import * as childProcess from "node:child_process";
 import { createHash } from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
-import { fetchWithRetry, IS_WINDOWS } from "../../core/common.js";
+import { fetchWithRetry, IS_WINDOWS, ResponseTooLargeError, readBodyWithByteCap } from "../../core/common.js";
+import { ConfigError } from "../../core/errors.js";
 import { warn } from "../../core/warn.js";
 import { githubHeaders } from "../../integrations/github.js";
 import { getDirname, mainPath, semverOrder } from "../../runtime.js";
@@ -14,6 +15,64 @@ const DEFAULT_PACKAGE_NAME = "akm-cli";
 const NODE_MODULES_SEGMENT = "/node_modules/";
 const BUN_GLOBAL_INSTALL_PATTERN = /(^|\/)\.bun\/(?:[^/]+\/)+node_modules\//;
 const PNPM_GLOBAL_INSTALL_PATTERN = /(^|\/)(?:pnpm\/global|\.pnpm-global)(?:\/\d+)?\/node_modules\//;
+const MIGRATION_CONTRACT_VERSION = "0.9.0-rc.0";
+const MIGRATION_CONTRACT_BLOCKED_MESSAGE = "AKM 0.8 does not implement the migrate command or the --migration-config upgrade contract, so self-update cannot safely cross into 0.9. " +
+    "Prepare the 0.9 config and an independent backup, install or stage the 0.9 binary manually, then use the new binary to run: " +
+    "akm migrate apply --config <prepared-0.9.json>. See docs/migration/v0.8-to-v0.9.md.";
+const MAX_BINARY_DOWNLOAD_BYTES = 256 * 1024 * 1024;
+const MAX_CHECKSUM_METADATA_BYTES = 1024 * 1024;
+export function defaultMigrationCommand(preparedConfigPath) {
+    const configArgs = preparedConfigPath ? ["--config", preparedConfigPath] : [];
+    return {
+        preflight: (akmBin) => runRequiredCommand(akmBin, ["migrate", "status"], "Migration preflight"),
+        stagedPreflight: (akmBin) => runRequiredCommand(akmBin, ["migrate", "status", ...configArgs], "Staged migration preflight"),
+        apply: (akmBin) => runRequiredCommand(akmBin, ["migrate", "apply", ...configArgs], "Migration apply"),
+    };
+}
+async function streamResponseToFile(response, destination, maxBytes) {
+    const declaredText = response.headers.get("content-length");
+    if (declaredText) {
+        const declared = Number(declaredText);
+        if (Number.isFinite(declared) && declared > maxBytes) {
+            await response.body?.cancel().catch(() => undefined);
+            throw new ResponseTooLargeError(response.url || "binary download", maxBytes, declared);
+        }
+    }
+    if (!response.body)
+        throw new Error("Binary download response did not provide a streaming body.");
+    const fd = fs.openSync(destination, "w", 0o600);
+    const reader = response.body.getReader();
+    const hash = createHash("sha256");
+    let byteSize = 0;
+    try {
+        while (true) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            if (!value)
+                continue;
+            byteSize += value.byteLength;
+            if (byteSize > maxBytes) {
+                await reader.cancel().catch(() => undefined);
+                throw new ResponseTooLargeError(response.url || "binary download", maxBytes, byteSize);
+            }
+            hash.update(value);
+            let written = 0;
+            while (written < value.byteLength)
+                written += fs.writeSync(fd, value, written, value.byteLength - written);
+        }
+        fs.fdatasyncSync(fd);
+        return { byteSize, sha256: hash.digest("hex") };
+    }
+    catch (error) {
+        removeFileBestEffort(destination);
+        throw error;
+    }
+    finally {
+        reader.releaseLock();
+        fs.closeSync(fd);
+    }
+}
 /** Read live runtime signals. */
 export function getInstallSignals() {
     return {
@@ -63,7 +122,7 @@ export function getAkmBinaryName() {
         return "akm-darwin-arm64";
     if (platform === "win32" && arch === "x64")
         return "akm-windows-x64.exe";
-    throw new Error(`Unsupported platform for binary upgrade: ${platform}/${arch}`);
+    throw new ConfigError(`Unsupported platform for binary upgrade: ${platform}/${arch}`, "UNSUPPORTED_PLATFORM");
 }
 export async function checkForUpdate(currentVersion) {
     const installMethod = detectInstallMethod();
@@ -72,7 +131,7 @@ export async function checkForUpdate(currentVersion) {
     if (!response.ok) {
         throw new Error(`Failed to check for updates: ${response.status} ${response.statusText}`);
     }
-    const release = (await response.json());
+    const release = JSON.parse(await readBodyWithByteCap(response, MAX_CHECKSUM_METADATA_BYTES));
     const latestTag = release.tag_name ?? "";
     const latestVersion = latestTag.replace(/^v/, "");
     return {
@@ -82,10 +141,26 @@ export async function checkForUpdate(currentVersion) {
         installMethod,
     };
 }
-export async function performUpgrade(check, opts) {
+/**
+ * Whether the operator has asked to bypass upgrade checksum verification.
+ *
+ * Deliberately NOT a CLI flag (C6): STABILITY.md states checksum verification
+ * is not optional, so the recovery hatch for a genuinely broken `checksums.txt`
+ * is this internal, undocumented-on-purpose env var — not something
+ * discoverable in `--help` or offered by tab completion.
+ *
+ * Extracted rather than read inline so `performUpgrade` stays under the
+ * function-size bar (`scripts/lint-src-fn-size.ts`), whose baseline only
+ * shrinks.
+ */
+function checksumBypassRequested() {
+    return process.env.AKM_UPGRADE_SKIP_CHECKSUM === "1";
+}
+export async function performUpgrade(check, opts, dependencies) {
     const { currentVersion, latestVersion, installMethod } = check;
     const force = opts?.force === true;
     const skipPostUpgrade = opts?.skipPostUpgrade === true;
+    const migration = dependencies?.migration ?? defaultMigrationCommand(opts?.migrationConfig);
     // All install methods can short-circuit here unless the user explicitly forces an upgrade.
     if (!check.updateAvailable && !force) {
         return {
@@ -96,11 +171,17 @@ export async function performUpgrade(check, opts) {
             message: `akm v${currentVersion} is already the latest version`,
         };
     }
+    if (latestVersion &&
+        semverOrder(currentVersion, MIGRATION_CONTRACT_VERSION) < 0 &&
+        semverOrder(latestVersion, MIGRATION_CONTRACT_VERSION) >= 0) {
+        throw new ConfigError(MIGRATION_CONTRACT_BLOCKED_MESSAGE, "UPGRADE_BLOCKED");
+    }
     const packageManagerCommand = getPackageManagerUpgradeCommand(installMethod);
     if (packageManagerCommand) {
         if (!latestVersion) {
             throw new Error("Unable to determine latest version from GitHub releases. Check https://github.com/itlackey/akm/releases");
         }
+        migration.preflight("akm");
         const result = childProcess.spawnSync(packageManagerCommand.command, packageManagerCommand.args, {
             encoding: "utf8",
             env: process.env,
@@ -113,6 +194,7 @@ export async function performUpgrade(check, opts) {
             const details = (result.stderr ?? "").trim() || (result.stdout ?? "").trim() || `exit code ${result.status}`;
             throw new Error(`Failed to upgrade akm via ${installMethod}: ${details}\nRun manually: ${packageManagerCommand.displayCommand}`);
         }
+        migration.apply("akm");
         return {
             currentVersion,
             newVersion: latestVersion,
@@ -139,31 +221,53 @@ export async function performUpgrade(check, opts) {
     const binaryName = getAkmBinaryName();
     const binaryUrl = `https://github.com/${REPO}/releases/download/${tag}/${binaryName}`;
     const checksumsUrl = `https://github.com/${REPO}/releases/download/${tag}/checksums.txt`;
+    const execPath = dependencies?.execPath ?? process.execPath;
+    const execDir = path.dirname(execPath);
+    const execName = path.basename(execPath);
+    const stagedPath = IS_WINDOWS
+        ? path.join(execDir, `.${execName}.new.${process.pid}`)
+        : path.join(execDir, `.${execName}.tmp.${process.pid}`);
+    const backupPath = `${execPath}${IS_WINDOWS ? ".old" : ".bak"}`;
     // Download binary
     const binaryResponse = await fetchWithRetry(binaryUrl);
     if (!binaryResponse.ok) {
         throw new Error(`Failed to download binary: ${binaryResponse.status} ${binaryResponse.statusText}`);
     }
-    const binaryData = new Uint8Array(await binaryResponse.arrayBuffer());
-    // Download and verify checksum (mandatory — upgrade is blocked if checksums cannot be fetched)
+    let downloaded;
+    try {
+        downloaded = await streamResponseToFile(binaryResponse, stagedPath, MAX_BINARY_DOWNLOAD_BYTES);
+        if (!IS_WINDOWS)
+            fs.chmodSync(stagedPath, 0o755);
+    }
+    catch (err) {
+        removeFileBestEffort(stagedPath);
+        const code = err.code;
+        if (code === "EACCES" || code === "EPERM") {
+            throw new ConfigError(`Permission denied writing to ${execDir}.\n` +
+                `${IS_WINDOWS ? "Try running as Administrator." : "Run: sudo akm upgrade"}\n` +
+                `Or re-run the install script: curl -fsSL https://raw.githubusercontent.com/${REPO}/main/install.sh | bash`, "UPGRADE_BLOCKED");
+        }
+        throw err;
+    }
+    // Download and verify checksum (mandatory — upgrade is blocked if checksums cannot be fetched).
     let checksumVerified = false;
-    const skipChecksum = opts?.skipChecksum === true;
+    const skipChecksum = checksumBypassRequested();
     try {
         const checksumsResponse = await fetchWithRetry(checksumsUrl);
         if (!checksumsResponse.ok) {
             if (skipChecksum) {
-                warn(`WARNING: checksums.txt fetch failed (HTTP ${checksumsResponse.status}). Proceeding without verification because --skip-checksum was provided.`);
+                warn(`WARNING: checksums.txt fetch failed (HTTP ${checksumsResponse.status}). Proceeding without verification because AKM_UPGRADE_SKIP_CHECKSUM=1 was set.`);
             }
             else {
                 throw new Error(`Checksum verification failed: could not fetch ${checksumsUrl} (HTTP ${checksumsResponse.status}). ` +
-                    `Use --skip-checksum to bypass (not recommended).`);
+                    `Set AKM_UPGRADE_SKIP_CHECKSUM=1 to bypass (not recommended).`);
             }
         }
         else {
-            const checksumsText = await checksumsResponse.text();
+            const checksumsText = await readBodyWithByteCap(checksumsResponse, MAX_CHECKSUM_METADATA_BYTES);
             const expectedHash = parseChecksumForFile(checksumsText, binaryName);
             if (expectedHash) {
-                const actualHash = createHash("sha256").update(binaryData).digest("hex");
+                const actualHash = downloaded.sha256;
                 if (actualHash !== expectedHash) {
                     throw new Error(`Checksum mismatch for ${binaryName}.\n` + `Expected: ${expectedHash}\n` + `Got:      ${actualHash}`);
                 }
@@ -171,11 +275,11 @@ export async function performUpgrade(check, opts) {
             }
             else {
                 if (skipChecksum) {
-                    warn(`WARNING: ${binaryName} not found in checksums.txt. Proceeding without verification because --skip-checksum was provided.`);
+                    warn(`WARNING: ${binaryName} not found in checksums.txt. Proceeding without verification because AKM_UPGRADE_SKIP_CHECKSUM=1 was set.`);
                 }
                 else {
                     throw new Error(`Checksum verification failed: ${binaryName} not listed in checksums.txt. ` +
-                        `Use --skip-checksum to bypass (not recommended).`);
+                        `Set AKM_UPGRADE_SKIP_CHECKSUM=1 to bypass (not recommended).`);
                 }
             }
         }
@@ -183,106 +287,54 @@ export async function performUpgrade(check, opts) {
     catch (err) {
         if (err instanceof Error &&
             (err.message.includes("Checksum mismatch") || err.message.includes("Checksum verification failed"))) {
+            removeFileBestEffort(stagedPath);
             throw err;
         }
         // Network or parse failure
         if (skipChecksum) {
-            warn(`WARNING: Could not fetch or parse checksums: ${err instanceof Error ? err.message : String(err)}. Proceeding because --skip-checksum was provided.`);
+            warn(`WARNING: Could not fetch or parse checksums: ${err instanceof Error ? err.message : String(err)}. Proceeding because AKM_UPGRADE_SKIP_CHECKSUM=1 was set.`);
         }
         else {
+            removeFileBestEffort(stagedPath);
             throw new Error(`Checksum verification failed: ${err instanceof Error ? err.message : String(err)}. ` +
-                `Use --skip-checksum to bypass (not recommended).`);
+                `Set AKM_UPGRADE_SKIP_CHECKSUM=1 to bypass (not recommended).`);
         }
     }
-    const execPath = process.execPath;
-    const execDir = path.dirname(execPath);
-    const execName = path.basename(execPath);
-    if (IS_WINDOWS) {
-        // Windows: rename running exe, write new one, clean up old on success
-        const oldPath = `${execPath}.old`;
-        try {
-            fs.renameSync(execPath, oldPath);
-        }
-        catch (err) {
-            const code = err.code;
-            if (code === "EPERM" || code === "EACCES") {
-                throw new Error(`Permission denied. Cannot rename ${execPath}.\n` +
-                    `Try running as Administrator, or re-download from https://github.com/${REPO}/releases`);
-            }
-            const detail = err instanceof Error ? err.message : String(err);
-            throw new Error(`Failed to rename ${execPath}: ${detail}`);
-        }
-        try {
-            fs.writeFileSync(execPath, binaryData);
-        }
-        catch (err) {
-            // Restore from old
-            fs.renameSync(oldPath, execPath);
-            throw err;
-        }
-        // Best-effort cleanup of .old
-        try {
-            fs.unlinkSync(oldPath);
-        }
-        catch {
-            // Windows may lock the old exe — it will be cleaned up on next startup or manually
-        }
+    try {
+        migration.preflight(execPath);
+        migration.stagedPreflight(stagedPath);
     }
-    else {
-        // Unix: write to temp file, chmod +x, atomic rename
-        const tmpPath = path.join(execDir, `.${execName}.tmp.${process.pid}`);
-        const bakPath = `${execPath}.bak`;
-        try {
-            fs.writeFileSync(tmpPath, binaryData);
-            fs.chmodSync(tmpPath, 0o755);
-        }
-        catch (err) {
-            // Clean up temp file on failure
-            try {
-                fs.unlinkSync(tmpPath);
-            }
-            catch {
-                /* ignore */
-            }
-            const code = err.code;
-            if (code === "EACCES" || code === "EPERM") {
-                throw new Error(`Permission denied writing to ${execDir}.\n` +
-                    `Run: sudo akm upgrade\n` +
-                    `Or re-run the install script: curl -fsSL https://raw.githubusercontent.com/${REPO}/main/install.sh | bash`);
-            }
-            throw err;
-        }
-        // Backup current, then atomic rename
-        try {
-            fs.copyFileSync(execPath, bakPath);
-            fs.renameSync(tmpPath, execPath);
-        }
-        catch (err) {
-            // Restore from backup if rename failed
-            try {
-                fs.unlinkSync(tmpPath);
-            }
-            catch {
-                /* ignore */
-            }
-            try {
-                if (fs.existsSync(bakPath) && !fs.existsSync(execPath)) {
-                    fs.renameSync(bakPath, execPath);
-                }
-            }
-            catch {
-                /* ignore */
-            }
-            throw err;
-        }
-        // Cleanup backup
-        try {
-            fs.unlinkSync(bakPath);
-        }
-        catch {
-            /* ignore */
+    catch (err) {
+        removeFileBestEffort(stagedPath);
+        throw err;
+    }
+    if (fs.existsSync(backupPath)) {
+        removeFileBestEffort(stagedPath);
+        throw new ConfigError(`Refusing to overwrite retained previous binary at ${backupPath}.`, "UPGRADE_BLOCKED");
+    }
+    try {
+        if (IS_WINDOWS)
+            fs.renameSync(execPath, backupPath);
+        else
+            fs.copyFileSync(execPath, backupPath);
+        fs.renameSync(stagedPath, execPath);
+    }
+    catch (err) {
+        removeFileBestEffort(stagedPath);
+        if (!fs.existsSync(execPath) && fs.existsSync(backupPath)) {
+            fs.renameSync(backupPath, execPath);
         }
+        throw err;
+    }
+    try {
+        migration.apply(execPath);
     }
+    catch (err) {
+        const detail = err instanceof Error ? err.message : String(err);
+        throw new Error(`Migration apply failed; the new binary remains installed and the previous binary retained at ${backupPath}: ${detail}`);
+    }
+    // Keep the previous binary available until migration apply has completed.
+    removeFileBestEffort(backupPath);
     return {
         currentVersion,
         newVersion: latestVersion,
@@ -290,32 +342,19 @@ export async function performUpgrade(check, opts) {
         installMethod,
         binaryPath: execPath,
         checksumVerified,
-        // For binary installs, the new binary now lives at execPath; spawn it
-        // directly so the post-upgrade work runs against the new code.
         postUpgrade: runPostUpgradeTasks(execPath, { skip: skipPostUpgrade }),
     };
 }
 /**
- * Run the post-upgrade tasks against the *new* binary as a child process.
- *
- * Why a child process: the running akm process still has the old code in
- * memory. Calling loadConfig()/akmIndex() in-process would use the old
- * implementations and miss any DB_VERSION / config-key changes the new
- * release introduces.
- *
- * The new binary's `akm index` does the work for us:
- *   1. loadConfig() runs at startup — auto-migrates legacy `stashes` →
- *      `sources` if the on-disk config still uses the old key.
- *   2. ensureSchema() converges index.db forward via its idempotent baseline
- *      schema + additive migrations (no destructive rebuild).
- *   3. The full reindex repopulates entries + workflow_documents + FTS.
+ * Rebuild the derived index after the explicit migration command succeeds.
+ * Migration and indexing are intentionally separate lifecycle steps.
  */
 function runPostUpgradeTasks(akmBin, opts) {
     if (opts.skip) {
         return {
             ok: true,
             skipped: true,
-            message: "Skipped post-upgrade tasks. Run `akm index` manually to migrate config and rebuild the index.",
+            message: "Migration completed; skipped the index rebuild. Run `akm index` manually to rebuild the index.",
         };
     }
     try {
@@ -328,7 +367,7 @@ function runPostUpgradeTasks(akmBin, opts) {
             return {
                 ok: false,
                 skipped: false,
-                message: `Post-upgrade tasks could not start: ${result.error.message}. Run \`akm index\` manually.`,
+                message: `Migration completed, but the index rebuild could not start: ${result.error.message}. Run \`akm index\` manually.`,
             };
         }
         if (result.status !== 0) {
@@ -337,14 +376,14 @@ function runPostUpgradeTasks(akmBin, opts) {
                 ok: false,
                 skipped: false,
                 exitCode: result.status,
-                message: `Post-upgrade \`akm index\` failed (${detail}). Run \`akm index\` manually.`,
+                message: `Migration completed, but post-upgrade \`akm index\` failed (${detail}). Run \`akm index\` manually.`,
             };
         }
         return {
             ok: true,
             skipped: false,
             exitCode: 0,
-            message: "Config migrated (if needed) and index rebuilt against the new binary.",
+            message: "Migration completed and the index was rebuilt against the new binary.",
         };
     }
     catch (err) {
@@ -352,10 +391,32 @@ function runPostUpgradeTasks(akmBin, opts) {
         return {
             ok: false,
             skipped: false,
-            message: `Post-upgrade tasks failed: ${detail}. Run \`akm index\` manually.`,
+            message: `Migration completed, but the index rebuild failed: ${detail}. Run \`akm index\` manually.`,
         };
     }
 }
+function runRequiredCommand(akmBin, args, label) {
+    const result = childProcess.spawnSync(akmBin, args, {
+        encoding: "utf8",
+        env: process.env,
+        stdio: "pipe",
+    });
+    if (result.error) {
+        throw new Error(`${label} could not start: ${result.error.message}`);
+    }
+    if (result.status !== 0) {
+        const detail = (result.stderr ?? "").trim() || (result.stdout ?? "").trim() || `exit code ${result.status}`;
+        throw new Error(`${label} failed (${detail}).`);
+    }
+}
+function removeFileBestEffort(filePath) {
+    try {
+        fs.unlinkSync(filePath);
+    }
+    catch {
+        // Cleanup is best-effort; the primary operation determines success.
+    }
+}
 function parseChecksumForFile(checksumsText, filename) {
     for (const line of checksumsText.split("\n")) {
         const trimmed = line.trim();