@asrunjs/asrun 0.7.0 → 0.9.0

package/dist/lib/tar.js

@@ -0,0 +1,79 @@
+import zlib from 'node:zlib';
+/**
+ * Reads one file out of a `.tgz`/`.tar`, which is how `pnpm asrun upgrade` reads the migration manifest of the release
+ * it is about to install: the registry serves the package as a tarball, and the manifest has to be looked at before
+ * anything is installed. No external `tar` binary and no dependency: npm writes plain (portable) ustar entries.
+ */
+const BLOCK = 512;
+function text(header, offset, length) {
+    const end = header.indexOf(0, offset);
+    const stop = end === -1 || end > offset + length ? offset + length : end;
+    return header.subarray(offset, stop).toString('utf8');
+}
+/** A numeric header field: octal digits, NUL/space padded. */
+function octal(header, offset, length) {
+    const raw = text(header, offset, length).trim();
+    return raw === '' ? 0 : parseInt(raw, 8);
+}
+function isZeroBlock(block) {
+    for (const byte of block)
+        if (byte !== 0)
+            return false;
+    return true;
+}
+/** The path of a PAX extended header (`LEN key=value\n` records), or null when it carries none. */
+function paxPath(body) {
+    let offset = 0;
+    while (offset < body.length) {
+        const space = body.indexOf(0x20, offset); // the length field ends at the first space
+        if (space === -1)
+            break;
+        const length = Number(body.subarray(offset, space).toString('utf8'));
+        if (!Number.isFinite(length) || length <= 0)
+            break;
+        const record = body.subarray(space + 1, offset + length - 1).toString('utf8'); // without the trailing newline
+        const equals = record.indexOf('=');
+        if (equals > 0 && record.slice(0, equals).replace(/^\w+\./, '') === 'path')
+            return record.slice(equals + 1);
+        offset += length;
+    }
+    return null;
+}
+/**
+ * The content of `wanted` inside a tarball (gzipped or not), or null when the archive has no such file. Only regular
+ * files are considered; a directory entry of the same name is skipped.
+ */
+export function readFileFromTarball(archive, wanted) {
+    const data = archive.length > 1 && archive[0] === 0x1f && archive[1] === 0x8b ? zlib.gunzipSync(archive) : archive;
+    // A PAX or GNU long-name entry names the file of the *next* header; npm tarballs use one for long paths.
+    let pendingName;
+    for (let offset = 0; offset + BLOCK <= data.length;) {
+        const header = data.subarray(offset, offset + BLOCK);
+        if (isZeroBlock(header))
+            break;
+        const size = octal(header, 124, 12);
+        const type = String.fromCharCode(header[156] || 0x30);
+        const body = data.subarray(offset + BLOCK, offset + BLOCK + size);
+        offset += BLOCK + Math.ceil(size / BLOCK) * BLOCK;
+        if (type === 'x') {
+            pendingName = paxPath(body) ?? pendingName;
+            continue;
+        }
+        if (type === 'L') {
+            pendingName = text(body, 0, body.length);
+            continue;
+        }
+        // A global header (`g`) and the link-name header (`K`) say nothing about the next file's path.
+        if (type === 'g' || type === 'K')
+            continue;
+        const name = text(header, 0, 100);
+        const prefix = text(header, 345, 155);
+        const fullName = pendingName ?? (prefix === '' ? name : `${prefix}/${name}`);
+        pendingName = undefined;
+        if (type !== '0' && type !== '\0' && type !== '7')
+            continue;
+        if (fullName === wanted)
+            return body;
+    }
+    return null;
+}

package/dist/lib/update-check.d.ts

@@ -0,0 +1,52 @@
+export declare const CACHE_FILE: string;
+/** Development only: a hand-written answer, so the notice can be seen without publishing a release. */
+export declare const MOCK_FILE: string;
+/** `installed` is a package from the registry; `checkout` is the framework's own git repository. */
+export type InstallKind = 'installed' | 'checkout';
+/** What the last check found. `latest` stays null when the registry could not be read (`error` says why). */
+export interface UpdateStatus {
+    /** The version in the framework's own `package.json`. */
+    current: string;
+    latest: string | null;
+    /** True when `latest` is a version newer than `current`. */
+    available: boolean;
+    /** When the answer was fetched (ISO); the cached answer keeps the time of the fetch. */
+    checkedAt: string;
+    kind: InstallKind;
+    /** True when ASRUN_NO_UPDATE_CHECK turned the check off; nothing was fetched. */
+    disabled: boolean;
+    /** True when a development mock supplied the version or the install kind instead of the registry. */
+    mocked: boolean;
+    error: string | null;
+}
+/**
+ * The newest release on the registry, compared with what this process runs. `force` asks the registry again even when
+ * the cache is fresh (the web UI's daily check does that); every other caller shares the cache.
+ *
+ * A development mock (ASRUN_UPDATE_MOCK_* or `.tmp/update-mock.json`) answers instead of the registry and is never
+ * cached, so removing it brings the real check back at once.
+ */
+export declare function checkForUpdate(options?: {
+    force?: boolean;
+}): UpdateStatus;
+/** The command that moves this installation to the newest release. */
+export declare function upgradeCommand(kind: InstallKind): string;
+/**
+ * Whether ANSI colors belong on this stream: an interactive terminal, unless NO_COLOR or FORCE_COLOR says otherwise.
+ * `FORCE_COLOR` wins, so a smoke test can see the colored line in a captured log.
+ */
+export declare function useColor(stream: {
+    isTTY?: boolean;
+}): boolean;
+/**
+ * The one-line notice, or null when there is nothing to say. `color` adds a badge and highlights the version and the
+ * command, for a person looking at a terminal; the API and a piped log keep the plain sentence.
+ */
+export declare function formatNotice(status: UpdateStatus, options: {
+    color?: boolean;
+}): string | null;
+/**
+ * Prints the notice on stderr, before a command does its own work. stderr keeps stdout clean for pipelines, and any
+ * failure here is swallowed: a command's own result never depends on the registry answering.
+ */
+export declare function announceUpdate(): void;

package/dist/lib/update-check.js

@@ -0,0 +1,223 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { compareVersions, isVersion } from './migrations.js';
+import { FRAMEWORK_ROOT, PACKAGE, TMP_DIR, isRepoCheckout } from './paths.js';
+import { releaseInfo } from './registry.js';
+/**
+ * Is a newer release of the framework on the registry? The command line asks before every command and the web UI asks
+ * once at startup and once a day; both read the same cache in `.tmp/`, so the registry is asked at most once a day per
+ * machine. A failed read is silent: a check that cannot run must never get in the way of a real command.
+ */
+/** The dist-tag the check compares against. */
+const DIST_TAG = 'latest';
+/** How long a successful answer is reused. */
+const FRESH_MS = 24 * 60 * 60 * 1000;
+/** A failed read is retried much sooner, so an offline minute does not hide the next real answer for a day. */
+const RETRY_MS = 60 * 60 * 1000;
+/** The registry is a side question: it never holds a command up for longer than this. */
+const TIMEOUT_MS = 5_000;
+export const CACHE_FILE = path.join(TMP_DIR, 'update-check.json');
+/** Development only: a hand-written answer, so the notice can be seen without publishing a release. */
+export const MOCK_FILE = path.join(TMP_DIR, 'update-mock.json');
+/** ASRUN_NO_UPDATE_CHECK=1 (or true/yes) turns the check off, for a pipeline or a machine without a registry. */
+function checksDisabled() {
+    const value = (process.env.ASRUN_NO_UPDATE_CHECK ?? '').trim().toLowerCase();
+    return value !== '' && value !== '0' && value !== 'false' && value !== 'no';
+}
+function mockKind(value) {
+    return value === 'installed' || value === 'checkout' ? value : undefined;
+}
+/** The mock the environment names: ASRUN_UPDATE_MOCK_LATEST / ASRUN_UPDATE_MOCK_KIND, both optional. */
+function mockFromEnv() {
+    const latest = (process.env.ASRUN_UPDATE_MOCK_LATEST ?? '').trim();
+    const kind = mockKind((process.env.ASRUN_UPDATE_MOCK_KIND ?? '').trim().toLowerCase());
+    const validLatest = isVersion(latest) ? latest : undefined;
+    if (validLatest === undefined && kind === undefined)
+        return null;
+    return { ...(validLatest !== undefined && { latest: validLatest }), ...(kind !== undefined && { kind }) };
+}
+/** The mock in `.tmp/update-mock.json`, written for a live demo of the notice; malformed fields are ignored. */
+function mockFromFile() {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(MOCK_FILE, 'utf8'));
+        const latest = typeof parsed.latest === 'string' && isVersion(parsed.latest.trim()) ? parsed.latest.trim() : undefined;
+        const kind = mockKind(parsed.kind);
+        if (latest === undefined && kind === undefined)
+            return null;
+        return { ...(latest !== undefined && { latest }), ...(kind !== undefined && { kind }) };
+    }
+    catch {
+        return null;
+    }
+}
+/** The development mock, field by field: the environment wins over the file, so a shell variable can pin one field. */
+function mockConfig() {
+    const env = mockFromEnv();
+    const file = mockFromFile();
+    if (env === null && file === null)
+        return null;
+    const latest = env?.latest ?? file?.latest;
+    const kind = env?.kind ?? file?.kind;
+    return { ...(latest !== undefined && { latest }), ...(kind !== undefined && { kind }) };
+}
+/** The version of the framework this process runs, or null when its manifest cannot be read. */
+function installedVersion() {
+    try {
+        const manifest = JSON.parse(fs.readFileSync(path.join(FRAMEWORK_ROOT, 'package.json'), 'utf8'));
+        return typeof manifest.version === 'string' ? manifest.version : null;
+    }
+    catch {
+        return null;
+    }
+}
+function readCache() {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(CACHE_FILE, 'utf8'));
+        if (typeof parsed.checkedAt !== 'number' || typeof parsed.current !== 'string')
+            return null;
+        return {
+            checkedAt: parsed.checkedAt,
+            current: parsed.current,
+            latest: typeof parsed.latest === 'string' ? parsed.latest : null,
+            error: typeof parsed.error === 'string' ? parsed.error : null,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/** Written next to the reports and the other local state; a read-only workspace simply keeps no cache. */
+function writeCache(entry) {
+    try {
+        fs.mkdirSync(path.dirname(CACHE_FILE), { recursive: true });
+        fs.writeFileSync(CACHE_FILE, `${JSON.stringify(entry, null, 2)}\n`, 'utf8');
+    }
+    catch {
+        // No cache is only a slower check next time.
+    }
+}
+function statusFrom(entry, kind, disabled, mocked = false) {
+    const available = entry.latest !== null &&
+        isVersion(entry.latest) &&
+        isVersion(entry.current) &&
+        compareVersions(entry.latest, entry.current) > 0;
+    return {
+        current: entry.current,
+        latest: entry.latest,
+        available,
+        checkedAt: new Date(entry.checkedAt).toISOString(),
+        kind,
+        disabled,
+        mocked,
+        error: entry.error,
+    };
+}
+/**
+ * The newest release on the registry, compared with what this process runs. `force` asks the registry again even when
+ * the cache is fresh (the web UI's daily check does that); every other caller shares the cache.
+ *
+ * A development mock (ASRUN_UPDATE_MOCK_* or `.tmp/update-mock.json`) answers instead of the registry and is never
+ * cached, so removing it brings the real check back at once.
+ */
+export function checkForUpdate(options = {}) {
+    const mock = mockConfig();
+    const kind = mock?.kind ?? (isRepoCheckout() ? 'checkout' : 'installed');
+    const current = installedVersion();
+    if (current === null) {
+        return {
+            current: 'unknown',
+            latest: null,
+            available: false,
+            checkedAt: new Date().toISOString(),
+            kind,
+            disabled: checksDisabled(),
+            mocked: mock !== null,
+            error: `could not read ${path.join(FRAMEWORK_ROOT, 'package.json')}`,
+        };
+    }
+    if (checksDisabled()) {
+        return {
+            current,
+            latest: null,
+            available: false,
+            checkedAt: new Date().toISOString(),
+            kind,
+            disabled: true,
+            mocked: mock !== null,
+            error: null,
+        };
+    }
+    if (mock?.latest !== undefined) {
+        return statusFrom({ checkedAt: Date.now(), current, latest: mock.latest, error: null }, kind, false, true);
+    }
+    const cached = readCache();
+    if (options.force !== true && cached !== null && cached.current === current) {
+        const age = Date.now() - cached.checkedAt;
+        const ttl = cached.latest === null ? RETRY_MS : FRESH_MS;
+        if (age >= 0 && age < ttl)
+            return statusFrom(cached, kind, false, mock !== null);
+    }
+    const lookup = releaseInfo(PACKAGE, DIST_TAG, TIMEOUT_MS);
+    const entry = 'info' in lookup && isVersion(lookup.info.version)
+        ? { checkedAt: Date.now(), current, latest: lookup.info.version, error: null }
+        : {
+            checkedAt: Date.now(),
+            current,
+            latest: null,
+            error: 'error' in lookup ? lookup.error : `the registry answered "${lookup.info.version}", which is not a version`,
+        };
+    writeCache(entry);
+    return statusFrom(entry, kind, false, mock !== null);
+}
+/** The command that moves this installation to the newest release. */
+export function upgradeCommand(kind) {
+    return kind === 'checkout' ? 'git pull' : 'pnpm asrun upgrade';
+}
+/**
+ * Whether ANSI colors belong on this stream: an interactive terminal, unless NO_COLOR or FORCE_COLOR says otherwise.
+ * `FORCE_COLOR` wins, so a smoke test can see the colored line in a captured log.
+ */
+export function useColor(stream) {
+    const force = (process.env.FORCE_COLOR ?? '').trim().toLowerCase();
+    if (force !== '' && force !== '0' && force !== 'false')
+        return true;
+    const noColor = (process.env.NO_COLOR ?? '').trim();
+    if (noColor !== '')
+        return false;
+    return stream.isTTY === true;
+}
+/** One ANSI-styled run, or the text untouched when colors are off. */
+const paint = (text, code, color) => (color ? `\u001b[${code}m${text}\u001b[0m` : text);
+/**
+ * The one-line notice, or null when there is nothing to say. `color` adds a badge and highlights the version and the
+ * command, for a person looking at a terminal; the API and a piped log keep the plain sentence.
+ */
+export function formatNotice(status, options) {
+    if (!status.available || status.latest === null)
+        return null;
+    const color = options.color === true;
+    // The plain line reads as a sentence; the badge only exists to catch the eye on a terminal.
+    const badge = color ? `${paint(' UPDATE ', '43;30;1', true)} ` : '';
+    const release = paint(`${PACKAGE} ${status.latest}`, '1;33', color);
+    const command = paint(upgradeCommand(status.kind), '1;36', color);
+    const tail = status.kind === 'checkout'
+        ? `is available (this checkout is ${status.current}). Update the framework checkout: ${command}`
+        : `is available (installed ${status.current}). Upgrade: ${command}`;
+    return `${badge}${release} ${tail}`;
+}
+/**
+ * Prints the notice on stderr, before a command does its own work. stderr keeps stdout clean for pipelines, and any
+ * failure here is swallowed: a command's own result never depends on the registry answering.
+ */
+export function announceUpdate() {
+    if (process.argv.includes('--help'))
+        return;
+    try {
+        const notice = formatNotice(checkForUpdate(), { color: useColor(process.stderr) });
+        if (notice !== null)
+            console.error(notice);
+    }
+    catch {
+        // A check is a courtesy; a broken one is not a command failure.
+    }
+}

package/dist/migrations/index.d.ts

@@ -0,0 +1,23 @@
+import type { Migration } from '../lib/migrations.js';
+/**
+ * The workspace migrations of this framework, in the order they were introduced.
+ *
+ * A migration is a change an *existing* workspace has to make when the framework moves it from an older release to a
+ * newer one: a config entry that moved, a file whose shape changed, a dependency range that has to follow the peer
+ * dependency. Anything `init --update` refreshes by itself is not a migration (that is what the generated files are
+ * for), and anything that only concerns brand-new workspaces belongs in `templates/`.
+ *
+ * Adding one:
+ * 1. Append an entry with an id of `<version>-<slug>` and the version of the release that *introduces* the change
+ *    (`version` in `package.json` after the release PR is merged, which is the next version at the time of writing).
+ * 2. Explain it for the person: `summary` is one line, `appliesTo` says which workspaces it matters for, `details`
+ *    adds what the summary cannot, and `manual` lists what only a person can do.
+ * 3. `auto: true` only when the change is idempotent and safe to run without asking (`apply` decides, `detect` skips a
+ *    workspace that is already fine). A change to a file the project owns (`AGENTS.md`, `profiles.yaml`, a project
+ *    config) is a `manual` step, never an automatic edit.
+ * 4. Set `breaking: true` when an untouched workspace can stop working. `pnpm asrun upgrade` then asks before it
+ *    installs anything, using the manifest `pnpm build` writes (`dist/migrations/manifest.json`).
+ * 5. Never delete or renumber an entry: a workspace on any older release may still need it. The interface is documented
+ *    in `docs/agents/framework-dev.md`.
+ */
+export declare const MIGRATIONS: Migration[];

package/dist/migrations/index.js

@@ -0,0 +1,22 @@
+/**
+ * The workspace migrations of this framework, in the order they were introduced.
+ *
+ * A migration is a change an *existing* workspace has to make when the framework moves it from an older release to a
+ * newer one: a config entry that moved, a file whose shape changed, a dependency range that has to follow the peer
+ * dependency. Anything `init --update` refreshes by itself is not a migration (that is what the generated files are
+ * for), and anything that only concerns brand-new workspaces belongs in `templates/`.
+ *
+ * Adding one:
+ * 1. Append an entry with an id of `<version>-<slug>` and the version of the release that *introduces* the change
+ *    (`version` in `package.json` after the release PR is merged, which is the next version at the time of writing).
+ * 2. Explain it for the person: `summary` is one line, `appliesTo` says which workspaces it matters for, `details`
+ *    adds what the summary cannot, and `manual` lists what only a person can do.
+ * 3. `auto: true` only when the change is idempotent and safe to run without asking (`apply` decides, `detect` skips a
+ *    workspace that is already fine). A change to a file the project owns (`AGENTS.md`, `profiles.yaml`, a project
+ *    config) is a `manual` step, never an automatic edit.
+ * 4. Set `breaking: true` when an untouched workspace can stop working. `pnpm asrun upgrade` then asks before it
+ *    installs anything, using the manifest `pnpm build` writes (`dist/migrations/manifest.json`).
+ * 5. Never delete or renumber an entry: a workspace on any older release may still need it. The interface is documented
+ *    in `docs/agents/framework-dev.md`.
+ */
+export const MIGRATIONS = [];

package/dist/migrations/manifest.json

@@ -0,0 +1 @@
+[]

package/dist/scripts/build.js

@@ -2,8 +2,10 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { spawnSync } from 'node:child_process';
 import { COPIED_SCRIPTS } from '../lib/build-artifacts.js';
+import { MANIFEST_FILE, toManifest } from '../lib/migrations.js';
 import { commandScript } from '../lib/node-cli.js';
 import { FRAMEWORK_ROOT } from '../lib/paths.js';
+import { MIGRATIONS } from '../migrations/index.js';
 // Compiles the framework to `dist/`: JavaScript and type declarations that Node and Playwright can load from a
 // node_modules folder (Node refuses to strip types there). The plain `.mjs` tools are copied as they are.
 const tsc = commandScript('typescript', 'tsc');
@@ -19,3 +21,8 @@ for (const file of COPIED_SCRIPTS) {
     fs.mkdirSync(path.dirname(to), { recursive: true });
     fs.copyFileSync(from, to);
 }
+// The migration manifest of the published package. A still-old `pnpm asrun upgrade` reads it out of the *target*
+// tarball before installing, so it has to be in `dist/`, next to the compiled registry the installed command uses.
+const manifestFile = path.join(FRAMEWORK_ROOT, MANIFEST_FILE);
+fs.mkdirSync(path.dirname(manifestFile), { recursive: true });
+fs.writeFileSync(manifestFile, JSON.stringify(toManifest(MIGRATIONS), null, 2) + '\n');

package/dist/scripts/cli.js

@@ -1,6 +1,11 @@
 // `pnpm asrun <command>`: a thin dispatcher so every subcommand keeps one entry point.
 // Anything that is not a subcommand is passed to the run command unchanged.
+import { announceUpdate } from '../lib/update-check.js';
 const [command, ...rest] = process.argv.slice(2);
+// The same courtesy the installed `asrun` command shows: one line on stderr when the registry has a newer release.
+// `upgrade` reads the registry itself, and `help` has no work to do.
+if (!['upgrade', 'help', '--help-init'].includes(command ?? '') && !process.argv.includes('--help'))
+    announceUpdate();
 async function main() {
     if (command === 'init') {
         const { main: init } = await import('./init.js');
@@ -17,20 +22,33 @@ async function main() {
         process.exitCode = await reset(rest);
         return;
     }
+    if (command === 'upgrade') {
+        const { main: upgrade } = await import('./upgrade.js');
+        process.exitCode = await upgrade(rest);
+        return;
+    }
+    if (command === 'migrate') {
+        const { main: migrate } = await import('./migrate.js');
+        process.exitCode = await migrate(rest);
+        return;
+    }
     if (command === 'help' || command === '--help-init') {
         console.log(USAGE);
         return;
     }
     await import('./run.js');
 }
-const USAGE = `Usage: pnpm asrun [init|doctor|reset] [options]
+const USAGE = `Usage: pnpm asrun [init|doctor|reset|upgrade|migrate] [options]
 
   (no subcommand)  Run the tests of one environment. See "pnpm asrun --help".
   init             Create the files a workspace needs (never overwrites; --update refreshes generated files,
                    --root <dir> targets another folder, --force overwrites every file init writes,
                    --force <path> overwrites one file).
-  doctor           Check the workspace: profiles, tsconfig alias, generated files, skill overrides.
+  doctor           Check the workspace: profiles, tsconfig alias, generated files, skill overrides, migrations.
   reset            Remove node_modules and the files init writes, for a clean reinstall (keeps cases, specs,
-                   profiles.yaml, package.json and edited scaffold files; see "pnpm asrun reset --help").`;
+                   profiles.yaml, package.json and edited scaffold files; see "pnpm asrun reset --help").
+  upgrade          Install the newest asrun, refresh the workspace files and apply its migrations, after checking the
+                   target release for breaking changes (see "pnpm asrun upgrade --help").
+  migrate          Apply the workspace migrations of the installed release, or list them (see "pnpm asrun migrate
+                   --help"). "upgrade" runs it; use it after a manual install.`;
 await main();
-export {};

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). */