@asrunjs/asrun 0.7.0 → 0.8.0

package/dist/lib/runtime-deps.js

@@ -0,0 +1,161 @@
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnTarget } from './command.js';
+export const RUNTIME_EXTRAS = [
+    {
+        pkg: 'ffmpeg-static',
+        provides: 'joining the recordings of a test that opened more than one browser tab into one video',
+        probe: ['ffmpeg', '-version'],
+        builds: true,
+    },
+];
+/** Every package whose install scripts pnpm may run: the `allowBuilds` block of `pnpm-workspace.yaml`. */
+export const BUILD_APPROVALS = [
+    // esbuild comes in through tsx, which a Git dependency builds with (`prepare`).
+    ...new Set(['esbuild', ...RUNTIME_EXTRAS.filter((extra) => extra.builds).map((extra) => extra.pkg)]),
+];
+const escapePattern = (text) => text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+/** True when the machine already provides what that package would (its probe exits 0). */
+export function hasCapability(extra) {
+    if (extra.probe.length === 0)
+        return false;
+    // `spawnTarget` resolves a Windows `.cmd` shim (ffmpeg installed through winget or a wrapper script) without a shell.
+    const target = spawnTarget(extra.probe[0], extra.probe.slice(1));
+    if (target === null)
+        return false;
+    const result = spawnSync(target.file, target.args, {
+        stdio: 'ignore',
+        ...(target.throughShell && { windowsVerbatimArguments: true }),
+    });
+    return result.status === 0;
+}
+/** True when the workspace itself has the package (installed on demand, so a devDependency). */
+export function installedInWorkspace(root, pkg) {
+    return fs.existsSync(path.join(root, 'node_modules', pkg, 'package.json'));
+}
+/** A package name as a YAML mapping key: quoted when it starts with `@`, which YAML reads as a directive. */
+const yamlKey = (pkg) => (pkg.startsWith('@') ? `'${pkg}'` : pkg);
+/** The `allowBuilds` entry pattern of a package, for both quoted and plain keys. */
+const approvalPattern = (pkg) => new RegExp(`^\\s+['"]?${escapePattern(pkg)}['"]?\\s*:`);
+/**
+ * Adds `<pkg>: true` to the `allowBuilds` block of the workspace's `pnpm-workspace.yaml`, before the package is
+ * installed. Text-level on purpose: the file belongs to the project, comments and order included.
+ *
+ * Returns how it ended up: `present` (already approved), `added`, `created` (the file had no block), `inline` (the
+ * block is a one-line map, which only a person can extend) or `no-file` (the workspace has no `pnpm-workspace.yaml`).
+ */
+export function approveBuild(root, pkg) {
+    const file = path.join(root, 'pnpm-workspace.yaml');
+    let text;
+    try {
+        text = fs.readFileSync(file, 'utf8');
+    }
+    catch {
+        return 'no-file';
+    }
+    const eol = text.includes('\r\n') ? '\r\n' : '\n';
+    const lines = text.split(/\r?\n/);
+    const start = lines.findIndex((line) => /^allowBuilds\s*:/.test(line));
+    if (start === -1) {
+        const body = text.replace(/\s*$/, '');
+        fs.writeFileSync(file, `${body === '' ? '' : `${body}${eol}${eol}`}allowBuilds:${eol}  ${yamlKey(pkg)}: true${eol}`);
+        return 'created';
+    }
+    if (/^allowBuilds\s*:\s*\S/.test(lines[start]))
+        return 'inline';
+    let end = start + 1;
+    for (let i = start + 1; i < lines.length; i++) {
+        // The block stops at the first line that is not indented (a blank line included).
+        if (lines[i].trim() === '' || !/^\s/.test(lines[i]))
+            break;
+        if (approvalPattern(pkg).test(lines[i]))
+            return 'present';
+        end = i + 1;
+    }
+    lines.splice(end, 0, `  ${yamlKey(pkg)}: true`);
+    fs.writeFileSync(file, lines.join(eol));
+    return 'added';
+}
+/**
+ * Adds the package to `minimumReleaseAgeExclude` in the workspace's `pnpm-workspace.yaml`, so pnpm's release age does
+ * not hold a fresh release back while `pnpm asrun upgrade` installs it. Text-level, like `approveBuild`, because the
+ * file belongs to the project.
+ *
+ * Returns how it ended up: `present` (already listed), `added`, `created` (the file had no block), `inline` (the list
+ * is written inline, which only a person can extend) or `no-file` (the workspace has no `pnpm-workspace.yaml`).
+ */
+export function excludeReleaseAge(root, pkg) {
+    const file = path.join(root, 'pnpm-workspace.yaml');
+    let text;
+    try {
+        text = fs.readFileSync(file, 'utf8');
+    }
+    catch {
+        return 'no-file';
+    }
+    const eol = text.includes('\r\n') ? '\r\n' : '\n';
+    const lines = text.split(/\r?\n/);
+    const start = lines.findIndex((line) => /^minimumReleaseAgeExclude\s*:/.test(line));
+    const entry = `'${pkg}'`;
+    if (start === -1) {
+        const body = text.replace(/\s*$/, '');
+        fs.writeFileSync(file, `${body === '' ? '' : `${body}${eol}${eol}`}minimumReleaseAgeExclude:${eol}  - ${entry}${eol}`);
+        return 'created';
+    }
+    if (/^minimumReleaseAgeExclude\s*:\s*\S/.test(lines[start])) {
+        return lines[start].includes(entry) ? 'present' : 'inline';
+    }
+    let end = start + 1;
+    for (let i = start + 1; i < lines.length; i++) {
+        if (lines[i].trim() === '' || !/^\s/.test(lines[i]))
+            break;
+        if (lines[i].includes(entry))
+            return 'present';
+        end = i + 1;
+    }
+    lines.splice(end, 0, `  - ${entry}`);
+    fs.writeFileSync(file, lines.join(eol));
+    return 'added';
+}
+/**
+ * Installs every runtime extra the workspace still lacks, after approving its install script. The package becomes a
+ * devDependency of the workspace (`pnpm add -D`), which is what "on demand" means: a project that never needs the
+ * capability never downloads it. A failure is never fatal: the feature that needs the package degrades, and `init`
+ * tells the person.
+ */
+export function ensureRuntimeExtras(root, onInstall = () => { }) {
+    const outcomes = [];
+    for (const extra of RUNTIME_EXTRAS) {
+        if (hasCapability(extra) || installedInWorkspace(root, extra.pkg)) {
+            outcomes.push({ extra, status: 'present' });
+            continue;
+        }
+        onInstall(extra);
+        // The approval has to be there first: pnpm 12 refuses an install script it has not approved.
+        approveBuild(root, extra.pkg);
+        const target = spawnTarget('pnpm', ['add', '-D', extra.pkg]);
+        const result = target === null
+            ? null
+            : spawnSync(target.file, target.args, {
+                cwd: root,
+                stdio: 'inherit',
+                ...(target.throughShell && { windowsVerbatimArguments: true }),
+            });
+        const error = result?.error ?? undefined;
+        outcomes.push(result === null
+            ? { extra, status: 'failed', detail: 'pnpm was not found on PATH' }
+            : result.status === 0
+                ? { extra, status: 'installed' }
+                : {
+                    extra,
+                    status: 'failed',
+                    detail: error !== undefined
+                        ? error.code === 'ENOENT'
+                            ? 'pnpm was not found on PATH'
+                            : error.message
+                        : `pnpm add exited with code ${result.status}`,
+                });
+    }
+    return outcomes;
+}

package/dist/lib/tar.d.ts

@@ -0,0 +1,5 @@
+/**
+ * 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 declare function readFileFromTarball(archive: Buffer, wanted: string): Buffer | null;

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 {};