@asrunjs/asrun 0.6.0 → 0.7.0

package/dist/scripts/init.js

@@ -3,18 +3,21 @@ import path from 'node:path';
 import { spawnSync } from 'node:child_process';
 import { FRAMEWORK_ROOT, TEMPLATES_DIR } from '../lib/paths.js';
 /**
- * Creates the files a workspace needs. It is safe to run many times: it never overwrites a file the project owns, and
- * `--update` refreshes only the files generated from the framework templates.
+ * 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>] [--no-env] [--install [spec]]
+const USAGE = `Usage: pnpm asrun init [--root <dir>] [--update] [--force [<path>]] [--reset-rules] [--no-env] [--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/*,
                   .opencode/commands/*)
+  --force         overwrite every file this tool writes, for a clean installation (keeps the project's own data:
+                  profiles.yaml, package.json; AGENTS.md and CLAUDE.md need --reset-rules)
   --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)
-  --install [spec]  also add the dependency (default "asrun"; e.g. --install github:<owner>/<repo>#<tag>)`;
+  --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 = [
     { file: 'playwright.config.ts', template: 'playwright.config.ts' },
@@ -30,7 +33,7 @@ export const GENERATED = [
     { file: '.opencode/commands/heal-spec.md', template: '.claude/commands/heal-spec.md' },
 ];
 /** Files `init` creates once; after that the project owns them and may edit them freely. */
-const ONCE = [
+export const ONCE = [
     { file: 'AGENTS.md', template: 'AGENTS.md' },
     { file: 'CLAUDE.md', template: 'CLAUDE.md' },
     { file: '.mcp.json', template: '.mcp.json' },
@@ -44,9 +47,9 @@ 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();
-const MARKER = '.asrun.json';
-const DOTENV_HEADER = '# asrun: the workspace these commands run against (relative to this file).';
-const PACKAGE = '@asrunjs/asrun';
+export const MARKER = '.asrun.json';
+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');
 }
@@ -79,11 +82,18 @@ export function frameworkPath(root) {
 export function isInstalled(root) {
     return fs.existsSync(path.join(path.resolve(root, frameworkPath(root)), 'package.json'));
 }
-/** Fills the `{{framework}}` and `{{playwright}}` placeholders of a template. */
+/** The range the workspace's `package.json` names for the framework: `^` plus the version that wrote the workspace. */
+let asrunRange;
+function asrunDependencyRange() {
+    asrunRange ??= `^${frameworkVersion().version}`;
+    return asrunRange;
+}
+/** Fills the `{{framework}}`, `{{playwright}}` and `{{asrun}}` placeholders of a template. */
 export function renderTemplate(name, root) {
     return readTemplate(name)
         .replaceAll('{{framework}}', frameworkPath(root))
-        .replaceAll('{{playwright}}', playwrightBin(root));
+        .replaceAll('{{playwright}}', playwrightBin(root))
+        .replaceAll('{{asrun}}', asrunDependencyRange());
 }
 /**
  * The Playwright CLI the MCP server runs. The workspace's own install is the normal place; a workspace that lives
@@ -113,13 +123,21 @@ export function frameworkVersion() {
     }
     return { version, commit };
 }
-/** Merges the template's npm scripts and devDependencies into an existing package.json (never overwrites). */
+/** True when any dependency block of the manifest already names `name`, whatever the range. */
+function declaredIn(manifest, name) {
+    return [manifest.dependencies, manifest.devDependencies, manifest.optionalDependencies, manifest.peerDependencies].some((block) => block?.[name] !== undefined);
+}
+/**
+ * Merges the template's npm scripts and devDependencies into an existing package.json (never overwrites). The
+ * framework itself is one of those devDependencies, so a workspace whose `pnpm add` step failed still names it and
+ * `pnpm install` is enough to fix it.
+ */
 function mergePackageJson(root) {
     const file = path.join(root, 'package.json');
     if (!fs.existsSync(file))
         return [];
     const current = JSON.parse(fs.readFileSync(file, 'utf8'));
-    const template = JSON.parse(readTemplate('package.json'));
+    const template = JSON.parse(renderTemplate('package.json', root));
     const added = [];
     current.scripts ??= {};
     for (const [name, command] of Object.entries(template.scripts)) {
@@ -130,10 +148,10 @@ function mergePackageJson(root) {
     }
     current.devDependencies ??= {};
     for (const [name, range] of Object.entries(template.devDependencies)) {
-        if (current.devDependencies[name] === undefined) {
-            current.devDependencies[name] = range;
-            added.push(`devDependencies.${name}`);
-        }
+        if (declaredIn(current, name))
+            continue;
+        current.devDependencies[name] = range;
+        added.push(`devDependencies.${name}`);
     }
     if (added.length > 0)
         fs.writeFileSync(file, JSON.stringify(current, null, 2) + '\n');
@@ -204,9 +222,22 @@ export async function main(args) {
     const installAt = args.indexOf('--install');
     const install = installAt >= 0;
     const installSpec = install && args[installAt + 1] && !args[installAt + 1].startsWith('-') ? args[installAt + 1] : PACKAGE;
-    const forced = args
-        .flatMap((arg, index) => (arg === '--force' && args[index + 1] ? [args[index + 1]] : []))
-        .map((file) => file.split('\\').join('/'));
+    // `--force` alone overwrites every file init writes; `--force <path>` still names one file, so the messages the
+    // docs and doctor print keep working. The next token is a path only when it does not look like another flag.
+    const forced = [];
+    let forceAll = false;
+    for (let index = 0; index < args.length; index++) {
+        if (args[index] !== '--force')
+            continue;
+        const next = args[index + 1];
+        if (next !== undefined && !next.startsWith('-')) {
+            forced.push(next.split('\\').join('/'));
+            index++;
+        }
+        else {
+            forceAll = true;
+        }
+    }
     const resetRules = args.includes('--reset-rules');
     const skipEnv = args.includes('--no-env');
     if (path.resolve(root) === path.resolve(FRAMEWORK_ROOT)) {
@@ -219,8 +250,9 @@ export async function main(args) {
     const kept = [];
     const notes = [];
     const framework = frameworkPath(root);
-    // `--force` repairs a file this tool writes. A project's own rules are never overwritten by a framework update:
-    // `AGENTS.md`, `CLAUDE.md` and `.claude/skills/**` need `--reset-rules` on top.
+    // `--force` repairs a file this tool writes; without a path it rewrites every one of them. A project's own rules
+    // are never overwritten by a framework update: `AGENTS.md`, `CLAUDE.md` and `.claude/skills/**` need
+    // `--reset-rules` on top. The workspace's own data (`profiles.yaml`, `package.json`) is only replaced when named.
     const owned = [...GENERATED, ...ONCE].map((entry) => entry.file);
     const projectRules = (file) => file === 'AGENTS.md' || file === 'CLAUDE.md' || file === '.claude/skills' || file.startsWith('.claude/skills/');
     for (const file of forced) {
@@ -244,14 +276,26 @@ export async function main(args) {
         written.push(entry.file);
     };
     for (const entry of GENERATED)
-        place(entry, update || forced.includes(entry.file));
+        place(entry, update || forceAll || forced.includes(entry.file));
+    const keptProjectData = [];
+    const keptRules = [];
     for (const entry of ONCE) {
         // The demo workspace lives inside the framework repository: it has no package manager settings of its own.
         if (framework.startsWith('..') && (entry.file === 'pnpm-workspace.yaml' || entry.file === 'package.json'))
             continue;
-        place(entry, forced.includes(entry.file));
+        const explicit = forced.includes(entry.file);
+        const projectData = entry.file === 'profiles.yaml' || entry.file === 'package.json';
+        const rules = projectRules(entry.file);
+        const overwrite = explicit || (forceAll && !projectData && (!rules || resetRules));
+        if (forceAll && !explicit && fs.existsSync(path.join(root, entry.file))) {
+            if (projectData)
+                keptProjectData.push(entry.file);
+            if (rules && !resetRules)
+                keptRules.push(entry.file);
+        }
+        place(entry, overwrite);
     }
-    const gitignore = ensureGitignore(root, update);
+    const gitignore = ensureGitignore(root, update || forceAll);
     const merged = mergePackageJson(root);
     const dotenv = skipEnv ? 'skipped' : ensureDotEnv(process.cwd(), root);
     if (fs.existsSync(path.join(root, 'tsconfig.json')) && !written.includes('tsconfig.json')) {
@@ -265,6 +309,10 @@ export async function main(args) {
         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.');
+        }
         if (/^packages\s*:/m.test(workspace)) {
             notes.push('pnpm-workspace.yaml lists "packages"; asrun is a dependency now, so that list can go.');
         }
@@ -290,11 +338,38 @@ export async function main(args) {
             notes.push('Add "pnpm asrun *" to sandbox.excludedCommands in .claude/settings.json (see templates/.claude/settings.json).');
         }
     }
+    if (keptRules.length > 0) {
+        notes.push(`${keptRules.join(', ')} kept: the project owns them. Add --reset-rules to replace them with the template.`);
+    }
+    if (keptProjectData.length > 0) {
+        const profileHint = keptProjectData.includes('profiles.yaml')
+            ? ' Use "pnpm asrun init --force profiles.yaml" to replace the profile file.'
+            : '';
+        notes.push(`${keptProjectData.join(', ')} kept: --force never replaces the workspace's own data.${profileHint}`);
+    }
     // Install last, so pnpm-workspace.yaml (the build-script approval) already exists. Its absence is the reason
     // "pnpm add -D @asrunjs/asrun" fails on pnpm 12 with ERR_PNPM_IGNORED_BUILDS.
     const installed = isInstalled(root);
     if (install && !installed) {
-        if (spawnSync('pnpm', ['add', '-D', installSpec], { cwd: root, stdio: 'inherit', shell: process.platform === 'win32' }).status !== 0) {
+        const result = spawnSync('pnpm', ['add', '-D', installSpec], {
+            cwd: root,
+            stdio: 'inherit',
+            shell: process.platform === 'win32',
+        });
+        if (result.status !== 0) {
+            // `status` is null when pnpm never started (not on PATH, or killed): pnpm prints nothing then, so without this
+            // message the workspace would stay half initialized with no explanation.
+            const error = result.error;
+            const reason = error !== undefined
+                ? error.code === 'ENOENT'
+                    ? 'pnpm was not found on PATH'
+                    : error.message
+                : result.signal !== null
+                    ? `pnpm was stopped by ${result.signal}`
+                    : `pnpm add exited with code ${result.status}`;
+            console.error(`\n  ! ${installSpec} was not installed: ${reason}`);
+            console.error(`    Run "pnpm add -D ${installSpec}" in ${root}, then "pnpm asrun init" again.`);
+            console.error('    The files above are written, but nothing that calls "asrun" works until the dependency is there.');
             return 1;
         }
     }
@@ -307,7 +382,7 @@ export async function main(args) {
         generated: GENERATED.map((entry) => entry.file),
         updatedAt: new Date().toISOString(),
     }, null, 2) + '\n');
-    const label = firstRun ? 'Initialized' : update ? 'Refreshed' : 'Checked';
+    const label = firstRun ? 'Initialized' : forceAll ? 'Forced' : update ? 'Refreshed' : 'Checked';
     console.log(`${label} workspace: ${root}`);
     console.log(`  framework: ${PACKAGE} ${version.version} at ${framework}`);
     if (written.length > 0)

package/dist/scripts/reset.d.ts

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

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

package/docs/agents/framework-dev.md

@@ -44,10 +44,19 @@ is relevant to a project that uses asrun as a dependency.
 
   `pnpm demo:reset` deletes the database and seeds it again; logins must be redone afterwards. Demo accounts are in
   `examples/demo/README.md`.
+
+  `.env` is per machine and gitignored, so a fresh clone has none: `init --root examples/demo` writes it in the folder
+  the command runs in (`ASRUN_ROOT=examples/demo`), and `pnpm go` does the same in its third step, so no manual step is
+  needed. Without it `pnpm go` still finds the demo through its fallback, but the other commands (`pnpm asrun`,
+  `pnpm signin`, `pnpm explore`) resolve the workspace from `ASRUN_ROOT` and then from the current folder, and stop
+  with "No workspace found: this is the framework folder".
 - Everything the framework reads for a project goes through `ROOT` in `lib/paths.ts` (the workspace root); its own
   assets (templates, docs, skills, its `node_modules`) go through `FRAMEWORK_ROOT`. Never write into
   `FRAMEWORK_ROOT` at run time.
 - After changing `lib/`, run `pnpm build` before exercising the demo's specs.
+- `pnpm build` copies `scripts/*.mjs` into `dist/scripts/`, where they sit one folder deeper than in this repository.
+  `pnpm verify:pack` (part of CI) checks that layout on a packed tarball; the checkout alone hides such bugs, because
+  there `scripts/go.mjs` is next to `bin/asrun.mjs`.
 - `templates/` is the source of the files a workspace gets. When a template changes, bump `version` in
   `package.json` so `pnpm asrun doctor` in a project shows that it is behind.
 - `init` owns two lists: `GENERATED` (rewritten by `--update`; the commands and the Playwright files) and `ONCE`
@@ -151,6 +160,25 @@ Every lead, label and tooltip is written for the person using the UI, never for
 - **Say what the user sees.** "The run appears in the Jobs bar", not "the command runs in a one-shot session"; "the
   browser shows a small card", not "the agent pauses on a `writes` step".
 
+## Releases
+
+Nothing bumps the version by hand. A merge to `main` runs `.github/workflows/release.yml`, and Release Please opens
+(or refreshes) one `chore(release): X.Y.Z` pull request holding the next `package.json` version and the matching
+`CHANGELOG.md` entry. Merging that pull request is the release: the same run tags the commit `vX.Y.Z` and publishes to
+npm.
+
+- The next version comes from the commit messages on `main`, and a squashed pull request title becomes that message.
+  `fix:` is a patch, `feat:` a minor, `feat!:` a major (the project is past 0.x, so a breaking change releases
+  `1.0.0`). `chore:`, `ci:` and the rest ship nothing and open no release at all.
+  `.github/workflows/pr-title.yml` enforces the prefixes.
+- `templates/`, `docs/`, `ui/dist/` and `.claude/` are shipped files: a change to them needs `fix:` or `feat:`, not
+  `docs:`, or no release is made and no workspace ever sees the new version (`pnpm asrun doctor` compares it).
+- `release.yml` is the only uploader. When an upload fails after the tag exists, run it by hand with the tag instead of
+  re-running the failed job: `gh workflow run release.yml -f tag=v1.0.0` (`-f dry_run=true` packs without uploading).
+  A re-run of the push run finds the release already made and skips publishing.
+- npm authentication is trusted publishing (OIDC, no secret): the workflow filename in the package's trusted publisher
+  settings is `release.yml`. A private repository gets no provenance, so the package page shows no provenance badge.
+
 ## Before you open a pull request
 
 ```bash
@@ -162,6 +190,6 @@ pnpm ui:build       # ui/dist/ must match ui/web and ui/server
 ```
 
 - `pnpm build` and `pnpm ui:build` also run from `prepare` and `prepack`, so a published package is complete.
-- Bump `version` when `templates/` or the shipped docs change; `pnpm asrun doctor` in a project compares it.
+- The version is not bumped by hand (see Releases).
 - Keep the demo's committed expectations (`profiles.yaml`, `cases/`, `tests/`, baselines) in step with the demo site.
   Baselines are a person's decision: never let an agent regenerate them.

package/docs/commands.md

@@ -9,6 +9,7 @@ thin wrappers, so `pnpm asrun`, `pnpm signin` and the rest work as below. The sa
 |---|---|
 | Install / update the framework | `pnpm dlx @asrunjs/asrun init --install`, `pnpm add -D @asrunjs/asrun@latest` |
 | Prepare or check the workspace | `pnpm asrun init [--update]`, `pnpm asrun doctor` |
+| Start over with fresh dependencies | `pnpm asrun reset [--yes] [--state] [--lockfile]` |
 | Start the web UI | `pnpm go`, `pnpm ui`, `pnpm ui:dev` |
 | See which profiles are logged in | `pnpm status [--env <env>]` |
 | Log in a profile (a person, with 2FA) | `pnpm signin <profile-id>` |
@@ -150,14 +151,18 @@ pnpm cleanup --env staging --forget
 
 A write case registers everything it creates (named `[asrun] ...`) and removes it after the test, also after a
 failure. Whatever could not be removed is listed in the report and by `cleanup`. Delete it by hand in the product,
-then run `--forget` so it is not listed again. `--env` is required.
+then run `--forget` so it is not listed again. `--env` is required. `cleanup` is about test data in the product;
+`pnpm asrun reset` (below) is the command that removes workspace files and dependencies.
 
 ## Web UI
 
 ```bash
-pnpm go          # install + build + start + open the browser (the usual command)
-pnpm ui          # build the web app and serve http://127.0.0.1:4173
-pnpm ui:dev      # Vite on :5173 with hot reload, API in watch mode
+pnpm go             # install + build + start + open the browser (the usual command)
+pnpm go --no-open   # same, without opening a browser
+pnpm go --no-ui     # install and prepare the workspace, then stop (no server)
+pnpm go --dry-run   # only print the resolved workspace, framework and asrun command
+pnpm ui             # build the web app and serve http://127.0.0.1:4173
+pnpm ui:dev         # Vite on :5173 with hot reload, API in watch mode
 ```
 
 The UI only listens on `127.0.0.1`. Set `ASRUN_UI_PORT` to change the port (`ASRUN_UI_WEB_PORT` for the Vite dev
@@ -166,10 +171,22 @@ server). See [web-ui.md](./web-ui.md).
 ## Workspace
 
 ```bash
-pnpm asrun init [--update] [--force <file>] [--reset-rules] [--root <dir>] [--no-env] [--install [spec]]
+pnpm asrun init [--update] [--force] [--force <file>] [--reset-rules] [--root <dir>] [--no-env] [--install [spec]]
 pnpm asrun doctor
+pnpm asrun reset [--root <dir>] [--dry-run] [--yes] [--state] [--lockfile]
 ```
 
-`init` writes the workspace files; `--update` refreshes only the generated ones. `doctor` checks profiles,
-`tsconfig.json`, `playwright.config.ts`, the generated files, the installed version, the project rule table and the
-skill overrides. Full details in [install.md](./install.md).
+`init` writes the workspace files; `--update` refreshes only the generated ones, and `--force` rewrites every file
+init writes (a single file with `--force <file>`). `--force` still keeps `profiles.yaml` and `package.json`; name
+`--force profiles.yaml` to replace profiles, and add `--reset-rules` to replace `AGENTS.md` or `CLAUDE.md`.
+`doctor` checks profiles, `tsconfig.json`, `playwright.config.ts`, the generated files, the installed version, the
+project rule table and the skill overrides.
+
+`reset` removes `node_modules` and the files `init` writes, for a clean reinstall. It deletes a once-only file only
+when it is still identical to its template, so edited files stay; `cases/`, specs, baselines, `profiles.yaml`,
+`package.json` and `.claude/skills/**` are never removed. `--state` also removes `.auth/`, `reports/`, `.tmp/`,
+`.explore/`, `test-results/`, `playwright-report/` and `.playwright-mcp/`; `--lockfile` also removes
+`pnpm-lock.yaml`. It lists what it would remove and asks for confirmation (`--yes` skips it, `--dry-run` only
+lists). After it, run `pnpm dlx @asrunjs/asrun init --install` and `pnpm go`.
+
+Full details in [install.md](./install.md).