coding-agent-harness 1.0.5 → 1.0.6

package/dist/check-runtime-emit.mjs

@@ -0,0 +1,304 @@
+#!/usr/bin/env node
+// @ts-nocheck
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+const defaultRepoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const typescriptVersion = "5.9.3";
+export function checkRuntimeEmitContract({ projectRoot = defaultRepoRoot, configPath, expectedDir, outDir, } = {}) {
+    const violations = [];
+    const usesDefaultConfig = configPath === undefined;
+    const resolvedConfigPath = configPath || path.join(projectRoot, "tsconfig.dist.json");
+    const absoluteProjectRoot = path.resolve(projectRoot);
+    const absoluteConfig = path.resolve(resolvedConfigPath);
+    const absoluteOutDir = outDir ? path.resolve(outDir) : fs.mkdtempSync(path.join(os.tmpdir(), "harness-runtime-emit-out-"));
+    const absoluteExpectedDir = expectedDir ? path.resolve(expectedDir) : usesDefaultConfig ? path.join(absoluteProjectRoot, "dist") : undefined;
+    const sourceFiles = collectSourceFiles(absoluteProjectRoot, { roots: absoluteExpectedDir && !usesDefaultConfig ? undefined : ["scripts"] });
+    if (!fs.existsSync(absoluteConfig)) {
+        return {
+            ok: false,
+            violations: [{ code: "missing-config", message: `runtime emit config not found: ${absoluteConfig}` }],
+        };
+    }
+    if (absoluteExpectedDir && !fs.existsSync(absoluteExpectedDir)) {
+        violations.push({
+            code: "missing-expected-dir",
+            message: `runtime emit expected directory not found: ${absoluteExpectedDir}`,
+        });
+    }
+    for (const source of sourceFiles) {
+        const content = fs.readFileSync(source, "utf8");
+        for (const specifier of parseLocalImportSpecifiers(content)) {
+            if (/\.(ts|mts)$/.test(specifier)) {
+                violations.push({
+                    code: "typescript-source-import",
+                    file: toPosix(path.relative(absoluteProjectRoot, source)),
+                    specifier,
+                    message: `${toPosix(path.relative(absoluteProjectRoot, source))} imports TypeScript source specifier ${specifier}`,
+                });
+            }
+        }
+    }
+    if (sourceFiles.length === 0 && !absoluteExpectedDir) {
+        return {
+            ok: violations.length === 0,
+            violations,
+            outDir: absoluteOutDir,
+            expectedDir: absoluteExpectedDir,
+            skippedEmit: true,
+            sourceFiles: 0,
+        };
+    }
+    const emit = runTypeScriptEmit({ projectRoot: absoluteProjectRoot, configPath: absoluteConfig, outDir: absoluteOutDir });
+    if (emit.status !== 0) {
+        violations.push({
+            code: "emit-failed",
+            message: `TypeScript runtime emit failed\nSTDOUT:\n${emit.stdout}\nSTDERR:\n${emit.stderr}`,
+        });
+    }
+    if (absoluteExpectedDir && fs.existsSync(absoluteExpectedDir) && emit.status === 0) {
+        compareDirectories({
+            expectedDir: absoluteExpectedDir,
+            actualDir: absoluteOutDir,
+            violations,
+        });
+    }
+    return {
+        ok: violations.length === 0,
+        violations,
+        outDir: absoluteOutDir,
+        expectedDir: absoluteExpectedDir,
+        skippedEmit: false,
+        sourceFiles: sourceFiles.length,
+    };
+}
+function runTypeScriptEmit({ projectRoot, configPath, outDir }) {
+    return spawnSync("npm", ["exec", "--yes", "--package", `typescript@${typescriptVersion}`, "--", "tsc", "-p", configPath, "--outDir", outDir, "--noCheck"], {
+        cwd: projectRoot,
+        encoding: "utf8",
+    });
+}
+function compareDirectories({ expectedDir, actualDir, violations }) {
+    const expectedFiles = collectFiles(expectedDir).filter((file) => file.endsWith(".mjs")).sort();
+    const actualFiles = collectFiles(actualDir).filter((file) => file.endsWith(".mjs")).sort();
+    const expectedRelatives = expectedFiles.map((file) => toPosix(path.relative(expectedDir, file)));
+    const actualRelatives = actualFiles.map((file) => toPosix(path.relative(actualDir, file)));
+    for (const relative of expectedRelatives) {
+        if (!actualRelatives.includes(relative)) {
+            violations.push({
+                code: "missing-emitted-file",
+                file: relative,
+                message: `expected emitted file missing: ${relative}`,
+            });
+        }
+    }
+    for (const relative of actualRelatives) {
+        if (!expectedRelatives.includes(relative)) {
+            violations.push({
+                code: "unexpected-emitted-file",
+                file: relative,
+                message: `unexpected emitted file: ${relative}`,
+            });
+            continue;
+        }
+        const expected = fs.readFileSync(path.join(expectedDir, relative), "utf8");
+        const actual = fs.readFileSync(path.join(actualDir, relative), "utf8");
+        if (expected !== actual) {
+            violations.push({
+                code: "emit-drift",
+                file: relative,
+                message: `emitted .mjs drift detected: ${relative}`,
+            });
+        }
+    }
+}
+function collectSourceFiles(projectRoot, { roots } = {}) {
+    const files = [];
+    const sourceRoots = roots?.length ? roots.map((root) => path.join(projectRoot, root)) : [projectRoot];
+    for (const sourceRoot of sourceRoots) {
+        if (fs.existsSync(sourceRoot))
+            walk(sourceRoot, files, (file) => file.endsWith(".mts"), projectRoot);
+    }
+    return files.sort();
+}
+function collectFiles(directory) {
+    const files = [];
+    if (fs.existsSync(directory))
+        walk(directory, files, () => true);
+    return files.sort();
+}
+function walk(current, files, predicate, sourceRoot) {
+    const stat = fs.lstatSync(current);
+    if (stat.isSymbolicLink())
+        return;
+    if (stat.isDirectory()) {
+        const name = path.basename(current);
+        const topLevel = sourceRoot ? path.relative(sourceRoot, current).split(path.sep)[0] : "";
+        if (name === "node_modules" || name === ".git" || name === ".worktrees" || name === "tmp" || topLevel === "fixtures")
+            return;
+        for (const entry of fs.readdirSync(current))
+            walk(path.join(current, entry), files, predicate, sourceRoot);
+        return;
+    }
+    if (stat.isFile() && predicate(current))
+        files.push(current);
+}
+function parseLocalImportSpecifiers(content) {
+    const specifiers = [];
+    let index = 0;
+    while (index < content.length) {
+        const skipped = skipNonCode(content, index);
+        if (skipped !== index) {
+            index = skipped;
+            continue;
+        }
+        if (isKeywordAt(content, index, "import")) {
+            const afterKeyword = skipWhitespace(content, index + "import".length);
+            if (content[afterKeyword] === "(") {
+                const specifier = readFirstStringArgument(content, afterKeyword + 1);
+                if (isLocalSpecifier(specifier))
+                    specifiers.push(specifier);
+                index = afterKeyword + 1;
+                continue;
+            }
+            const statement = content.slice(index, findStatementEnd(content, index));
+            const sideEffect = statement.match(/\bimport\s+["']([^"']+)["']/s);
+            const fromImport = statement.match(/\bfrom\s*["']([^"']+)["']/s);
+            const specifier = fromImport?.[1] || sideEffect?.[1];
+            if (isLocalSpecifier(specifier))
+                specifiers.push(specifier);
+        }
+        else if (isKeywordAt(content, index, "export")) {
+            const statement = content.slice(index, findStatementEnd(content, index));
+            const fromExport = statement.match(/\bfrom\s*["']([^"']+)["']/s);
+            if (isLocalSpecifier(fromExport?.[1]))
+                specifiers.push(fromExport[1]);
+        }
+        index += 1;
+    }
+    return specifiers;
+}
+function isLocalSpecifier(specifier) {
+    return typeof specifier === "string" && (specifier.startsWith("./") || specifier.startsWith("../"));
+}
+function skipNonCode(content, index) {
+    const char = content[index];
+    const next = content[index + 1];
+    if (char === "/" && next === "/") {
+        const lineEnd = content.indexOf("\n", index + 2);
+        return lineEnd === -1 ? content.length : lineEnd + 1;
+    }
+    if (char === "/" && next === "*") {
+        const commentEnd = content.indexOf("*/", index + 2);
+        return commentEnd === -1 ? content.length : commentEnd + 2;
+    }
+    if (char === "'" || char === '"' || char === "`")
+        return skipString(content, index, char);
+    return index;
+}
+function skipString(content, index, quote) {
+    let cursor = index + 1;
+    while (cursor < content.length) {
+        if (content[cursor] === "\\") {
+            cursor += 2;
+            continue;
+        }
+        if (content[cursor] === quote)
+            return cursor + 1;
+        cursor += 1;
+    }
+    return content.length;
+}
+function isKeywordAt(content, index, keyword) {
+    if (!content.startsWith(keyword, index))
+        return false;
+    const before = content[index - 1];
+    const after = content[index + keyword.length];
+    return !isIdentifierChar(before) && !isIdentifierChar(after);
+}
+function isIdentifierChar(char) {
+    return typeof char === "string" && /[A-Za-z0-9_$]/.test(char);
+}
+function skipWhitespace(content, index) {
+    let cursor = index;
+    while (/\s/.test(content[cursor] || ""))
+        cursor += 1;
+    return cursor;
+}
+function findStatementEnd(content, index) {
+    let cursor = index;
+    while (cursor < content.length) {
+        const skipped = skipNonCode(content, cursor);
+        if (skipped !== cursor) {
+            cursor = skipped;
+            continue;
+        }
+        if (content[cursor] === ";")
+            return cursor + 1;
+        if (content[cursor] === "\n")
+            return cursor;
+        cursor += 1;
+    }
+    return content.length;
+}
+function readFirstStringArgument(content, index) {
+    const start = skipWhitespace(content, index);
+    const quote = content[start];
+    if (quote !== "'" && quote !== '"')
+        return undefined;
+    let cursor = start + 1;
+    let value = "";
+    while (cursor < content.length) {
+        const char = content[cursor];
+        if (char === "\\") {
+            value += content[cursor + 1] || "";
+            cursor += 2;
+            continue;
+        }
+        if (char === quote)
+            return value;
+        value += char;
+        cursor += 1;
+    }
+    return undefined;
+}
+function toPosix(value) {
+    return value.split(path.sep).join("/");
+}
+function parseArgs(argv) {
+    const args = {};
+    for (let index = 0; index < argv.length; index += 1) {
+        const arg = argv[index];
+        if (arg === "--project-root")
+            args.projectRoot = argv[++index];
+        else if (arg === "--config")
+            args.configPath = argv[++index];
+        else if (arg === "--expected-dir")
+            args.expectedDir = argv[++index];
+        else if (arg === "--out-dir")
+            args.outDir = argv[++index];
+        else
+            throw new Error(`Unknown argument: ${arg}`);
+    }
+    return args;
+}
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+    try {
+        const result = checkRuntimeEmitContract(parseArgs(process.argv.slice(2)));
+        if (!result.ok) {
+            console.error(result.violations.map((violation) => violation.message).join("\n"));
+            process.exit(1);
+        }
+        if (result.skippedEmit) {
+            console.log("Runtime emit contract passed (no runtime .mts sources)");
+            process.exit(0);
+        }
+        console.log("Runtime emit contract passed");
+    }
+    catch (error) {
+        console.error(error instanceof Error ? error.message : String(error));
+        process.exit(1);
+    }
+}

package/dist/check-type-boundaries.mjs

@@ -0,0 +1,139 @@
+#!/usr/bin/env node
+// @ts-nocheck
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+const defaultRepoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const sourceRoots = ["scripts", "tests"];
+const importPattern = /\b(import|export)\s+(type\s+)?(?:[^'"]*?\s+from\s+)?["']([^"']+)["']|\bimport\s*\(\s*["']([^"']+)["']\s*\)/g;
+const tsEscapePattern = /@(ts-ignore|ts-expect-error)\b|(?:^|[^A-Za-z0-9_$])(?:as\s+any|:\s*any\b)/;
+export function checkTypeBoundaries({ repoRoot = defaultRepoRoot } = {}) {
+    const files = collectSourceFiles(repoRoot);
+    const violations = [];
+    for (const file of files) {
+        const absolutePath = path.join(repoRoot, file);
+        const content = fs.readFileSync(absolutePath, "utf8");
+        const imports = parseImports(content);
+        if (file.endsWith(".ts")) {
+            const lines = content.split(/\r?\n/);
+            for (const [index, line] of lines.entries()) {
+                if (tsEscapePattern.test(line)) {
+                    violations.push({
+                        code: "ts-escape-hatch",
+                        file,
+                        line: index + 1,
+                        message: `${file}:${index + 1} uses a TypeScript escape hatch that requires review`,
+                    });
+                }
+            }
+        }
+        for (const imported of imports) {
+            if (!isLocalSpecifier(imported.specifier))
+                continue;
+            const target = resolveLocalSpecifier(repoRoot, file, imported.specifier);
+            if (file.endsWith(".mjs") && (hasTypeScriptSourceExtension(imported.specifier) || hasTypeScriptSourceExtension(target))) {
+                violations.push({
+                    code: "mjs-imports-ts",
+                    file,
+                    specifier: imported.specifier,
+                    message: `${file} imports TypeScript from runtime .mjs: ${imported.specifier}`,
+                });
+            }
+            if (target && isSharedTypesPath(target) && !isTypeOnlyTypeScriptImport(file, imported)) {
+                violations.push({
+                    code: "types-value-import",
+                    file,
+                    specifier: imported.specifier,
+                    message: `${file} value-imports shared type island: ${imported.specifier}`,
+                });
+            }
+        }
+    }
+    return { ok: violations.length === 0, violations };
+}
+function collectSourceFiles(repoRoot) {
+    const files = [];
+    for (const root of sourceRoots) {
+        const absoluteRoot = path.join(repoRoot, root);
+        if (!fs.existsSync(absoluteRoot))
+            continue;
+        walk(absoluteRoot, files, repoRoot);
+    }
+    return files.sort();
+}
+function walk(current, files, repoRoot) {
+    const stat = fs.lstatSync(current);
+    if (stat.isSymbolicLink())
+        return;
+    if (stat.isDirectory()) {
+        const name = path.basename(current);
+        if (name === "node_modules" || name === ".worktrees" || name === "tmp")
+            return;
+        for (const entry of fs.readdirSync(current))
+            walk(path.join(current, entry), files, repoRoot);
+        return;
+    }
+    if (stat.isFile() && /\.(mjs|mts|ts)$/.test(current)) {
+        files.push(path.relative(repoRoot, current).split(path.sep).join("/"));
+    }
+}
+function parseImports(content) {
+    const imports = [];
+    for (const match of content.matchAll(importPattern)) {
+        imports.push({
+            kind: match[1] || "import",
+            typeOnly: match[2] === "type ",
+            specifier: match[3] || match[4],
+        });
+    }
+    return imports;
+}
+function isLocalSpecifier(specifier) {
+    return specifier.startsWith("./") || specifier.startsWith("../") || specifier.startsWith("/");
+}
+function resolveLocalSpecifier(repoRoot, importer, specifier) {
+    const importerDir = path.dirname(path.join(repoRoot, importer));
+    const basePath = specifier.startsWith("/") ? path.join(repoRoot, specifier) : path.resolve(importerDir, specifier);
+    const candidates = candidatePaths(basePath);
+    for (const candidate of candidates) {
+        if (fs.existsSync(candidate))
+            return path.relative(repoRoot, candidate).split(path.sep).join("/");
+    }
+    const relative = path.relative(repoRoot, basePath).split(path.sep).join("/");
+    return relative.startsWith("..") ? undefined : relative;
+}
+function candidatePaths(basePath) {
+    const extension = path.extname(basePath);
+    if (extension) {
+        const paths = [basePath];
+        if (extension === ".js")
+            paths.push(basePath.slice(0, -3) + ".ts", basePath.slice(0, -3) + ".mts");
+        return paths;
+    }
+    return [
+        basePath,
+        `${basePath}.mjs`,
+        `${basePath}.mts`,
+        `${basePath}.ts`,
+        `${basePath}.js`,
+        path.join(basePath, "index.mjs"),
+        path.join(basePath, "index.ts"),
+    ];
+}
+function isSharedTypesPath(relativePath) {
+    return relativePath === "scripts/lib/types" || relativePath.startsWith("scripts/lib/types/");
+}
+function hasTypeScriptSourceExtension(filePath) {
+    return typeof filePath === "string" && /\.(mts|ts)$/.test(filePath);
+}
+function isTypeOnlyTypeScriptImport(file, imported) {
+    return file.endsWith(".ts") && imported.kind === "import" && imported.typeOnly;
+}
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+    const result = checkTypeBoundaries();
+    if (!result.ok) {
+        console.error(result.violations.map((violation) => violation.message).join("\n"));
+        process.exit(1);
+    }
+    console.log("Type boundary guards passed");
+}

package/dist/commands/dashboard-command.mjs

@@ -0,0 +1,80 @@
+// @ts-nocheck
+// Dashboard command parsing stays behavior-first until command handler types are modeled.
+import fs from "node:fs";
+import path from "node:path";
+import { normalizeTarget, serveDashboardWorkbench, writeDashboardFolder, writeDashboardSingleFile, } from "../lib/harness-core.mjs";
+import { dashboardWatchRoots } from "../lib/harness-paths.mjs";
+export async function runDashboardCommand({ takeFlag, takeOption, targetArg }) {
+    const watch = takeFlag("--watch");
+    const workbench = takeFlag("--workbench");
+    const out = takeOption("--out", path.join("tmp", "harness-dashboard.html"));
+    const outDir = takeOption("--out-dir", "");
+    const host = takeOption("--host", "127.0.0.1");
+    const port = takeOption("--port", "0");
+    const localeOverride = takeOption("--locale", "");
+    const opts = localeOverride ? { localeOverride } : {};
+    if (workbench) {
+        if (!outDir) {
+            console.error("dashboard --workbench requires --out-dir so regenerated data has a stable folder");
+            process.exit(2);
+        }
+        try {
+            assertV2DashboardTarget(targetArg());
+            await serveDashboardWorkbench(outDir, targetArg(), { ...opts, host, port });
+        }
+        catch (error) {
+            console.error(error.message);
+            process.exit(1);
+        }
+    }
+    if (watch) {
+        if (!outDir) {
+            console.error("dashboard --watch requires --out-dir so updates are written to a stable folder");
+            process.exit(2);
+        }
+        const target = targetArg();
+        assertV2DashboardTarget(target);
+        const normalizedTarget = normalizeTarget(target);
+        const watchRoots = dashboardWatchRoots(normalizedTarget.harness);
+        const regenerate = () => {
+            try {
+                console.log(writeDashboardFolder(outDir, target, opts));
+                console.log(`dashboard regenerated: ${new Date().toISOString()}`);
+            }
+            catch (error) {
+                console.error(`dashboard regeneration failed: ${error.message}`);
+            }
+        };
+        regenerate();
+        let timer = null;
+        const watchers = watchRoots.map((watchRoot) => fs.watch(watchRoot, { recursive: true }, () => {
+            clearTimeout(timer);
+            timer = setTimeout(regenerate, 300);
+        }));
+        const close = () => {
+            for (const watcher of watchers)
+                watcher.close();
+            clearTimeout(timer);
+            process.exit(0);
+        };
+        process.on("SIGINT", close);
+        process.on("SIGTERM", close);
+        console.log(`watching ${watchRoots.join(", ")}`);
+        await new Promise(() => { });
+    }
+    assertV2DashboardTarget(targetArg());
+    if (outDir) {
+        console.log(writeDashboardFolder(outDir, targetArg(), opts));
+    }
+    else {
+        console.log(writeDashboardSingleFile(out, targetArg(), opts));
+    }
+    process.exit(0);
+}
+function assertV2DashboardTarget(target) {
+    const normalizedTarget = normalizeTarget(target);
+    if (normalizedTarget.harness?.version === 2)
+        return;
+    console.error("dashboard requires v2 harness structure; run `harness migrate-structure --plan` then `harness migrate-structure --apply`");
+    process.exit(1);
+}

package/dist/commands/migration-command.mjs

@@ -0,0 +1,152 @@
+// @ts-nocheck
+import { applyStructureMigration, buildMigrationPlan, planStructureMigration, runMigration, verifyMigrationSession, } from "../lib/harness-core.mjs";
+import { applyTaskAuditIndexMigration, planTaskAuditIndexMigration, } from "../lib/task-audit-migration.mjs";
+export function runMigrationCommand(command, { args, takeFlag, takeOption, targetArg }) {
+    if (command === "migrate-structure") {
+        const json = takeFlag("--json");
+        const apply = takeFlag("--apply");
+        const planOnly = takeFlag("--plan");
+        const force = takeFlag("--force");
+        try {
+            const result = apply && !planOnly
+                ? applyStructureMigration(targetArg(), { force })
+                : planStructureMigration(targetArg());
+            if (json) {
+                console.log(JSON.stringify(result, null, 2));
+            }
+            else {
+                console.log(`Structure migration ${result.applied ? "applied" : "plan"}: ${result.target}`);
+                console.log(`manifest: ${result.manifest}`);
+                console.log(`actions: ${result.summary.actions}`);
+                for (const action of result.actions || [])
+                    console.log(`- ${action.action}: ${action.source || "(none)"} -> ${action.destination}`);
+            }
+        }
+        catch (error) {
+            console.error(error.message);
+            process.exit(1);
+        }
+        return;
+    }
+    if (command === "migrate-task-audit-index") {
+        const json = takeFlag("--json");
+        const apply = takeFlag("--apply");
+        const planOnly = takeFlag("--plan");
+        try {
+            const result = apply && !planOnly
+                ? applyTaskAuditIndexMigration(targetArg())
+                : planTaskAuditIndexMigration(targetArg());
+            if (json) {
+                console.log(JSON.stringify(result, null, 2));
+            }
+            else {
+                console.log(`Task audit INDEX migration ${result.result}: ${result.target}`);
+                console.log(`actions: ${result.summary.actions}`);
+                console.log(`legacy audit blocks: ${result.summary.legacyAuditBlocks}`);
+                console.log(`failures: ${result.summary.failures}`);
+                for (const action of result.actions || [])
+                    console.log(`- ${action.taskId}: ${action.legacyBlocks.join(", ")}`);
+                for (const failure of result.failures || [])
+                    console.error(`Failure: ${failure.taskId}: ${failure.failure}`);
+            }
+            process.exit(result.failures?.length ? 1 : 0);
+        }
+        catch (error) {
+            if (json && error.plan)
+                console.error(JSON.stringify(error.plan, null, 2));
+            else
+                console.error(error.message);
+            process.exit(1);
+        }
+    }
+    if (command === "migrate-plan") {
+        const json = takeFlag("--json");
+        const limit = Number.parseInt(takeOption("--limit", "20"), 10) || 20;
+        try {
+            const plan = buildMigrationPlan(targetArg(), { limit });
+            if (json) {
+                console.log(JSON.stringify(plan, null, 2));
+            }
+            else {
+                console.log(`Migration Plan: ${plan.target}`);
+                console.log(`mode: ${plan.mode}`);
+                console.log(`warnings: ${plan.summary.warnings}`);
+                console.log(`task actions: ${plan.summary.taskActions}`);
+                console.log(`visual map actions: ${plan.summary.visualMapActions}`);
+                console.log(`legacy visual-only tasks: ${plan.summary.legacyVisualOnly}`);
+                console.log(`weak briefs: ${plan.summary.weakBrief}`);
+                console.log(`unknown classifications: ${plan.summary.unknownClassification}`);
+                console.log(`full cutover eligible: ${plan.summary.fullCutoverEligible ? "yes" : "no"}`);
+                console.log(`review actions: ${plan.summary.reviewSchemaGaps}`);
+                console.log(`legacy actions: ${plan.summary.legacyReferenceGaps}`);
+                console.log(`legacy residuals: ${plan.summary.legacyResiduals}`);
+                console.log(`recommended capabilities: ${plan.summary.recommendedCapabilities.join(", ") || "none"}`);
+                console.log("\nPhases:");
+                for (const phase of plan.phases)
+                    console.log(`- ${phase.id}: ${phase.title}`);
+                console.log("\nTop task actions:");
+                for (const action of plan.taskActions)
+                    console.log(`- ${action.taskId}: add ${action.files.join(", ")}`);
+                console.log("\nTop review actions:");
+                for (const action of plan.reviewActions)
+                    console.log(`- ${action.path}: add ${action.missing.join(", ")}`);
+                console.log("\nTop legacy residuals:");
+                for (const action of plan.legacyResiduals)
+                    console.log(`- ${action.taskId}: ${action.missing} (${action.reason})`);
+                console.log("\nNext commands:");
+                for (const next of plan.nextCommands)
+                    console.log(`- ${next}`);
+            }
+        }
+        catch (error) {
+            console.error(error.message);
+            process.exit(1);
+        }
+        return;
+    }
+    if (command === "migrate-run") {
+        const locale = takeOption("--locale", "");
+        const assumeLocale = takeFlag("--assume-locale");
+        const allowDirty = takeFlag("--allow-dirty");
+        const planOnly = takeFlag("--plan-only");
+        const outDir = takeOption("--out-dir", "");
+        const sessionDir = takeOption("--session-dir", "");
+        try {
+            console.log(JSON.stringify(runMigration(targetArg(), {
+                locale,
+                assumeLocale,
+                allowDirty,
+                planOnly,
+                outDir,
+                sessionDir,
+            }), null, 2));
+        }
+        catch (error) {
+            console.error(error.message);
+            process.exit(1);
+        }
+        return;
+    }
+    if (command === "migrate-verify") {
+        const json = takeFlag("--json");
+        const fullCutover = takeFlag("--full-cutover");
+        const sessionPath = args.shift();
+        if (!sessionPath) {
+            console.error("Missing session.json path");
+            process.exit(2);
+        }
+        const result = verifyMigrationSession(sessionPath, { fullCutover });
+        if (json) {
+            console.log(JSON.stringify(result, null, 2));
+        }
+        else {
+            for (const failure of result.failures)
+                console.error(`Failure: ${failure}`);
+            for (const warning of result.warnings)
+                console.log(`Warning: ${warning}`);
+            console.log(`Migration verify ${result.status}: ${result.sessionPath}`);
+        }
+        process.exit(result.status === "pass" ? 0 : 1);
+    }
+    throw new Error(`Unsupported migration command: ${command}`);
+}