@asrunjs/asrun 0.6.1 → 0.8.0

package/dist/scripts/reset.js

@@ -0,0 +1,233 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import readline from 'node:readline/promises';
+import { FRAMEWORK_ROOT, ROOT } from '../lib/paths.js';
+import { DOTENV_HEADER, GENERATED, MARKER, ONCE, PACKAGE, renderTemplate } from './init.js';
+/**
+ * `pnpm asrun reset`: removes the installed dependencies and the files `init` wrote, so the workspace can be
+ * scaffolded again from scratch (`pnpm dlx @asrunjs/asrun init --install`). It never deletes the project's own
+ * content: cases, specs, profiles.yaml, package.json, skill overrides and scaffold files the project edited stay.
+ */
+const USAGE = `Usage: pnpm asrun reset [--root <dir>] [--dry-run] [--yes] [--state] [--lockfile]
+
+  --root <dir>  the workspace to reset (default: the current workspace)
+  --dry-run     list what would be removed, and change nothing
+  --yes         skip the confirmation prompt (for unattended runs)
+  --state       also remove local state: .auth/, reports/, .tmp/, .explore/, test-results/,
+                playwright-report/, .playwright-mcp/
+  --lockfile    also remove pnpm-lock.yaml
+
+Always removed: node_modules/ and the files init writes (the generated config/commands, .asrun.json, the asrun block
+of .gitignore, the ASRUN_ROOT line of .env). A file init writes is kept when the project edited it; profiles.yaml and
+package.json always stay.`;
+/** Local state, never committed: removed only with `--state`, because `.auth/` means logging in again. */
+const STATE_DIRS = ['.auth', 'reports', '.tmp', '.explore', 'test-results', 'playwright-report', '.playwright-mcp'];
+/** The block `init` writes into `.gitignore` (see `templates/gitignore`). */
+const ASRUN_BLOCK = /# >>> asrun[\s\S]*?# <<< asrun\r?\n?/;
+function samePath(left, right) {
+    const a = path.resolve(left);
+    const b = path.resolve(right);
+    return process.platform === 'win32' ? a.toLowerCase() === b.toLowerCase() : a === b;
+}
+function isInside(dir, parent) {
+    const relative = path.relative(path.resolve(parent), path.resolve(dir));
+    return relative !== '' && !relative.startsWith('..') && !path.isAbsolute(relative);
+}
+function isAsrunEnvLine(line) {
+    return line.trim() === DOTENV_HEADER || /^\s*(?:export\s+)?ASRUN_ROOT\s*=/.test(line);
+}
+/** Removes the asrun block; deletes the file when nothing else was in it. */
+function cleanGitignore(file) {
+    const text = fs.readFileSync(file, 'utf8');
+    const next = text.replace(ASRUN_BLOCK, '').trimEnd();
+    if (next === '')
+        fs.rmSync(file, { force: true });
+    else
+        fs.writeFileSync(file, `${next}\n`);
+}
+/** Removes the asrun header and the ASRUN_ROOT line; deletes the file when nothing else was in it. */
+function cleanDotEnv(file) {
+    const lines = fs
+        .readFileSync(file, 'utf8')
+        .split(/\r?\n/)
+        .filter((line) => !isAsrunEnvLine(line));
+    const next = lines.join('\n').replace(/\n{3,}/g, '\n\n').trimEnd();
+    if (next === '')
+        fs.rmSync(file, { force: true });
+    else
+        fs.writeFileSync(file, `${next}\n`);
+}
+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;
+    };
+    const root = path.resolve(value('--root') ?? ROOT);
+    const dryRun = args.includes('--dry-run');
+    const yes = args.includes('--yes');
+    const includeState = args.includes('--state');
+    const includeLockfile = args.includes('--lockfile');
+    if (samePath(root, FRAMEWORK_ROOT) || isInside(root, FRAMEWORK_ROOT)) {
+        console.error(`Refusing to reset ${root}: it is (inside) the framework's own checkout, not a workspace that installed asrun. ` +
+            'Run this command in the project that uses asrun, or pass --root <dir>.');
+        return 1;
+    }
+    if (![MARKER, 'profiles.yaml'].some((marker) => fs.existsSync(path.join(root, marker)))) {
+        console.error(`No workspace at ${root}: neither ${MARKER} nor profiles.yaml is there. ` +
+            'Point --root at the project that uses asrun.');
+        return 1;
+    }
+    const planned = [];
+    const keptEdited = [];
+    const leftInPlace = [];
+    const fileItem = (relative) => {
+        const target = path.join(root, relative);
+        if (!fs.existsSync(target))
+            return null;
+        return { label: relative, apply: () => fs.rmSync(target, { force: true }) };
+    };
+    const dirItem = (relative) => {
+        const target = path.join(root, relative);
+        if (!fs.existsSync(target))
+            return null;
+        return {
+            label: `${relative}/`,
+            apply: () => fs.rmSync(target, { recursive: true, force: true, maxRetries: 3, retryDelay: 100 }),
+        };
+    };
+    // The installed dependencies (the framework included), so `pnpm install` starts from nothing.
+    const deps = dirItem('node_modules');
+    if (deps)
+        planned.push(deps);
+    const lockfile = path.join(root, 'pnpm-lock.yaml');
+    if (fs.existsSync(lockfile)) {
+        if (includeLockfile)
+            planned.push({ label: 'pnpm-lock.yaml', apply: () => fs.rmSync(lockfile, { force: true }) });
+        else
+            leftInPlace.push('pnpm-lock.yaml (remove with --lockfile)');
+    }
+    // The files `init` generates, always rewritten by the next `init`.
+    for (const entry of GENERATED) {
+        const item = fileItem(entry.file);
+        if (item)
+            planned.push(item);
+    }
+    // The files `init` creates once. Only a file still identical to its template is the scaffold's; an edited file
+    // (AGENTS.md with project rules, a customized tsconfig.json) belongs to the project and stays.
+    for (const entry of ONCE) {
+        // The manifest is the project's own even when init created it: init only merges the scripts and devDependencies.
+        if (entry.file === 'package.json')
+            continue;
+        const target = path.join(root, entry.file);
+        if (!fs.existsSync(target))
+            continue;
+        let unchanged = false;
+        try {
+            unchanged = fs.readFileSync(target, 'utf8') === renderTemplate(entry.template, root);
+        }
+        catch {
+            // Unreadable: treat it as the project's and leave it alone.
+        }
+        if (unchanged)
+            planned.push({ label: entry.file, apply: () => fs.rmSync(target, { force: true }) });
+        else
+            keptEdited.push(entry.file);
+    }
+    const marker = fileItem(MARKER);
+    if (marker)
+        planned.push(marker);
+    const gitignore = path.join(root, '.gitignore');
+    if (fs.existsSync(gitignore) && ASRUN_BLOCK.test(fs.readFileSync(gitignore, 'utf8'))) {
+        planned.push({ label: '.gitignore (the asrun block)', apply: () => cleanGitignore(gitignore) });
+    }
+    const dotenv = path.join(root, '.env');
+    if (fs.existsSync(dotenv) && fs.readFileSync(dotenv, 'utf8').split(/\r?\n/).some(isAsrunEnvLine)) {
+        planned.push({ label: '.env (the asrun lines)', apply: () => cleanDotEnv(dotenv) });
+    }
+    for (const relative of STATE_DIRS) {
+        const target = path.join(root, relative);
+        if (!fs.existsSync(target))
+            continue;
+        if (includeState) {
+            const item = dirItem(relative);
+            if (item)
+                planned.push(item);
+        }
+        else {
+            leftInPlace.push(`${relative}/ (remove with --state)`);
+        }
+    }
+    if (planned.length === 0) {
+        console.log(`Nothing to reset in ${root}.`);
+        if (keptEdited.length > 0)
+            console.log(`Kept (edited by the project): ${keptEdited.join(', ')}`);
+        for (const note of leftInPlace)
+            console.log(`Left in place: ${note}`);
+        return 0;
+    }
+    console.log(`Workspace: ${root}`);
+    console.log(dryRun ? '\nWould remove:' : '\nThis removes:');
+    for (const item of planned)
+        console.log(`  - ${item.label}`);
+    if (keptEdited.length > 0)
+        console.log(`\nKept (edited by the project): ${keptEdited.join(', ')}`);
+    for (const note of leftInPlace)
+        console.log(`Left in place: ${note}`);
+    if (includeState && fs.existsSync(path.join(root, '.auth'))) {
+        console.log('\n! .auth/ goes too: every profile must be signed in again.');
+    }
+    if (dryRun) {
+        console.log('\nNothing was removed (--dry-run).');
+        return 0;
+    }
+    if (!yes) {
+        if (!process.stdin.isTTY || !process.stdout.isTTY) {
+            console.error('\nRefusing to remove anything: there is no terminal to confirm in. A person adds --yes to do it.');
+            return 1;
+        }
+        const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+        const answer = (await rl.question('\nType "yes" to remove them: ')).trim().toLowerCase();
+        rl.close();
+        if (answer !== 'yes') {
+            console.error('Cancelled. Nothing was removed.');
+            return 1;
+        }
+    }
+    let failed = 0;
+    const removed = [];
+    for (const item of planned) {
+        try {
+            item.apply();
+            removed.push(item.label);
+        }
+        catch (error) {
+            failed += 1;
+            console.error(`  ! ${item.label}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    // Folders the removals left empty (a workspace with no cases, or no project overrides) are part of the scaffold too.
+    for (const relative of ['cases', 'tests', '.claude/commands', '.opencode/commands', '.claude', '.opencode']) {
+        const target = path.join(root, relative);
+        try {
+            if (fs.existsSync(target) && fs.readdirSync(target).length === 0) {
+                fs.rmdirSync(target);
+                removed.push(`${relative}/`);
+            }
+        }
+        catch {
+            // not empty, or in use: leave it
+        }
+    }
+    if (failed > 0) {
+        console.error(`\n${failed} item(s) could not be removed (a file may be in use). Close what uses the workspace and run ` +
+            '"pnpm asrun reset" again.');
+        return 1;
+    }
+    console.log(`\nRemoved ${removed.length} item(s).`);
+    console.log(`\nNext:\n  pnpm dlx ${PACKAGE} init --install\n  pnpm go`);
+    return 0;
+}

package/dist/scripts/run.js

@@ -12,29 +12,29 @@ import { describeLeftovers, findLeftovers } from '../lib/records.js';
 import { filterArgs } from '../lib/run-filters.js';
 import { ALLOW_WRITES_ENV, describeSkippedWriteCases, describeWriteCases, findWriteCases, isProtectedEnv, planRun, } from '../lib/write-gate.js';
 import { checkSession, formatNotLoggedIn, NOT_LOGGED_IN_ENV, skipProfileHint, } from '../lib/session.js';
-const USAGE = `Usage: pnpm asrun --env <env> [--profile a,b] [--skip-profile a,b] [--tag name] [--logged-in] [--suite name] [--grep text] [--read-only] [--allow-writes=<env>] [--update-baselines <case,case>] [--report-id <id>] [playwright options...]
-
-  --env is required and has no default (the environments are listed in profiles.yaml, e.g. production, staging).
-
-  pnpm asrun --env staging            all profiles, all cases
-  pnpm asrun --env production --profile example-production    one profile
-  pnpm asrun --env production --skip-profile example-production    all profiles except these
-  pnpm asrun --env production --tag us             only the profiles that carry the tag "us"
-  pnpm asrun --env production --logged-in         only the profiles that are logged in (the others are left out, not failed)
-  pnpm asrun --env production --suite smoke       only cases whose front matter lists "smoke" under "suites"
-                                         (comma-separated for several: --suite smoke,regression; a case in
-                                         both runs once). --priority is the old name of --suite.
-  pnpm asrun --env production --read-only         leave out the cases that write data (front matter "writes")
-  pnpm asrun --env production --allow-writes=production run cases that write data in production WITHOUT the prompt. For
-                                         people running unattended; AI agents must never add this flag.
-  pnpm asrun --env production --grep landing      one case (matches the test title)
-  pnpm asrun --env staging --grep documents --update-baselines documents/landing-page
-                                         run the chosen cases as usual, except the listed ones: those are run separately
-                                         and their screenshot baselines are overwritten with what the page shows now
-                                         (--update-snapshots=all). Look at the new images afterwards:
-                                         pnpm baselines:review <case-id>
-  pnpm asrun --env staging --ui       interactive mode
-  pnpm asrun --env production --step-text   overlay the current test step on the videos
+const USAGE = `Usage: pnpm asrun --env <env> [--profile a,b] [--skip-profile a,b] [--tag name] [--logged-in] [--suite name] [--grep text] [--read-only] [--allow-writes=<env>] [--update-baselines <case,case>] [--report-id <id>] [playwright options...]
+
+  --env is required and has no default (the environments are listed in profiles.yaml, e.g. production, staging).
+
+  pnpm asrun --env staging            all profiles, all cases
+  pnpm asrun --env production --profile example-production    one profile
+  pnpm asrun --env production --skip-profile example-production    all profiles except these
+  pnpm asrun --env production --tag us             only the profiles that carry the tag "us"
+  pnpm asrun --env production --logged-in         only the profiles that are logged in (the others are left out, not failed)
+  pnpm asrun --env production --suite smoke       only cases whose front matter lists "smoke" under "suites"
+                                         (comma-separated for several: --suite smoke,regression; a case in
+                                         both runs once). --priority is the old name of --suite.
+  pnpm asrun --env production --read-only         leave out the cases that write data (front matter "writes")
+  pnpm asrun --env production --allow-writes=production run cases that write data in production WITHOUT the prompt. For
+                                         people running unattended; AI agents must never add this flag.
+  pnpm asrun --env production --grep landing      one case (matches the test title)
+  pnpm asrun --env staging --grep documents --update-baselines documents/landing-page
+                                         run the chosen cases as usual, except the listed ones: those are run separately
+                                         and their screenshot baselines are overwritten with what the page shows now
+                                         (--update-snapshots=all). Look at the new images afterwards:
+                                         pnpm baselines:review <case-id>
+  pnpm asrun --env staging --ui       interactive mode
+  pnpm asrun --env production --step-text   overlay the current test step on the videos
                                          (also --step-text=1|true|yes|on; off by default; 0|false|no|off disables)`;
 const TRUE_VALUES = ['1', 'true', 'yes', 'on'];
 const FALSE_VALUES = ['0', 'false', 'no', 'off'];
@@ -147,7 +147,8 @@ const knownEnvs = listEnvs(allProfiles);
 const listOnly = passthrough.includes('--list');
 if (!env && !listOnly) {
     console.error(`Choose the environment to test: --env <env>  (${knownEnvs.join(' | ')}). There is no default.\n` +
-        `Example: pnpm asrun --env ${knownEnvs.includes('staging') ? 'staging' : (knownEnvs[0] ?? '<env>')}`);
+        `Example: pnpm asrun --env ${knownEnvs.includes('staging') ? 'staging' : (knownEnvs[0] ?? '<env>')}\n` +
+        'All options: pnpm asrun --help. To check the installation instead: pnpm asrun doctor');
     process.exit(1);
 }
 if (env && !knownEnvs.includes(env)) {

package/dist/scripts/upgrade.d.ts

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

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;