@hozu/cli 0.10.0 → 0.11.0

package/dist/commands/migrate.js

@@ -1,26 +1,32 @@
 import { spawnSync } from 'node:child_process';
 import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
 import { dirname, extname, join, relative, resolve } from 'node:path';
-import { fileURLToPath } from 'node:url';
-import { runnerOf, writeAgentFiles } from 'create-hozu';
+import { fileURLToPath, pathToFileURL } from 'node:url';
 import { HozuCliError } from '../errors.js';
 import { load } from '../load.js';
+import { chain, compareMinor, minorOf, OLDEST } from '../migrate/steps.js';
 import { runCheck } from './check.js';
-import { migrateGuide, skillTargets } from './migrate-agent.js';
-import { migrateApp, migratePackage } from './migrate-app.js';
-import { forget, lineOf, parse, walk } from './migrate-ast.js';
-import { migrateForms } from './migrate-forms.js';
-import { migrateFreshness } from './migrate-freshness.js';
-import { migrateHead } from './migrate-head.js';
-import { migrateLinks } from './migrate-links.js';
-import { migrateLists } from './migrate-lists.js';
-import { differences, normalize07 } from './migrate-normalize.js';
-import { migrateOps } from './migrate-ops.js';
-import { migrateParts } from './migrate-parts.js';
+import { runSkill } from './skill.js';
 const SKIP = /(^|\/)(node_modules|dist|\.[^/]+)(\/|$)/;
-const RECORD = '.hozu/migrate-0.7.json';
+const cliVersion = () => {
+    const pkg = new URL('../../package.json', import.meta.url);
+    return JSON.parse(readFileSync(fileURLToPath(pkg), 'utf8')).version;
+};
+export function installedCore(config) {
+    let d = dirname(config);
+    for (;;) {
+        const pkg = join(d, 'node_modules/@hozu/core/package.json');
+        if (existsSync(pkg))
+            return JSON.parse(readFileSync(pkg, 'utf8')).version;
+        const up = dirname(d);
+        if (up === d)
+            return null;
+        d = up;
+    }
+}
 export function sources(dir) {
-    const out = new Map();
+    const out = [];
     const visit = (d) => {
         for (const name of readdirSync(d).sort()) {
             const path = join(d, name);
@@ -29,329 +35,228 @@ export function sources(dir) {
             if (statSync(path).isDirectory())
                 visit(path);
             else if (extname(name) === '.ts' && !name.endsWith('.d.ts'))
-                out.set(path, readFileSync(path, 'utf8'));
+                out.push(path);
         }
     };
     visit(dir);
     return out;
 }
-export function checkOn07(config) {
-    const self = fileURLToPath(import.meta.url);
-    const child = spawnSync(process.execPath, ['--no-warnings', join(dirname(self), `migrate-stale${extname(self)}`), config], { cwd: dirname(config), maxBuffer: 1 << 28, env: { ...process.env, NODE_OPTIONS: '' } });
+/** The IR as the app's installed Hozu builds it, in a child process with the app's own transform hook. */
+function recordWithInstalled(config) {
+    const require = createRequire(config);
+    let register;
     try {
-        return JSON.parse(child.stdout.toString());
+        register = require.resolve('@hozu/transform/register');
     }
     catch {
-        return {
-            core: null,
-            irVersion: null,
-            skipped: `the stale check failed: ${child.stderr.toString().split('\n').find(Boolean) ?? 'no output'}`,
-            stale: [],
-            routes: {},
-            errors: [],
-            ir: null,
-        };
+        throw new HozuCliError('config', 'hozu migrate needs the app’s installed @hozu/transform to read the old IR', ['npm install, then run hozu migrate again']);
     }
-}
-const PRINTS = [
-    [
-        'any',
-        /AsyncLocalStorage/,
-        'request state in AsyncLocalStorage (hand-made i18n?): the URL holds the language (site.locales)',
-        'i18n',
-    ],
-    [
-        'any',
-        /accept-language/i,
-        'hand-made language negotiation: the URL holds the language (site.locales), no Accept-Language redirect',
-        'i18n',
-    ],
-    [
-        'any',
-        /Session\s*=\s*z\.object\(\{[^}]*\b(?:lang|locale|language)\s*:/,
-        'a language in the session: the URL holds the language (site.locales), not the session',
-        'i18n',
-    ],
-    [
-        'resolvers',
-        /<html\b[^>]*\blang\b|text\/html|<!doctype/i,
-        'HTML from a resolver is HZ053: make it a ui.page with head.failed',
-        'pages',
-    ],
-];
-const REDIRECT = "a redirect Response: declare output: 'redirect' and return redirect(ui.link(…))";
-const statusOf = (n) => {
-    if (n?.type === 'Literal' && typeof n.value === 'number')
-        return n.value;
-    if (n?.type !== 'ObjectExpression')
-        return null;
-    const p = n.properties.find((x) => x.type === 'Property' && (x.key.name ?? x.key.value) === 'status');
-    return p?.value.type === 'Literal' && typeof p.value.value === 'number' ? p.value.value : null;
-};
-function responses(file, source) {
-    let program;
+    const self = fileURLToPath(import.meta.url);
+    const script = join(dirname(self), `../migrate/record-ir${extname(self)}`);
+    const child = spawnSync(process.execPath, ['--no-warnings', '--import', pathToFileURL(register).href, script, config], { cwd: dirname(config), maxBuffer: 1 << 28, env: { ...process.env, NODE_OPTIONS: '' } });
     try {
-        program = parse(source);
+        return JSON.parse(child.stdout.toString());
     }
     catch {
-        return [];
+        throw new HozuCliError('build', `hozu migrate could not build the app with its installed Hozu: ${child.stderr.toString().split('\n').find(Boolean) ?? 'no output'}`, ['npx hozu check   # fix the app on its current version first']);
     }
+}
+/** JSON pointers where two IRs differ, each with both values, at most 50. */
+export function differences(before, after, at = '') {
     const out = [];
-    walk(program, (n) => {
-        const c = n.callee;
-        const built = n.type === 'NewExpression' && c.type === 'Identifier' && c.name === 'Response';
-        const helper = n.type === 'CallExpression' &&
-            c.type === 'MemberExpression' &&
-            c.object.type === 'Identifier' &&
-            c.object.name === 'Response' &&
-            ['json', 'redirect'].includes(c.property.name);
-        if (!built && !helper)
+    const show = (v) => {
+        const s = v === undefined ? 'absent' : JSON.stringify(v);
+        return s.length > 80 ? `${s.slice(0, 77)}…` : s;
+    };
+    const visit = (a, b, path) => {
+        if (out.length >= 50)
             return;
-        const status = statusOf(n.arguments[1]) ?? (helper && c.property.name === 'redirect' ? 302 : null);
-        if (status === null || status < 300 || status >= 500)
+        if (JSON.stringify(a) === JSON.stringify(b))
             return;
-        const message = status < 400
-            ? REDIRECT
-            : `a ${status} Response: declare errors: { Name: schema } and failed: { Name: ${status} }, and return fail('Name', …)`;
-        out.push({
-            file,
-            line: lineOf(source, n.start),
-            rule: 'print',
-            message,
-            see: 'endpoints',
-            behaviour: true,
-        });
-    });
+        const objects = a && b && typeof a === 'object' && typeof b === 'object' && Array.isArray(a) === Array.isArray(b);
+        if (!objects) {
+            out.push(`${path || '/'}: ${show(a)} → ${show(b)}`);
+            return;
+        }
+        const keys = [...new Set([...Object.keys(a), ...Object.keys(b)])].sort();
+        for (const k of keys)
+            visit(a[k], b[k], `${path}/${k.replace(/~/g, '~0').replace(/\//g, '~1')}`);
+    };
+    visit(before, after, at);
     return out;
 }
-/** What migrate cannot rewrite and check cannot see (ADR 0043 Migration). */
-export function printed(file, source) {
+function raisePackages(pkgPath, version, write) {
+    if (!existsSync(pkgPath))
+        return [];
+    const source = readFileSync(pkgPath, 'utf8');
+    const pkg = JSON.parse(source);
     const out = [];
-    const resolvers = /\bimplement\s*\(/.test(source);
-    for (const [where, re, message, see] of PRINTS) {
-        if (where === 'resolvers' && !resolvers)
-            continue;
-        const m = re.exec(source);
-        if (m)
-            out.push({ file, line: lineOf(source, m.index), rule: 'print', message, see, behaviour: true });
-    }
-    return resolvers ? [...out, ...responses(file, source)] : out;
-}
-/** Every source rewrite of `hozu migrate 0.8`, in memory: removed files are absent from `files`. */
-export function rewriteSources(dir, config, before, routes) {
-    const files = new Map(before);
-    const notes = [];
-    const passes = [
-        migrateOps,
-        migrateHead,
-        migrateFreshness,
-        (s, f) => migrateLinks(s, f, routes),
-        migrateForms,
-        migrateLists,
-    ];
-    for (const pass of passes)
-        for (const [file, source] of files) {
-            forget();
-            const r = pass(source, file);
-            files.set(file, r.code);
-            notes.push(...r.notes);
+    for (const field of ['dependencies', 'devDependencies'])
+        for (const [name, range] of Object.entries(pkg[field] ?? {})) {
+            if (!name.startsWith('@hozu/') && name !== 'create-hozu')
+                continue;
+            if (/^(workspace|file|link):/.test(range))
+                continue;
+            const next = `^${version}`;
+            if (range === next)
+                continue;
+            pkg[field][name] = next;
+            out.push({ name, from: range, to: next });
         }
-    for (let round = 0; round < 5; round++) {
-        forget();
-        const parts = migrateParts(files);
-        for (const [f, s] of parts.files)
-            files.set(f, s);
-        notes.push(...parts.notes.filter((n) => !notes.some((m) => m.file === n.file && m.message === n.message)));
-        if (!parts.files.size)
-            break;
-    }
-    forget();
-    const app = migrateApp(dir, config, files);
-    for (const [f, s] of app.write)
-        files.set(f, s);
-    notes.push(...app.notes);
-    for (const f of app.remove)
-        files.delete(f);
-    for (const [file, source] of files)
-        notes.push(...printed(file, source));
-    forget();
-    return { files, notes, app };
+    if (out.length && write)
+        writeFileSync(pkgPath, `${JSON.stringify(pkg, null, 2)}\n`);
+    return out;
 }
-export async function runMigrate(cwd, configArg, version, options = {}) {
-    if (version !== '0.8')
-        throw new HozuCliError('usage', 'hozu migrate upgrades a 0.7 app: hozu migrate 0.8', ['hozu migrate 0.8']);
-    const config = resolve(cwd, configArg ?? 'hozu.config.ts');
+const installCommand = (dir) => existsSync(join(dir, 'pnpm-lock.yaml'))
+    ? 'pnpm install'
+    : existsSync(join(dir, 'yarn.lock'))
+        ? 'yarn install'
+        : 'npm install';
+export async function runMigrate(cwd, options) {
+    const config = resolve(cwd, options.config ?? 'hozu.config.ts');
     if (!existsSync(config))
         throw new HozuCliError('config', `No config found at ${config}`, [
-            'Run hozu migrate 0.8 in the app directory',
+            'run hozu migrate in the app directory',
         ]);
     const dir = dirname(config);
-    const rel = (f) => relative(cwd, f) || '.';
-    const on07 = checkOn07(config);
-    const record = join(dir, RECORD);
-    if (on07.ir) {
-        mkdirSync(dirname(record), { recursive: true });
-        writeFileSync(record, JSON.stringify(on07.ir));
-    }
-    const before = sources(dir);
-    const { files, notes, app } = rewriteSources(dir, config, before, new Map(Object.entries(on07.routes)));
-    const changed = [];
-    const write = (file, code) => {
-        if (file.endsWith('hozu.lock.json'))
-            return;
-        writeFileSync(file, code);
-        changed.push(rel(file));
+    const rel = (p) => relative(cwd, p) || '.';
+    const installed = options.versions?.installed ?? installedCore(config);
+    if (!installed)
+        throw new HozuCliError('config', 'No installed @hozu/core: install the app’s dependencies first', [
+            installCommand(dir),
+        ]);
+    const target = options.versions?.target ?? cliVersion();
+    const from = minorOf(installed);
+    const to = minorOf(target);
+    if (compareMinor(from, OLDEST) < 0)
+        throw new HozuCliError('usage', `hozu migrate starts at ${OLDEST}.0; this app is on ${installed}. Upgrade it to ${OLDEST} by hand with the CHANGELOG first`, ['https://github.com/olevatorr/Hozu/blob/main/CHANGELOG.md']);
+    if (compareMinor(from, to) > 0)
+        throw new HozuCliError('usage', `The app is on ${installed}, newer than this CLI (${target})`, [
+            `npx @hozu/cli@${installed} …`,
+        ]);
+    const record = join(dir, `.hozu/migrate-${from}.json`);
+    const out = {
+        ok: true,
+        from: installed,
+        to: target,
+        phase: 'current',
+        dryRun: options.dryRun,
+        steps: [],
+        changed: [],
+        notes: [],
+        packages: [],
+        record: null,
+        ir: { compared: false, skipped: null, differences: [] },
+        guide: [],
+        check: null,
+        next: [],
     };
-    for (const [file, code] of files)
-        if (before.get(file) !== code)
-            write(file, code);
-    for (const file of app.remove)
-        rmSync(file, { force: true });
-    const pkgPath = join(dir, 'package.json');
-    if (existsSync(pkgPath)) {
-        const source = readFileSync(pkgPath, 'utf8');
-        const pkg = migratePackage(source, app.entry);
-        if (pkg.code !== source)
-            write(pkgPath, pkg.code);
-        notes.push(...pkg.notes.map((n) => ({ ...n, file: pkgPath })));
-    }
-    const guide = [];
-    const targets = skillTargets(dir);
-    if (targets.length) {
-        const runner = runnerOf(process.env.npm_config_user_agent);
-        const agent = targets.length === 2 ? 'both' : targets[0].guide === 'CLAUDE.md' ? 'claude' : 'agents';
-        const existing = new Map(targets.map((t) => [
-            t.guide,
-            existsSync(join(dir, t.guide)) ? readFileSync(join(dir, t.guide), 'utf8') : null,
-        ]));
-        const skills = new Map(targets.map((t) => [t.skill, contentOf(join(dir, t.skill))]));
-        await writeAgentFiles(dir, agent, { name: dir.split('/').pop(), runner });
-        for (const t of targets) {
-            if (contentOf(join(dir, t.skill)) !== skills.get(t.skill))
-                changed.push(rel(join(dir, t.skill)));
-            const file = join(dir, t.guide);
-            const r = migrateGuide(existing.get(t.guide) ?? null, t, dir, runner);
-            if (r.kind === 'custom') {
-                guide.push({ file: rel(file), state: 'custom', block: r.block });
-            }
-            else {
-                if (r.kind !== 'current')
-                    write(file, r.code);
-                guide.push({ file: rel(file), state: r.kind, block: null });
+    if (compareMinor(from, to) < 0) {
+        const plan = chain(from, to);
+        if (!plan)
+            throw new HozuCliError('usage', `No migration path from ${from} to ${to}`, []);
+        out.phase = 'rewrite';
+        out.steps = plan.map((s) => ({ from: s.from, to: s.to, summary: s.summary }));
+        const ir = (options.recordIR ?? recordWithInstalled)(config);
+        for (const file of sources(dir)) {
+            let code = readFileSync(file, 'utf8');
+            const original = code;
+            let edits = 0;
+            for (const step of plan) {
+                const r = step.rewrite(rel(file), code);
+                code = r.code;
+                edits += r.count;
+                out.notes.push(...r.notes);
             }
+            if (code === original)
+                continue;
+            out.changed.push({ file: rel(file), edits });
+            if (!options.dryRun)
+                writeFileSync(file, code);
         }
-    }
-    const installed = on07.core ?? installedCore(config);
-    const next = [];
-    let check = null;
-    const ir = { compared: false, skipped: null, differences: [] };
-    if (on07.irVersion !== 2) {
-        next.push(`upgrade every @hozu/* dependency to 0.8: ${upgradeCommand(dir)}`);
-        next.push('npx hozu migrate 0.8   # again after the upgrade: nothing to rewrite, then it runs hozu check');
-        if (on07.ir)
-            next.push(`keep ${RECORD} until that second run: it holds the 0.7 IR it compares with (a reinstall keeps it; delete it afterwards)`);
-    }
-    else if (options.runCheck !== false) {
-        const loaded = await load(configArg, cwd);
-        if (existsSync(record)) {
-            const before = normalize07(JSON.parse(readFileSync(record, 'utf8')));
-            ir.compared = true;
-            ir.differences = differences(before, loaded.build(false).ir);
-            next.push(`delete ${RECORD}: the IR comparison with 0.7 is done`);
+        out.packages = raisePackages(join(dir, 'package.json'), target, !options.dryRun);
+        if (!options.dryRun) {
+            mkdirSync(dirname(record), { recursive: true });
+            writeFileSync(join(dir, `.hozu/migrate-${to}.json`), JSON.stringify({ from, to, ir }));
         }
-        else
-            ir.skipped = `${RECORD} is missing: it is written by the run on the 0.7 app, before the upgrade`;
-        check = await runCheck(loaded, cwd, false);
-        if (!check.ok)
-            next.push('npx hozu check   # fix each diagnostic; accept the lock with --update-lock');
+        out.record = rel(join(dir, `.hozu/migrate-${to}.json`));
+        out.next.push(`${installCommand(dir)}   # installs Hozu ${target}`, 'npx hozu migrate   # again: compares the IR with the old one and runs hozu check');
+        return out;
+    }
+    const saved = join(dir, `.hozu/migrate-${to}.json`);
+    if (!existsSync(saved)) {
+        out.next.push('Nothing to migrate: the app is on this CLI’s version.');
+        return out;
     }
-    const ok = !guide.some((g) => g.state === 'custom') && (check?.ok ?? true);
-    return {
-        ok,
-        installed,
-        stale: { skipped: on07.skipped, entries: on07.stale },
-        changed: [...new Set(changed)].sort(),
-        removed: app.remove.map(rel).sort(),
-        notes: notes.map((n) => ({ ...n, file: rel(n.file) })),
-        guide,
-        ir,
-        next,
-        check,
+    out.phase = 'verify';
+    out.record = rel(saved);
+    const { from: was, ir: before } = JSON.parse(readFileSync(saved, 'utf8'));
+    const plan = chain(was, to) ?? [];
+    out.steps = plan.map((s) => ({ from: s.from, to: s.to, summary: s.summary }));
+    const loaded = await load(options.config, cwd);
+    const normalized = plan.reduce((ir, step) => step.normalize(ir), before);
+    out.ir = {
+        compared: true,
+        skipped: null,
+        differences: differences(normalized, loaded.build(false).ir),
     };
-}
-function contentOf(dir) {
-    const out = [];
-    const visit = (d) => {
-        for (const name of readdirSync(d).sort()) {
-            const path = join(d, name);
-            if (statSync(path).isDirectory())
-                visit(path);
-            else
-                out.push(`${relative(dir, path)}\n${readFileSync(path, 'utf8')}`);
+    if (!options.dryRun) {
+        const agents = ['.claude/skills/hozu', '.agents/skills/hozu'].filter((p) => existsSync(join(dir, p)));
+        if (agents.length) {
+            const written = await runSkill(dir, undefined);
+            out.guide = written.written.map((f) => rel(resolve(dir, f)));
+            for (const c of written.custom)
+                out.notes.push({
+                    file: rel(resolve(dir, c.guide)),
+                    line: 1,
+                    message: `not a Hozu template: replace its Hozu section with this block\n${c.block}`,
+                    see: null,
+                });
         }
-    };
-    if (existsSync(dir))
-        visit(dir);
-    return out.join('\u0000');
-}
-function installedCore(config) {
-    let d = dirname(config);
-    for (;;) {
-        const pkg = join(d, 'node_modules/@hozu/core/package.json');
-        if (existsSync(pkg))
-            return JSON.parse(readFileSync(pkg, 'utf8')).version;
-        const up = dirname(d);
-        if (up === d)
-            return null;
-        d = up;
     }
-}
-function upgradeCommand(dir) {
-    const pkg = existsSync(join(dir, 'package.json'))
-        ? JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8'))
-        : {};
-    const names = [...Object.keys(pkg.dependencies ?? {}), ...Object.keys(pkg.devDependencies ?? {})]
-        .filter((n) => n.startsWith('@hozu/'))
-        .sort();
-    const tool = existsSync(join(dir, 'pnpm-lock.yaml'))
-        ? 'pnpm add'
-        : existsSync(join(dir, 'yarn.lock'))
-            ? 'yarn add'
-            : 'npm install';
-    return `${tool} ${names.map((n) => `${n}@^0.8.0`).join(' ')}`;
+    if (options.check !== false) {
+        out.check = await runCheck(loaded, cwd, false);
+        if (!out.check.ok)
+            out.next.push('npx hozu check   # fix each diagnostic; accept intended lock changes with --update-lock');
+    }
+    out.ok = out.ir.differences.length === 0 && (out.check?.ok ?? true);
+    if (out.ir.differences.length)
+        out.next.push('Review each IR difference: it is a behaviour change the migration did not declare');
+    if (out.ok && !options.dryRun) {
+        rmSync(saved);
+        out.next.push('Done. Commit the migration; hozu.lock.json was not touched.');
+    }
+    return out;
 }
 export function describeMigrate(r) {
     const lines = [];
-    lines.push(r.stale.skipped
-        ? `1. stale under 0.7: skipped (${r.stale.skipped})`
-        : `1. stale under 0.7: ${r.stale.entries.length} lock ${r.stale.entries.length === 1 ? 'entry' : 'entries'}${r.stale.entries.length ? ' (review each before --update-lock):' : ''}`);
-    for (const e of r.stale.entries)
-        lines.push(`   ${e.feature} ${e.id} [${e.kind}]${e.was ? `\n     was: ${e.was}` : ''}${e.now ? `\n     now: ${e.now}` : ''}`);
-    lines.push(`2. rewrote ${r.changed.length} ${r.changed.length === 1 ? 'path' : 'paths'}${r.removed.length ? `, removed ${r.removed.join(', ')}` : ''}`);
-    const behaviour = r.notes.filter((n) => n.behaviour);
-    const rest = r.notes.filter((n) => !n.behaviour);
-    for (const n of rest)
-        lines.push(`   ${n.file}:${n.line}  ${n.message}${n.see ? `  (hozu docs ${n.see})` : ''}`);
-    if (behaviour.length) {
-        lines.push('   Behaviour changes and code to move by hand:');
-        for (const n of behaviour)
-            lines.push(`   ! ${n.file}:${n.line}  ${n.message}${n.see ? `  (hozu docs ${n.see})` : ''}`);
+    const title = r.phase === 'rewrite' ? 'rewrite' : r.phase === 'verify' ? 'verify' : 'nothing to do';
+    lines.push(`hozu migrate ${r.from} → ${r.to}: ${title}${r.dryRun ? ' (dry run, nothing written)' : ''}`);
+    for (const s of r.steps)
+        lines.push(`  ${s.from} → ${s.to}: ${s.summary}`);
+    if (r.phase === 'rewrite') {
+        lines.push(`  rewrote ${r.changed.length} ${r.changed.length === 1 ? 'file' : 'files'}`);
+        for (const c of r.changed)
+            lines.push(`    ${c.file} (${c.edits} ${c.edits === 1 ? 'edit' : 'edits'})`);
+        for (const p of r.packages)
+            lines.push(`  ${p.name}: ${p.from} → ${p.to}`);
+        if (r.record)
+            lines.push(`  saved the old IR to ${r.record}`);
     }
-    for (const g of r.guide)
-        lines.push(g.state === 'custom'
-            ? `   ${g.file} is not a Hozu template: replace its Hozu section with this block (the markers keep it current):\n\n${g.block}`
-            : `   ${g.file}: Hozu block ${g.state}`);
-    let step = 3;
-    if (r.ir.skipped)
-        lines.push(`${step++}. IR comparison with 0.7: skipped (${r.ir.skipped})`);
+    if (r.notes.length)
+        lines.push('  by hand:');
+    for (const n of r.notes)
+        lines.push(`    ${n.file}:${n.line}  ${n.message}${n.see ? `  (hozu docs ${n.see})` : ''}`);
     if (r.ir.compared)
         lines.push(r.ir.differences.length
-            ? `${step++}. the IR differs from 0.7 (after the mapping every rewrite allows) at ${r.ir.differences.length} ${r.ir.differences.length === 1 ? 'place' : 'places'}; each is a behaviour change to review:\n${r.ir.differences.map((d) => `   ! ${d}`).join('\n')}`
-            : `${step++}. the IR equals the 0.7 IR apart from the mapping every rewrite allows (ADR 0043 Migration)`);
+            ? `  the IR differs from ${r.from === r.to ? 'the saved one' : r.from} after the declared mapping, at ${r.ir.differences.length} ${r.ir.differences.length === 1 ? 'place' : 'places'}:\n${r.ir.differences.map((d) => `    ! ${d}`).join('\n')}`
+            : '  the IR equals the old one after the declared mapping');
+    for (const g of r.guide)
+        lines.push(`  updated ${g}`);
     if (r.check)
-        lines.push(`${step++}. hozu check: ${r.check.ok ? 'ok' : 'failed'} · ${r.check.validate.summary.errors} errors, ${r.check.validate.summary.warnings} warnings · lock ${r.check.validate.lock}`);
+        lines.push(`  hozu check: ${r.check.ok ? 'ok' : 'failed'} · ${r.check.validate.summary.errors} errors, ${r.check.validate.summary.warnings} warnings`);
     for (const n of r.next)
-        lines.push(`${step++}. ${n}`);
+        lines.push(`next: ${n}`);
     lines.push('Migrate never writes hozu.lock.json and never deletes a contract.');
     return `${lines.join('\n')}\n`;
 }