@asrunjs/asrun 0.7.0 → 0.8.0

package/dist/scripts/doctor.js

@@ -3,7 +3,10 @@ import path from 'node:path';
 import { loadProfiles, listEnvs, PROFILES_FILE } from '../lib/profiles.js';
 import { FRAMEWORK_ROOT, ROOT, SKILLS_DIR } from '../lib/paths.js';
 import { spawnTarget } from '../lib/command.js';
+import { migrationState, pendingMigrations } from '../lib/migrations.js';
+import { MIGRATIONS } from '../migrations/index.js';
 import { GENERATED, frameworkPath, frameworkVersion, PACKAGE, renderTemplate } from './init.js';
+import { BUILD_APPROVALS, RUNTIME_EXTRAS, hasCapability, installedInWorkspace } from '../lib/runtime-deps.js';
 import { builtFile, COPIED_SCRIPTS } from '../lib/build-artifacts.js';
 /**
  * Checks that a workspace is complete and consistent with the framework it points at. It never writes anything.
@@ -87,9 +90,11 @@ export async function main(args) {
         errors.push(`${PACKAGE} is not installed in this workspace: run "pnpm add -D ${PACKAGE}", then "pnpm asrun init". ` +
             'Every script that calls "asrun" fails until then.');
     }
-    // The manifest, written by init: it names where the workspace reaches the framework.
+    // The manifest, written by init: it names where the workspace reaches the framework, and since when the workspace
+    // has been migrated.
     const manifest = read(path.join(ROOT, '.asrun.json'));
     let recordedPath;
+    let marker = null;
     const installedVersion = frameworkVersion();
     if (manifest === null) {
         errors.push('No .asrun.json: this workspace was never initialized, or "init" stopped before it finished (for example the ' +
@@ -98,10 +103,12 @@ export async function main(args) {
     else {
         try {
             const parsed = JSON.parse(manifest);
+            marker = parsed;
             recordedPath = parsed.frameworkPath;
-            facts.push(`version:   asrun ${parsed.version ?? '?'} (${parsed.commit ?? '?'})`);
-            if (parsed.version !== undefined && parsed.version !== installedVersion.version) {
-                warnings.push(`asrun is installed at ${installedVersion.version}, but this workspace was set up with ${parsed.version}: run "pnpm asrun init --update".`);
+            facts.push(`version:   asrun ${typeof parsed.version === 'string' ? parsed.version : '?'} (${parsed.commit ?? '?'})`);
+            if (typeof parsed.version === 'string' && parsed.version !== installedVersion.version) {
+                warnings.push(`asrun is installed at ${installedVersion.version}, but this workspace was set up with ${parsed.version}: ` +
+                    'run "pnpm asrun upgrade" (or reinstall the version this workspace needs).');
             }
             if (recordedPath !== undefined && !fs.existsSync(path.resolve(ROOT, recordedPath))) {
                 errors.push(`.asrun.json points at "${recordedPath}", which does not exist. Run "pnpm add -D @asrunjs/asrun" and then "pnpm asrun init".`);
@@ -112,6 +119,27 @@ export async function main(args) {
         }
     }
     const framework = recordedPath ?? actualPath;
+    // Workspace migrations: `migrations.since` is the release the workspace matches, so newer ones are still to do. A
+    // workspace upgraded by hand (pnpm add + init --update) keeps the old baseline, which is what makes this check work.
+    if (marker !== null) {
+        try {
+            const state = migrationState(marker, installedVersion.version);
+            const outstanding = state.manual.length;
+            facts.push(`migrations: since ${state.since}${outstanding > 0 ? `, ${outstanding} manual step(s) outstanding` : ''}`);
+            const pending = pendingMigrations(MIGRATIONS, state.since, installedVersion.version);
+            if (pending.length > 0) {
+                warnings.push(`${pending.length} workspace migration(s) apply between ${state.since} and ${installedVersion.version} ` +
+                    `(${pending.map((migration) => migration.id).join(', ')}): run "pnpm asrun migrate".`);
+            }
+            if (outstanding > 0) {
+                warnings.push(`Manual migration steps are still open (${state.manual.join(', ')}): run "pnpm asrun migrate --list" to see ` +
+                    'them, then "pnpm asrun migrate --ack <id>" once they are done.');
+            }
+        }
+        catch (error) {
+            errors.push(`The migration registry is invalid: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
     // The framework repository compiles itself into `dist/`, and `templates/playwright.config.ts` makes every workspace
     // load the config from there. A build older than the sources therefore keeps runs on the previous code.
     const stale = staleDistFiles();
@@ -231,13 +259,27 @@ export async function main(args) {
         // The framework is outside the workspace (examples/demo): the framework repository manages itself.
     }
     else if (workspaceFile === null) {
-        warnings.push('pnpm-workspace.yaml is missing: add the "allowBuilds" block from templates/pnpm-workspace.yaml, or pnpm skips the build scripts of esbuild and ffmpeg-static.');
+        warnings.push(`pnpm-workspace.yaml is missing: run "pnpm asrun init" (it writes the "allowBuilds" entries for ${BUILD_APPROVALS.join(', ')}), or pnpm skips those install scripts.`);
     }
-    else if (!workspaceFile.includes('allowBuilds')) {
-        warnings.push('pnpm-workspace.yaml has no "allowBuilds": pnpm skips the build scripts of esbuild and ffmpeg-static.');
+    else {
+        const missing = BUILD_APPROVALS.filter((pkg) => {
+            const entry = new RegExp(`^\\s+['"]?${pkg.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}['"]?\\s*:`, 'm');
+            return !entry.test(workspaceFile);
+        });
+        if (missing.length > 0) {
+            warnings.push(`pnpm-workspace.yaml has no "allowBuilds" entry for ${missing.join(', ')}: run "pnpm asrun init" (it adds ` +
+                'the entry before installing), or pnpm skips that install script.');
+        }
+        if (/^packages\s*:/m.test(workspaceFile)) {
+            warnings.push('pnpm-workspace.yaml lists "packages"; asrun is a dependency now, so that list can go.');
+        }
     }
-    else if (/^packages\s*:/m.test(workspaceFile)) {
-        warnings.push('pnpm-workspace.yaml lists "packages"; asrun is a dependency now, so that list can go.');
+    // Optional packages the workspace installs on demand, when this machine does not provide the capability itself.
+    for (const extra of RUNTIME_EXTRAS) {
+        if (hasCapability(extra) || installedInWorkspace(ROOT, extra.pkg) || installedInWorkspace(FRAMEWORK_ROOT, extra.pkg))
+            continue;
+        warnings.push(`${extra.pkg} is not installed and this machine does not provide it: ${extra.provides} is skipped. Run ` +
+            '"pnpm asrun init" (or "pnpm go") to install it, or install the tool yourself and run doctor again.');
     }
     let scripts = null;
     try {

package/dist/scripts/go.mjs

@@ -111,9 +111,10 @@ if (dryRun) {
 function ensurePnpmWorkspace() {
   if (frameworkRelative.startsWith('..')) return 'skipped';
   const file = path.join(ROOT, 'pnpm-workspace.yaml');
-  const block = 'allowBuilds:\n  esbuild: true\n  ffmpeg-static: true\n';
+  // `init` (step 3) adds the entry of each optional package it installs on demand, e.g. ffmpeg-static.
+  const block = 'allowBuilds:\n  esbuild: true\n';
   if (!fs.existsSync(file)) {
-    fs.writeFileSync(file, `# asrun's dependencies (esbuild through tsx, ffmpeg-static) compile a binary on install.\n${block}`);
+    fs.writeFileSync(file, `# asrun's dependencies (esbuild through tsx) compile a binary on install.\n${block}`);
     return 'created';
   }
   const text = fs.readFileSync(file, 'utf8');
@@ -140,7 +141,8 @@ function open(target) {
   spawn(command, args, {stdio: 'ignore', detached: true}).on('error', () => {}).unref();
 }
 
-// ffmpeg joins the videos of a test's browser tabs into one. Never fatal: the optional ffmpeg-static package is the fallback.
+// ffmpeg joins the videos of a test's browser tabs into one. Never fatal: `init` (step 3) installs the bundled
+// ffmpeg-static when this machine has no ffmpeg.
 function ensureFfmpeg() {
   // ffmpeg does not know `--version`, only `-version`.
   if (spawnSync('ffmpeg', ['-version'], {stdio: 'ignore', shell}).status === 0) return console.log('ffmpeg: ok');
@@ -151,11 +153,11 @@ function ensureFfmpeg() {
         ? ['winget', ['install', '--id', 'Gyan.FFmpeg', '-e', '--accept-source-agreements', '--accept-package-agreements']]
         : null;
   if (!installer) {
-    return warn('ffmpeg not found; the bundled ffmpeg-static is used instead. To install it yourself: brew install ffmpeg | winget install Gyan.FFmpeg | sudo apt install ffmpeg');
+    return warn('ffmpeg not found; the bundled ffmpeg-static is installed when the workspace is prepared, in step 3. To install ffmpeg yourself: brew install ffmpeg | winget install Gyan.FFmpeg | sudo apt install ffmpeg');
   }
   console.log(`ffmpeg not found, installing it: ${installer[0]} ${installer[1].join(' ')}`);
   if (run(...installer)) console.log('ffmpeg: installed');
-  else warn('Could not install ffmpeg; the bundled ffmpeg-static is used instead.');
+  else warn('Could not install ffmpeg; the bundled ffmpeg-static is installed when the workspace is prepared, in step 3.');
 }
 
 step(1, 'Checking this machine');

package/dist/scripts/init.d.ts

@@ -1,3 +1,4 @@
+import { MARKER, PACKAGE } from '../lib/paths.js';
 /** Files `init` owns: `--update` rewrites exactly these, and a project never edits them. */
 export declare const GENERATED: {
     file: string;
@@ -8,9 +9,9 @@ export declare const ONCE: {
     file: string;
     template: string;
 }[];
-export declare const MARKER = ".asrun.json";
+export { MARKER };
+export { PACKAGE };
 export declare const DOTENV_HEADER = "# asrun: the workspace these commands run against (relative to this file).";
-export declare const PACKAGE = "@asrunjs/asrun";
 /** How the workspace reaches the framework: `./node_modules/@asrunjs/asrun`, or a relative folder in the framework repo. */
 export declare function frameworkPath(root: string): string;
 /** True when this workspace has the package installed (or is the framework's own checkout). */

package/dist/scripts/init.js

@@ -1,13 +1,16 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { spawnSync } from 'node:child_process';
-import { FRAMEWORK_ROOT, TEMPLATES_DIR } from '../lib/paths.js';
+import { FRAMEWORK_ROOT, MARKER, PACKAGE, TEMPLATES_DIR, isRepoCheckout } from '../lib/paths.js';
+import { migrationState, pendingMigrations } from '../lib/migrations.js';
+import { MIGRATIONS } from '../migrations/index.js';
+import { BUILD_APPROVALS, RUNTIME_EXTRAS, approveBuild, ensureRuntimeExtras, hasCapability, installedInWorkspace, } from '../lib/runtime-deps.js';
 /**
  * Creates the files a workspace needs. It is safe to run many times: it never overwrites a file the project owns,
  * `--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] [--install [spec]]
+const USAGE = `Usage: pnpm asrun init [--root <dir>] [--update] [--force [<path>]] [--reset-rules] [--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/*,
@@ -17,6 +20,7 @@ const USAGE = `Usage: pnpm asrun init [--root <dir>] [--update] [--force [<path>
   --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)
   --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 = [
@@ -47,16 +51,13 @@ export const ONCE = [
 ];
 // 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();
-export const MARKER = '.asrun.json';
+// 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).';
-export const PACKAGE = '@asrunjs/asrun';
 function readTemplate(name) {
     return fs.readFileSync(path.join(TEMPLATES_DIR, name), 'utf8');
 }
-/** True in the framework's own repository (not an installed package). */
-function isRepoCheckout() {
-    return !FRAMEWORK_ROOT.split(path.sep).includes('node_modules') && fs.existsSync(path.join(FRAMEWORK_ROOT, 'examples', 'demo'));
-}
 /** How the workspace reaches the framework: `./node_modules/@asrunjs/asrun`, or a relative folder in the framework repo. */
 export function frameworkPath(root) {
     if (!isRepoCheckout()) {
@@ -240,6 +241,7 @@ export async function main(args) {
     }
     const resetRules = args.includes('--reset-rules');
     const skipEnv = args.includes('--no-env');
+    const skipExtras = args.includes('--no-extras');
     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).');
@@ -298,6 +300,25 @@ export async function main(args) {
     const gitignore = ensureGitignore(root, update || forceAll);
     const merged = mergePackageJson(root);
     const dotenv = skipEnv ? 'skipped' : ensureDotEnv(process.cwd(), root);
+    // pnpm runs only the install scripts that pnpm-workspace.yaml approves. A file written before a package joined
+    // BUILD_APPROVALS (or one a project edited by hand) gets the missing entries here, before anything is installed:
+    // a note would be too late, the install that follows would already have skipped the script.
+    const approved = [];
+    const approvalsBroken = [];
+    if (!framework.startsWith('..')) {
+        for (const pkg of BUILD_APPROVALS) {
+            const result = approveBuild(root, pkg);
+            if (result === 'added' || result === 'created')
+                approved.push(pkg);
+            if (result === 'inline' || result === 'no-file')
+                approvalsBroken.push(pkg);
+        }
+        if (approvalsBroken.length > 0) {
+            notes.push(`pnpm-workspace.yaml has no "allowBuilds" block to extend: add ${approvalsBroken
+                .map((pkg) => `"${pkg}: true"`)
+                .join(', ')} under "allowBuilds" by hand, or pnpm skips its install script.`);
+        }
+    }
     if (fs.existsSync(path.join(root, 'tsconfig.json')) && !written.includes('tsconfig.json')) {
         const tsconfig = fs.readFileSync(path.join(root, 'tsconfig.json'), 'utf8');
         if (tsconfig.includes('@asrun/')) {
@@ -306,9 +327,6 @@ export async function main(args) {
     }
     if (fs.existsSync(path.join(root, 'pnpm-workspace.yaml')) && !written.includes('pnpm-workspace.yaml')) {
         const workspace = fs.readFileSync(path.join(root, 'pnpm-workspace.yaml'), 'utf8');
-        if (!workspace.includes('allowBuilds')) {
-            notes.push('Add "allowBuilds: {esbuild: true, ffmpeg-static: true}" to pnpm-workspace.yaml, or pnpm skips their build scripts.');
-        }
         if (!workspace.includes('minimumReleaseAgeExclude')) {
             notes.push('Add an "@asrunjs/asrun" entry to "minimumReleaseAgeExclude" in pnpm-workspace.yaml, or pnpm installs the ' +
                 'previous release for 24 hours after a new one.');
@@ -373,15 +391,53 @@ export async function main(args) {
             return 1;
         }
     }
+    // Optional packages stay out of the package's dependency graph (a runtime dependency with an install script makes
+    // "pnpm dlx @asrunjs/asrun" stop at pnpm's build-approval picker, which nobody can answer in a pipeline), so the
+    // workspace installs one here, only when this machine lacks what it provides. A failure never stops init.
+    const extrasInstalled = [];
+    const extrasSkipped = [];
+    if (!framework.startsWith('..') && isInstalled(root)) {
+        if (skipExtras) {
+            for (const extra of RUNTIME_EXTRAS) {
+                if (!hasCapability(extra) && !installedInWorkspace(root, extra.pkg))
+                    extrasSkipped.push(extra.pkg);
+            }
+            if (extrasSkipped.length > 0) {
+                notes.push(`Optional packages were not installed (--no-extras): ${extrasSkipped.join(', ')}. Run "pnpm asrun init" ` +
+                    'without --no-extras, or "pnpm go", when the machine needs them.');
+            }
+        }
+        else {
+            for (const outcome of ensureRuntimeExtras(root, (extra) => console.log(`\n  Installing ${extra.pkg} (${extra.provides})`))) {
+                if (outcome.status === 'installed')
+                    extrasInstalled.push(outcome.extra.pkg);
+                else if (outcome.status === 'failed') {
+                    notes.push(`${outcome.extra.pkg} was not installed (${outcome.detail}): ${outcome.extra.provides} is skipped until ` +
+                        `it is. Run "pnpm add -D ${outcome.extra.pkg}" in ${root}, then "pnpm asrun init" again.`);
+                }
+            }
+        }
+    }
     const version = frameworkVersion();
+    const previous = readManifest(root);
+    // The marker records the installed version, but the migration baseline is the release the workspace was last
+    // 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);
     fs.writeFileSync(path.join(root, MARKER), JSON.stringify({
         framework: PACKAGE,
         frameworkPath: framework,
         version: version.version,
         commit: version.commit,
+        migrations,
         generated: GENERATED.map((entry) => entry.file),
         updatedAt: new Date().toISOString(),
     }, null, 2) + '\n');
+    const pending = pendingMigrations(MIGRATIONS, 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".');
+    }
     const label = firstRun ? 'Initialized' : forceAll ? 'Forced' : update ? 'Refreshed' : 'Checked';
     console.log(`${label} workspace: ${root}`);
     console.log(`  framework: ${PACKAGE} ${version.version} at ${framework}`);
@@ -391,6 +447,12 @@ export async function main(args) {
         console.log(`  kept:      ${kept.join(', ')}`);
     if (merged.length > 0)
         console.log(`  merged:    package.json -> ${merged.join(', ')}`);
+    // A file init just wrote already has the entries; only an existing one is worth reporting as changed.
+    if (approved.length > 0 && !written.includes('pnpm-workspace.yaml')) {
+        console.log(`  allowBuilds: added ${approved.join(', ')} to pnpm-workspace.yaml`);
+    }
+    if (extrasInstalled.length > 0)
+        console.log(`  extras:    installed ${extrasInstalled.join(', ')}`);
     if (gitignore !== 'kept')
         console.log(`  .gitignore: ${gitignore}`);
     if (dotenv !== 'skipped')

package/dist/scripts/migrate.d.ts

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

package/dist/scripts/migrate.js

@@ -0,0 +1,259 @@
+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 { MIGRATIONS } from '../migrations/index.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
+ * runs after a manual `pnpm add -D @asrunjs/asrun@latest`, or to see what is still open.
+ *
+ * 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]
+
+  --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)
+  --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-all       mark every outstanding manual step as done
+
+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.`;
+/** The version of the package this command runs from: never beyond it, because its code is what applies migrations. */
+function installedVersion() {
+    try {
+        const manifest = JSON.parse(fs.readFileSync(path.join(FRAMEWORK_ROOT, 'package.json'), 'utf8'));
+        return typeof manifest.version === 'string' ? manifest.version : '0.0.0';
+    }
+    catch {
+        return '0.0.0';
+    }
+}
+/** The value of a flag that takes one; undefined when the flag is absent or has no value. */
+function flagValue(args, name) {
+    const index = args.indexOf(name);
+    return index >= 0 && args[index + 1] !== undefined && !args[index + 1].startsWith('-') ? args[index + 1] : undefined;
+}
+/** Every `--ack <id>` of the command line. */
+function acknowledged(args) {
+    const ids = [];
+    for (let index = 0; index < args.length; index++) {
+        if (args[index] === '--ack' && args[index + 1] !== undefined && !args[index + 1].startsWith('-')) {
+            ids.push(args[index + 1]);
+            index++;
+        }
+    }
+    return ids;
+}
+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. */
+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';
+    }
+    finally {
+        rl.close();
+    }
+}
+function printManual(ids) {
+    if (ids.length === 0)
+        return;
+    console.log('\nManual steps left (do them, then mark them done with "pnpm asrun migrate --ack <id>"):');
+    for (const id of ids) {
+        const migration = MIGRATIONS.find((entry) => entry.id === id);
+        if (migration === undefined) {
+            console.log(`  ${id}`);
+            continue;
+        }
+        console.log(`  ${migration.version}  ${migration.id}: ${migration.summary}`);
+        for (const line of migration.manual ?? [])
+            console.log(`    - ${line}`);
+    }
+}
+export async function main(args) {
+    if (args.includes('--help')) {
+        console.log(USAGE);
+        return 0;
+    }
+    const root = path.resolve(flagValue(args, '--root') ?? ROOT);
+    const dryRun = args.includes('--dry-run');
+    const yes = args.includes('--yes');
+    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>.');
+        return 1;
+    }
+    const marker = readMarker(root);
+    if (marker === null) {
+        console.error(`No ${MARKER} in ${root}: this is not an initialized asrun workspace. Run "pnpm asrun init" first.`);
+        return 1;
+    }
+    const installed = installedVersion();
+    const state = migrationState(marker, installed);
+    // `--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) {
+            console.log('\nThis release has no migrations.');
+        }
+        else {
+            console.log(`\n${MIGRATIONS.length} migration(s) known to this release:`);
+            for (const migration of MIGRATIONS) {
+                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' : ''}`);
+            }
+        }
+        printManual(state.manual);
+        return 0;
+    }
+    const ackAll = args.includes('--ack-all');
+    const ackIds = acknowledged(args);
+    if (ackAll || ackIds.length > 0) {
+        const unknown = ackIds.filter((id) => !state.manual.includes(id));
+        if (unknown.length > 0) {
+            console.error(`Not outstanding: ${unknown.join(', ')}. Run "pnpm asrun migrate --list" to see what is.`);
+            return 1;
+        }
+        const manual = ackAll ? [] : state.manual.filter((id) => !ackIds.includes(id));
+        writeMigrationState(root, { since: state.since, manual });
+        console.log(ackAll
+            ? `Acknowledged every outstanding manual step (${state.manual.length}).`
+            : `Acknowledged: ${ackIds.join(', ')}.`);
+        printManual(manual);
+        return 0;
+    }
+    const from = flagValue(args, '--from') ?? state.since;
+    const to = flagValue(args, '--to') ?? installed;
+    if (!isVersion(from) || !isVersion(to)) {
+        console.error(`Not a version: ${!isVersion(from) ? from : to}`);
+        return 1;
+    }
+    if (compareVersions(to, installed) > 0) {
+        console.error(`Refusing to migrate to ${to}: the installed package is ${installed}. The code that applies a migration is the ` +
+            'installed one, so run "pnpm asrun upgrade" (or "pnpm add -D @asrunjs/asrun@latest") first.');
+        return 1;
+    }
+    // A baseline recorded further than the installed release means the workspace was set up by a newer package (or the
+    // install went backwards). Nothing to apply; say so instead of silently moving the baseline back.
+    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);
+        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);
+    console.log(`Workspace: ${root}`);
+    console.log(`asrun:     ${installed}${installed === to ? '' : ` (migrating to ${to})`}`);
+    if (pending.length === 0) {
+        console.log(`Migrations: none between ${start} and ${to}.`);
+        // Nothing was skipped, so the baseline moves up to the release that was asked for: a workspace with an empty
+        // 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);
+        return 0;
+    }
+    console.log(`Migrations: ${pending.length} between ${start} and ${to}`);
+    for (const migration of pending) {
+        console.log(`  ${describe(migration)}${migration.auto === true ? '  (automatic)' : ''}${migration.breaking ? '  (breaking)' : ''}`);
+        if (migration.appliesTo !== undefined)
+            console.log(`      affects: ${migration.appliesTo}`);
+        for (const line of migration.manual ?? [])
+            console.log(`      - ${line}`);
+    }
+    if (dryRun) {
+        console.log('\nNothing was applied (--dry-run).');
+        return 0;
+    }
+    const automatic = pending.filter((migration) => migration.auto === true && typeof migration.apply === 'function');
+    const breaking = automatic.filter((migration) => migration.breaking === true);
+    if (breaking.length > 0 && !yes) {
+        if (!process.stdin.isTTY || !process.stdout.isTTY) {
+            console.error(`\nRefusing to apply ${breaking.length} breaking migration(s): there is no terminal to confirm in. ` +
+                'A person adds --yes to do it.');
+            return 1;
+        }
+        const answer = await confirm(`\nType "migrate" to apply ${breaking.length} breaking migration(s): `);
+        if (!answer) {
+            console.error('Cancelled. Nothing was applied.');
+            return 1;
+        }
+    }
+    const context = {
+        root,
+        frameworkRoot: FRAMEWORK_ROOT,
+        from: start,
+        to,
+        log: (text) => console.log(`      ${text}`),
+    };
+    const state2 = { since: state.since, manual: [...state.manual] };
+    // The baseline moves one *release* at a time: several migrations may come with the same version, and a failure in
+    // the middle of one release must leave the whole release pending, so a retry repeats it instead of skipping the rest.
+    let done = state.since;
+    let applied = 0;
+    let skipped = 0;
+    for (let index = 0; index < pending.length; index++) {
+        const migration = pending[index];
+        const label = `${migration.version} ${migration.id}`;
+        const lastOfRelease = index === pending.length - 1 || pending[index + 1].version !== migration.version;
+        if (migration.auto !== true || typeof migration.apply !== 'function') {
+            console.log(`  -> ${label}: a person has to do this`);
+            for (const line of migration.manual ?? [])
+                console.log(`       - ${line}`);
+            if ((migration.manual ?? []).length > 0)
+                state2.manual.push(migration.id);
+            if (lastOfRelease)
+                done = migration.version;
+            continue;
+        }
+        if (migration.detect !== undefined && !migration.detect(context)) {
+            console.log(`  ok ${label}: already in place`);
+            skipped++;
+            if (lastOfRelease)
+                done = migration.version;
+            continue;
+        }
+        console.log(`  .. ${label}`);
+        try {
+            await migration.apply(context);
+        }
+        catch (error) {
+            // The baseline stops at the last release that finished, so fixing the cause and running the command again
+            // repeats this release (its migrations must be idempotent) and nothing later.
+            writeMigrationState(root, { since: done, manual: [...new Set(state2.manual)] });
+            console.error(`\n  ! ${label} failed: ${error instanceof Error ? error.message : String(error)}`);
+            console.error(`    The workspace is migrated up to ${done}. Fix the cause and run "pnpm asrun migrate" again.`);
+            return 1;
+        }
+        console.log(`  ok ${label}`);
+        applied++;
+        if (lastOfRelease)
+            done = migration.version;
+    }
+    if (compareVersions(to, done) > 0)
+        done = to;
+    state2.since = done;
+    const manual = [...new Set(state2.manual)];
+    writeMigrationState(root, { since: state2.since, manual });
+    console.log(`\nApplied ${applied} migration(s)${skipped > 0 ? `, ${skipped} already in place` : ''}. ` +
+        `Baseline: ${state2.since}.`);
+    printManual(manual);
+    return 0;
+}

package/dist/scripts/run.js

@@ -147,7 +147,8 @@ const knownEnvs = listEnvs(allProfiles);
 const listOnly = passthrough.includes('--list');
 if (!env && !listOnly) {
     console.error(`Choose the environment to test: --env <env>  (${knownEnvs.join(' | ')}). There is no default.\n` +
-        `Example: pnpm asrun --env ${knownEnvs.includes('staging') ? 'staging' : (knownEnvs[0] ?? '<env>')}`);
+        `Example: pnpm asrun --env ${knownEnvs.includes('staging') ? 'staging' : (knownEnvs[0] ?? '<env>')}\n` +
+        'All options: pnpm asrun --help. To check the installation instead: pnpm asrun doctor');
     process.exit(1);
 }
 if (env && !knownEnvs.includes(env)) {

package/dist/scripts/upgrade.d.ts

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