@asrunjs/asrun 0.7.0 → 0.8.0

package/AGENTS.md

@@ -151,9 +151,12 @@ Three steps, each learns one thing: the intent, the facts and inputs, the implem
    writes data and never creates baselines. A tagged step with no `- Recipe:` line (an old `## Inputs` line counts
    until it is moved) stops with `needs-input`: run `/explore-case` first. Running specs is a separate step
    (`pnpm asrun`, or the Run page).
-Workspace maintenance is separate from the AI steps: `pnpm asrun init [--update] [--force]` writes or refreshes the
-workspace files, and `pnpm asrun reset` removes `node_modules` and the files init wrote (edited files, cases, specs,
-`profiles.yaml` and `package.json` stay), so `pnpm dlx @asrunjs/asrun init --install` can scaffold again.
+Workspace maintenance is separate from the AI steps: `pnpm asrun upgrade` installs the newest framework, refreshes the
+generated files and applies the release's workspace migrations (it checks the target release for breaking changes
+before installing), `pnpm asrun init [--update] [--force]` writes or refreshes the workspace files, `pnpm asrun
+migrate` applies only the migrations (for a manual install), and `pnpm asrun reset` removes `node_modules` and the
+files init wrote (edited files, cases, specs, `profiles.yaml` and `package.json` stay), so
+`pnpm dlx @asrunjs/asrun init --install` can scaffold again.
 Do not hand-write specs unless asked. Do not edit `lib/` to make a single spec pass.
 Every case step is wrapped in `test.step('<n>. <case step text>', ...)` so reports and traces show the
 case's own steps (see the skill's `references/conventions.md`).

package/README.md

@@ -31,8 +31,8 @@ AsRun is a devDependency, not a service. Your profiles, cases, specs and baselin
 
 - **Node.js 22+** and **pnpm**.
 - **ffmpeg** to join the recordings of one test into a video. `pnpm go` installs it with Homebrew or winget; on Linux
-  run `sudo apt install ffmpeg`. When it is missing, the bundled `ffmpeg-static` is used; if neither works, the report
-  lists the videos separately.
+  run `sudo apt install ffmpeg`. When it is missing, `pnpm go` / `pnpm asrun init` install the bundled `ffmpeg-static`
+  into the workspace; if neither works, the report lists the videos separately.
 - **Claude Code** or **OpenCode** for the AI steps. Everything else works without them.
 
 ## Install
@@ -50,14 +50,18 @@ first time, `pnpm go` is enough.
 To update:
 
 ```bash
-pnpm add -D @asrunjs/asrun@latest
-pnpm asrun init --update
-pnpm asrun doctor
+pnpm asrun upgrade
 ```
 
-`init --update` refreshes only the generated files; it never overwrites `AGENTS.md`, `CLAUDE.md` or your skill
-overrides. `doctor` checks profiles, generated files, the installed version and the project rules. `init --force`
-rewrites every file init writes (rules still need `--reset-rules`; `profiles.yaml` and `package.json` stay yours).
+It checks the new release for breaking changes and migrations before installing it, installs it, refreshes the
+generated files, applies the migrations and runs `doctor`. `--dry-run` shows the plan and changes nothing. A workspace
+that predates `upgrade` updates once by hand: `pnpm add -D @asrunjs/asrun@latest`, `pnpm asrun init --update`,
+`pnpm asrun migrate`, `pnpm asrun doctor`.
+
+`init --update` alone refreshes only the generated files; it never overwrites `AGENTS.md`, `CLAUDE.md` or your skill
+overrides. `doctor` checks profiles, generated files, the installed version, the migrations and the project rules.
+`init --force` rewrites every file init writes (rules still need `--reset-rules`; `profiles.yaml` and `package.json`
+stay yours).
 
 To start over with fresh dependencies and a fresh scaffold:
 
@@ -79,9 +83,9 @@ pnpm asrun init
 pnpm go
 ```
 
-On pnpm 12, run `init` before adding the dependency: it writes the `allowBuilds` entry that `esbuild` and
-`ffmpeg-static` need, or `pnpm add` stops with `ERR_PNPM_IGNORED_BUILDS`. The same file exempts `@asrunjs/asrun` from
-pnpm's 24-hour release age, so a fresh release installs right away. Details and flags:
+On pnpm 12, run `init` before adding the dependency: it writes the `allowBuilds` entry `esbuild` needs, and the entry
+of each optional package it installs on demand, or `pnpm add` stops with `ERR_PNPM_IGNORED_BUILDS`. The same file
+exempts `@asrunjs/asrun` from pnpm's 24-hour release age, so a fresh release installs right away. Details and flags:
 [install.md](./docs/install.md).
 
 </details>
@@ -147,6 +151,7 @@ Details: [ai-workflow.md](./docs/ai-workflow.md#customizing-the-prompts).
 
 | I want to... | Command |
 |---|---|
+| Upgrade the framework and migrate the workspace | `pnpm asrun upgrade` |
 | Check the workspace | `pnpm asrun doctor` |
 | Start over with fresh dependencies and scaffold | `pnpm asrun reset [--yes] [--state] [--lockfile]` |
 | See which profiles are logged in | `pnpm status [--env <env>]` |
@@ -175,6 +180,11 @@ editor, form panel, spec view, AI runs, notes-to-cases), **Run tests** (filters,
 confirmation), **Reports** (failure first, then video, screenshots, trace, full Playwright report), **Jobs** (live log
 of every command), **Help** and **AI guide**. See [web-ui.md](./docs/web-ui.md).
 
+Every `asrun` command, and the web UI (at startup and once a day at 00:00 UTC), ask the registry whether a newer release
+exists and, at most once a day and only if so, say which version and how to get it: `pnpm asrun upgrade`, or the badge in
+the top bar. The check never blocks a command and stays quiet when the registry cannot be reached; set
+`ASRUN_NO_UPDATE_CHECK=1` to switch it off.
+
 ## Safety
 
 Tests run against real sites, so the defaults are strict:

package/bin/asrun.mjs

@@ -3,7 +3,7 @@
 import {spawn} from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
-import {fileURLToPath} from 'node:url';
+import {fileURLToPath, pathToFileURL} from 'node:url';
 
 const FRAMEWORK = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 const DIST = path.join(FRAMEWORK, 'dist');
@@ -14,6 +14,8 @@ const SCRIPTS = {
   init: 'cli.js',
   doctor: 'cli.js',
   reset: 'cli.js',
+  upgrade: 'cli.js',
+  migrate: 'cli.js',
   go: 'go.mjs',
   ui: 'ui.js',
   'ui:dev': 'ui-dev.js',
@@ -40,8 +42,22 @@ if (!fs.existsSync(script)) {
   process.exit(1);
 }
 
-// `init`, `doctor` and `reset` are subcommands of cli.js; it reads them from its own arguments.
+// `init`, `doctor`, `reset`, `upgrade` and `migrate` are subcommands of cli.js; it reads them from its own arguments.
 const cliArgs = scriptName === 'cli.js' && subcommand ? [subcommand, ...args] : args;
+
+// A newer release on the registry gets one line on stderr before the command starts. The check reads `.tmp/` and asks
+// the registry at most once a day; it is silent on any failure. The scripts of `cli.js` show the notice themselves (a
+// framework checkout's `pnpm asrun` goes straight there), `upgrade` reads the registry itself, and both UI servers print
+// the notice from their own process, so all of them are left alone. An older install has no such file: the import fails.
+if (scriptName !== 'cli.js' && !['ui', 'ui:dev', 'help', '--help-init'].includes(subcommand ?? args[0] ?? '')) {
+  try {
+    const {announceUpdate} = await import(pathToFileURL(path.join(DIST, 'lib', 'update-check.js')).href);
+    announceUpdate();
+  } catch {
+    // Nothing to check with, or nothing to report.
+  }
+}
+
 const child = spawn(process.execPath, [script, ...cliArgs], {cwd: process.cwd(), stdio: 'inherit'});
 child.on('error', (error) => {
   console.error(`Could not start asrun: ${error.message}`);

package/dist/lib/ffmpeg.js

@@ -3,22 +3,33 @@ import fs from 'node:fs';
 import { createRequire } from 'node:module';
 import os from 'node:os';
 import path from 'node:path';
+import { ROOT } from './paths.js';
 let cached;
+/**
+ * The binary of `ffmpeg-static`: a devDependency of the workspace that `init`/`go` installed on demand. Resolved from
+ * the workspace first (where it lives), then from the framework's own install (a development checkout, or a hoisted
+ * dependency).
+ */
+function bundledFfmpeg() {
+    for (const anchor of [path.join(ROOT, 'package.json'), import.meta.url]) {
+        try {
+            const bundled = createRequire(anchor)('ffmpeg-static');
+            if (bundled && fs.existsSync(bundled))
+                return bundled;
+        }
+        catch {
+            // Not installed here: try the next place, then fall back to no ffmpeg at all.
+        }
+    }
+    return null;
+}
 /** The system `ffmpeg` if there is one, else the binary of the optional `ffmpeg-static` package, else null. */
 export function findFfmpeg() {
     if (cached !== undefined)
         return cached;
     if (spawnSync('ffmpeg', ['-version'], { stdio: 'ignore' }).status === 0)
         return (cached = 'ffmpeg');
-    try {
-        const bundled = createRequire(import.meta.url)('ffmpeg-static');
-        if (bundled && fs.existsSync(bundled))
-            return (cached = bundled);
-    }
-    catch {
-        // ffmpeg-static is optional and may not be installed.
-    }
-    return (cached = null);
+    return (cached = bundledFfmpeg());
 }
 /**
  * Joins `inputs` (in order) into one webm at `output`. Re-encodes on purpose: Playwright's recordings have loose
@@ -28,7 +39,7 @@ export function findFfmpeg() {
 export function concatVideos(inputs, output) {
     const ffmpeg = findFfmpeg();
     if (!ffmpeg)
-        return 'ffmpeg not found (install ffmpeg or the optional ffmpeg-static package)';
+        return 'ffmpeg not found (install ffmpeg, or run "pnpm asrun init" to install the bundled ffmpeg-static)';
     fs.mkdirSync(path.dirname(output), { recursive: true });
     const listDir = fs.mkdtempSync(path.join(os.tmpdir(), 'asrun-concat-'));
     const list = path.join(listDir, 'inputs.txt');

package/dist/lib/migrations.d.ts

@@ -0,0 +1,106 @@
+/**
+ * Workspace migrations: the changes an existing workspace must make when the framework moves it from an older
+ * release to a newer one (the registry is `migrations/index.ts`, the procedure is in `docs/agents/framework-dev.md`).
+ *
+ * The same entries are published as `dist/migrations/manifest.json`. A still-old `pnpm asrun upgrade` reads that file
+ * out of the target release *before* it installs it, so the manifest holds data only: never a function.
+ */
+/** What a migration receives while it runs, after the new release is installed. */
+export interface MigrationContext {
+    /** the workspace root (the project that owns `profiles.yaml`) */
+    root: string;
+    /** the installed package folder of the framework */
+    frameworkRoot: string;
+    /** the version the workspace was last migrated from (`migrations.since` in `.asrun.json`) */
+    from: string;
+    /** the installed version the workspace is being migrated to */
+    to: string;
+    /** one line of progress for the person running the command */
+    log: (text: string) => void;
+}
+/**
+ * One change an existing workspace must make. Append one to `MIGRATIONS`; never delete an entry, because a workspace
+ * on any older release may still need it.
+ */
+export interface Migration {
+    /** stable and unique: `<version>-<slug>`, for example `0.9.0-pnpm-release-age` */
+    id: string;
+    /** the release that introduced the change; workspaces older than this get the migration */
+    version: string;
+    /** one line for the person, in the release plan before the install and in the migration output after it */
+    summary: string;
+    /** true when the change can break an existing workspace, so `upgrade` asks before installing */
+    breaking?: boolean;
+    /** which workspaces the change matters for, in words, for the pre-install report */
+    appliesTo?: string;
+    /** what changes, and why, when the summary is not enough */
+    details?: string;
+    /** steps only a person can do; they are printed and remembered until they are acknowledged */
+    manual?: string[];
+    /** true when the migration runs without asking after the install; the command still prints what it did */
+    auto?: boolean;
+    /** true when the workspace already looks migrated; a false answer skips `apply` */
+    detect?: (context: MigrationContext) => boolean;
+    /** the change itself; must be idempotent and only touch what the migration describes */
+    apply?: (context: MigrationContext) => void | Promise<void>;
+}
+/** A migration as it travels in `dist/migrations/manifest.json`: the same entry without its code. */
+export type MigrationManifestEntry = Omit<Migration, 'detect' | 'apply'>;
+/**
+ * The migration state of a workspace, recorded in `.asrun.json`. `since` is the release the workspace was last
+ * migrated from, so only newer entries apply. It survives `init --update`, which is what keeps a manual
+ * `pnpm add -D @asrunjs/asrun@latest` from erasing what still has to be done.
+ */
+export interface MigrationState {
+    since: string;
+    /** ids of migrations whose manual steps were reported and not acknowledged with `migrate --ack` yet */
+    manual: string[];
+}
+/** The part of `.asrun.json` this module reads. The rest belongs to `init`. */
+export interface WorkspaceMarker {
+    version?: unknown;
+    migrations?: {
+        since?: unknown;
+        manual?: unknown;
+    };
+    [key: string]: unknown;
+}
+/** Where `pnpm build` writes the manifest, relative to the package root. */
+export declare const MANIFEST_FILE = "dist/migrations/manifest.json";
+/** The same file inside an npm tarball, which prefixes every path with `package/`. */
+export declare const MANIFEST_ENTRY = "package/dist/migrations/manifest.json";
+/** True when the text is a version a migration can be ordered by (`x.y.z`, an optional leading `v`, a prerelease). */
+export declare function isVersion(value: string): boolean;
+/**
+ * Orders two versions: negative when `left` is older, positive when it is newer, 0 when they are equal. A prerelease
+ * sorts before its release (`1.0.0-beta` < `1.0.0`). Throws on text that is not a version: a migration with a bad
+ * `version` is a mistake, not something to guess about.
+ */
+export declare function compareVersions(left: string, right: string): number;
+/** Anything a migration list can be filtered by: a registry entry or a manifest entry. */
+export interface VersionedMigration {
+    id: string;
+    version: string;
+}
+/**
+ * The entries that apply to a workspace moved from `since` to `to`: strictly newer than `since`, at or before `to`, in
+ * version order (id order for two entries of the same version). Both bounds are inclusive/exclusive on purpose:
+ * `since` is the release the workspace already matches, `to` is the release being installed.
+ */
+export declare function pendingMigrations<T extends VersionedMigration>(entries: readonly T[], since: string, to: string): T[];
+/** The manifest of a registry: the same entries, without the code that cannot travel in JSON. */
+export declare function toManifest(entries: readonly Migration[]): MigrationManifestEntry[];
+/** The marker of a workspace, or null when the file is missing or not a JSON object. */
+export declare function readMarker(root: string): WorkspaceMarker | null;
+/**
+ * The migration state of a workspace. A marker written before migrations existed (or by a workspace that was never
+ * initialized) has no `migrations` block: its recorded `version` is then the baseline, and a workspace with neither
+ * starts at the installed version, so no historical entry runs on it.
+ */
+export declare function migrationState(marker: WorkspaceMarker | null, installedVersion: string): MigrationState;
+/**
+ * Writes the migration state back into the marker and keeps every other field (init writes the rest). The workspace
+ * must already have a marker: `migrate` says so instead of creating one, because a workspace that was never
+ * initialized has no release to migrate from.
+ */
+export declare function writeMigrationState(root: string, state: MigrationState): void;

package/dist/lib/migrations.js

@@ -0,0 +1,106 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { MARKER } from './paths.js';
+/** Where `pnpm build` writes the manifest, relative to the package root. */
+export const MANIFEST_FILE = 'dist/migrations/manifest.json';
+/** The same file inside an npm tarball, which prefixes every path with `package/`. */
+export const MANIFEST_ENTRY = `package/${MANIFEST_FILE}`;
+const VERSION = /^v?(\d+)(?:\.(\d+))?(?:\.(\d+))?(?:-([0-9A-Za-z.-]+))?$/;
+function parseVersion(value) {
+    const match = VERSION.exec(value.trim());
+    if (match === null)
+        return null;
+    return {
+        core: [Number(match[1]), Number(match[2] ?? 0), Number(match[3] ?? 0)],
+        pre: match[4] ?? '',
+    };
+}
+/** True when the text is a version a migration can be ordered by (`x.y.z`, an optional leading `v`, a prerelease). */
+export function isVersion(value) {
+    return parseVersion(value) !== null;
+}
+/**
+ * Orders two versions: negative when `left` is older, positive when it is newer, 0 when they are equal. A prerelease
+ * sorts before its release (`1.0.0-beta` < `1.0.0`). Throws on text that is not a version: a migration with a bad
+ * `version` is a mistake, not something to guess about.
+ */
+export function compareVersions(left, right) {
+    const a = parseVersion(left);
+    const b = parseVersion(right);
+    if (a === null)
+        throw new Error(`"${left}" is not a version`);
+    if (b === null)
+        throw new Error(`"${right}" is not a version`);
+    for (let index = 0; index < a.core.length; index++) {
+        if (a.core[index] !== b.core[index])
+            return a.core[index] - b.core[index];
+    }
+    if (a.pre === b.pre)
+        return 0;
+    if (a.pre === '')
+        return 1;
+    if (b.pre === '')
+        return -1;
+    return a.pre < b.pre ? -1 : 1;
+}
+/**
+ * The entries that apply to a workspace moved from `since` to `to`: strictly newer than `since`, at or before `to`, in
+ * version order (id order for two entries of the same version). Both bounds are inclusive/exclusive on purpose:
+ * `since` is the release the workspace already matches, `to` is the release being installed.
+ */
+export function pendingMigrations(entries, since, to) {
+    return entries
+        .filter((entry) => compareVersions(entry.version, since) > 0 && compareVersions(entry.version, to) <= 0)
+        .sort((a, b) => compareVersions(a.version, b.version) || a.id.localeCompare(b.id));
+}
+/** The manifest of a registry: the same entries, without the code that cannot travel in JSON. */
+export function toManifest(entries) {
+    return entries.map(({ id, version, summary, breaking, appliesTo, details, manual, auto }) => ({
+        id,
+        version,
+        summary,
+        ...(breaking !== undefined && { breaking }),
+        ...(appliesTo !== undefined && { appliesTo }),
+        ...(details !== undefined && { details }),
+        ...(manual !== undefined && { manual }),
+        ...(auto !== undefined && { auto }),
+    }));
+}
+/** The marker of a workspace, or null when the file is missing or not a JSON object. */
+export function readMarker(root) {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(path.join(root, MARKER), 'utf8'));
+        return parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * The migration state of a workspace. A marker written before migrations existed (or by a workspace that was never
+ * initialized) has no `migrations` block: its recorded `version` is then the baseline, and a workspace with neither
+ * starts at the installed version, so no historical entry runs on it.
+ */
+export function migrationState(marker, installedVersion) {
+    const recorded = marker?.migrations;
+    const since = typeof recorded?.since === 'string' && isVersion(recorded.since)
+        ? recorded.since
+        : typeof marker?.version === 'string' && isVersion(marker.version)
+            ? marker.version
+            : installedVersion;
+    const manual = Array.isArray(recorded?.manual)
+        ? recorded.manual.filter((id) => typeof id === 'string')
+        : [];
+    return { since, manual: [...new Set(manual)] };
+}
+/**
+ * Writes the migration state back into the marker and keeps every other field (init writes the rest). The workspace
+ * must already have a marker: `migrate` says so instead of creating one, because a workspace that was never
+ * initialized has no release to migrate from.
+ */
+export function writeMigrationState(root, state) {
+    const file = path.join(root, MARKER);
+    const marker = readMarker(root) ?? {};
+    marker.migrations = { since: state.since, manual: [...new Set(state.manual)] };
+    fs.writeFileSync(file, JSON.stringify(marker, null, 2) + '\n');
+}

package/dist/lib/paths.d.ts

@@ -1,4 +1,13 @@
 export declare const FRAMEWORK_ROOT: string;
+/** The manifest `init` writes: framework version, migration baseline and the generated file list. */
+export declare const MARKER = ".asrun.json";
+/** The published framework package: the dependency a workspace installs and the name the registry is asked for. */
+export declare const PACKAGE = "@asrunjs/asrun";
+/**
+ * True in the framework's own repository, where the framework is a git checkout rather than an installed package. Such a
+ * checkout has no registry install to upgrade: `upgrade` refuses to run there and the release check suggests git.
+ */
+export declare function isRepoCheckout(): boolean;
 /**
  * The workspace root: the project that uses the framework. Everything the framework reads or writes for a project
  * (`profiles.yaml`, `cases/`, `tests/`, `.auth/`, `reports/`, `.tmp/`) is relative to it.

package/dist/lib/paths.js

@@ -38,8 +38,19 @@ function loadEnvFile(file) {
 loadEnvFile(path.join(process.cwd(), '.env'));
 if (process.env.ASRUN_ROOT === undefined)
     loadEnvFile(path.join(FRAMEWORK_ROOT, '.env'));
+/** The manifest `init` writes: framework version, migration baseline and the generated file list. */
+export const MARKER = '.asrun.json';
+/** The published framework package: the dependency a workspace installs and the name the registry is asked for. */
+export const PACKAGE = '@asrunjs/asrun';
+/**
+ * True in the framework's own repository, where the framework is a git checkout rather than an installed package. Such a
+ * checkout has no registry install to upgrade: `upgrade` refuses to run there and the release check suggests git.
+ */
+export function isRepoCheckout() {
+    return !FRAMEWORK_ROOT.split(path.sep).includes('node_modules') && fs.existsSync(path.join(FRAMEWORK_ROOT, 'examples', 'demo'));
+}
 /** Files that mark the root of a workspace: the project that owns `profiles.yaml`, `cases/` and `tests/`. */
-const WORKSPACE_MARKERS = ['.asrun.json', 'profiles.yaml'];
+const WORKSPACE_MARKERS = [MARKER, 'profiles.yaml'];
 function findWorkspace(from) {
     let dir = path.resolve(from);
     for (;;) {

package/dist/lib/registry.d.ts

@@ -0,0 +1,31 @@
+import { type MigrationManifestEntry } from './migrations.js';
+/**
+ * How `pnpm asrun upgrade` learns what a release contains before it installs it: the registry gives the version and the
+ * tarball of a dist-tag, and the tarball carries the migration manifest (`dist/migrations/manifest.json`). Nothing here
+ * writes: it only reads the registry and the archive it serves.
+ */
+export interface ReleaseInfo {
+    /** the concrete version the spec resolves to */
+    version: string;
+    /** where the registry serves that release */
+    tarball: string;
+}
+/** A read of the registry that failed, with a message for the person; never thrown, so the caller can offer the manual path. */
+export type ReleaseLookup = {
+    info: ReleaseInfo;
+} | {
+    error: string;
+};
+/**
+ * Resolves `@<scope>/<name>@<spec>` (a version, a dist-tag such as `latest`) to its version and tarball.
+ * `pnpm view` is used on purpose: it reads the same registry and `.npmrc` the install will use.
+ * `timeoutMs` stops a slow or unreachable registry from holding a caller up; `upgrade` leaves it out, a release check
+ * always passes one.
+ */
+export declare function releaseInfo(pkg: string, spec: string, timeoutMs?: number): ReleaseLookup;
+/**
+ * The migration manifest of a release, or null when it ships none (a release older than the manifest itself, which
+ * has nothing to report). Throws only when the download or the archive is broken, so the caller can say that the
+ * pre-install check could not be done instead of pretending the release has no migrations.
+ */
+export declare function releaseManifest(tarball: string, timeoutMs?: number): Promise<MigrationManifestEntry[] | null>;

package/dist/lib/registry.js

@@ -0,0 +1,66 @@
+import { spawnSync } from 'node:child_process';
+import { spawnTarget } from './command.js';
+import { MANIFEST_ENTRY } from './migrations.js';
+import { readFileFromTarball } from './tar.js';
+/**
+ * Resolves `@<scope>/<name>@<spec>` (a version, a dist-tag such as `latest`) to its version and tarball.
+ * `pnpm view` is used on purpose: it reads the same registry and `.npmrc` the install will use.
+ * `timeoutMs` stops a slow or unreachable registry from holding a caller up; `upgrade` leaves it out, a release check
+ * always passes one.
+ */
+export function releaseInfo(pkg, spec, timeoutMs) {
+    const target = spawnTarget('pnpm', ['view', `${pkg}@${spec}`, 'version', 'dist.tarball', '--json']);
+    if (target === null)
+        return { error: 'pnpm was not found on PATH' };
+    const result = spawnSync(target.file, target.args, {
+        encoding: 'utf8',
+        ...(timeoutMs !== undefined && { timeout: timeoutMs }),
+        ...(target.throughShell && { windowsVerbatimArguments: true }),
+    });
+    const error = result.error;
+    if (error !== undefined) {
+        return { error: error.code === 'ENOENT' ? 'pnpm was not found on PATH' : error.message };
+    }
+    if (result.status !== 0) {
+        const detail = `${result.stderr ?? ''}${result.stdout ?? ''}`.trim().split(/\r?\n/).filter(Boolean).pop();
+        return {
+            error: detail ?? `pnpm view exited with code ${result.status}`,
+        };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(result.stdout);
+    }
+    catch {
+        const detail = (result.stdout ?? '').trim().split(/\r?\n/).filter(Boolean).slice(-1)[0];
+        return { error: `pnpm view did not answer with JSON${detail === undefined ? '' : `: ${detail}`}` };
+    }
+    const version = typeof parsed.version === 'string' ? parsed.version : undefined;
+    const tarball = typeof parsed['dist.tarball'] === 'string'
+        ? parsed['dist.tarball']
+        : typeof parsed.dist?.tarball === 'string'
+            ? parsed.dist.tarball
+            : undefined;
+    if (version === undefined || tarball === undefined) {
+        return { error: `the registry did not report a version and tarball for ${pkg}@${spec}` };
+    }
+    return { info: { version, tarball } };
+}
+/**
+ * The migration manifest of a release, or null when it ships none (a release older than the manifest itself, which
+ * has nothing to report). Throws only when the download or the archive is broken, so the caller can say that the
+ * pre-install check could not be done instead of pretending the release has no migrations.
+ */
+export async function releaseManifest(tarball, timeoutMs = 30_000) {
+    const response = await fetch(tarball, { signal: AbortSignal.timeout(timeoutMs) });
+    if (!response.ok)
+        throw new Error(`${response.status} ${response.statusText} for ${tarball}`);
+    const archive = Buffer.from(await response.arrayBuffer());
+    const entry = readFileFromTarball(archive, MANIFEST_ENTRY);
+    if (entry === null)
+        return null;
+    const parsed = JSON.parse(entry.toString('utf8'));
+    if (!Array.isArray(parsed))
+        throw new Error(`${MANIFEST_ENTRY} is not a JSON array`);
+    return parsed;
+}

package/dist/lib/runtime-deps.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Packages the framework installs on demand, instead of depending on them.
+ *
+ * A runtime dependency that runs 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` (that file belongs to the project, not to the
+ * sandbox), and in a pipeline nobody can answer the picker. So an optional package stays out of `dependencies` and
+ * `optionalDependencies`, and `init` (also through `go`) installs it into the workspace as a devDependency when the
+ * machine does not already provide what it gives.
+ *
+ * To add one, append it to `RUNTIME_EXTRAS`: its `allowBuilds` entry is then written by `init`/`go` before the
+ * install, `doctor` warns when it is missing, and `verify:pack` checks that it never becomes a runtime dependency.
+ */
+export interface RuntimeExtra {
+    /** the npm package, installed into the workspace on demand */
+    pkg: string;
+    /** one line for the person: what does not work without it */
+    provides: string;
+    /** a command that proves the machine already has the capability (exit code 0); empty means "never present" */
+    probe: string[];
+    /** the package runs an install script, so `pnpm-workspace.yaml` needs an `allowBuilds` entry for it */
+    builds: boolean;
+}
+export declare const RUNTIME_EXTRAS: RuntimeExtra[];
+/** Every package whose install scripts pnpm may run: the `allowBuilds` block of `pnpm-workspace.yaml`. */
+export declare const BUILD_APPROVALS: string[];
+/** True when the machine already provides what that package would (its probe exits 0). */
+export declare function hasCapability(extra: RuntimeExtra): boolean;
+/** True when the workspace itself has the package (installed on demand, so a devDependency). */
+export declare function installedInWorkspace(root: string, pkg: string): boolean;
+/**
+ * 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 declare function approveBuild(root: string, pkg: string): 'present' | 'added' | 'created' | 'inline' | 'no-file';
+/**
+ * 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 declare function excludeReleaseAge(root: string, pkg: string): 'present' | 'added' | 'created' | 'inline' | 'no-file';
+export interface ExtraOutcome {
+    extra: RuntimeExtra;
+    status: 'present' | 'installed' | 'failed';
+    /** why the install failed, for the message `init` prints */
+    detail?: string;
+}
+/**
+ * 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 declare function ensureRuntimeExtras(root: string, onInstall?: (extra: RuntimeExtra) => void): ExtraOutcome[];