@pikku/cli 0.12.89 → 0.12.91

package/dist/src/fabric/lib/frontend-typecheck.d.ts

@@ -0,0 +1,46 @@
+export interface FrontendTypeCheckResult {
+    /** fabric.config.json frontend key, e.g. "app" */
+    name: string;
+    /** absolute directory that was type-checked */
+    dir: string;
+    /**
+     * The invocation that actually ran, e.g. `yarn run tsc` or `npx tsc --noEmit`.
+     * A finding tells the user to reproduce it, so it has to be the command this
+     * check chose — not a guess at their package manager.
+     */
+    command: string;
+    /** raw `file(line,col): error TSxxxx: message` lines, in tsc's order */
+    errors: string[];
+    /** set when the frontend could not be checked at all (no tsconfig, tsc missing) */
+    skipped?: string;
+}
+/**
+ * Run each deployable frontend's type-check exactly as the Fabric build
+ * container does, so a type error fails `fabric validate` on the developer's
+ * machine instead of eight minutes into a deploy.
+ *
+ * The container runs the frontend's own `tsc` script (falling back to
+ * `tsc --noEmit`) and aborts the deploy on a non-zero exit; the deploy budget
+ * is 10/day, so spending one on a TS2353 is expensive. Everything else in
+ * validate is a structural heuristic *approximating* this compile — this is the
+ * compile.
+ */
+export declare function typeCheckFrontends(root: string, frontendDirs: Array<{
+    name: string;
+    dir: string;
+}>): Promise<FrontendTypeCheckResult[]>;
+/**
+ * The frontend's own `tsc` script when it has one — that is what the build
+ * container runs — otherwise `tsc --noEmit` through the project's package
+ * manager, so the compiler resolved is the workspace-local one.
+ */
+export declare function resolveTypeCheckCommand(root: string, dir: string): Promise<{
+    command: string;
+    args: string[];
+}>;
+/**
+ * Keep only tsc's diagnostic lines. The runner wraps the command with its own
+ * chatter ("$ tsc --noEmit", "error Command failed with exit code 2"), which is
+ * noise in a finding.
+ */
+export declare function parseTscErrors(output: string): string[];

package/dist/src/fabric/lib/frontend-typecheck.js

@@ -0,0 +1,139 @@
+import { spawn } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+/**
+ * Run each deployable frontend's type-check exactly as the Fabric build
+ * container does, so a type error fails `fabric validate` on the developer's
+ * machine instead of eight minutes into a deploy.
+ *
+ * The container runs the frontend's own `tsc` script (falling back to
+ * `tsc --noEmit`) and aborts the deploy on a non-zero exit; the deploy budget
+ * is 10/day, so spending one on a TS2353 is expensive. Everything else in
+ * validate is a structural heuristic *approximating* this compile — this is the
+ * compile.
+ */
+export async function typeCheckFrontends(root, frontendDirs) {
+    const results = [];
+    for (const { name, dir } of frontendDirs) {
+        const { command, args } = await resolveTypeCheckCommand(root, dir);
+        const invocation = [command, ...args].join(' ');
+        if (!existsSync(join(dir, 'tsconfig.json'))) {
+            results.push({
+                name,
+                dir,
+                command: invocation,
+                errors: [],
+                skipped: 'no tsconfig.json',
+            });
+            continue;
+        }
+        const { code, output, spawnError } = await run(command, args, dir);
+        if (spawnError) {
+            results.push({
+                name,
+                dir,
+                command: invocation,
+                errors: [],
+                skipped: spawnError,
+            });
+            continue;
+        }
+        results.push({
+            name,
+            dir,
+            command: invocation,
+            errors: code === 0 ? [] : parseTscErrors(output),
+        });
+    }
+    return results;
+}
+/**
+ * The frontend's own `tsc` script when it has one — that is what the build
+ * container runs — otherwise `tsc --noEmit` through the project's package
+ * manager, so the compiler resolved is the workspace-local one.
+ */
+export async function resolveTypeCheckCommand(root, dir) {
+    const pkg = await readPackageJson(dir);
+    const runner = await resolveRunner(root, dir);
+    return pkg?.scripts?.tsc
+        ? { command: runner, args: ['run', 'tsc'] }
+        : { command: runner === 'npm' ? 'npx' : runner, args: ['tsc', '--noEmit'] };
+}
+async function readPackageJson(dir) {
+    try {
+        return JSON.parse(await readFile(join(dir, 'package.json'), 'utf-8'));
+    }
+    catch {
+        // A frontend without a readable package.json still gets checked via the
+        // `tsc --noEmit` fallback — the missing manifest is reported by other checks.
+        return null;
+    }
+}
+/**
+ * The package manager the project declares, so `run tsc` resolves the same
+ * workspace-local typescript the deploy would. Falls back to npm.
+ */
+async function resolveRunner(root, dir) {
+    for (const candidate of [dir, root]) {
+        const pkg = await readPackageJson(candidate);
+        const declared = pkg?.packageManager;
+        if (declared)
+            return declared.split('@')[0];
+    }
+    if (existsSync(join(root, 'bun.lock')) || existsSync(join(root, 'bun.lockb')))
+        return 'bun';
+    if (existsSync(join(root, 'yarn.lock')))
+        return 'yarn';
+    if (existsSync(join(root, 'pnpm-lock.yaml')))
+        return 'pnpm';
+    return 'npm';
+}
+function run(command, args, cwd) {
+    return new Promise((resolve) => {
+        let output = '';
+        const child = spawn(command, args, {
+            cwd,
+            shell: process.platform === 'win32',
+            env: { ...process.env, FORCE_COLOR: '0', NO_COLOR: '1' },
+        });
+        child.stdout?.on('data', (chunk) => {
+            output += chunk.toString();
+        });
+        child.stderr?.on('data', (chunk) => {
+            output += chunk.toString();
+        });
+        child.on('error', (error) => {
+            resolve({
+                code: 1,
+                output,
+                spawnError: error.code === 'ENOENT'
+                    ? `${command} not found on PATH`
+                    : error.message,
+            });
+        });
+        child.on('close', (code) => resolve({ code: code ?? 1, output }));
+    });
+}
+/**
+ * Keep only tsc's diagnostic lines. The runner wraps the command with its own
+ * chatter ("$ tsc --noEmit", "error Command failed with exit code 2"), which is
+ * noise in a finding.
+ */
+export function parseTscErrors(output) {
+    const diagnostic = /^\S.*?\(\d+,\d+\): (?:error|warning) TS\d+: /;
+    const errors = output
+        .split('\n')
+        .map((line) => line.trimEnd())
+        .filter((line) => diagnostic.test(line));
+    if (errors.length > 0)
+        return errors;
+    // A non-zero exit with no parseable diagnostic still failed the build — keep
+    // the tail rather than reporting a clean pass. A silent failure (no output at
+    // all) must still return something: an empty list here reads as "compiled
+    // fine" and lets the deploy the check exists to prevent go ahead.
+    const tail = output.trim().split('\n').slice(-5).filter(Boolean);
+    return tail.length > 0
+        ? tail
+        : ['type-check exited non-zero without producing any output'];
+}

package/dist/src/functions/commands/db-baseline.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Record the pending migrations as applied, without running them.
+ *
+ * For a database that already contains what they describe. The case it exists
+ * for is a schema that was created at boot and written down afterwards: every
+ * deployment already has those tables, so applying the migration fails, and
+ * leaving it pending forever means the history never catches up with reality.
+ *
+ * Refuses unless the database really is up to date, because that is the entire
+ * premise. A database that is behind gets the same report `db check` gives —
+ * baselining it would bury a real gap under a history claiming otherwise.
+ */
+export declare const dbBaseline: import("#pikku").PikkuFunctionConfig<{}, void, "rpc" | "session", import("#pikku").PikkuFunctionSessionless<{}, void, "rpc" | "session", import("#pikku").WiredServices> | import("#pikku").PikkuFunction<{}, void, "rpc" | "session", import("#pikku").WiredServices>, undefined, undefined>;

package/dist/src/functions/commands/db-baseline.js

@@ -0,0 +1,48 @@
+import { pikkuSessionlessFunc } from '#pikku';
+import { resolveDb, baseline } from '../db/local-db.js';
+import { loadUserConfigForDb } from './db-shared.js';
+/**
+ * Record the pending migrations as applied, without running them.
+ *
+ * For a database that already contains what they describe. The case it exists
+ * for is a schema that was created at boot and written down afterwards: every
+ * deployment already has those tables, so applying the migration fails, and
+ * leaving it pending forever means the history never catches up with reality.
+ *
+ * Refuses unless the database really is up to date, because that is the entire
+ * premise. A database that is behind gets the same report `db check` gives —
+ * baselining it would bury a real gap under a history claiming otherwise.
+ */
+export const dbBaseline = pikkuSessionlessFunc({
+    remote: true,
+    func: async ({ logger, config }) => {
+        const userConfig = await loadUserConfigForDb({ config, logger });
+        if (!userConfig)
+            return;
+        const resolved = resolveDb(userConfig, config.rootDir, config.outDir, config.runtimeDir);
+        if (!resolved) {
+            logger.error('pikku db baseline: no database configured — set sqliteDb or postgresUrl in your createConfig.');
+            throw new Error('no database configured');
+        }
+        const result = await baseline(resolved, config.rootDir, config.srcDirectories, logger);
+        if (result.status === 'behind') {
+            logger.error('db baseline: refused — the database does not yet contain everything the migrations describe:');
+            if (result.drift.missingTables.length) {
+                logger.error(`  missing tables: ${result.drift.missingTables.join(', ')}`);
+            }
+            for (const { table, columns } of result.drift.missingColumns) {
+                logger.error(`  ${table} missing columns: ${columns.join(', ')}`);
+            }
+            logger.error('  Baselining now would record migrations that never ran. Run `pikku db migrate` instead.');
+            throw new Error('database is behind its migrations');
+        }
+        if (result.recorded.length === 0) {
+            logger.info('db baseline: nothing pending — every migration is recorded');
+            return;
+        }
+        logger.info(`db baseline: recorded ${result.recorded.length} migration(s) as applied without running them:`);
+        for (const name of result.recorded) {
+            logger.info(`  ${name}`);
+        }
+    },
+});

package/dist/src/functions/commands/db-check.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Report how the configured database differs from the schema its migrations
+ * define.
+ *
+ * Answers the question nobody can otherwise answer without going and looking by
+ * hand: does this database still match what we wrote down? Missing tables and
+ * columns fail the command — the database is behind and a migration has not
+ * been applied. Tables the migrations never mention are reported but never
+ * fail: something created them outside the migration history, which is worth
+ * seeing but is not this command's to fix.
+ */
+export declare const dbCheck: import("#pikku").PikkuFunctionConfig<{}, void, "rpc" | "session", import("#pikku").PikkuFunctionSessionless<{}, void, "rpc" | "session", import("#pikku").WiredServices> | import("#pikku").PikkuFunction<{}, void, "rpc" | "session", import("#pikku").WiredServices>, undefined, undefined>;

package/dist/src/functions/commands/db-check.js

@@ -0,0 +1,64 @@
+import { pikkuSessionlessFunc } from '#pikku';
+import { resolveDb, computeSchemaDrift } from '../db/local-db.js';
+import { loadUserConfigForDb } from './db-shared.js';
+/**
+ * Report how the configured database differs from the schema its migrations
+ * define.
+ *
+ * Answers the question nobody can otherwise answer without going and looking by
+ * hand: does this database still match what we wrote down? Missing tables and
+ * columns fail the command — the database is behind and a migration has not
+ * been applied. Tables the migrations never mention are reported but never
+ * fail: something created them outside the migration history, which is worth
+ * seeing but is not this command's to fix.
+ */
+export const dbCheck = pikkuSessionlessFunc({
+    remote: true,
+    func: async ({ logger, config }) => {
+        const userConfig = await loadUserConfigForDb({ config, logger });
+        if (!userConfig)
+            return;
+        const resolved = resolveDb(userConfig, config.rootDir, config.outDir, config.runtimeDir);
+        if (!resolved) {
+            logger.error('pikku db check: no database configured — set sqliteDb or postgresUrl in your createConfig.');
+            throw new Error('no database configured');
+        }
+        const drift = await computeSchemaDrift(resolved, config.rootDir, config.srcDirectories, logger);
+        // Table names elide the `public` schema, which reads as ambiguous in a
+        // report whose whole point can be a second copy of `app.orders` sitting in
+        // `public`. Put the schema back for display only.
+        const qualify = (table) => resolved.dialect === 'postgres' && !table.includes('.')
+            ? `public.${table}`
+            : table;
+        if (drift.runtimeTables.length) {
+            logger.info(`db check: ${drift.runtimeTables.length} table(s) the pikku runtime created at boot, which no migration records:`);
+            for (const table of drift.runtimeTables) {
+                logger.info(`  ${qualify(table)}`);
+            }
+            logger.info('  Run `pikku db generate` to write them down, so the schema stops depending on which services happened to start.');
+        }
+        if (drift.extraTables.length) {
+            logger.info(`db check: ${drift.extraTables.length} table(s) in the database that no migration creates:`);
+            for (const table of drift.extraTables) {
+                logger.info(`  ${qualify(table)}`);
+            }
+            logger.info('  Left alone — a migration cannot know whether these hold data worth keeping.');
+            for (const { schema, requires, owner } of drift.skippedRuntimeSchemas) {
+                logger.info(`  Note: the runtime's '${schema}' tables could not be recognised — it needs '${requires}', which this project does not create. ${owner} owns it.`);
+            }
+        }
+        if (drift.inSync) {
+            logger.info('db check: the database matches its migrations');
+            return;
+        }
+        logger.error('db check: the database is behind its migrations:');
+        if (drift.missingTables.length) {
+            logger.error(`  missing tables: ${drift.missingTables.map(qualify).join(', ')}`);
+        }
+        for (const { table, columns } of drift.missingColumns) {
+            logger.error(`  ${qualify(table)} missing columns: ${columns.join(', ')}`);
+        }
+        logger.error('  Run `pikku db migrate` to apply them.');
+        throw new Error('database schema is behind its migrations');
+    },
+});

package/dist/src/functions/commands/db-codegen.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Regenerate the database types from the migration files alone, without
+ * connecting to the configured database.
+ *
+ * `db migrate` can only emit types after it has migrated the real database,
+ * which forces codegen to run late — after a deploy has already moved the
+ * schema. This command applies the same migrations to a throwaway database and
+ * introspects that, so `pikku all` can be given an accurate table zod on a
+ * machine with no database reachable at all.
+ */
+export declare const dbCodegen: import("#pikku").PikkuFunctionConfig<{}, void, "rpc" | "session", import("#pikku").PikkuFunctionSessionless<{}, void, "rpc" | "session", import("#pikku").WiredServices> | import("#pikku").PikkuFunction<{}, void, "rpc" | "session", import("#pikku").WiredServices>, undefined, undefined>;

package/dist/src/functions/commands/db-codegen.js

@@ -0,0 +1,39 @@
+import { pikkuSessionlessFunc } from '#pikku';
+import { resolveDb, migrateAndCodegen } from '../db/local-db.js';
+import { loadUserConfigForDb } from './db-shared.js';
+/**
+ * Regenerate the database types from the migration files alone, without
+ * connecting to the configured database.
+ *
+ * `db migrate` can only emit types after it has migrated the real database,
+ * which forces codegen to run late — after a deploy has already moved the
+ * schema. This command applies the same migrations to a throwaway database and
+ * introspects that, so `pikku all` can be given an accurate table zod on a
+ * machine with no database reachable at all.
+ */
+export const dbCodegen = pikkuSessionlessFunc({
+    remote: true,
+    func: async ({ logger, config }) => {
+        const userConfig = await loadUserConfigForDb({ config, logger });
+        if (!userConfig)
+            return;
+        const resolved = resolveDb(userConfig, config.rootDir, config.outDir, config.runtimeDir);
+        if (!resolved) {
+            logger.error('pikku db codegen: no database configured — set sqliteDb or postgresUrl in your createConfig.');
+            throw new Error('no database configured');
+        }
+        const { migrate, codegen, zod } = await migrateAndCodegen(resolved, {
+            scratch: true,
+        });
+        for (const warning of codegen.warnings) {
+            logger.diagnostic(warning);
+        }
+        logger.info(`db codegen: applied ${migrate.applied.length} migration(s) to a scratch ${resolved.dialect} database`);
+        logger.info(codegen.written
+            ? `db codegen: regenerated ${codegen.outFile} (${codegen.tables.length} tables)`
+            : `db codegen: ${codegen.outFile} unchanged`);
+        logger.info(zod.written
+            ? `db codegen: regenerated ${zod.outFile} (${zod.tables.length} tables)`
+            : `db codegen: ${zod.outFile} unchanged`);
+    },
+});

package/dist/src/functions/commands/db-export.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Publish this package's schema so a project consuming it as an addon can
+ * create its tables.
+ *
+ * An addon has no database of its own — it runs inside the consumer, against
+ * the consumer's — so it must never create tables at boot. It says what it
+ * needs, and the consumer's `db generate` folds that into its own migration
+ * history, where the project can review it like any other migration.
+ *
+ * Run this from the addon's build, beside the rest of its codegen.
+ */
+export declare const dbExport: import("#pikku").PikkuFunctionConfig<{}, void, "rpc" | "session", import("#pikku").PikkuFunctionSessionless<{}, void, "rpc" | "session", import("#pikku").WiredServices> | import("#pikku").PikkuFunction<{}, void, "rpc" | "session", import("#pikku").WiredServices>, undefined, undefined>;

package/dist/src/functions/commands/db-export.js

@@ -0,0 +1,31 @@
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { pikkuSessionlessFunc } from '#pikku';
+import { exportSchema } from '../db/local-db.js';
+/**
+ * Publish this package's schema so a project consuming it as an addon can
+ * create its tables.
+ *
+ * An addon has no database of its own — it runs inside the consumer, against
+ * the consumer's — so it must never create tables at boot. It says what it
+ * needs, and the consumer's `db generate` folds that into its own migration
+ * history, where the project can review it like any other migration.
+ *
+ * Run this from the addon's build, beside the rest of its codegen.
+ */
+export const dbExport = pikkuSessionlessFunc({
+    remote: true,
+    func: async ({ logger, config }) => {
+        const artifact = await exportSchema(config.rootDir);
+        const dialects = Object.keys(artifact);
+        if (dialects.length === 0) {
+            logger.info('db export: no db/sqlite or db/postgres migrations — nothing to publish');
+            return;
+        }
+        const file = join(config.outDir, 'db', 'pikku-db-meta.gen.json');
+        mkdirSync(dirname(file), { recursive: true });
+        writeFileSync(file, `${JSON.stringify(artifact, null, 2)}\n`, 'utf8');
+        logger.info(`db export: wrote ${file} for ${dialects.join(', ')}`);
+        logger.info('  Ship it with the package — a consumer resolves it through the package name.');
+    },
+});

package/dist/src/functions/commands/db-generate.js

@@ -1,9 +1,9 @@
 import { pikkuSessionlessFunc } from '#pikku';
-import { resolveDb, generateAuthMigration } from '../db/local-db.js';
+import { resolveDb, generateMigrations } from '../db/local-db.js';
 import { loadUserConfigForDb } from './db-shared.js';
 export const dbGenerate = pikkuSessionlessFunc({
     remote: true,
-    func: async ({ logger, config }) => {
+    func: async ({ logger, config, getInspectorState }) => {
         const userConfig = await loadUserConfigForDb({ config, logger });
         if (!userConfig)
             return;
@@ -12,31 +12,24 @@ export const dbGenerate = pikkuSessionlessFunc({
             logger.error('pikku db generate: no database configured — set sqliteDb or postgresUrl in your createConfig.');
             throw new Error('no database configured');
         }
-        const result = await generateAuthMigration(resolved, config.rootDir, config.srcDirectories, logger);
-        switch (result.status) {
-            case 'no-auth':
-                logger.info('db generate: no pikkuBetterAuth found — nothing to generate');
-                return;
-            case 'up-to-date':
-                logger.info('db generate: Better Auth schema already covered by existing migrations — nothing to generate');
-                return;
-            case 'incremental-unsupported': {
-                const cols = (result.missingColumns ?? [])
-                    .map((m) => `${m.table}(${m.columns.join(', ')})`)
-                    .join('; ');
-                logger.error('db generate: the Better Auth config requires schema changes on top of an existing auth schema:');
-                if (result.missingTables?.length) {
-                    logger.error(`  missing tables: ${result.missingTables.join(', ')}`);
-                }
-                if (cols)
-                    logger.error(`  missing columns: ${cols}`);
-                logger.error('  Write a forward migration adding these by hand (incremental auto-generation is not yet supported).');
-                throw new Error('incremental auth schema change requires a manual migration');
+        const state = await getInspectorState();
+        const addons = [...state.rpc.wireAddonDeclarations.values()].map(({ package: pkg, remote }) => ({ package: pkg, remote }));
+        const { upToDate, written } = await generateMigrations(resolved, config.rootDir, config.srcDirectories, logger, addons);
+        for (const source of upToDate) {
+            logger.info(`db generate: ${source} is already covered by existing migrations`);
+        }
+        if (written.length === 0) {
+            if (upToDate.length === 0) {
+                logger.info('db generate: nothing declares tables — nothing to generate');
+            }
+            return;
+        }
+        for (const { source, file, needsBackfill } of written) {
+            logger.info(`db generate: wrote ${file} for ${source}`);
+            for (const column of needsBackfill) {
+                logger.warn(`  ${column} is NOT NULL with no default — decide what existing rows get before applying.`);
             }
-            case 'written':
-                logger.info(`db generate: wrote ${result.file}`);
-                logger.info('  Review it, then run `pikku db migrate` to apply.');
-                return;
         }
+        logger.info('  Review them, then run `pikku db migrate` to apply.');
     },
 });

package/dist/src/functions/commands/dev.js

@@ -14,6 +14,7 @@ import { loadUserBootstrap, loadUserModule } from './load-user-project.js';
 import { startCoverageService } from './start-coverage.js';
 import { createDevAIAgentRunner } from './dev-ai-runner.js';
 import { resolveConsoleMount } from './serve-console.js';
+import { serverReadyLine } from '../../server/server-ready.js';
 export const dev = pikkuSessionlessFunc({
     remote: true,
     func: async ({ logger, config, getInspectorState, invalidateInspectorState, variables, devServerRunner, }, { port, watch, hmr, coverage, test }, { rpc }) => {
@@ -238,6 +239,7 @@ export const dev = pikkuSessionlessFunc({
         if (consoleMount) {
             logger.info(`Pikku Console available at http://${hostname}:${resolvedPort}${consoleMount.urlPrefix}`);
         }
+        logger.info(serverReadyLine(hostname, resolvedPort));
         let configWatcher;
         let watcher;
         process.once('SIGINT', async () => {

package/dist/src/functions/commands/load-user-project.d.ts

@@ -4,6 +4,13 @@
  * `pikkuState`.
  */
 export declare function loadUserBootstrap(pikkuDir: string): Promise<void>;
+/**
+ * Load the generated `pikku-bootstrap-scenarios.gen.{ts,js}`, which imports the
+ * app bootstrap and then registers the scenarios, features and steps that are
+ * deliberately kept out of it. Falls back to the app bootstrap for a project
+ * generated before the split existed.
+ */
+export declare function loadScenarioBootstrap(pikkuDir: string): Promise<void>;
 /**
  * Import a user-source TypeScript file (e.g. their config or services
  * factory) so it can be loaded from inside @pikku/cli's compiled JS.

package/dist/src/functions/commands/load-user-project.js

@@ -39,6 +39,27 @@ export async function loadUserBootstrap(pikkuDir) {
     ensureTsxRegistered();
     await importUserPath(bootstrapPath);
 }
+/**
+ * Load the generated `pikku-bootstrap-scenarios.gen.{ts,js}`, which imports the
+ * app bootstrap and then registers the scenarios, features and steps that are
+ * deliberately kept out of it. Falls back to the app bootstrap for a project
+ * generated before the split existed.
+ */
+export async function loadScenarioBootstrap(pikkuDir) {
+    const scenarioTs = join(pikkuDir, 'pikku-bootstrap-scenarios.gen.ts');
+    const scenarioJs = join(pikkuDir, 'pikku-bootstrap-scenarios.gen.js');
+    const scenarioPath = existsSync(scenarioTs)
+        ? scenarioTs
+        : existsSync(scenarioJs)
+            ? scenarioJs
+            : null;
+    if (!scenarioPath) {
+        await loadUserBootstrap(pikkuDir);
+        return;
+    }
+    ensureTsxRegistered();
+    await importUserPath(scenarioPath);
+}
 /**
  * Import a user-source TypeScript file (e.g. their config or services
  * factory) so it can be loaded from inside @pikku/cli's compiled JS.

package/dist/src/functions/commands/pikku-command-bootstrap.js

@@ -64,5 +64,17 @@ export const pikkuBootstrap = pikkuSessionlessFunc({
         })
             .join('\n');
         await writeFileInDir(logger, config.bootstrapFile, allBootstrapImports);
+        // The scenario bootstrap is the only entry point that registers scenarios,
+        // features and their steps. It pulls in the app bootstrap first so a runner
+        // needs to load one file, and so the meta files it merges onto are already
+        // in place however this module is reached.
+        const scenarioBootstrapImports = [
+            config.bootstrapFile,
+            config.scenarioStepsMetaFile,
+            config.scenarioStepsFile,
+            config.scenarioWiringsMetaFile,
+            config.scenarioWiringsFile,
+        ].map((to) => `import '${getFileImportRelativePath(config.scenarioBootstrapFile, to, config.packageMappings, config.forceRelativeImports)}'`);
+        await writeFileInDir(logger, config.scenarioBootstrapFile, scenarioBootstrapImports.join('\n'));
     },
 });

package/dist/src/functions/commands/scenario-browser.d.ts

@@ -0,0 +1,69 @@
+/**
+ * The scenario runner's browser lifecycle.
+ *
+ * Two jobs, both kept out of the run loop so they are testable without
+ * launching a browser: deciding whether a run needs a driver at all (and
+ * failing early, with instructions, when it does and cannot have one), and
+ * making the driver's optional isolation and diagnostics safe to call
+ * unconditionally.
+ */
+import type { ScenarioBrowserFailure, ScenarioBrowserProvider } from '@pikku/core/workflow';
+import type { ScenarioActorConfig } from '@pikku/core/services';
+/** The default driver, used when a project names no other. */
+export declare const DEFAULT_BROWSER_DRIVER = "@pikku/playwright";
+export interface ScenarioBrowserDriverOptions {
+    secret: string;
+    actors: Record<string, ScenarioActorConfig>;
+    signInPath?: string;
+    failureDir?: string;
+    config: unknown;
+}
+/**
+ * What a browser driver package exports.
+ *
+ * Nothing here is playwright-specific: a driver is anything that can hand a
+ * scenario step a `ScenarioBrowserProvider`. `@pikku/playwright` is the one
+ * pikku ships, named by `scenarios.browserDriver` only as a default.
+ */
+export interface ScenarioBrowserDriver {
+    createScenarioBrowserProvider?: (options: ScenarioBrowserDriverOptions) => ScenarioBrowserProvider;
+    /** The class form the bundled driver exports. */
+    PlaywrightScenarioBrowserProvider?: new (options: ScenarioBrowserDriverOptions) => ScenarioBrowserProvider;
+    /** Driver-specific config (headed, slowMo, timeouts) resolved from the env. */
+    browserConfigFromEnv?: (overrides: {
+        appUrl: string;
+        apiUrl: string;
+    }) => unknown;
+}
+export interface ResolveScenarioBrowserProviderOptions {
+    /** The environment name, for error messages that tell the user what to edit. */
+    environment: string;
+    apiUrl: string;
+    appUrl?: string;
+    secret: string;
+    actors: Record<string, ScenarioActorConfig>;
+    signInPath?: string;
+    /** Where failure screenshots are written. */
+    failureDir: string;
+    /** The scenarios that declared browser steps, named in the missing-driver error. */
+    browserScenarios: string[];
+    /** Package to drive the browser. Defaults to `@pikku/playwright`. */
+    driver?: string;
+    importDriver?: (specifier: string) => Promise<ScenarioBrowserDriver>;
+}
+/**
+ * Both failure modes here are discovered before the first scenario starts. A
+ * missing `appUrl` or an uninstalled driver found mid-run costs a whole run to
+ * learn about.
+ */
+export declare const resolveScenarioBrowserProvider: ({ environment, apiUrl, appUrl, secret, actors, signInPath, failureDir, browserScenarios, driver, importDriver, }: ResolveScenarioBrowserProviderOptions) => Promise<ScenarioBrowserProvider>;
+/**
+ * The three calls the run loop makes, safe against a run with no browser and
+ * against a driver that implements neither optional member.
+ */
+export interface ScenarioBrowserLifecycle {
+    reset(): Promise<void>;
+    captureFailure(label: string): Promise<ScenarioBrowserFailure[]>;
+    close(): Promise<void>;
+}
+export declare const scenarioBrowserLifecycle: (provider: ScenarioBrowserProvider | undefined) => ScenarioBrowserLifecycle;