@asrunjs/asrun 0.13.0 → 0.15.0

package/dist/scripts/init.js

@@ -1,8 +1,8 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { spawnSync } from 'node:child_process';
-import { FRAMEWORK_ROOT, MARKER, PACKAGE, TEMPLATES_DIR, isRepoCheckout } from '../lib/paths.js';
-import { migrationState, pendingMigrations } from '../lib/migrations.js';
+import { FRAMEWORK_ROOT, MARKER, PACKAGE, TEMPLATES_DIR } from '../lib/paths.js';
+import { migrationState, pendingMigrations, resolveMigrations } from '../lib/migrations.js';
 import { MIGRATIONS } from '../migrations/index.js';
 import { BUILD_APPROVALS, RUNTIME_EXTRAS, approveBuild, ensureRuntimeExtras, hasCapability, installedInWorkspace, } from '../lib/runtime-deps.js';
 /**
@@ -10,7 +10,7 @@ import { BUILD_APPROVALS, RUNTIME_EXTRAS, approveBuild, ensureRuntimeExtras, has
  * `--update` refreshes only the files generated from the framework templates, and `--force` rewrites every file it
  * writes (except the project's own data and, without `--reset-rules`, its rules).
  */
-const USAGE = `Usage: pnpm asrun init [--root <dir>] [--update] [--force [<path>]] [--reset-rules] [--no-env] [--no-extras] [--install [spec]]
+const USAGE = `Usage: pnpm asrun init [--root <dir>] [--update] [--force [<path>]] [--reset-rules] [--ack <file>...] [--no-env] [--no-extras] [--install [spec]]
 
   --root <dir>    the workspace to initialize (default: the current folder)
   --update        refresh the generated files (playwright.config.ts, tests/seed.spec.ts, .claude/commands/*,
@@ -19,111 +19,26 @@ const USAGE = `Usage: pnpm asrun init [--root <dir>] [--update] [--force [<path>
                   profiles.yaml, package.json; AGENTS.md and CLAUDE.md need --reset-rules)
   --force <path>  overwrite one file this tool writes, e.g. --force playwright.config.ts (may be repeated)
   --reset-rules   allow --force on AGENTS.md, CLAUDE.md or .claude/skills/** (project-owned rules)
+  --ack <path>    record that a project-owned file is aligned with the template of the installed release, without
+                  touching the file (after a merge); repeatable. Takes one of: ${ONCE.map((entry) => entry.file).join(', ')}
   --no-env        do not write .env (ASRUN_ROOT)
   --no-extras     do not install the optional packages this machine lacks (ffmpeg-static), which "pnpm go" does
-  --install [spec]  also add the dependency (default "@asrunjs/asrun"; e.g. --install github:<owner>/<repo>#<tag>)`;
-/** Files `init` owns: `--update` rewrites exactly these, and a project never edits them. */
-export const GENERATED = [
-    { file: 'playwright.config.ts', template: 'playwright.config.ts' },
-    { file: 'tests/seed.spec.ts', template: 'seed.spec.ts' },
-    { file: '.claude/commands/make-case.md', template: '.claude/commands/make-case.md' },
-    { file: '.claude/commands/explore-case.md', template: '.claude/commands/explore-case.md' },
-    { file: '.claude/commands/gen-spec.md', template: '.claude/commands/gen-spec.md' },
-    { file: '.claude/commands/heal-spec.md', template: '.claude/commands/heal-spec.md' },
-    // OpenCode does not read `.claude/commands` (only `.claude/skills`), so the same commands live here too.
-    { file: '.opencode/commands/make-case.md', template: '.claude/commands/make-case.md' },
-    { file: '.opencode/commands/explore-case.md', template: '.claude/commands/explore-case.md' },
-    { file: '.opencode/commands/gen-spec.md', template: '.claude/commands/gen-spec.md' },
-    { file: '.opencode/commands/heal-spec.md', template: '.claude/commands/heal-spec.md' },
-];
-/** Files `init` creates once; after that the project owns them and may edit them freely. */
-export const ONCE = [
-    { file: 'AGENTS.md', template: 'AGENTS.md' },
-    { file: 'CLAUDE.md', template: 'CLAUDE.md' },
-    { file: '.mcp.json', template: '.mcp.json' },
-    { file: 'opencode.jsonc', template: 'opencode.jsonc' },
-    { file: '.claude/settings.json', template: '.claude/settings.json' },
-    { file: 'tsconfig.json', template: 'tsconfig.json' },
-    { file: 'pnpm-workspace.yaml', template: 'pnpm-workspace.yaml' },
-    { file: 'profiles.yaml', template: 'profiles.yaml' },
-    { file: 'cases/_template.md', template: 'cases/_template.md' },
-    { file: 'package.json', template: 'package.json' },
-];
+  --install [spec]  also add the dependency (default "@asrunjs/asrun"; e.g. --install github:<owner>/<repo>#<tag>)
+
+Most of the time the upgrade prompt is better than running these by hand: "pnpm asrun upgrade --prompt".`;
+/**
+ * The files `init` writes come from `lib/scaffold.ts`, together with the baseline that records which template a
+ * project-owned file is aligned with. They are re-exported here because `doctor`, `reset` and the prompt import them
+ * from the command that writes them.
+ */
+export { GENERATED, ONCE, frameworkPath, frameworkVersion, isInstalled, renderTemplate } from '../lib/scaffold.js';
+import { GENERATED, ONCE, ackScaffold, frameworkPath, frameworkVersion, isInstalled, renderTemplate, scaffoldRecords, templateHash, } from '../lib/scaffold.js';
 // npm never packs a `.gitignore`, so the template is named `gitignore`; init writes it as `.gitignore`.
 const GITIGNORE_BLOCK = fs.readFileSync(path.join(TEMPLATES_DIR, 'gitignore'), 'utf8').trimEnd();
 // Re-exported: `doctor` and `reset` import the marker name from here, and `lib/paths.ts` is the one definition.
 export { MARKER };
 export { PACKAGE };
 export const DOTENV_HEADER = '# asrun: the workspace these commands run against (relative to this file).';
-function readTemplate(name) {
-    return fs.readFileSync(path.join(TEMPLATES_DIR, name), 'utf8');
-}
-/** How the workspace reaches the framework: `./node_modules/@asrunjs/asrun`, or a relative folder in the framework repo. */
-export function frameworkPath(root) {
-    if (!isRepoCheckout()) {
-        // The standard install location, or a hoisted one in a monorepo.
-        for (let dir = path.resolve(root);; dir = path.dirname(dir)) {
-            const candidate = path.join(dir, 'node_modules', PACKAGE);
-            if (fs.existsSync(path.join(candidate, 'package.json'))) {
-                const relative = path.relative(root, candidate).split(path.sep).join('/');
-                return relative.startsWith('.') ? relative : `./${relative}`;
-            }
-            if (path.dirname(dir) === dir)
-                break;
-        }
-        // Not installed yet (a scaffolding run): name the place the package will live.
-        return `./node_modules/${PACKAGE}`;
-    }
-    const relative = path.relative(root, FRAMEWORK_ROOT).split(path.sep).join('/');
-    if (relative === '')
-        return '.';
-    return relative.startsWith('.') ? relative : `./${relative}`;
-}
-/** True when this workspace has the package installed (or is the framework's own checkout). */
-export function isInstalled(root) {
-    return fs.existsSync(path.join(path.resolve(root, frameworkPath(root)), 'package.json'));
-}
-/** The range the workspace's `package.json` names for the framework: `^` plus the version that wrote the workspace. */
-let asrunRange;
-function asrunDependencyRange() {
-    asrunRange ??= `^${frameworkVersion().version}`;
-    return asrunRange;
-}
-/** Fills the `{{framework}}`, `{{playwright}}` and `{{asrun}}` placeholders of a template. */
-export function renderTemplate(name, root) {
-    return readTemplate(name)
-        .replaceAll('{{framework}}', frameworkPath(root))
-        .replaceAll('{{playwright}}', playwrightBin(root))
-        .replaceAll('{{asrun}}', asrunDependencyRange());
-}
-/**
- * The Playwright CLI the MCP server runs. The workspace's own install is the normal place; a workspace that lives
- * inside the framework repository (examples/demo) has no `node_modules` of its own, so it points at the framework's.
- * Kept relative: the file is committed and must not name a machine.
- */
-export function playwrightBin(root) {
-    if (fs.existsSync(path.join(root, 'node_modules', '.bin', 'playwright')))
-        return './node_modules/.bin/playwright';
-    const framework = frameworkPath(root);
-    return framework.startsWith('..') ? `${framework}/node_modules/.bin/playwright` : './node_modules/.bin/playwright';
-}
-export function frameworkVersion() {
-    let version = '0.0.0';
-    try {
-        version = JSON.parse(fs.readFileSync(path.join(FRAMEWORK_ROOT, 'package.json'), 'utf8')).version ?? version;
-    }
-    catch {
-        // keep the default
-    }
-    let commit = 'unknown';
-    try {
-        commit = spawnSync('git', ['-C', FRAMEWORK_ROOT, 'rev-parse', '--short', 'HEAD'], { encoding: 'utf8' }).stdout.trim() || 'unknown';
-    }
-    catch {
-        // keep the default
-    }
-    return { version, commit };
-}
 /** True when any dependency block of the manifest already names `name`, whatever the range. */
 function declaredIn(manifest, name) {
     return [manifest.dependencies, manifest.devDependencies, manifest.optionalDependencies, manifest.peerDependencies].some((block) => block?.[name] !== undefined);
@@ -242,13 +157,47 @@ export async function main(args) {
     const resetRules = args.includes('--reset-rules');
     const skipEnv = args.includes('--no-env');
     const skipExtras = args.includes('--no-extras');
+    // `--ack <file>`: the project merged the template's part by hand and says so. It never writes the file.
+    const acknowledged = [];
+    for (let index = 0; index < args.length; index++) {
+        if (args[index] !== '--ack')
+            continue;
+        const next = args[index + 1];
+        if (next !== undefined && !next.startsWith('-')) {
+            acknowledged.push(next.split('\\').join('/'));
+            index++;
+        }
+    }
     if (path.resolve(root) === path.resolve(FRAMEWORK_ROOT)) {
         console.error('This folder is the framework itself, not a workspace. Run "pnpm asrun init" inside the project that uses ' +
             'asrun, or pass --root <dir> (the framework develops against examples/demo).');
         return 1;
     }
+    if (acknowledged.length > 0) {
+        const unknown = acknowledged.filter((file) => !ONCE.some((entry) => entry.file === file));
+        if (unknown.length > 0) {
+            console.error(`--ack ${unknown.join(', ')}: only a file init creates once can be acknowledged (${ONCE.map((entry) => entry.file).join(', ')}).`);
+            return 1;
+        }
+        const missing = acknowledged.filter((file) => !fs.existsSync(path.join(root, file)));
+        if (missing.length > 0) {
+            console.error(`--ack ${missing.join(', ')}: the file does not exist. Write it from the template first: ` +
+                `"pnpm asrun init --force ${missing[0]}".`);
+            return 1;
+        }
+        if (!fs.existsSync(path.join(root, MARKER))) {
+            console.error(`No ${MARKER} in ${root}: this is not an initialized asrun workspace. Run "pnpm asrun init" first.`);
+            return 1;
+        }
+        const version = frameworkVersion().version;
+        const done = ackScaffold(root, acknowledged, version);
+        console.log(`Acknowledged ${done.join(', ')} as aligned with the ${version} templates.`);
+        console.log('Run "pnpm asrun upgrade --prompt" to see what is still outstanding.');
+        return 0;
+    }
     const firstRun = !fs.existsSync(path.join(root, MARKER));
     const written = [];
+    const writtenScaffold = [];
     const kept = [];
     const notes = [];
     const framework = frameworkPath(root);
@@ -276,6 +225,10 @@ export async function main(args) {
         fs.mkdirSync(path.dirname(target), { recursive: true });
         fs.writeFileSync(target, renderTemplate(entry.template, root));
         written.push(entry.file);
+        // The file now matches this release's template, so its baseline starts here: a later release can tell "nobody
+        // touched it" from "the project edited it".
+        if (ONCE.some((candidate) => candidate.file === entry.file))
+            writtenScaffold.push(entry.file);
     };
     for (const entry of GENERATED)
         place(entry, update || forceAll || forced.includes(entry.file));
@@ -424,16 +377,44 @@ export async function main(args) {
     // migrated *from*. It only moves when a migration succeeds, so a manual "pnpm add" followed by "init --update"
     // cannot erase what still has to be done.
     const migrations = migrationState(previous, version.version);
+    // The scaffold baseline: what each project-owned file is aligned with. A file this run wrote starts at this
+    // release's template; every other recorded file keeps its baseline, so a later release can still say whether the
+    // template moved under it. A file without a record (a workspace from before the baseline, or one the project edited
+    // after an init) gets one only when it already equals the template — anything else stays `unknown-base` until
+    // somebody merges it and runs "pnpm asrun init --ack <file>".
+    const scaffold = scaffoldRecords(previous);
+    for (const entry of ONCE) {
+        if (writtenScaffold.includes(entry.file)) {
+            scaffold[entry.file] = { version: version.version, template: templateHash(renderTemplate(entry.template, root)) };
+            continue;
+        }
+        if (scaffold[entry.file] !== undefined)
+            continue;
+        const file = path.join(root, entry.file);
+        if (!fs.existsSync(file))
+            continue;
+        const template = renderTemplate(entry.template, root);
+        if (fs.readFileSync(file, 'utf8').replace(/\r\n/g, '\n') !== template.replace(/\r\n/g, '\n'))
+            continue;
+        scaffold[entry.file] = { version: version.version, template: templateHash(template) };
+    }
+    // The release the workspace came from, for the upgrade prompt ("0.14.0 -> 0.15.0"). Written only when it changed, so
+    // a second "init --update" does not erase it.
+    const previousVersion = (typeof previous?.version === 'string' && previous.version !== version.version
+        ? { version: previous.version, at: typeof previous.updatedAt === 'string' ? previous.updatedAt : new Date().toISOString() }
+        : previous?.previous);
     fs.writeFileSync(path.join(root, MARKER), JSON.stringify({
         framework: PACKAGE,
         frameworkPath: framework,
         version: version.version,
         commit: version.commit,
         migrations,
+        scaffold,
+        ...(previousVersion !== undefined && { previous: previousVersion }),
         generated: GENERATED.map((entry) => entry.file),
         updatedAt: new Date().toISOString(),
     }, null, 2) + '\n');
-    const pending = pendingMigrations(MIGRATIONS, migrations.since, version.version);
+    const pending = pendingMigrations(resolveMigrations(MIGRATIONS, version.version), migrations.since, version.version);
     if (pending.length > 0) {
         notes.push(`${pending.length} workspace migration(s) apply (${pending.map((migration) => migration.id).join(', ')}): ` +
             'run "pnpm asrun migrate".');

package/dist/scripts/migrate.js

@@ -2,8 +2,11 @@ import fs from 'node:fs';
 import path from 'node:path';
 import readline from 'node:readline/promises';
 import { FRAMEWORK_ROOT, MARKER, ROOT } from '../lib/paths.js';
-import { compareVersions, isVersion, migrationState, pendingMigrations, readMarker, writeMigrationState, } from '../lib/migrations.js';
+import { compareVersions, isVersion, migrationState, pendingMigrations, readMarker, resolveMigrations, writeMigrationState, } from '../lib/migrations.js';
 import { MIGRATIONS } from '../migrations/index.js';
+import { ackScaffold, scaffoldFiles } from '../lib/scaffold.js';
+import { nextStepsText, upgradePrompt } from '../lib/upgrade-prompt.js';
+import { useColor } from '../lib/term.js';
 /**
  * `pnpm asrun migrate`: brings an existing workspace up to the release that is installed, by running the migrations
  * recorded in `migrations/index.ts`. `pnpm asrun upgrade` runs it after the install; it is also the command a person
@@ -12,17 +15,20 @@ import { MIGRATIONS } from '../migrations/index.js';
  * It writes only what a migration describes, plus the migration state in `.asrun.json`. It never installs anything:
  * a migration whose release is newer than the installed package does not run.
  */
-const USAGE = `Usage: pnpm asrun migrate [--root <dir>] [--list] [--dry-run] [--yes] [--from <version>] [--to <version>]
-                             [--ack <id> ...|--ack-all]
+const USAGE = `Usage: pnpm asrun migrate [--root <dir>] [--list] [--dry-run] [--yes|-y] [--from <version>] [--to <version>]
+                               [--ack <id> ...|--ack-all] [--prompt [--json]]
 
   --root <dir>    the workspace to migrate (default: the current workspace)
   --list          list every migration of the installed release and its state, and change nothing
   --dry-run       show the migrations that would run, and change nothing
-  --yes           apply breaking migrations without the confirmation prompt (for unattended runs)
+  --yes, -y       apply breaking migrations without the confirmation prompt (for unattended runs)
   --from <ver>    pretend the workspace is at that release (default: the recorded migrations.since)
   --to <ver>      migrate up to that release (default: the installed one; never beyond it)
-  --ack <id>      mark the manual steps of that migration as done (repeatable)
+  --ack <id>      mark the manual steps of that migration as done (repeatable); a migration that names project files
+                  also records them as aligned with this release's templates
   --ack-all       mark every outstanding manual step as done
+  --prompt        print the prompt that hands the leftover work to an AI agent, and change nothing
+  --json          with --prompt: the same answer as JSON, for the web UI
 
 The migration baseline lives in .asrun.json ("migrations.since"). It only advances when a migration succeeds, so an
 interrupted or failed run can simply be repeated.`;
@@ -55,33 +61,49 @@ function acknowledged(args) {
 function describe(migration) {
     return `${migration.version}  ${migration.id}  ${migration.summary}`;
 }
-/** Asks a person to confirm; without a terminal it refuses instead of assuming an answer. */
+/** Asks a person to confirm; an empty line or anything that is not "y"/"yes" means no. */
 async function confirm(question) {
     if (!process.stdin.isTTY || !process.stdout.isTTY)
         return false;
     const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
     try {
-        return (await rl.question(question)).trim().toLowerCase() === 'migrate';
+        const answer = (await rl.question(`${question} [y/N] `)).trim().toLowerCase();
+        return answer === 'y' || answer === 'yes';
     }
     finally {
         rl.close();
     }
 }
-function printManual(ids) {
+/**
+ * The manual steps still to do. Each one ends with the exact command that clears it: a placeholder `<id>` is what made
+ * people leave these open, because nothing in the output said which id to pass.
+ */
+function printManual(ids, registry) {
     if (ids.length === 0)
         return;
-    console.log('\nManual steps left (do them, then mark them done with "pnpm asrun migrate --ack <id>"):');
+    console.log('\nManual steps left (do them, then record that they are done):');
     for (const id of ids) {
-        const migration = MIGRATIONS.find((entry) => entry.id === id);
+        const migration = registry.find((entry) => entry.id === id);
         if (migration === undefined) {
             console.log(`  ${id}`);
+            console.log(`    when done: pnpm asrun migrate --ack ${id}`);
             continue;
         }
         console.log(`  ${migration.version}  ${migration.id}: ${migration.summary}`);
         for (const line of migration.manual ?? [])
             console.log(`    - ${line}`);
+        console.log(`    when done: pnpm asrun migrate --ack ${migration.id}`);
     }
 }
+/**
+ * The framed "what is left" block, the same one an upgrade prints: project files whose template moved under the
+ * workspace, plus the manual steps still open. It carries paste-ready commands and names the agent entry point.
+ */
+function reportNext(root) {
+    const next = nextStepsText(root, { color: useColor(process.stdout) });
+    if (next !== null)
+        console.log(`\n${next}`);
+}
 export async function main(args) {
     if (args.includes('--help')) {
         console.log(USAGE);
@@ -89,7 +111,9 @@ export async function main(args) {
     }
     const root = path.resolve(flagValue(args, '--root') ?? ROOT);
     const dryRun = args.includes('--dry-run');
-    const yes = args.includes('--yes');
+    const yes = args.includes('--yes') || args.includes('-y');
+    const promptOnly = args.includes('--prompt');
+    const asJson = args.includes('--json');
     if (path.resolve(root) === path.resolve(FRAMEWORK_ROOT)) {
         console.error('This folder is the framework itself, not a workspace. Run "pnpm asrun migrate" in the project that uses ' +
             'asrun, or pass --root <dir>.');
@@ -101,24 +125,40 @@ export async function main(args) {
         return 1;
     }
     const installed = installedVersion();
+    // Entries still carrying the `unreleased` sentinel are resolved to the installed release before anything compares
+    // versions: this is the release whose code they came with, whatever the release pull request ended up numbering it.
+    const registry = resolveMigrations(MIGRATIONS, installed);
     const state = migrationState(marker, installed);
+    // `--prompt` is the same answer as "pnpm asrun upgrade --prompt": what is left, for an AI agent. It changes nothing.
+    if (promptOnly) {
+        const payload = upgradePrompt(root);
+        console.log(asJson ? JSON.stringify(payload, null, 2) : payload.prompt);
+        return 0;
+    }
+    if (asJson) {
+        console.error('--json belongs to --prompt: "pnpm asrun migrate --prompt --json".');
+        return 1;
+    }
     // `--list` answers "what does this release contain, and where is this workspace", without touching anything.
     if (args.includes('--list')) {
         console.log(`Workspace: ${root}`);
         console.log(`asrun:     ${installed} installed, migrations since ${state.since}`);
-        if (MIGRATIONS.length === 0) {
+        if (registry.length === 0) {
             console.log('\nThis release has no migrations.');
         }
         else {
-            console.log(`\n${MIGRATIONS.length} migration(s) known to this release:`);
-            for (const migration of MIGRATIONS) {
+            console.log(`\n${registry.length} migration(s) known to this release:`);
+            for (const migration of registry) {
                 const applied = compareVersions(migration.version, state.since) <= 0;
                 const mark = applied ? 'ok ' : migration.manual !== undefined && migration.manual.length > 0 ? '-> ' : '   ';
                 console.log(`  ${mark}${describe(migration)}`);
                 console.log(`      ${applied ? 'already at or before the baseline' : 'pending'}${migration.breaking ? ', breaking' : ''}`);
+                if (!applied && (migration.manual ?? []).length > 0) {
+                    console.log(`      when done: pnpm asrun migrate --ack ${migration.id}`);
+                }
             }
         }
-        printManual(state.manual);
+        printManual(state.manual, registry);
         return 0;
     }
     const ackAll = args.includes('--ack-all');
@@ -131,10 +171,20 @@ export async function main(args) {
         }
         const manual = ackAll ? [] : state.manual.filter((id) => !ackIds.includes(id));
         writeMigrationState(root, { since: state.since, manual });
+        // A migration that names project files says they are aligned with this release's templates; acknowledging it is the
+        // same statement, so it advances their baseline too and the NEXT block stops naming them.
+        const files = scaffoldFiles(registry.filter((migration) => ackAll || ackIds.includes(migration.id)).flatMap((migration) => migration.files ?? []));
+        const acknowledgedFiles = files.length === 0 ? [] : ackScaffold(root, files, installed);
         console.log(ackAll
             ? `Acknowledged every outstanding manual step (${state.manual.length}).`
             : `Acknowledged: ${ackIds.join(', ')}.`);
-        printManual(manual);
+        if (acknowledgedFiles.length > 0) {
+            console.log(`Aligned with the ${installed} templates: ${acknowledgedFiles.join(', ')}.`);
+        }
+        printManual(manual, registry);
+        const next = nextStepsText(root, { color: useColor(process.stdout) });
+        if (next !== null)
+            console.log(`\n${next}`);
         return 0;
     }
     const from = flagValue(args, '--from') ?? state.since;
@@ -153,12 +203,13 @@ export async function main(args) {
     if (compareVersions(to, state.since) <= 0) {
         console.log(`Workspace: ${root}`);
         console.log(`Migrations: none — the baseline is ${state.since}, the installed release is ${installed}.`);
-        printManual(state.manual);
+        printManual(state.manual, registry);
+        reportNext(root);
         return 0;
     }
     // `--from` may only move the start forward: migrations the workspace's baseline already covers never run again.
     const start = compareVersions(from, state.since) < 0 ? state.since : from;
-    const pending = pendingMigrations(MIGRATIONS, start, to);
+    const pending = pendingMigrations(registry, start, to);
     console.log(`Workspace: ${root}`);
     console.log(`asrun:     ${installed}${installed === to ? '' : ` (migrating to ${to})`}`);
     if (pending.length === 0) {
@@ -167,7 +218,8 @@ export async function main(args) {
         // registry (or a release without migrations) then stops reporting the old baseline in `doctor`.
         if (!dryRun)
             writeMigrationState(root, { since: to, manual: state.manual });
-        printManual(state.manual);
+        printManual(state.manual, registry);
+        reportNext(root);
         return 0;
     }
     console.log(`Migrations: ${pending.length} between ${start} and ${to}`);
@@ -177,6 +229,8 @@ export async function main(args) {
             console.log(`      affects: ${migration.appliesTo}`);
         for (const line of migration.manual ?? [])
             console.log(`      - ${line}`);
+        if ((migration.manual ?? []).length > 0)
+            console.log(`      when done: pnpm asrun migrate --ack ${migration.id}`);
     }
     if (dryRun) {
         console.log('\nNothing was applied (--dry-run).');
@@ -190,7 +244,7 @@ export async function main(args) {
                 'A person adds --yes to do it.');
             return 1;
         }
-        const answer = await confirm(`\nType "migrate" to apply ${breaking.length} breaking migration(s): `);
+        const answer = await confirm(`\nApply ${breaking.length} breaking migration(s)?`);
         if (!answer) {
             console.error('Cancelled. Nothing was applied.');
             return 1;
@@ -213,6 +267,14 @@ export async function main(args) {
         const migration = pending[index];
         const label = `${migration.version} ${migration.id}`;
         const lastOfRelease = index === pending.length - 1 || pending[index + 1].version !== migration.version;
+        // An advisory entry says the release touched project files but asks nothing: report it as done so the baseline can
+        // move, and never leave a manual step behind (there is none).
+        if (migration.advisory === true) {
+            console.log(`  ok ${label}: nothing for a workspace to do`);
+            if (lastOfRelease)
+                done = migration.version;
+            continue;
+        }
         if (migration.auto !== true || typeof migration.apply !== 'function') {
             console.log(`  -> ${label}: a person has to do this`);
             for (const line of migration.manual ?? [])
@@ -254,6 +316,7 @@ export async function main(args) {
     writeMigrationState(root, { since: state2.since, manual });
     console.log(`\nApplied ${applied} migration(s)${skipped > 0 ? `, ${skipped} already in place` : ''}. ` +
         `Baseline: ${state2.since}.`);
-    printManual(manual);
+    printManual(manual, registry);
+    reportNext(root);
     return 0;
 }

package/dist/scripts/migrations-check.d.ts

@@ -0,0 +1 @@
+export declare function main(args: string[]): number;