@asrunjs/asrun 0.7.0 → 0.9.0

package/dist/scripts/init.js

@@ -1,13 +1,16 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { spawnSync } from 'node:child_process';
-import { FRAMEWORK_ROOT, TEMPLATES_DIR } from '../lib/paths.js';
+import { FRAMEWORK_ROOT, MARKER, PACKAGE, TEMPLATES_DIR, isRepoCheckout } from '../lib/paths.js';
+import { migrationState, pendingMigrations } from '../lib/migrations.js';
+import { MIGRATIONS } from '../migrations/index.js';
+import { BUILD_APPROVALS, RUNTIME_EXTRAS, approveBuild, ensureRuntimeExtras, hasCapability, installedInWorkspace, } from '../lib/runtime-deps.js';
 /**
  * Creates the files a workspace needs. It is safe to run many times: it never overwrites a file the project owns,
  * `--update` refreshes only the files generated from the framework templates, and `--force` rewrites every file it
  * writes (except the project's own data and, without `--reset-rules`, its rules).
  */
-const USAGE = `Usage: pnpm asrun init [--root <dir>] [--update] [--force [<path>]] [--reset-rules] [--no-env] [--install [spec]]
+const USAGE = `Usage: pnpm asrun init [--root <dir>] [--update] [--force [<path>]] [--reset-rules] [--no-env] [--no-extras] [--install [spec]]
 
   --root <dir>    the workspace to initialize (default: the current folder)
   --update        refresh the generated files (playwright.config.ts, tests/seed.spec.ts, .claude/commands/*,
@@ -17,6 +20,7 @@ const USAGE = `Usage: pnpm asrun init [--root <dir>] [--update] [--force [<path>
   --force <path>  overwrite one file this tool writes, e.g. --force playwright.config.ts (may be repeated)
   --reset-rules   allow --force on AGENTS.md, CLAUDE.md or .claude/skills/** (project-owned rules)
   --no-env        do not write .env (ASRUN_ROOT)
+  --no-extras     do not install the optional packages this machine lacks (ffmpeg-static), which "pnpm go" does
   --install [spec]  also add the dependency (default "@asrunjs/asrun"; e.g. --install github:<owner>/<repo>#<tag>)`;
 /** Files `init` owns: `--update` rewrites exactly these, and a project never edits them. */
 export const GENERATED = [
@@ -47,16 +51,13 @@ export const ONCE = [
 ];
 // npm never packs a `.gitignore`, so the template is named `gitignore`; init writes it as `.gitignore`.
 const GITIGNORE_BLOCK = fs.readFileSync(path.join(TEMPLATES_DIR, 'gitignore'), 'utf8').trimEnd();
-export const MARKER = '.asrun.json';
+// Re-exported: `doctor` and `reset` import the marker name from here, and `lib/paths.ts` is the one definition.
+export { MARKER };
+export { PACKAGE };
 export const DOTENV_HEADER = '# asrun: the workspace these commands run against (relative to this file).';
-export const PACKAGE = '@asrunjs/asrun';
 function readTemplate(name) {
     return fs.readFileSync(path.join(TEMPLATES_DIR, name), 'utf8');
 }
-/** True in the framework's own repository (not an installed package). */
-function isRepoCheckout() {
-    return !FRAMEWORK_ROOT.split(path.sep).includes('node_modules') && fs.existsSync(path.join(FRAMEWORK_ROOT, 'examples', 'demo'));
-}
 /** How the workspace reaches the framework: `./node_modules/@asrunjs/asrun`, or a relative folder in the framework repo. */
 export function frameworkPath(root) {
     if (!isRepoCheckout()) {
@@ -240,6 +241,7 @@ export async function main(args) {
     }
     const resetRules = args.includes('--reset-rules');
     const skipEnv = args.includes('--no-env');
+    const skipExtras = args.includes('--no-extras');
     if (path.resolve(root) === path.resolve(FRAMEWORK_ROOT)) {
         console.error('This folder is the framework itself, not a workspace. Run "pnpm asrun init" inside the project that uses ' +
             'asrun, or pass --root <dir> (the framework develops against examples/demo).');
@@ -298,6 +300,25 @@ export async function main(args) {
     const gitignore = ensureGitignore(root, update || forceAll);
     const merged = mergePackageJson(root);
     const dotenv = skipEnv ? 'skipped' : ensureDotEnv(process.cwd(), root);
+    // pnpm runs only the install scripts that pnpm-workspace.yaml approves. A file written before a package joined
+    // BUILD_APPROVALS (or one a project edited by hand) gets the missing entries here, before anything is installed:
+    // a note would be too late, the install that follows would already have skipped the script.
+    const approved = [];
+    const approvalsBroken = [];
+    if (!framework.startsWith('..')) {
+        for (const pkg of BUILD_APPROVALS) {
+            const result = approveBuild(root, pkg);
+            if (result === 'added' || result === 'created')
+                approved.push(pkg);
+            if (result === 'inline' || result === 'no-file')
+                approvalsBroken.push(pkg);
+        }
+        if (approvalsBroken.length > 0) {
+            notes.push(`pnpm-workspace.yaml has no "allowBuilds" block to extend: add ${approvalsBroken
+                .map((pkg) => `"${pkg}: true"`)
+                .join(', ')} under "allowBuilds" by hand, or pnpm skips its install script.`);
+        }
+    }
     if (fs.existsSync(path.join(root, 'tsconfig.json')) && !written.includes('tsconfig.json')) {
         const tsconfig = fs.readFileSync(path.join(root, 'tsconfig.json'), 'utf8');
         if (tsconfig.includes('@asrun/')) {
@@ -306,9 +327,6 @@ export async function main(args) {
     }
     if (fs.existsSync(path.join(root, 'pnpm-workspace.yaml')) && !written.includes('pnpm-workspace.yaml')) {
         const workspace = fs.readFileSync(path.join(root, 'pnpm-workspace.yaml'), 'utf8');
-        if (!workspace.includes('allowBuilds')) {
-            notes.push('Add "allowBuilds: {esbuild: true, ffmpeg-static: true}" to pnpm-workspace.yaml, or pnpm skips their build scripts.');
-        }
         if (!workspace.includes('minimumReleaseAgeExclude')) {
             notes.push('Add an "@asrunjs/asrun" entry to "minimumReleaseAgeExclude" in pnpm-workspace.yaml, or pnpm installs the ' +
                 'previous release for 24 hours after a new one.');
@@ -373,15 +391,53 @@ export async function main(args) {
             return 1;
         }
     }
+    // Optional packages stay out of the package's dependency graph (a runtime dependency with an install script makes
+    // "pnpm dlx @asrunjs/asrun" stop at pnpm's build-approval picker, which nobody can answer in a pipeline), so the
+    // workspace installs one here, only when this machine lacks what it provides. A failure never stops init.
+    const extrasInstalled = [];
+    const extrasSkipped = [];
+    if (!framework.startsWith('..') && isInstalled(root)) {
+        if (skipExtras) {
+            for (const extra of RUNTIME_EXTRAS) {
+                if (!hasCapability(extra) && !installedInWorkspace(root, extra.pkg))
+                    extrasSkipped.push(extra.pkg);
+            }
+            if (extrasSkipped.length > 0) {
+                notes.push(`Optional packages were not installed (--no-extras): ${extrasSkipped.join(', ')}. Run "pnpm asrun init" ` +
+                    'without --no-extras, or "pnpm go", when the machine needs them.');
+            }
+        }
+        else {
+            for (const outcome of ensureRuntimeExtras(root, (extra) => console.log(`\n  Installing ${extra.pkg} (${extra.provides})`))) {
+                if (outcome.status === 'installed')
+                    extrasInstalled.push(outcome.extra.pkg);
+                else if (outcome.status === 'failed') {
+                    notes.push(`${outcome.extra.pkg} was not installed (${outcome.detail}): ${outcome.extra.provides} is skipped until ` +
+                        `it is. Run "pnpm add -D ${outcome.extra.pkg}" in ${root}, then "pnpm asrun init" again.`);
+                }
+            }
+        }
+    }
     const version = frameworkVersion();
+    const previous = readManifest(root);
+    // The marker records the installed version, but the migration baseline is the release the workspace was last
+    // migrated *from*. It only moves when a migration succeeds, so a manual "pnpm add" followed by "init --update"
+    // cannot erase what still has to be done.
+    const migrations = migrationState(previous, version.version);
     fs.writeFileSync(path.join(root, MARKER), JSON.stringify({
         framework: PACKAGE,
         frameworkPath: framework,
         version: version.version,
         commit: version.commit,
+        migrations,
         generated: GENERATED.map((entry) => entry.file),
         updatedAt: new Date().toISOString(),
     }, null, 2) + '\n');
+    const pending = pendingMigrations(MIGRATIONS, migrations.since, version.version);
+    if (pending.length > 0) {
+        notes.push(`${pending.length} workspace migration(s) apply (${pending.map((migration) => migration.id).join(', ')}): ` +
+            'run "pnpm asrun migrate".');
+    }
     const label = firstRun ? 'Initialized' : forceAll ? 'Forced' : update ? 'Refreshed' : 'Checked';
     console.log(`${label} workspace: ${root}`);
     console.log(`  framework: ${PACKAGE} ${version.version} at ${framework}`);
@@ -391,6 +447,12 @@ export async function main(args) {
         console.log(`  kept:      ${kept.join(', ')}`);
     if (merged.length > 0)
         console.log(`  merged:    package.json -> ${merged.join(', ')}`);
+    // A file init just wrote already has the entries; only an existing one is worth reporting as changed.
+    if (approved.length > 0 && !written.includes('pnpm-workspace.yaml')) {
+        console.log(`  allowBuilds: added ${approved.join(', ')} to pnpm-workspace.yaml`);
+    }
+    if (extrasInstalled.length > 0)
+        console.log(`  extras:    installed ${extrasInstalled.join(', ')}`);
     if (gitignore !== 'kept')
         console.log(`  .gitignore: ${gitignore}`);
     if (dotenv !== 'skipped')

package/dist/scripts/migrate.d.ts

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

package/dist/scripts/migrate.js

@@ -0,0 +1,259 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import readline from 'node:readline/promises';
+import { FRAMEWORK_ROOT, MARKER, ROOT } from '../lib/paths.js';
+import { compareVersions, isVersion, migrationState, pendingMigrations, readMarker, writeMigrationState, } from '../lib/migrations.js';
+import { MIGRATIONS } from '../migrations/index.js';
+/**
+ * `pnpm asrun migrate`: brings an existing workspace up to the release that is installed, by running the migrations
+ * recorded in `migrations/index.ts`. `pnpm asrun upgrade` runs it after the install; it is also the command a person
+ * runs after a manual `pnpm add -D @asrunjs/asrun@latest`, or to see what is still open.
+ *
+ * It writes only what a migration describes, plus the migration state in `.asrun.json`. It never installs anything:
+ * a migration whose release is newer than the installed package does not run.
+ */
+const USAGE = `Usage: pnpm asrun migrate [--root <dir>] [--list] [--dry-run] [--yes] [--from <version>] [--to <version>]
+                             [--ack <id> ...|--ack-all]
+
+  --root <dir>    the workspace to migrate (default: the current workspace)
+  --list          list every migration of the installed release and its state, and change nothing
+  --dry-run       show the migrations that would run, and change nothing
+  --yes           apply breaking migrations without the confirmation prompt (for unattended runs)
+  --from <ver>    pretend the workspace is at that release (default: the recorded migrations.since)
+  --to <ver>      migrate up to that release (default: the installed one; never beyond it)
+  --ack <id>      mark the manual steps of that migration as done (repeatable)
+  --ack-all       mark every outstanding manual step as done
+
+The migration baseline lives in .asrun.json ("migrations.since"). It only advances when a migration succeeds, so an
+interrupted or failed run can simply be repeated.`;
+/** The version of the package this command runs from: never beyond it, because its code is what applies migrations. */
+function installedVersion() {
+    try {
+        const manifest = JSON.parse(fs.readFileSync(path.join(FRAMEWORK_ROOT, 'package.json'), 'utf8'));
+        return typeof manifest.version === 'string' ? manifest.version : '0.0.0';
+    }
+    catch {
+        return '0.0.0';
+    }
+}
+/** The value of a flag that takes one; undefined when the flag is absent or has no value. */
+function flagValue(args, name) {
+    const index = args.indexOf(name);
+    return index >= 0 && args[index + 1] !== undefined && !args[index + 1].startsWith('-') ? args[index + 1] : undefined;
+}
+/** Every `--ack <id>` of the command line. */
+function acknowledged(args) {
+    const ids = [];
+    for (let index = 0; index < args.length; index++) {
+        if (args[index] === '--ack' && args[index + 1] !== undefined && !args[index + 1].startsWith('-')) {
+            ids.push(args[index + 1]);
+            index++;
+        }
+    }
+    return ids;
+}
+function describe(migration) {
+    return `${migration.version}  ${migration.id}  ${migration.summary}`;
+}
+/** Asks a person to confirm; without a terminal it refuses instead of assuming an answer. */
+async function confirm(question) {
+    if (!process.stdin.isTTY || !process.stdout.isTTY)
+        return false;
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        return (await rl.question(question)).trim().toLowerCase() === 'migrate';
+    }
+    finally {
+        rl.close();
+    }
+}
+function printManual(ids) {
+    if (ids.length === 0)
+        return;
+    console.log('\nManual steps left (do them, then mark them done with "pnpm asrun migrate --ack <id>"):');
+    for (const id of ids) {
+        const migration = MIGRATIONS.find((entry) => entry.id === id);
+        if (migration === undefined) {
+            console.log(`  ${id}`);
+            continue;
+        }
+        console.log(`  ${migration.version}  ${migration.id}: ${migration.summary}`);
+        for (const line of migration.manual ?? [])
+            console.log(`    - ${line}`);
+    }
+}
+export async function main(args) {
+    if (args.includes('--help')) {
+        console.log(USAGE);
+        return 0;
+    }
+    const root = path.resolve(flagValue(args, '--root') ?? ROOT);
+    const dryRun = args.includes('--dry-run');
+    const yes = args.includes('--yes');
+    if (path.resolve(root) === path.resolve(FRAMEWORK_ROOT)) {
+        console.error('This folder is the framework itself, not a workspace. Run "pnpm asrun migrate" in the project that uses ' +
+            'asrun, or pass --root <dir>.');
+        return 1;
+    }
+    const marker = readMarker(root);
+    if (marker === null) {
+        console.error(`No ${MARKER} in ${root}: this is not an initialized asrun workspace. Run "pnpm asrun init" first.`);
+        return 1;
+    }
+    const installed = installedVersion();
+    const state = migrationState(marker, installed);
+    // `--list` answers "what does this release contain, and where is this workspace", without touching anything.
+    if (args.includes('--list')) {
+        console.log(`Workspace: ${root}`);
+        console.log(`asrun:     ${installed} installed, migrations since ${state.since}`);
+        if (MIGRATIONS.length === 0) {
+            console.log('\nThis release has no migrations.');
+        }
+        else {
+            console.log(`\n${MIGRATIONS.length} migration(s) known to this release:`);
+            for (const migration of MIGRATIONS) {
+                const applied = compareVersions(migration.version, state.since) <= 0;
+                const mark = applied ? 'ok ' : migration.manual !== undefined && migration.manual.length > 0 ? '-> ' : '   ';
+                console.log(`  ${mark}${describe(migration)}`);
+                console.log(`      ${applied ? 'already at or before the baseline' : 'pending'}${migration.breaking ? ', breaking' : ''}`);
+            }
+        }
+        printManual(state.manual);
+        return 0;
+    }
+    const ackAll = args.includes('--ack-all');
+    const ackIds = acknowledged(args);
+    if (ackAll || ackIds.length > 0) {
+        const unknown = ackIds.filter((id) => !state.manual.includes(id));
+        if (unknown.length > 0) {
+            console.error(`Not outstanding: ${unknown.join(', ')}. Run "pnpm asrun migrate --list" to see what is.`);
+            return 1;
+        }
+        const manual = ackAll ? [] : state.manual.filter((id) => !ackIds.includes(id));
+        writeMigrationState(root, { since: state.since, manual });
+        console.log(ackAll
+            ? `Acknowledged every outstanding manual step (${state.manual.length}).`
+            : `Acknowledged: ${ackIds.join(', ')}.`);
+        printManual(manual);
+        return 0;
+    }
+    const from = flagValue(args, '--from') ?? state.since;
+    const to = flagValue(args, '--to') ?? installed;
+    if (!isVersion(from) || !isVersion(to)) {
+        console.error(`Not a version: ${!isVersion(from) ? from : to}`);
+        return 1;
+    }
+    if (compareVersions(to, installed) > 0) {
+        console.error(`Refusing to migrate to ${to}: the installed package is ${installed}. The code that applies a migration is the ` +
+            'installed one, so run "pnpm asrun upgrade" (or "pnpm add -D @asrunjs/asrun@latest") first.');
+        return 1;
+    }
+    // A baseline recorded further than the installed release means the workspace was set up by a newer package (or the
+    // install went backwards). Nothing to apply; say so instead of silently moving the baseline back.
+    if (compareVersions(to, state.since) <= 0) {
+        console.log(`Workspace: ${root}`);
+        console.log(`Migrations: none — the baseline is ${state.since}, the installed release is ${installed}.`);
+        printManual(state.manual);
+        return 0;
+    }
+    // `--from` may only move the start forward: migrations the workspace's baseline already covers never run again.
+    const start = compareVersions(from, state.since) < 0 ? state.since : from;
+    const pending = pendingMigrations(MIGRATIONS, start, to);
+    console.log(`Workspace: ${root}`);
+    console.log(`asrun:     ${installed}${installed === to ? '' : ` (migrating to ${to})`}`);
+    if (pending.length === 0) {
+        console.log(`Migrations: none between ${start} and ${to}.`);
+        // Nothing was skipped, so the baseline moves up to the release that was asked for: a workspace with an empty
+        // registry (or a release without migrations) then stops reporting the old baseline in `doctor`.
+        if (!dryRun)
+            writeMigrationState(root, { since: to, manual: state.manual });
+        printManual(state.manual);
+        return 0;
+    }
+    console.log(`Migrations: ${pending.length} between ${start} and ${to}`);
+    for (const migration of pending) {
+        console.log(`  ${describe(migration)}${migration.auto === true ? '  (automatic)' : ''}${migration.breaking ? '  (breaking)' : ''}`);
+        if (migration.appliesTo !== undefined)
+            console.log(`      affects: ${migration.appliesTo}`);
+        for (const line of migration.manual ?? [])
+            console.log(`      - ${line}`);
+    }
+    if (dryRun) {
+        console.log('\nNothing was applied (--dry-run).');
+        return 0;
+    }
+    const automatic = pending.filter((migration) => migration.auto === true && typeof migration.apply === 'function');
+    const breaking = automatic.filter((migration) => migration.breaking === true);
+    if (breaking.length > 0 && !yes) {
+        if (!process.stdin.isTTY || !process.stdout.isTTY) {
+            console.error(`\nRefusing to apply ${breaking.length} breaking migration(s): there is no terminal to confirm in. ` +
+                'A person adds --yes to do it.');
+            return 1;
+        }
+        const answer = await confirm(`\nType "migrate" to apply ${breaking.length} breaking migration(s): `);
+        if (!answer) {
+            console.error('Cancelled. Nothing was applied.');
+            return 1;
+        }
+    }
+    const context = {
+        root,
+        frameworkRoot: FRAMEWORK_ROOT,
+        from: start,
+        to,
+        log: (text) => console.log(`      ${text}`),
+    };
+    const state2 = { since: state.since, manual: [...state.manual] };
+    // The baseline moves one *release* at a time: several migrations may come with the same version, and a failure in
+    // the middle of one release must leave the whole release pending, so a retry repeats it instead of skipping the rest.
+    let done = state.since;
+    let applied = 0;
+    let skipped = 0;
+    for (let index = 0; index < pending.length; index++) {
+        const migration = pending[index];
+        const label = `${migration.version} ${migration.id}`;
+        const lastOfRelease = index === pending.length - 1 || pending[index + 1].version !== migration.version;
+        if (migration.auto !== true || typeof migration.apply !== 'function') {
+            console.log(`  -> ${label}: a person has to do this`);
+            for (const line of migration.manual ?? [])
+                console.log(`       - ${line}`);
+            if ((migration.manual ?? []).length > 0)
+                state2.manual.push(migration.id);
+            if (lastOfRelease)
+                done = migration.version;
+            continue;
+        }
+        if (migration.detect !== undefined && !migration.detect(context)) {
+            console.log(`  ok ${label}: already in place`);
+            skipped++;
+            if (lastOfRelease)
+                done = migration.version;
+            continue;
+        }
+        console.log(`  .. ${label}`);
+        try {
+            await migration.apply(context);
+        }
+        catch (error) {
+            // The baseline stops at the last release that finished, so fixing the cause and running the command again
+            // repeats this release (its migrations must be idempotent) and nothing later.
+            writeMigrationState(root, { since: done, manual: [...new Set(state2.manual)] });
+            console.error(`\n  ! ${label} failed: ${error instanceof Error ? error.message : String(error)}`);
+            console.error(`    The workspace is migrated up to ${done}. Fix the cause and run "pnpm asrun migrate" again.`);
+            return 1;
+        }
+        console.log(`  ok ${label}`);
+        applied++;
+        if (lastOfRelease)
+            done = migration.version;
+    }
+    if (compareVersions(to, done) > 0)
+        done = to;
+    state2.since = done;
+    const manual = [...new Set(state2.manual)];
+    writeMigrationState(root, { since: state2.since, manual });
+    console.log(`\nApplied ${applied} migration(s)${skipped > 0 ? `, ${skipped} already in place` : ''}. ` +
+        `Baseline: ${state2.since}.`);
+    printManual(manual);
+    return 0;
+}

package/dist/scripts/run.js

@@ -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>;