@asrunjs/asrun 0.7.0 → 0.9.0

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[];

package/dist/lib/runtime-deps.js

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

package/dist/lib/tar.d.ts

@@ -0,0 +1,5 @@
+/**
+ * The content of `wanted` inside a tarball (gzipped or not), or null when the archive has no such file. Only regular
+ * files are considered; a directory entry of the same name is skipped.
+ */
+export declare function readFileFromTarball(archive: Buffer, wanted: string): Buffer | null;