@e2edev/e2e 0.5.0 → 0.6.0

package/dist/cli/init/{backends.js → engines.js}

@@ -1,50 +1,59 @@
-/** CLI scaffold presets. Backend packages are referenced as generated source, never imported. */
+/** CLI scaffold presets. Engine packages are referenced as generated source, never imported. */
 import os from 'node:os';
+/** Engines version independently of the runner and pin the runner through their own peer range. */
+const ENGINE_RANGE = '0.x';
 /** Builds prompt choices and scaffolds with defaults for the machine running init. */
-export function getBackendPresets() {
+export function getEnginePresets() {
     const ios = os.platform() === 'darwin';
     return [
-        {
-            id: 'none',
-            label: 'None',
-            hint: 'HTTP tests or your own backend',
-            dependencies: {},
-            imports: [],
-            config: `  app: { url: process.env.APP_URL ?? 'http://localhost:3000' },
-  // Add a backend here when your tests need to drive an app.
-  targets: [{ name: 'default', platform: 'custom' }],`,
-            example: `import { test, expect } from '@e2edev/e2e';
-
-test('app responds', async () => {
-  const response = await fetch(process.env.APP_URL ?? 'http://localhost:3000');
-  expect(response.ok).toBe(true);
-});
-`,
-            runCommand: 'APP_URL=http://localhost:3000 npx --no-install e2e run',
-        },
         {
             id: 'playwright',
             label: 'Playwright',
             hint: 'browser testing',
-            dependencies: { '@e2edev/playwright': 'beta' },
+            dependencies: { '@e2edev/playwright': ENGINE_RANGE },
             imports: ["import { playwright } from '@e2edev/playwright';"],
-            config: `  app: { url: process.env.APP_URL ?? 'http://localhost:3000' },
-  targets: [{ name: 'web', platform: 'web', backend: playwright() }],`,
+            config: `  // The engine declares the app it drives; APP_URL overrides the default at run time.
+  targets: [{
+    name: 'web',
+    platform: 'web',
+    engine: playwright({
+      url: process.env.APP_URL ?? 'http://localhost:3000',
+      // Let the runner start the dev server and wait for url to answer:
+      // command: { executable: 'npm', args: ['run', 'dev'] },
+    }),
+  }],`,
             example: `import { test } from '@e2edev/playwright';
 import { expect } from '@e2edev/e2e';
 
 test('app opens', async ({ app, web }) => {
-  await app.open();
-  await expect(web).toHaveURL('/');
+  await app.open('/');
+  await expect(web.locator('body')).toBeVisible();
 });
 `,
             aiExample: `
 // Runs when E2E_MODEL and E2E_MODEL_API_KEY are set:
 // test('the agent drives a flow', async ({ app, agent }) => {
-//   await app.open();
+//   await app.open('/');
 //   await agent.act('one goal in plain language');
 //   await agent.assert('one question about the screen');
 // });
+`,
+            runCommand: 'APP_URL=http://localhost:3000 npx --no-install e2e run',
+        },
+        {
+            id: 'none',
+            label: 'None',
+            hint: 'HTTP tests or your own engine',
+            dependencies: {},
+            imports: [],
+            config: `  // Add an engine here when your tests need to drive an app.
+  targets: [{ name: 'default', platform: 'custom' }],`,
+            example: `import { test, expect } from '@e2edev/e2e';
+
+test('app responds', async () => {
+  const response = await fetch(process.env.APP_URL ?? 'http://localhost:3000');
+  expect(response.ok).toBe(true);
+});
 `,
             runCommand: 'APP_URL=http://localhost:3000 npx --no-install e2e run',
         },
@@ -52,14 +61,14 @@ test('app opens', async ({ app, web }) => {
             id: 'agent-device',
             label: 'agent-device',
             hint: 'mobile testing: iOS and Android',
-            dependencies: { '@e2edev/agent-device': 'beta' },
+            dependencies: { '@e2edev/agent-device': ENGINE_RANGE },
             imports: ["import { agentDevice } from '@e2edev/agent-device';"],
             config: ios
                 ? `  // Requires Xcode and an iOS simulator. Replace Settings with your app's bundle ID.
-  targets: [{ name: 'ios', platform: 'ios', backend: agentDevice({ platform: 'ios', app: 'Settings' }) }],
+  targets: [{ name: 'ios', platform: 'ios', engine: agentDevice({ platform: 'ios', app: 'Settings' }) }],
   workers: 1,`
                 : `  // Requires the Android SDK and an emulator. Replace com.android.settings with your app's package.
-  targets: [{ name: 'android', platform: 'android', backend: agentDevice({ platform: 'android', app: 'com.android.settings' }) }],
+  targets: [{ name: 'android', platform: 'android', engine: agentDevice({ platform: 'android', app: 'com.android.settings' }) }],
   workers: 1,`,
             example: `import { test } from '@e2edev/agent-device';
 import { expect } from '@e2edev/e2e';
@@ -87,12 +96,12 @@ test('Settings opens', async ({ screen }) => {
         },
     ];
 }
-export const DEFAULT_BACKEND_ID = 'none';
+export const DEFAULT_ENGINE_ID = 'playwright';
 /** Resolves a preset with the common shape used by scaffold generation. */
-export function getBackendPreset(id) {
-    const preset = getBackendPresets().find((entry) => entry.id === id);
+export function getEnginePreset(id) {
+    const preset = getEnginePresets().find((entry) => entry.id === id);
     if (preset === undefined)
-        throw new Error(`unknown backend: ${id}`);
+        throw new Error(`unknown engine: ${id}`);
     return preset;
 }
-//# sourceMappingURL=backends.js.map
+//# sourceMappingURL=engines.js.map

package/dist/cli/init/engines.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"engines.js","sourceRoot":"","sources":["../../../src/cli/init/engines.ts"],"names":[],"mappings":"AAAA,gGAAgG;AAEhG,OAAO,EAAE,MAAM,SAAS,CAAC;AAczB,mGAAmG;AACnG,MAAM,YAAY,GAAG,KAAK,CAAC;AAE3B,sFAAsF;AACtF,MAAM,UAAU,gBAAgB;IAC9B,MAAM,GAAG,GAAG,EAAE,CAAC,QAAQ,EAAE,KAAK,QAAQ,CAAC;IACvC,OAAO;QACL;YACE,EAAE,EAAE,YAAY;YAChB,KAAK,EAAE,YAAY;YACnB,IAAI,EAAE,iBAAiB;YACvB,YAAY,EAAE,EAAE,oBAAoB,EAAE,YAAY,EAAE;YACpD,OAAO,EAAE,CAAC,kDAAkD,CAAC;YAC7D,MAAM,EAAE;;;;;;;;;MASR;YACA,OAAO,EAAE;;;;;;;CAOd;YACK,SAAS,EAAE;;;;;;;CAOhB;YACK,UAAU,EAAE,wDAAwD;SACrE;QACD;YACE,EAAE,EAAE,MAAM;YACV,KAAK,EAAE,MAAM;YACb,IAAI,EAAE,+BAA+B;YACrC,YAAY,EAAE,EAAE;YAChB,OAAO,EAAE,EAAE;YACX,MAAM,EAAE;sDACwC;YAChD,OAAO,EAAE;;;;;;CAMd;YACK,UAAU,EAAE,wDAAwD;SACrE;QACD;YACE,EAAE,EAAE,cAAc;YAClB,KAAK,EAAE,cAAc;YACrB,IAAI,EAAE,iCAAiC;YACvC,YAAY,EAAE,EAAE,sBAAsB,EAAE,YAAY,EAAE;YACtD,OAAO,EAAE,CAAC,qDAAqD,CAAC;YAChE,MAAM,EAAE,GAAG;gBACT,CAAC,CAAC;;cAEI;gBACN,CAAC,CAAC;;cAEI;YACR,OAAO,EAAE;;;;iBAIE,GAAG,CAAC,CAAC,CAAC,iDAAiD,CAAC,CAAC,CAAC,wCAAwC;;CAElH;YACK,SAAS,EAAE,GAAG;gBACZ,CAAC,CAAC;;;;;;CAMT;gBACO,CAAC,CAAC;;;;;;CAMT;YACK,UAAU,EAAE,0BAA0B;SACvC;KACyC,CAAC;AAC/C,CAAC;AAGD,MAAM,CAAC,MAAM,iBAAiB,GAAG,YAA+B,CAAC;AAEjE,2EAA2E;AAC3E,MAAM,UAAU,eAAe,CAAC,EAAY;IAC1C,MAAM,MAAM,GAAG,gBAAgB,EAAE,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC;IACnE,IAAI,MAAM,KAAK,SAAS;QAAE,MAAM,IAAI,KAAK,CAAC,mBAAmB,EAAE,EAAE,CAAC,CAAC;IACnE,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/cli/init/package.d.ts

@@ -1,4 +1,4 @@
-/** package.json reading, dependency additions, and package-manager detection for `e2e init`. */
+/** package.json reading and dependency additions for `e2e init`. */
 import { z } from 'zod';
 declare const packageSchema: z.ZodObject<{
     dependencies: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
@@ -6,6 +6,7 @@ declare const packageSchema: z.ZodObject<{
     peerDependencies: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
     optionalDependencies: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
     packageManager: z.ZodOptional<z.ZodString>;
+    scripts: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
 }, z.core.$loose>;
 type PackageManifest = z.infer<typeof packageSchema>;
 /**
@@ -21,8 +22,11 @@ export declare function readPackage(cwd: string): {
         peerDependencies?: Record<string, string> | undefined;
         optionalDependencies?: Record<string, string> | undefined;
         packageManager?: string | undefined;
+        scripts?: Record<string, string> | undefined;
     };
 };
+/** Why a manifest failed to read: the JSON parser's own position, or the field that has the wrong shape. */
+export declare function describeManifestError(cause: unknown): string;
 /** Adds only missing dependencies to devDependencies and returns what was added. */
 export declare function addDependencies(manifest: PackageManifest, dependencies: Readonly<Record<string, string>>): {
     manifest: {
@@ -32,11 +36,23 @@ export declare function addDependencies(manifest: PackageManifest, dependencies:
         peerDependencies?: Record<string, string> | undefined;
         optionalDependencies?: Record<string, string> | undefined;
         packageManager?: string | undefined;
+        scripts?: Record<string, string> | undefined;
+    };
+    additions: [string, string][];
+};
+/** Adds only missing scripts and returns what was added. */
+export declare function addScripts(manifest: PackageManifest, scripts: Readonly<Record<string, string>>): {
+    manifest: {
+        [x: string]: unknown;
+        dependencies?: Record<string, string> | undefined;
+        devDependencies?: Record<string, string> | undefined;
+        peerDependencies?: Record<string, string> | undefined;
+        optionalDependencies?: Record<string, string> | undefined;
+        packageManager?: string | undefined;
+        scripts?: Record<string, string> | undefined;
     };
     additions: [string, string][];
 };
-/** The `packageManager` field wins, then a lockfile, then the manager that invoked the CLI, then npm. */
-export declare function detectPackageManager(cwd: string, manifest: PackageManifest): string;
 /** Serializes with the original manifest's indentation and newline convention. */
 export declare function serializePackage(manifest: PackageManifest, original: string | undefined): string;
 export {};

package/dist/cli/init/package.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"package.d.ts","sourceRoot":"","sources":["../../../src/cli/init/package.ts"],"names":[],"mappings":"AAAA,gGAAgG;AAIhG,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,QAAA,MAAM,aAAa;;;;;;iBAMjB,CAAC;AACH,KAAK,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAC;AAWrD;;;GAGG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM;;;;;;;;;;EAKtC;AAQD,oFAAoF;AACpF,wBAAgB,eAAe,CAAC,QAAQ,EAAE,eAAe,EAAE,YAAY,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;;;;;;;;;;EAOxG;AAED,yGAAyG;AACzG,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,eAAe,GAAG,MAAM,CAQnF;AAED,kFAAkF;AAClF,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,eAAe,EAAE,QAAQ,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAIhG"}
+{"version":3,"file":"package.d.ts","sourceRoot":"","sources":["../../../src/cli/init/package.ts"],"names":[],"mappings":"AAAA,oEAAoE;AAIpE,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,QAAA,MAAM,aAAa;;;;;;;iBAOjB,CAAC;AACH,KAAK,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAC;AAErD;;;GAGG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM;;;;;;;;;;;EAKtC;AAED,4GAA4G;AAC5G,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAO5D;AAQD,oFAAoF;AACpF,wBAAgB,eAAe,CAAC,QAAQ,EAAE,eAAe,EAAE,YAAY,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;;;;;;;;;;;EAOxG;AAED,4DAA4D;AAC5D,wBAAgB,UAAU,CAAC,QAAQ,EAAE,eAAe,EAAE,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;;;;;;;;;;;EAO9F;AAED,kFAAkF;AAClF,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,eAAe,EAAE,QAAQ,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAIhG"}

package/dist/cli/init/package.js

@@ -1,4 +1,4 @@
-/** package.json reading, dependency additions, and package-manager detection for `e2e init`. */
+/** package.json reading and dependency additions for `e2e init`. */
 import { existsSync, readFileSync } from 'node:fs';
 import path from 'node:path';
 import { z } from 'zod';
@@ -9,15 +9,8 @@ const packageSchema = z.looseObject({
     peerDependencies: dependencyBlock,
     optionalDependencies: dependencyBlock,
     packageManager: z.string().optional(),
+    scripts: z.record(z.string(), z.string()).optional(),
 });
-const PACKAGE_MANAGERS = new Set(['npm', 'pnpm', 'yarn', 'bun']);
-const LOCKFILES = [
-    ['pnpm-lock.yaml', 'pnpm'],
-    ['yarn.lock', 'yarn'],
-    ['bun.lock', 'bun'],
-    ['bun.lockb', 'bun'],
-    ['package-lock.json', 'npm'],
-];
 /**
  * Reads and validates the manifest, keeping its original text so edits can
  * preserve formatting. A missing manifest starts as a private ESM package.
@@ -28,6 +21,15 @@ export function readPackage(cwd) {
     const manifest = packageSchema.parse(original === undefined ? { private: true, type: 'module' } : JSON.parse(original));
     return { original, manifest };
 }
+/** Why a manifest failed to read: the JSON parser's own position, or the field that has the wrong shape. */
+export function describeManifestError(cause) {
+    if (cause instanceof z.ZodError) {
+        return cause.issues
+            .map((issue) => `${issue.path.length === 0 ? 'package.json' : issue.path.join('.')}: ${issue.message}`)
+            .join('; ');
+    }
+    return cause instanceof Error ? cause.message : String(cause);
+}
 /** True when any dependency section lists `name`, so existing versions and workspace links are kept. */
 function declaresDependency(manifest, name) {
     return [manifest.dependencies, manifest.devDependencies, manifest.peerDependencies, manifest.optionalDependencies]
@@ -43,17 +45,15 @@ export function addDependencies(manifest, dependencies) {
         additions,
     };
 }
-/** The `packageManager` field wins, then a lockfile, then the manager that invoked the CLI, then npm. */
-export function detectPackageManager(cwd, manifest) {
-    const configured = manifest.packageManager?.split('@')[0];
-    if (configured !== undefined && PACKAGE_MANAGERS.has(configured))
-        return configured;
-    for (const [lock, manager] of LOCKFILES) {
-        if (existsSync(path.join(cwd, lock)))
-            return manager;
-    }
-    const invoking = process.env['npm_config_user_agent']?.split('/')[0];
-    return invoking !== undefined && PACKAGE_MANAGERS.has(invoking) ? invoking : 'npm';
+/** Adds only missing scripts and returns what was added. */
+export function addScripts(manifest, scripts) {
+    const additions = Object.entries(scripts).filter(([name]) => manifest.scripts?.[name] === undefined);
+    if (additions.length === 0)
+        return { manifest, additions };
+    return {
+        manifest: { ...manifest, scripts: { ...manifest.scripts, ...Object.fromEntries(additions) } },
+        additions,
+    };
 }
 /** Serializes with the original manifest's indentation and newline convention. */
 export function serializePackage(manifest, original) {

package/dist/cli/init/package.js.map

@@ -1 +1 @@
-{"version":3,"file":"package.js","sourceRoot":"","sources":["../../../src/cli/init/package.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"package.js","sourceRoot":"","sources":["../../../src/cli/init/package.ts"],"names":[],"mappings":"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"}

package/dist/cli/init/scaffold.d.ts

@@ -1,6 +1,6 @@
-import { type BackendId } from './backends.ts';
-/** Composes common setup, the selected backend, and optional AI support. */
-export declare function createScaffold(backendId: BackendId, ai: boolean): {
+import { type EngineId } from './engines.ts';
+/** Composes common setup, the selected engine, and optional AI support. */
+export declare function createScaffold(engineId: EngineId, ai: boolean): {
     dependencies: {
         '@e2edev/e2e': string;
         ai?: string;

package/dist/cli/init/scaffold.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"scaffold.d.ts","sourceRoot":"","sources":["../../../src/cli/init/scaffold.ts"],"names":[],"mappings":"AACA,OAAO,EAAoB,KAAK,SAAS,EAAE,MAAM,eAAe,CAAC;AAQjE,4EAA4E;AAC5E,wBAAgB,cAAc,CAAC,SAAS,EAAE,SAAS,EAAE,EAAE,EAAE,OAAO;;;;;;;;EA2B/D"}
+{"version":3,"file":"scaffold.d.ts","sourceRoot":"","sources":["../../../src/cli/init/scaffold.ts"],"names":[],"mappings":"AACA,OAAO,EAAmB,KAAK,QAAQ,EAAE,MAAM,cAAc,CAAC;AAS9D,2EAA2E;AAC3E,wBAAgB,cAAc,CAAC,QAAQ,EAAE,QAAQ,EAAE,EAAE,EAAE,OAAO;;;;;;;;EA2B7D"}

package/dist/cli/init/scaffold.js

@@ -1,36 +1,37 @@
 import { packageVersion } from '../../internal/package-version.js';
-import { getBackendPreset } from './backends.js';
+import { getEnginePreset } from './engines.js';
 const AGENT_IMPORT = "import { createAgent } from '@e2edev/e2e/agent';";
 const AGENT_CONFIG = `  // The model comes from E2E_MODEL; authenticate with E2E_MODEL_API_KEY.
+  // To call a provider directly, pass an AI SDK model: createAgent({ model: openai('gpt-5.4-mini') }).
   agent: createAgent({
     system: 'You are a thorough QA agent. Verify every outcome.',
   }),`;
-/** Composes common setup, the selected backend, and optional AI support. */
-export function createScaffold(backendId, ai) {
-    const backend = getBackendPreset(backendId);
+/** Composes common setup, the selected engine, and optional AI support. */
+export function createScaffold(engineId, ai) {
+    const engine = getEnginePreset(engineId);
     const imports = [
-        "import { defineConfig } from '@e2edev/e2e';",
+        "import type { E2EConfig } from '@e2edev/e2e';",
         ...(ai ? [AGENT_IMPORT] : []),
-        ...backend.imports,
+        ...engine.imports,
     ];
     const configFields = [
         ...(ai ? [AGENT_CONFIG] : []),
-        backend.config,
+        engine.config,
     ];
     return {
         dependencies: {
             '@e2edev/e2e': `^${packageVersion(import.meta.url, '../../../package.json', '0.0.0')}`,
-            ...backend.dependencies,
+            ...engine.dependencies,
             ...(ai ? { ai: '^7.0.0' } : {}),
         },
         config: `${imports.join('\n')}
 
-export default defineConfig({
+export default {
 ${configFields.join('\n')}
-});
+} satisfies E2EConfig;
 `,
-        example: backend.example + (ai ? backend.aiExample ?? '' : ''),
-        runCommand: backend.runCommand,
+        example: engine.example + (ai ? engine.aiExample ?? '' : ''),
+        runCommand: engine.runCommand,
     };
 }
 //# sourceMappingURL=scaffold.js.map

package/dist/cli/init/scaffold.js.map

@@ -1 +1 @@
-{"version":3,"file":"scaffold.js","sourceRoot":"","sources":["../../../src/cli/init/scaffold.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,mCAAmC,CAAC;AACnE,OAAO,EAAE,gBAAgB,EAAkB,MAAM,eAAe,CAAC;AAEjE,MAAM,YAAY,GAAG,kDAAkD,CAAC;AACxE,MAAM,YAAY,GAAG;;;MAGf,CAAC;AAEP,4EAA4E;AAC5E,MAAM,UAAU,cAAc,CAAC,SAAoB,EAAE,EAAW;IAC9D,MAAM,OAAO,GAAG,gBAAgB,CAAC,SAAS,CAAC,CAAC;IAC5C,MAAM,OAAO,GAAG;QACd,6CAA6C;QAC7C,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;QAC7B,GAAG,OAAO,CAAC,OAAO;KACnB,CAAC;IACF,MAAM,YAAY,GAAG;QACnB,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;QAC7B,OAAO,CAAC,MAAM;KACf,CAAC;IAEF,OAAO;QACL,YAAY,EAAE;YACZ,aAAa,EAAE,IAAI,cAAc,CAAC,OAAO,IAAI,CAAC,GAAG,EAAE,uBAAuB,EAAE,OAAO,CAAC,EAAE;YACtF,GAAG,OAAO,CAAC,YAAY;YACvB,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SAChC;QACD,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC;;;EAG/B,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC;;CAExB;QACG,OAAO,EAAE,OAAO,CAAC,OAAO,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,SAAS,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC9D,UAAU,EAAE,OAAO,CAAC,UAAU;KAC/B,CAAC;AACJ,CAAC"}
+{"version":3,"file":"scaffold.js","sourceRoot":"","sources":["../../../src/cli/init/scaffold.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,mCAAmC,CAAC;AACnE,OAAO,EAAE,eAAe,EAAiB,MAAM,cAAc,CAAC;AAE9D,MAAM,YAAY,GAAG,kDAAkD,CAAC;AACxE,MAAM,YAAY,GAAG;;;;MAIf,CAAC;AAEP,2EAA2E;AAC3E,MAAM,UAAU,cAAc,CAAC,QAAkB,EAAE,EAAW;IAC5D,MAAM,MAAM,GAAG,eAAe,CAAC,QAAQ,CAAC,CAAC;IACzC,MAAM,OAAO,GAAG;QACd,+CAA+C;QAC/C,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;QAC7B,GAAG,MAAM,CAAC,OAAO;KAClB,CAAC;IACF,MAAM,YAAY,GAAG;QACnB,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;QAC7B,MAAM,CAAC,MAAM;KACd,CAAC;IAEF,OAAO;QACL,YAAY,EAAE;YACZ,aAAa,EAAE,IAAI,cAAc,CAAC,OAAO,IAAI,CAAC,GAAG,EAAE,uBAAuB,EAAE,OAAO,CAAC,EAAE;YACtF,GAAG,MAAM,CAAC,YAAY;YACtB,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SAChC;QACD,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC;;;EAG/B,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC;;CAExB;QACG,OAAO,EAAE,MAAM,CAAC,OAAO,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,SAAS,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC5D,UAAU,EAAE,MAAM,CAAC,UAAU;KAC9B,CAAC;AACJ,CAAC"}

package/dist/cli/init.d.ts

@@ -1,11 +1,23 @@
-/** Non-destructive project scaffolding (spec 06-cli.md). */
+/** Non-destructive project scaffolding. */
 export interface InitOptions {
     yes?: boolean;
+    /**
+     * The directory argument as the user typed it, when `cwd` was chosen from
+     * one; the closing `next:` line then starts with `cd` into it.
+     */
+    directory?: string;
+    /**
+     * Whether prompts can be answered. The CLI passes its terminal state; a
+     * non-interactive run without `--yes` stops before asking anything, since
+     * a prompt nobody can answer would otherwise wait forever.
+     */
+    interactive?: boolean;
 }
 /**
  * Runs `e2e init`. Every prompt happens before the first write, existing
  * config and test files are never touched, and dependencies install only when
- * the user asks.
+ * the user asks. The agent skill is offered once; later runs refresh the
+ * copies that exist and never add new locations.
  */
 export declare function init(cwd: string, options?: InitOptions): Promise<number>;
 //# sourceMappingURL=init.d.ts.map

package/dist/cli/init.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../src/cli/init.ts"],"names":[],"mappings":"AAAA,4DAA4D;AAW5D,MAAM,WAAW,WAAW;IAC1B,GAAG,CAAC,EAAE,OAAO,CAAC;CACf;AAYD;;;;GAIG;AACH,wBAAsB,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,GAAE,WAAgB,GAAG,OAAO,CAAC,MAAM,CAAC,CAsGlF"}
+{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../src/cli/init.ts"],"names":[],"mappings":"AAAA,2CAA2C;AAgB3C,MAAM,WAAW,WAAW;IAC1B,GAAG,CAAC,EAAE,OAAO,CAAC;IACd;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAiBD;;;;;GAKG;AACH,wBAAsB,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,GAAE,WAAgB,GAAG,OAAO,CAAC,MAAM,CAAC,CAoKlF"}

package/dist/cli/init.js

@@ -1,34 +1,56 @@
-/** Non-destructive project scaffolding (spec 06-cli.md). */
+/** Non-destructive project scaffolding. */
 import * as clack from '@clack/prompts';
 import { spawnSync } from 'node:child_process';
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import os from 'node:os';
 import path from 'node:path';
 import { esmPackageHint } from '../config/esm.js';
-import { getBackendPresets, DEFAULT_BACKEND_ID } from './init/backends.js';
-import { addDependencies, detectPackageManager, readPackage, serializePackage } from './init/package.js';
+import { detectPackageManager } from '../internal/package-manager.js';
+import { DOCS_URL } from './docs-url.js';
+import { findInstalledSkillDirs, planSkillInstall, SKILL_LOCATIONS } from './init/agent-skill.js';
+import { getEnginePresets, DEFAULT_ENGINE_ID } from './init/engines.js';
+import { addDependencies, addScripts, describeManifestError, readPackage, serializePackage } from './init/package.js';
 import { createScaffold } from './init/scaffold.js';
+import { MISSING_SKILL_MESSAGE, readSkillFiles } from './skill.js';
+const CACHE_IGNORE_ENTRY = '.e2e/cache/';
 const GITIGNORE_ENTRIES = [
     'node_modules/',
     '.e2e/artifacts/',
-    '.e2e/cache/',
+    CACHE_IGNORE_ENTRY,
     '.e2e/sessions/',
     '.e2e/report.json',
     '.e2e/ai-trace.json',
     '.e2e/junit.xml',
+    '.e2e/logs/',
 ];
+const SCRIPTS = { 'test:e2e': 'e2e run' };
 /**
  * Runs `e2e init`. Every prompt happens before the first write, existing
  * config and test files are never touched, and dependencies install only when
- * the user asks.
+ * the user asks. The agent skill is offered once; later runs refresh the
+ * copies that exist and never add new locations.
  */
 export async function init(cwd, options = {}) {
-    clack.intro('e2e init');
+    clack.intro(options.directory === undefined ? 'e2e init' : `e2e init ${options.directory}`);
+    if (options.interactive === false && !options.yes) {
+        clack.log.error('e2e init asks questions and needs an interactive terminal; run it from a terminal, or pass --yes to accept the defaults (Playwright, AI on, no installation)');
+        return 2;
+    }
+    if (existsSync(cwd) && !statSync(cwd).isDirectory()) {
+        clack.log.error(`${options.directory ?? cwd} is a file, not a directory`);
+        return 2;
+    }
     let pkg;
     try {
         pkg = readPackage(cwd);
     }
-    catch {
-        clack.log.error('invalid package.json; fix it before running e2e init');
+    catch (cause) {
+        clack.log.error(`${path.join(cwd, 'package.json')} could not be read: ${describeManifestError(cause)}; fix it before running e2e init`);
+        return 2;
+    }
+    const bundledSkill = readSkillFiles();
+    if (bundledSkill.length === 0) {
+        clack.log.error(MISSING_SKILL_MESSAGE);
         return 2;
     }
     const existingConfig = ['e2e.config.ts', 'e2e.config.mts'].find((file) => existsSync(path.join(cwd, file)));
@@ -47,49 +69,73 @@ export async function init(cwd, options = {}) {
     const existingIgnore = existsSync(gitignorePath) ? readFileSync(gitignorePath, 'utf8') : '';
     const ignoreLines = existingIgnore.split(/\r?\n/);
     const missingIgnore = GITIGNORE_ENTRIES.filter((entry) => !ignoreLines.includes(entry));
-    // Backend and AI are choices for a new config only; an existing config keeps its own dependencies.
-    let backend = DEFAULT_BACKEND_ID;
+    // Engine and AI are choices for a new config only; an existing config keeps its own dependencies.
+    let engine = existingConfig === undefined ? DEFAULT_ENGINE_ID : 'none';
     let ai = existingConfig === undefined;
     if (existingConfig === undefined && !options.yes) {
-        const selectedBackend = await clack.select({
-            message: 'Which backend?',
-            initialValue: DEFAULT_BACKEND_ID,
-            options: getBackendPresets().map(({ id, label, hint }) => ({ value: id, label, hint })),
+        const selectedEngine = await clack.select({
+            message: 'Which engine?',
+            initialValue: DEFAULT_ENGINE_ID,
+            options: getEnginePresets().map(({ id, label, hint }) => ({ value: id, label, hint })),
         });
-        if (clack.isCancel(selectedBackend))
+        if (clack.isCancel(selectedEngine))
             return cancelled();
-        backend = selectedBackend;
+        engine = selectedEngine;
         const enableAi = await clack.confirm({ message: 'Enable AI testing? Adds AI SDK v7.', initialValue: true });
         if (clack.isCancel(enableAi))
             return cancelled();
         ai = enableAi;
     }
-    const scaffold = createScaffold(backend, ai);
-    const { manifest, additions } = addDependencies(pkg.manifest, scaffold.dependencies);
-    if (additions.length > 0) {
-        clack.log.info(`add dev dependencies: ${additions.map(([name, version]) => `${name}@${version}`).join(', ')}`);
+    // The skill goes where an earlier run put it; a project without one chooses.
+    let skillDirs = findInstalledSkillDirs(cwd);
+    if (skillDirs.length === 0) {
+        if (options.yes) {
+            skillDirs = SKILL_LOCATIONS.map((location) => location.dir);
+        }
+        else {
+            const selected = await clack.multiselect({
+                message: 'Install the e2e skill for coding agents?',
+                options: SKILL_LOCATIONS.map(({ dir, hint }) => ({ value: dir, label: dir, hint })),
+                initialValues: SKILL_LOCATIONS.map((location) => location.dir),
+                required: false,
+            });
+            if (clack.isCancel(selected))
+                return cancelled();
+            skillDirs = selected;
+        }
+    }
+    const skillInstalls = planSkillInstall(cwd, skillDirs, bundledSkill);
+    const scaffold = createScaffold(engine, ai);
+    const dependencies = addDependencies(pkg.manifest, scaffold.dependencies);
+    const { manifest, additions: scripts } = addScripts(dependencies.manifest, SCRIPTS);
+    if (dependencies.additions.length > 0) {
+        clack.log.info(`add dev dependencies: ${dependencies.additions.map(([name, version]) => `${name}@${version}`).join(', ')}`);
+    }
+    if (scripts.length > 0) {
+        clack.log.info(`add scripts: ${scripts.map(([name, command]) => `${name} (${command})`).join(', ')}`);
     }
     const files = [
-        ...(pkg.original === undefined || additions.length > 0
+        ...(pkg.original === undefined || dependencies.additions.length > 0 || scripts.length > 0
             ? [{ relative: 'package.json', content: serializePackage(manifest, pkg.original), existing: pkg.original !== undefined }]
             : []),
         ...(existingConfig === undefined ? [{ relative: 'e2e.config.ts', content: scaffold.config, existing: false }] : []),
         ...(exampleExists ? [] : [{ relative: examplePath, content: scaffold.example, existing: false }]),
     ];
-    if (files.length === 0 && missingIgnore.length === 0) {
+    if (files.length === 0 && skillInstalls.length === 0 && missingIgnore.length === 0) {
         clack.outro('nothing to create; project already initialized');
         return 0;
     }
     if (!options.yes) {
         const actions = [
             ...files.map((file) => `${file.existing ? 'update' : 'create'} ${file.relative}`),
+            ...skillInstalls.map((install) => `${install.existing ? 'update' : 'create'} ${install.relative}/`),
             ...(missingIgnore.length > 0 ? ['update .gitignore'] : []),
         ];
         const proceed = await clack.confirm({ message: `${actions.join(', ')}?` });
         if (clack.isCancel(proceed) || !proceed)
             return cancelled();
     }
-    const manager = detectPackageManager(cwd, manifest);
+    const manager = detectPackageManager(cwd, manifest.packageManager);
     let install = false;
     if (!options.yes) {
         const selected = await clack.confirm({ message: `Install dependencies with ${manager}?`, initialValue: true });
@@ -97,16 +143,31 @@ export async function init(cwd, options = {}) {
             return cancelled();
         install = selected;
     }
+    // The first write; a directory named on the command line comes into being here.
+    mkdirSync(cwd, { recursive: true });
     for (const file of files) {
         const absolute = path.join(cwd, file.relative);
         mkdirSync(path.dirname(absolute), { recursive: true });
         writeFileSync(absolute, file.content, 'utf8');
         clack.log.success(`${file.existing ? 'updated' : 'created'} ${file.relative}`);
     }
+    for (const skill of skillInstalls) {
+        for (const file of skill.files) {
+            mkdirSync(path.dirname(file.absolute), { recursive: true });
+            writeFileSync(file.absolute, file.content, 'utf8');
+        }
+        clack.log.success(`${skill.existing ? 'updated' : 'created'} ${skill.relative}/ (${skill.files.length} files)`);
+    }
+    if (skillDirs.length === 0) {
+        clack.log.info('skipped the agent skill; agents can still print it with npx --no-install e2e guide');
+    }
     if (missingIgnore.length > 0) {
         const prefix = existingIgnore === '' || existingIgnore.endsWith('\n') ? '' : '\n';
         writeFileSync(gitignorePath, `${existingIgnore}${prefix}${missingIgnore.join('\n')}\n`, 'utf8');
         clack.log.success(`updated .gitignore (${missingIgnore.length} entries)`);
+        if (missingIgnore.includes(CACHE_IGNORE_ENTRY)) {
+            clack.log.info(`${CACHE_IGNORE_ENTRY} is ignored; committing agent.act replays is opt-in, see ${DOCS_URL}/reference/config#commit-your-traces`);
+        }
     }
     if (install) {
         const result = spawnSync(manager, ['install'], { cwd, stdio: 'inherit', shell: process.platform === 'win32' });
@@ -117,9 +178,27 @@ export async function init(cwd, options = {}) {
             return result.signal === 'SIGINT' ? 130 : 2;
         }
     }
-    clack.outro(`next: ${install ? '' : `${manager} install, then `}${scaffold.runCommand}`);
+    if (!existsSync(path.join(cwd, 'tsconfig.json'))) {
+        clack.log.info('no tsconfig.json; add one for editor completions on e2e.config.ts and tests/');
+    }
+    const next = [
+        options.directory === undefined ? undefined : `cd ${shellArgument(options.directory)}`,
+        install ? undefined : `${manager} install`,
+        scaffold.runCommand,
+    ].filter((step) => step !== undefined);
+    clack.outro(`next: ${next.join(', then ')}`);
     return 0;
 }
+/**
+ * A path as the user will paste it into their shell: bare while every character
+ * is safe, otherwise quoted for the platform (single quotes for POSIX shells,
+ * double quotes for cmd and PowerShell), so `apps/my web` stays one argument.
+ */
+function shellArgument(value) {
+    if (/^[A-Za-z0-9_./@%+=:,-]+$/.test(value))
+        return value;
+    return os.platform() === 'win32' ? `"${value.replaceAll('"', '""')}"` : `'${value.replaceAll("'", "'\\''")}'`;
+}
 /** Cancellation is only reachable before the first write, so nothing needs undoing. */
 function cancelled() {
     clack.cancel('cancelled; no changes were made');