@asrunjs/asrun 0.7.0 → 0.8.0

package/dist/scripts/upgrade.js

@@ -0,0 +1,256 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import readline from 'node:readline/promises';
+import { spawnSync } from 'node:child_process';
+import { spawnTarget } from '../lib/command.js';
+import { compareVersions, isVersion, migrationState, pendingMigrations, readMarker, } from '../lib/migrations.js';
+import { FRAMEWORK_ROOT, MARKER, ROOT } from '../lib/paths.js';
+import { releaseInfo, releaseManifest } from '../lib/registry.js';
+import { excludeReleaseAge } from '../lib/runtime-deps.js';
+import { frameworkPath, PACKAGE } from './init.js';
+/**
+ * `pnpm asrun upgrade`: one command that installs the newest framework, refreshes the workspace files and applies the
+ * migrations the new release brings.
+ *
+ * The order matters. The migration manifest of the *target* release is read out of its tarball first, so breaking
+ * changes are known before anything is written; the install comes next, and `init --update`, `migrate` and `doctor`
+ * then run through the *newly installed* package, never through the code that is being replaced.
+ */
+const USAGE = `Usage: pnpm asrun upgrade [--version <version|dist-tag>] [--root <dir>] [--dry-run] [--yes]
+
+  --version <v>   the release to install (default: latest); a dist-tag or a concrete version
+  --root <dir>    the workspace to upgrade (default: the current workspace)
+  --dry-run       print the target release and the migrations it brings, and change nothing
+  --yes           install without asking (a breaking change, or a release that cannot be checked)
+
+What it does, in this order:
+  1. resolve the target release and read its migration manifest from the registry;
+  2. show the breaking changes and the migrations between the workspace's baseline and that release;
+  3. install @asrunjs/asrun at that version (a fresh release is exempted from pnpm's release age first);
+  4. run "init --update", "migrate" and "doctor" through the installed package.
+
+A release older than the migration manifest cannot be checked in advance: the command says so and asks before it
+installs. "pnpm asrun migrate" runs only the migration part, for a workspace that was upgraded by hand.`;
+/** How a workspace reaches its install: the nearest `node_modules/@asrunjs/asrun` at or above the workspace root. */
+function installedDir(root) {
+    for (let dir = path.resolve(root);; dir = path.dirname(dir)) {
+        const candidate = path.join(dir, 'node_modules', PACKAGE);
+        if (fs.existsSync(path.join(candidate, 'package.json')))
+            return candidate;
+        if (path.dirname(dir) === dir)
+            return null;
+    }
+}
+/** The version of the package installed in that workspace, or null when it is not there. */
+function installedVersion(dir) {
+    if (dir === null)
+        return null;
+    try {
+        const manifest = JSON.parse(fs.readFileSync(path.join(dir, 'package.json'), 'utf8'));
+        return typeof manifest.version === 'string' ? manifest.version : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** A person types the word; without a terminal there is no confirmation, and the command refuses. */
+async function confirm(question) {
+    if (!process.stdin.isTTY || !process.stdout.isTTY)
+        return null;
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        return (await rl.question(question)).trim().toLowerCase() === 'upgrade';
+    }
+    finally {
+        rl.close();
+    }
+}
+function printMigration(entry) {
+    const tags = [entry.breaking === true ? 'breaking' : '', entry.auto === true ? 'runs automatically' : 'needs a person']
+        .filter(Boolean)
+        .join(', ');
+    console.log(`  ${entry.breaking === true ? '!' : ' '} ${entry.version}  ${entry.summary}`);
+    console.log(`        ${entry.id}${tags === '' ? '' : `  (${tags})`}`);
+    if (entry.appliesTo !== undefined)
+        console.log(`        affects: ${entry.appliesTo}`);
+    if (entry.details !== undefined)
+        console.log(`        detail:  ${entry.details}`);
+    for (const line of entry.manual ?? [])
+        console.log(`        - ${line}`);
+}
+export async function main(args) {
+    if (args.includes('--help')) {
+        console.log(USAGE);
+        return 0;
+    }
+    const value = (name) => {
+        const index = args.indexOf(name);
+        return index >= 0 && args[index + 1] !== undefined && !args[index + 1].startsWith('-') ? args[index + 1] : undefined;
+    };
+    const root = path.resolve(value('--root') ?? ROOT);
+    const dryRun = args.includes('--dry-run');
+    const yes = args.includes('--yes');
+    const spec = value('--version') ?? 'latest';
+    if (path.resolve(root) === path.resolve(FRAMEWORK_ROOT)) {
+        console.error('This folder is the framework itself, not a workspace. Run "pnpm asrun upgrade" in the project that uses ' +
+            'asrun, or pass --root <dir>.');
+        return 1;
+    }
+    if (!fs.existsSync(path.join(root, MARKER))) {
+        console.error(`No ${MARKER} in ${root}: this is not an initialized asrun workspace. Run "pnpm asrun init" first.`);
+        return 1;
+    }
+    console.log('[1/4] Checking the release');
+    const directory = installedDir(root);
+    const current = installedVersion(directory);
+    if (directory === null || current === null) {
+        // The framework's own checkout (examples/demo) has no installed package and must be updated with git; a project
+        // that never installed the framework has to add the dependency.
+        const checkout = !path.resolve(root, frameworkPath(root)).split(path.sep).includes('node_modules');
+        if (checkout) {
+            console.error(`${root} uses the framework's own checkout (${path.resolve(root, frameworkPath(root))}), not an installed ` +
+                'package: there is nothing to install. Update that checkout with git.');
+        }
+        else {
+            console.error(`${PACKAGE} is not installed in ${root}. Run "pnpm add -D ${PACKAGE}@${spec}" and then "pnpm asrun init".`);
+        }
+        return 1;
+    }
+    const lookup = releaseInfo(PACKAGE, spec);
+    if ('error' in lookup) {
+        console.error(`Could not read ${PACKAGE}@${spec} from the registry: ${lookup.error}`);
+        console.error(`\nUpgrade by hand instead:\n  pnpm add -D ${PACKAGE}@${spec}\n  pnpm asrun init --update\n  pnpm asrun migrate\n` +
+            '  pnpm asrun doctor');
+        return 1;
+    }
+    const target = lookup.info.version;
+    if (!isVersion(target) || !isVersion(current)) {
+        console.error(`The registry reported "${target}" and the workspace has "${current}"; expected versions.`);
+        return 1;
+    }
+    const order = compareVersions(target, current);
+    if (order === 0) {
+        console.log(`${PACKAGE} ${current} is already installed in ${root}.`);
+        console.log('To refresh the workspace files or apply migrations that are still pending, run "pnpm asrun init --update" ' +
+            'and "pnpm asrun migrate".');
+        return 0;
+    }
+    if (order < 0) {
+        console.error(`${PACKAGE}@${spec} is ${target}, which is older than the installed ${current}: upgrade never downgrades. ` +
+            `Run "pnpm add -D ${PACKAGE}@${target}" yourself if that is what you want.`);
+        return 1;
+    }
+    // The registry serves the package as a tarball; the manifest in it is what makes the pre-install check possible.
+    const state = migrationState(readMarker(root), current);
+    let warning = null;
+    let pending = [];
+    try {
+        const manifest = await releaseManifest(lookup.info.tarball);
+        if (manifest === null) {
+            warning = `${PACKAGE}@${target} ships no migration manifest (it predates it), so nothing could be checked in advance.`;
+        }
+        else {
+            pending = pendingMigrations(manifest, state.since, target);
+        }
+    }
+    catch (error) {
+        warning = `the migration manifest of ${PACKAGE}@${target} could not be read (${error instanceof Error ? error.message : String(error)}), so nothing could be checked in advance.`;
+    }
+    console.log(`Workspace: ${root}`);
+    console.log(`asrun:     ${current} -> ${target}`);
+    if (warning === null && pending.length === 0) {
+        console.log(`Migrations: none between ${state.since} and ${target}.`);
+    }
+    else if (pending.length > 0) {
+        console.log(`\nMigrations between ${state.since} and ${target}:`);
+        for (const entry of pending)
+            printMigration(entry);
+    }
+    if (warning !== null)
+        console.log(`\n  ! Cannot check the workspace up front: ${warning}`);
+    const breaking = pending.filter((entry) => entry.breaking === true);
+    const needsConfirmation = breaking.length > 0 || warning !== null;
+    if (dryRun) {
+        console.log(`\nWould install ${PACKAGE}@${target}, then run "init --update", "migrate" and "doctor" ` +
+            `(${pending.filter((entry) => entry.auto === true).length} automatic migration(s)).`);
+        console.log('Nothing was installed (--dry-run).');
+        return 0;
+    }
+    if (needsConfirmation) {
+        const question = breaking.length > 0
+            ? `\nType "upgrade" to install ${PACKAGE}@${target} despite ${breaking.length} breaking change(s): `
+            : `\nType "upgrade" to install ${PACKAGE}@${target} without the pre-install check: `;
+        const answer = await confirm(question);
+        if (answer === null) {
+            console.error('Refusing to install: there is no terminal to confirm in. A person adds --yes to do it.');
+            return 1;
+        }
+        if (!answer) {
+            console.error('Cancelled. Nothing was installed.');
+            return 1;
+        }
+    }
+    console.log(`\n[2/4] Installing ${PACKAGE}@${target}`);
+    const age = excludeReleaseAge(root, PACKAGE);
+    if (age === 'added' || age === 'created') {
+        console.log(`  pnpm-workspace.yaml: ${PACKAGE} exempted from pnpm's release age`);
+    }
+    else if (age === 'inline') {
+        console.log(`  ! pnpm-workspace.yaml has an inline "minimumReleaseAgeExclude": add ${PACKAGE} to it, or pnpm may install the ` +
+            'previous release instead of the one just published.');
+    }
+    const pnpm = spawnTarget('pnpm', ['add', '-D', `${PACKAGE}@${target}`]);
+    if (pnpm === null) {
+        console.error('pnpm was not found on PATH: install it, then run "pnpm asrun upgrade" again.');
+        return 1;
+    }
+    const install = spawnSync(pnpm.file, pnpm.args, {
+        cwd: root,
+        stdio: 'inherit',
+        ...(pnpm.throughShell && { windowsVerbatimArguments: true }),
+    });
+    if (install.status !== 0) {
+        const error = install.error;
+        const reason = error !== undefined
+            ? error.code === 'ENOENT'
+                ? 'pnpm was not found on PATH'
+                : error.message
+            : install.signal !== null
+                ? `pnpm was stopped by ${install.signal}`
+                : `pnpm add exited with code ${install.status}`;
+        console.error(`\n  ! ${PACKAGE}@${target} was not installed: ${reason}`);
+        console.error(`    Nothing after this step ran. Fix the cause and run "pnpm asrun upgrade" again.`);
+        return 1;
+    }
+    // Everything from here on runs the package that was just installed: its templates, its migrations, its checks. The
+    // process that started this command is still the old code, and must not write the marker with the old version.
+    const installedAfter = installedDir(root);
+    const after = installedVersion(installedAfter);
+    if (after !== null && after !== target) {
+        console.log(`\n  ! pnpm installed ${PACKAGE}@${after}, not @${target} (pnpm's release age can hold a fresh release back). ` +
+            'The workspace is brought up to the version that is there; run "pnpm asrun upgrade" again later.');
+    }
+    const bin = installedAfter === null ? '' : path.join(installedAfter, 'bin', 'asrun.mjs');
+    if (bin === '' || !fs.existsSync(bin)) {
+        console.error(`\n  ! The install finished, but the installed asrun command is missing (${bin || 'not found'}). ` +
+            'Run "pnpm install", then "pnpm asrun init --update".');
+        return 1;
+    }
+    const env = { ...process.env, ASRUN_ROOT: root };
+    const run = (commandArgs) => spawnSync(process.execPath, [bin, ...commandArgs], { cwd: process.cwd(), stdio: 'inherit', env });
+    console.log(`\n[3/4] Refreshing the workspace files and applying migrations`);
+    const init = run(['init', '--root', root, '--update']);
+    if (init.status !== 0) {
+        console.error(`\n  ! "init --update" failed. Fix the cause and run "pnpm asrun init --update", then "pnpm asrun migrate".`);
+        return 1;
+    }
+    const migrate = run(['migrate', '--root', root, '--yes']);
+    if (migrate.status !== 0) {
+        console.error(`\n  ! "migrate" failed. Fix the cause and run "pnpm asrun migrate" again.`);
+        return 1;
+    }
+    console.log(`\n[4/4] Checking the workspace`);
+    const doctor = run(['doctor']);
+    console.log(`\nUpgraded ${PACKAGE} ${current} -> ${after ?? target} in ${root}.`);
+    return doctor.status ?? 0;
+}

package/dist/ui/server/app.js

@@ -14,6 +14,7 @@ import { resolveInside, sendFile } from './files.js';
 import { JobConflictError, jobs } from './jobs.js';
 import { listAiModels } from './ai-models.js';
 import { fileEvents } from './watch-files.js';
+import { refreshUpdate, updateEvents, updateInfo } from './update.js';
 const REPORTS_DIR = path.join(ROOT, 'reports');
 // Built by `prepack` and shipped with the package; the framework repository builds it with `pnpm ui`.
 const WEB_DIST = path.join(FRAMEWORK_ROOT, 'ui', 'dist');
@@ -228,6 +229,17 @@ export function createApp({ port }) {
         const image = resolveInside(base, file.slice('.explore/'.length));
         return image ? sendFile(c, image) : c.notFound();
     });
+    // The release check of this server run. `refresh=1` asks the registry again and answers with the result (a person
+    // testing the notice, or a page that wants a fresh answer); otherwise the page gets the current state, and the first
+    // page load starts the check if it has not finished yet.
+    api.get('/update', async (c) => {
+        if (c.req.query('refresh') === '1')
+            return c.json(await refreshUpdate(true));
+        const info = updateInfo();
+        if (info.checkedAt === null)
+            void refreshUpdate(true);
+        return c.json(info);
+    });
     api.get('/reports', (c) => {
         if (!fs.existsSync(REPORTS_DIR))
             return c.json([]);
@@ -288,12 +300,18 @@ export function createApp({ port }) {
             if (open)
                 void stream.writeSSE({ event: 'files', data: JSON.stringify(change) }).catch(() => { });
         };
+        const updateListener = (info) => {
+            if (open)
+                void stream.writeSSE({ event: 'update', data: JSON.stringify(info) }).catch(() => { });
+        };
         jobs.events.on('job', listener);
         fileEvents.on('files', filesListener);
+        updateEvents.on('update', updateListener);
         stream.onAbort(() => {
             open = false;
             jobs.events.off('job', listener);
             fileEvents.off('files', filesListener);
+            updateEvents.off('update', updateListener);
         });
         while (open) {
             await stream.writeSSE({ event: 'ping', data: '' });

package/dist/ui/server/index.js

@@ -3,6 +3,7 @@ import { createApp } from './app.js';
 import { verifyProfiles } from './profiles.js';
 import { jobs } from './jobs.js';
 import { startFileWatcher } from './watch-files.js';
+import { startUpdateWatcher } from './update.js';
 const port = Number(process.env.ASRUN_UI_PORT ?? 4173);
 const app = createApp({ port });
 const server = serve({ fetch: app.fetch, port, hostname: '127.0.0.1' }, () => {
@@ -15,6 +16,8 @@ const server = serve({ fetch: app.fetch, port, hostname: '127.0.0.1' }, () => {
         console.log(`asrun UI: http://127.0.0.1:${port}`);
     }
     startFileWatcher();
+    // Once now (the notice lands on this terminal), then at every UTC midnight; the top bar picks the answer up.
+    startUpdateWatcher();
     void verifyProfiles();
 });
 server.on('error', (error) => {

package/dist/ui/server/update.d.ts

@@ -0,0 +1,18 @@
+import { EventEmitter } from 'node:events';
+import type { UpdateInfo } from '../shared/types.js';
+/**
+ * The release check of the web UI: once when the server starts, then once a day at 00:00 UTC. The answer is cached in
+ * `.tmp/` (see lib/update-check.ts), so several tabs and the command line share one registry read. Pages learn about a
+ * change through the `update` event of `/api/events`.
+ */
+export declare const updateEvents: EventEmitter<[never]>;
+/** What the UI should show now; before the first answer every field that needs one is null. */
+export declare function updateInfo(): UpdateInfo;
+/**
+ * Asks the registry again and tells the open pages. `force` goes past a fresh cache, which is what the startup and the
+ * daily checks do; the answer is written back to `.tmp/`, so the command line shares it. Overlapping calls share one
+ * read: the daily timer and the first page load can arrive together.
+ */
+export declare function refreshUpdate(force?: boolean): Promise<UpdateInfo>;
+/** Today's check, then one at every UTC midnight while the server runs. */
+export declare function startUpdateWatcher(): void;

package/dist/ui/server/update.js

@@ -0,0 +1,87 @@
+import { EventEmitter } from 'node:events';
+import { checkForUpdate, formatNotice, upgradeCommand, useColor } from '../../lib/update-check.js';
+/**
+ * The release check of the web UI: once when the server starts, then once a day at 00:00 UTC. The answer is cached in
+ * `.tmp/` (see lib/update-check.ts), so several tabs and the command line share one registry read. Pages learn about a
+ * change through the `update` event of `/api/events`.
+ */
+export const updateEvents = new EventEmitter();
+// One listener per open page; the default warning at ten tabs is noise.
+updateEvents.setMaxListeners(0);
+let status = null;
+let inFlight = null;
+/** The notice already printed, so a daily re-check of the same release does not repeat it. */
+let printedNotice = null;
+/** What the UI should show now; before the first answer every field that needs one is null. */
+export function updateInfo() {
+    if (status === null) {
+        return {
+            current: null,
+            latest: null,
+            available: false,
+            checkedAt: null,
+            kind: null,
+            command: null,
+            disabled: false,
+            mocked: false,
+            error: null,
+        };
+    }
+    return {
+        current: status.current,
+        latest: status.latest,
+        available: status.available,
+        checkedAt: status.checkedAt,
+        kind: status.kind,
+        command: status.available ? upgradeCommand(status.kind) : null,
+        disabled: status.disabled,
+        mocked: status.mocked,
+        error: status.error,
+    };
+}
+/**
+ * Asks the registry again and tells the open pages. `force` goes past a fresh cache, which is what the startup and the
+ * daily checks do; the answer is written back to `.tmp/`, so the command line shares it. Overlapping calls share one
+ * read: the daily timer and the first page load can arrive together.
+ */
+export function refreshUpdate(force = true) {
+    if (inFlight !== null)
+        return inFlight;
+    inFlight = (async () => {
+        try {
+            status = checkForUpdate({ force });
+        }
+        catch {
+            // checkForUpdate reports a failed read instead of throwing; if that ever changes, keep serving the last answer.
+        }
+        const answer = updateInfo();
+        const notice = status === null || status.disabled ? null : formatNotice(status, { color: useColor(process.stdout) });
+        // Printed on the terminal only when something changed: once at startup, and again for a newer release.
+        if (notice !== printedNotice && notice !== null) {
+            printedNotice = notice;
+            console.log(notice);
+        }
+        if (notice === null)
+            printedNotice = null;
+        updateEvents.emit('update', answer);
+        return answer;
+    })().finally(() => {
+        inFlight = null;
+    });
+    return inFlight;
+}
+/** Today's check, then one at every UTC midnight while the server runs. */
+export function startUpdateWatcher() {
+    void refreshUpdate(true);
+    scheduleNextCheck();
+}
+function scheduleNextCheck() {
+    const now = new Date();
+    const nextMidnight = Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), now.getUTCDate() + 1);
+    const timer = setTimeout(() => {
+        void refreshUpdate(true);
+        scheduleNextCheck();
+    }, Math.max(1_000, nextMidnight - now.getTime()));
+    // The check must never keep the server process alive on its own.
+    timer.unref();
+}

package/dist/ui/shared/types.d.ts

@@ -332,6 +332,30 @@ export interface InfoResponse {
     suites: string[];
     caseIds: string[];
 }
+/**
+ * What the web UI shows about a newer release. The first check of a server run may still be running, so every field
+ * that needs an answer is null until it finished.
+ */
+export interface UpdateInfo {
+    /** The version of the framework this server runs; null until the first check finished. */
+    current: string | null;
+    /** The newest release on the registry; null when there is none (or the registry could not be read). */
+    latest: string | null;
+    /** True when `latest` is newer than `current`. */
+    available: boolean;
+    /** When the answer was fetched, ISO. A cached answer keeps the time of the fetch. */
+    checkedAt: string | null;
+    /** `installed` when the framework comes from the registry, `checkout` for the framework's own git repository. */
+    kind: 'installed' | 'checkout' | null;
+    /** The line to run to get the newest release; null when there is nothing to upgrade. */
+    command: string | null;
+    /** True when ASRUN_NO_UPDATE_CHECK turned the check off. */
+    disabled: boolean;
+    /** True when the answer is a development mock (ASRUN_UPDATE_MOCK_* or `.tmp/update-mock.json`). */
+    mocked: boolean;
+    /** Why the last check could not read the registry; the UI stays quiet then. */
+    error: string | null;
+}
 /** Everything that belongs to one case. Shown before a delete or rename, and returned by them. */
 export interface CaseImpact {
     id: string;

package/docs/agents/framework-dev.md

@@ -66,6 +66,74 @@ is relevant to a project that uses asrun as a dependency.
 - A project's rules never flow back here. The framework reads a workspace only through `ROOT` at run time; nothing
   under `templates/` or `.claude/skills/` is generated from a project.
 
+### Seeing the release notice without a release
+
+`lib/update-check.ts` asks the registry for the newest version. To see the notice without publishing anything, make it
+answer with a made-up version. The check is the same code the command line and the web UI run, so both show exactly
+what a real release would produce.
+
+```powershell
+# A framework checkout (the default in this repository): the notice says to update with git
+$env:ASRUN_UPDATE_MOCK_LATEST = '9.9.9'
+pnpm asrun doctor       # stderr: ... Update the framework checkout: git pull
+pnpm ui                  # top-bar badge, and the dialog offers git pull
+
+# A registry install: the notice offers "pnpm asrun upgrade"
+$env:ASRUN_UPDATE_MOCK_KIND = 'installed'
+pnpm ui
+```
+
+- `ASRUN_UPDATE_MOCK_LATEST=<version>` replaces the registry answer; `ASRUN_UPDATE_MOCK_KIND=installed|checkout`
+  replaces the install-kind detection. Each field falls back, in this order, to the environment, then to
+  `.tmp/update-mock.json` at the workspace root (in this repository that is `examples/demo/.tmp/update-mock.json`,
+  because `.env` points `ASRUN_ROOT` there; for example `{"latest": "9.9.9", "kind": "installed"}`). A mock is never
+  written to the `.tmp/update-check.json` cache, so deleting the variable or the file brings the real check straight
+  back.
+- The environment is read when a process starts: a running `pnpm ui` must be restarted after changing it. The mock file
+  is read on every check, so editing it and pressing **Check again** (or `GET /api/update?refresh=1`) is enough.
+- The UI marks a mocked answer with a **Dev mock** tag, and the API returns `mocked: true`.
+- `ASRUN_NO_UPDATE_CHECK=1` still wins over both: it turns the notice off entirely.
+
+`GET /api/update` answers with the state of the server's last check; `GET /api/update?refresh=1` checks again first
+(it is what the dialog's **Check again** button calls).
+
+### Optional runtime packages
+
+A dependency with an install script makes `pnpm dlx @asrunjs/asrun` stop at pnpm's build-approval picker: the dlx
+sandbox does not read the workspace's `allowBuilds`, and in a pipeline nobody can answer the prompt. So a package that
+is heavy and optional (the bundled `ffmpeg-static` today) is not a dependency at all:
+
+- Add it to `RUNTIME_EXTRAS` in `lib/runtime-deps.ts`, with the line the person sees (`provides`), a `probe` command
+  that proves the machine already has the capability, and `builds: true` when the package runs an install script.
+- `init` (and therefore `go`, whose third step runs it) writes the `allowBuilds` entry and installs the package as a
+  dependency of the workspace, only when the probe fails; `--no-extras` leaves it out. `BUILD_APPROVALS` is the one
+  list `doctor`, `go` and the template of `pnpm-workspace.yaml` follow.
+- Resolve an extra from `ROOT` first, then from the framework's own install, the way `lib/ffmpeg.ts` does.
+- `doctor` warns while an extra is missing, and `verify:pack` fails when one of them becomes a runtime dependency
+  again (that would bring the dlx prompt back). CI runs it on a packed tarball.
+
+### Workspace migrations
+
+A release can require an *existing* workspace to change; `docs/commands.md` has the user's view. The registry is
+`migrations/index.ts`, and the interface plus the helpers live in `lib/migrations.ts`:
+
+- `version` is the release that introduces the change. `pnpm asrun migrate` runs an entry when
+  `migrations.since < version <= installed`, in version order, and moves `since` only after every entry of that
+  release has been processed, so a failed run repeats the release instead of skipping its other entries.
+- `auto: true` with an `apply` runs after the install, when `detect` says the workspace is not migrated yet. Keep it
+  idempotent: a run that failed repeats the entry.
+- Anything a person has to do is `manual: string[]`. The id is remembered in `.asrun.json` (`migrations.manual`) and
+  `doctor` keeps reminding until `pnpm asrun migrate --ack <id>`.
+- `breaking: true` makes `pnpm asrun upgrade` ask before installing anything. The pre-install check reads
+  `dist/migrations/manifest.json` out of the target tarball, so `pnpm build` has to write it (`scripts/build.ts`
+  serialises `MIGRATIONS` with `toManifest`). `verify:pack` asserts that a packed tarball carries the manifest and that
+  the reader in `lib/tar.ts` finds it.
+- Append only: never delete or renumber an entry, because a workspace on an older release may still need it. A change
+  that only concerns brand-new workspaces belongs in `templates/`, not in a migration.
+- `scripts/migrate.ts` applies the *installed* package's registry, so it never runs an entry from a release that is not
+  installed. `scripts/upgrade.ts` installs first, then runs `init --update`, `migrate` and `doctor` through the newly
+  installed bin (`bin/asrun.mjs`), never through the process that started the upgrade.
+
 ### Installing this repository as a Git dependency (private)
 
 The npm package is the public channel for users. This repository is private, so a Git dependency works only on a
@@ -164,8 +232,10 @@ Every lead, label and tooltip is written for the person using the UI, never for
 
 Nothing bumps the version by hand. A merge to `main` runs `.github/workflows/release.yml`, and Release Please opens
 (or refreshes) one `chore(release): X.Y.Z` pull request holding the next `package.json` version and the matching
-`CHANGELOG.md` entry. Merging that pull request is the release: the same run tags the commit `vX.Y.Z` and publishes to
-npm.
+`CHANGELOG.md` entry. Merging that pull request is the release: the same run tags the commit and publishes to npm.
+
+- Tags carry the package component, which manifest mode adds by default: `asrun-v0.7.0`, not `v0.7.0`. The publish check
+  accepts either, so a hand-made `v0.7.0` still works.
 
 - The next version comes from the commit messages on `main`, and a squashed pull request title becomes that message.
   `fix:` is a patch, `feat:` a minor, `feat!:` a major (the project is past 0.x, so a breaking change releases
@@ -174,8 +244,8 @@ npm.
 - `templates/`, `docs/`, `ui/dist/` and `.claude/` are shipped files: a change to them needs `fix:` or `feat:`, not
   `docs:`, or no release is made and no workspace ever sees the new version (`pnpm asrun doctor` compares it).
 - `release.yml` is the only uploader. When an upload fails after the tag exists, run it by hand with the tag instead of
-  re-running the failed job: `gh workflow run release.yml -f tag=v1.0.0` (`-f dry_run=true` packs without uploading).
-  A re-run of the push run finds the release already made and skips publishing.
+  re-running the failed job: `gh workflow run release.yml -f tag=asrun-v1.0.0` (`-f dry_run=true` packs without
+  uploading). A re-run of the push run finds the release already made and skips publishing.
 - npm authentication is trusted publishing (OIDC, no secret): the workflow filename in the package's trusted publisher
   settings is `release.yml`. A private repository gets no provenance, so the package page shows no provenance badge.
 

package/docs/commands.md

@@ -7,8 +7,10 @@ thin wrappers, so `pnpm asrun`, `pnpm signin` and the rest work as below. The sa
 
 | I want to... | Command |
 |---|---|
-| Install / update the framework | `pnpm dlx @asrunjs/asrun init --install`, `pnpm add -D @asrunjs/asrun@latest` |
+| Install the framework in a project | `pnpm dlx @asrunjs/asrun init --install` |
+| Upgrade the framework and migrate the workspace | `pnpm asrun upgrade [--version <v>] [--dry-run]` |
 | Prepare or check the workspace | `pnpm asrun init [--update]`, `pnpm asrun doctor` |
+| See or apply the workspace migrations after a manual install | `pnpm asrun migrate [--list] [--dry-run]` |
 | Start over with fresh dependencies | `pnpm asrun reset [--yes] [--state] [--lockfile]` |
 | Start the web UI | `pnpm go`, `pnpm ui`, `pnpm ui:dev` |
 | See which profiles are logged in | `pnpm status [--env <env>]` |
@@ -168,19 +170,87 @@ pnpm ui:dev         # Vite on :5173 with hot reload, API in watch mode
 The UI only listens on `127.0.0.1`. Set `ASRUN_UI_PORT` to change the port (`ASRUN_UI_WEB_PORT` for the Vite dev
 server). See [web-ui.md](./web-ui.md).
 
+The UI checks the registry for a newer release when it starts and then once a day at 00:00 UTC (the answer is cached in
+`.tmp/`, so the command line shares it). A newer release is printed on the terminal at startup and shows up as a badge
+in the top bar; click it to see the version and the command that upgrades this install. `pnpm asrun upgrade` is skipped
+there (it reads the registry itself). Set `ASRUN_NO_UPDATE_CHECK=1` to switch the check off, for a pipeline or a machine
+without a registry.
+
+## Upgrading the framework
+
+```bash
+pnpm asrun upgrade
+pnpm asrun upgrade --dry-run
+pnpm asrun upgrade --version 0.9.0
+```
+
+`upgrade` runs four steps, in this order:
+
+1. resolves the target release (`latest`, or the dist-tag/version `--version <v>` names) and prints
+   `installed -> target`;
+2. reads the **migration manifest of the target release out of its tarball, before installing anything**, and prints
+   the migrations and breaking changes between the workspace's baseline (`.asrun.json` → `migrations.since`) and that
+   release. A breaking change needs a person's confirmation (type `upgrade`); an unattended run passes `--yes`. A
+   release that ships no manifest (it predates the manifest) cannot be checked in advance: `upgrade` says so and asks
+   before it installs;
+3. installs `@asrunjs/asrun@<target>` (it first exempts a fresh release from pnpm's release age, or pnpm would install
+   the previous one);
+4. runs `init --update`, `migrate` and `doctor` through the package that was just installed.
+
+`--dry-run` stops after step 2. `--version` pins a release; `upgrade` never downgrades.
+
+Every `asrun` command also checks the registry for a newer release, at most once a day (the answer is cached in `.tmp/`
+and shared with the web UI), and prints one line on stderr before it starts:
+`@asrunjs/asrun 0.8.0 is available (installed 0.7.0). Upgrade: pnpm asrun upgrade`. On a terminal the line carries an
+`UPDATE` badge and highlights the version and the command; a pipe or a log gets the plain sentence. Inside the
+framework's own git checkout the line names `git pull` instead, because there is no installed package to upgrade. A
+failed check is silent. Set `ASRUN_NO_UPDATE_CHECK=1` to switch it off; `NO_COLOR` and `FORCE_COLOR` decide the colors
+as they do everywhere else.
+
+### Migrations
+
+A migration is a change an existing workspace must make when the framework moves it forward: 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. The registry is `migrations/index.ts` in the framework package, and the state
+lives in `.asrun.json`:
+
+```json
+"migrations": {"since": "0.7.0", "manual": ["0.8.0-rename-..."]}
+```
+
+`since` is the release the workspace matches. It only moves forward when a migration succeeds, so an interrupted run
+can simply be repeated. A migration marked `auto` runs by itself; one with `manual` steps is printed and remembered
+until a person does it and acknowledges it. `init --update` never advances the baseline, which is why a manual
+`pnpm add -D @asrunjs/asrun@latest` followed by `pnpm asrun init --update` still leaves its migrations pending.
+
+```bash
+pnpm asrun migrate              # apply what the installed release brings
+pnpm asrun migrate --dry-run    # show it, change nothing
+pnpm asrun migrate --list       # every migration of the installed release, and its state
+pnpm asrun migrate --ack <id>   # a manual step is done (--ack-all for every one)
+pnpm asrun migrate --to <v>     # stop at that release
+```
+
+`migrate` never installs anything, and refuses to migrate beyond the installed release: the code that applies a
+migration is the installed package. `doctor` warns while migrations or manual steps are outstanding.
+
 ## Workspace
 
 ```bash
-pnpm asrun init [--update] [--force] [--force <file>] [--reset-rules] [--root <dir>] [--no-env] [--install [spec]]
+pnpm asrun init [--update] [--force] [--force <file>] [--reset-rules] [--root <dir>] [--no-env] [--no-extras] [--install [spec]]
 pnpm asrun doctor
+pnpm asrun upgrade [--version <v>] [--dry-run] [--yes]
+pnpm asrun migrate [--list] [--dry-run] [--yes] [--ack <id>|--ack-all]
 pnpm asrun reset [--root <dir>] [--dry-run] [--yes] [--state] [--lockfile]
 ```
 
 `init` writes the workspace files; `--update` refreshes only the generated ones, and `--force` rewrites every file
 init writes (a single file with `--force <file>`). `--force` still keeps `profiles.yaml` and `package.json`; name
-`--force profiles.yaml` to replace profiles, and add `--reset-rules` to replace `AGENTS.md` or `CLAUDE.md`.
+`--force profiles.yaml` to replace profiles, and add `--reset-rules` to replace `AGENTS.md` or `CLAUDE.md`. It also
+adds the `allowBuilds` entries `pnpm-workspace.yaml` lacks, and installs the optional packages this machine lacks
+(`ffmpeg-static`; `--no-extras` skips them).
 `doctor` checks profiles, `tsconfig.json`, `playwright.config.ts`, the generated files, the installed version, the
-project rule table and the skill overrides.
+project rule table, the skill overrides and the workspace migrations. `upgrade` and `migrate` are described above.
 
 `reset` removes `node_modules` and the files `init` writes, for a clean reinstall. It deletes a once-only file only
 when it is still identical to its template, so edited files stay; `cases/`, specs, baselines, `profiles.yaml`,