@asrunjs/asrun 0.6.0 → 0.6.1

package/dist/scripts/doctor.js

@@ -3,7 +3,7 @@ import path from 'node:path';
 import { loadProfiles, listEnvs, PROFILES_FILE } from '../lib/profiles.js';
 import { FRAMEWORK_ROOT, ROOT, SKILLS_DIR } from '../lib/paths.js';
 import { spawnTarget } from '../lib/command.js';
-import { GENERATED, frameworkPath, frameworkVersion, renderTemplate } from './init.js';
+import { GENERATED, frameworkPath, frameworkVersion, PACKAGE, renderTemplate } from './init.js';
 import { builtFile, COPIED_SCRIPTS } from '../lib/build-artifacts.js';
 /**
  * Checks that a workspace is complete and consistent with the framework it points at. It never writes anything.
@@ -83,12 +83,17 @@ export async function main(args) {
     facts.push(`workspace: ${ROOT}`);
     const actualPath = frameworkPath(ROOT);
     facts.push(`framework: ${path.resolve(ROOT, actualPath)}`);
+    if (!fs.existsSync(path.join(path.resolve(ROOT, actualPath), 'package.json'))) {
+        errors.push(`${PACKAGE} is not installed in this workspace: run "pnpm add -D ${PACKAGE}", then "pnpm asrun init". ` +
+            'Every script that calls "asrun" fails until then.');
+    }
     // The manifest, written by init: it names where the workspace reaches the framework.
     const manifest = read(path.join(ROOT, '.asrun.json'));
     let recordedPath;
     const installedVersion = frameworkVersion();
     if (manifest === null) {
-        warnings.push('No .asrun.json: run "pnpm asrun init" in this folder.');
+        errors.push('No .asrun.json: this workspace was never initialized, or "init" stopped before it finished (for example the ' +
+            'pnpm add step failed). Run "pnpm asrun init" here.');
     }
     else {
         try {

package/dist/scripts/init.d.ts

@@ -3,11 +3,12 @@ export declare const GENERATED: {
     file: string;
     template: string;
 }[];
+export declare const PACKAGE = "@asrunjs/asrun";
 /** How the workspace reaches the framework: `./node_modules/@asrunjs/asrun`, or a relative folder in the framework repo. */
 export declare function frameworkPath(root: string): string;
 /** True when this workspace has the package installed (or is the framework's own checkout). */
 export declare function isInstalled(root: string): boolean;
-/** Fills the `{{framework}}` and `{{playwright}}` placeholders of a template. */
+/** Fills the `{{framework}}`, `{{playwright}}` and `{{asrun}}` placeholders of a template. */
 export declare function renderTemplate(name: string, root: string): string;
 /**
  * The Playwright CLI the MCP server runs. The workspace's own install is the normal place; a workspace that lives

package/dist/scripts/init.js

@@ -14,7 +14,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)
-  --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' },
@@ -46,7 +46,7 @@ const ONCE = [
 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 PACKAGE = '@asrunjs/asrun';
 function readTemplate(name) {
     return fs.readFileSync(path.join(TEMPLATES_DIR, name), 'utf8');
 }
@@ -79,11 +79,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 +120,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 +145,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');
@@ -294,7 +309,25 @@ export async function main(args) {
     // "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;
         }
     }

package/docs/install.md

@@ -26,6 +26,11 @@ writes `pnpm-workspace.yaml` with the `allowBuilds` entry (`esbuild` through `ts
 `pnpm add` exits with `ERR_PNPM_IGNORED_BUILDS`. An existing `pnpm-workspace.yaml` that lacks the entry gets a note
 instead: add the block by hand (see "Manual install").
 
+`init` also records `@asrunjs/asrun` (pinned to its own version) in the workspace `package.json`, so `pnpm install`
+installs the framework even without `--install`. When the install step itself fails — `pnpm` is not on `PATH`, the
+registry is unreachable, or a build script is not approved — `init` names the reason and stops before writing
+`.asrun.json`: fix the cause, run the `pnpm add -D @asrunjs/asrun` it prints, and run `pnpm asrun init` again.
+
 `pnpm go` then does the rest and is the command to remember:
 
 1. checks Node (22+) and ffmpeg, and warns when no AI CLI is installed;

package/docs/troubleshooting.md

@@ -95,6 +95,12 @@ project. Add `--reset-rules` to replace them with the template, and expect to lo
 `pnpm dlx @asrunjs/asrun init` first (it writes the `allowBuilds` entry), or add it to `pnpm-workspace.yaml` by hand;
 see [install.md](./install.md#manual-install).
 
+**`init` stopped and `.asrun.json` is missing** — the workspace files are written, but the `pnpm add -D
+@asrunjs/asrun` step failed, and `init` printed the reason (most often `pnpm` is not on `PATH`, or the registry
+refused the install). Run the command it prints, then `pnpm asrun init` again. Until then `pnpm asrun` and every
+script that calls `asrun` do not exist, and `pnpm asrun doctor` reports both the missing framework and the missing
+marker.
+
 **The AI did something you did not expect** — exploring and generating only read pages and edit the case file; healing
 edits the spec and runs it under the same write gate as any run (staging writes are allowed, any other environment
 needs a person's confirmation). None of them writes product data on its own, and none updates a baseline. If a step

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@asrunjs/asrun",
-  "version": "0.6.0",
+  "version": "0.6.1",
   "description": "Multi-profile end-to-end test suite: plain-language cases, AI-written Playwright specs, evidence for every run.",
   "license": "UNLICENSED",
   "author": "Zoro Chen",

package/templates/package.json

@@ -24,6 +24,7 @@
     "ui:dev": "asrun ui:dev"
   },
   "devDependencies": {
+    "@asrunjs/asrun": "{{asrun}}",
     "@playwright/test": "1.64.1",
     "@types/node": "^22.20.5",
     "typescript": "^7.0.2"