@pikku/cli 0.12.89 → 0.12.91

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

@@ -2,8 +2,16 @@ import { resolve, join } from 'node:path';
 import { mkdirSync, writeFileSync } from 'node:fs';
 import { pikkuSessionlessFunc } from '#pikku';
 import { InMemoryWorkflowService, createHttpScenarioActors, } from '@pikku/core/services';
-import { pikkuState } from '@pikku/core/internal';
-import { loadUserBootstrap } from './load-user-project.js';
+import { PikkuScenarioService } from '@pikku/core/scenario';
+import { pikkuState, getAllPackageStates } from '@pikku/core/internal';
+import { resolveFeatureScenarios } from '@pikku/core/workflow';
+import { loadScenarioBootstrap } from './load-user-project.js';
+import { collectScenarioStepProse, scenarioBrowserSteps, scenarioFailureFromSteps, scenarioStepRows, } from './scenario-ladder.js';
+import { formatScenarioReport } from './scenario-formatter.js';
+import { resolveScenarioBrowserProvider, scenarioBrowserLifecycle, } from './scenario-browser.js';
+import { resolveScenarioActors } from '../../utils/resolve-scenario-actors.js';
+import { spawnDevServer } from '../../server/spawn-dev-server.js';
+import { buildScenarioPlan } from './scenario-plan.js';
 const isScenario = (wf) => wf?.scenario === true;
 const listScenarios = (state) => Object.entries(state.workflows?.meta ?? {})
     .filter(([, wf]) => isScenario(wf))
@@ -12,27 +20,71 @@ const listScenarios = (state) => Object.entries(state.workflows?.meta ?? {})
     name: wf.name ?? id,
     description: wf.description ?? wf.summary ?? wf.title ?? null,
     tags: wf.tags ?? [],
+    skip: wf.skip,
 }));
+/**
+ * Features and scenario registrations, merged across the main package and any
+ * addon packages. A feature holds the very config objects the registrations
+ * hold, which is what makes membership resolvable by identity.
+ */
+const collectRegisteredWirings = () => {
+    const features = new Map();
+    const registrations = new Map();
+    for (const [packageName] of getAllPackageStates()) {
+        const scope = packageName === '__main__' ? null : packageName;
+        for (const [id, feature] of pikkuState(scope, 'workflows', 'features')) {
+            features.set(id, feature);
+        }
+        for (const [name, registration] of pikkuState(scope, 'workflows', 'registrations')) {
+            registrations.set(name, registration);
+        }
+    }
+    return { features, registrations };
+};
 export const scenarioList = pikkuSessionlessFunc({
-    func: async ({ logger, getInspectorState }) => {
-        const state = await getInspectorState();
+    func: async ({ logger, config, getInspectorState }) => {
+        const state = await getInspectorState(false, false, false, true);
         const flows = listScenarios(state);
         if (flows.length === 0) {
             logger.info('No scenarios found (pikkuScenario exports).');
             return;
         }
+        await loadScenarioBootstrap(resolve(config.rootDir, config.outDir));
+        const { features, registrations } = collectRegisteredWirings();
+        const { entries, unresolved } = resolveFeatureScenarios(features, registrations);
+        for (const { featureId, index } of unresolved) {
+            logger.error(`Feature '${featureId}' scenario #${index} is not a registered scenario — it will not run.`);
+        }
+        const describe = (name) => flows.find((flow) => flow.name === name)?.description;
+        for (const [featureId, feature] of features) {
+            const featureTags = feature.tags?.length
+                ? `  [${feature.tags.join(', ')}]`
+                : '';
+            logger.info(`${feature.name ?? featureId}${featureTags}`);
+            if (feature.description) {
+                logger.info(`  ${feature.description}`);
+            }
+            for (const entry of entries.filter((e) => e.featureId === featureId)) {
+                const data = entry.data ? ` ${JSON.stringify(entry.data)}` : '';
+                logger.info(`  - ${entry.scenarioName}${data}`);
+            }
+        }
+        const inAFeature = new Set(entries.map((entry) => entry.scenarioName));
         for (const flow of flows) {
+            if (inAFeature.has(flow.name))
+                continue;
             const tags = flow.tags.length ? `  [${flow.tags.join(', ')}]` : '';
             logger.info(`${flow.name}${tags}`);
-            if (flow.description) {
-                logger.info(`  ${flow.description}`);
+            const description = describe(flow.name);
+            if (description) {
+                logger.info(`  ${description}`);
             }
         }
     },
 });
 export const scenarioRun = pikkuSessionlessFunc({
-    func: async ({ logger, config, getInspectorState, variables }, { environment, flows, tags, coverage }) => {
-        const state = await getInspectorState(true);
+    func: async ({ logger, config, getInspectorState, variables }, { environment, flows, features, tags, excludeTags, coverage, browser = true, spawn = false, keepAlive = false, trace = false, }) => {
+        const state = await getInspectorState(true, false, false, true);
         const environments = config.scenarios?.environments ?? {};
         const env = environments[environment];
         if (!env) {
@@ -42,20 +94,62 @@ export const scenarioRun = pikkuSessionlessFunc({
                     ? `Configured environments: ${known.join(', ')}`
                     : `Add scenarios.environments to pikku.config.json, e.g. { "${environment}": { "apiUrl": "https://app.example.com/api" } }`));
         }
-        let selected = listScenarios(state);
-        if (flows) {
-            const names = new Set(flows.split(',').map((f) => f.trim()));
-            const unknown = [...names].filter((n) => !selected.some((f) => f.name === n));
-            if (unknown.length) {
-                throw new Error(`Unknown scenario(s): ${unknown.join(', ')}. Available: ${selected.map((f) => f.name).join(', ')}`);
+        if (spawn) {
+            const { hostname, port } = new URL(env.apiUrl);
+            const resolvedPort = Number(port || 80);
+            logger.info(`Starting a server for '${environment}' on ${env.apiUrl}`);
+            const server = await spawnDevServer({
+                cwd: config.rootDir,
+                port: resolvedPort,
+                hostname,
+                coverage,
+                env: { API_URL: env.apiUrl },
+                onOutput: (text) => process.stdout.write(text),
+            });
+            // Registered rather than wrapped in a try/finally: the run below sets
+            // process.exitCode and can throw, and an exit handler covers both without
+            // the whole command body having to nest inside one block.
+            if (!keepAlive) {
+                process.once('exit', server.stop);
+                process.once('SIGINT', () => {
+                    server.stop();
+                    process.exit(1);
+                });
+                process.once('SIGTERM', () => {
+                    server.stop();
+                    process.exit(1);
+                });
             }
-            selected = selected.filter((f) => names.has(f.name));
+            await server.waitUntilReady();
         }
-        if (tags) {
-            const wanted = tags.split(',').map((t) => t.trim());
-            selected = selected.filter((f) => wanted.some((t) => f.tags.includes(t)));
+        // Features live in runtime state, not inspector meta — their scenario lists
+        // may be built by an ordinary loop — so the project has to be loaded before
+        // anything can be selected.
+        await loadScenarioBootstrap(resolve(config.rootDir, config.outDir));
+        const { features: registeredFeatures, registrations } = collectRegisteredWirings();
+        const split = (value) => value ? value.split(',').map((part) => part.trim()) : undefined;
+        let { groups, unresolved } = buildScenarioPlan({
+            scenarios: listScenarios(state).map(({ name, tags: flowTags, skip }) => ({
+                name,
+                tags: flowTags,
+                skip,
+            })),
+            features: registeredFeatures,
+            registrations,
+            flows: split(flows),
+            featureIds: split(features),
+            tags: split(tags),
+            excludeTags: split(excludeTags),
+        });
+        if (unresolved.length > 0) {
+            for (const { featureId, index } of unresolved) {
+                logger.error(`Feature '${featureId}' scenario #${index} is not a registered scenario. ` +
+                    `A feature references scenarios by imported identifier — a scenario built inline inside a feature is never registered.`);
+            }
+            process.exitCode = 1;
+            return;
         }
-        if (selected.length === 0) {
+        if (groups.length === 0) {
             logger.error('No scenarios matched.');
             process.exitCode = 1;
             return;
@@ -65,15 +159,57 @@ export const scenarioRun = pikkuSessionlessFunc({
             throw new Error('SCENARIO_ACTOR_SECRET is not set — scenario actors cannot sign in. ' +
                 'Export it in the environment running this command (never put it in pikku.config.json).');
         }
+        // Declared actors plus one per persona nobody declared a body for. Resolved
+        // once: the HTTP actors and the Playwright provider below must see the same
+        // registry, and codegen resolved the same way to type `ScenarioActorName`.
+        const scenarioActors = resolveScenarioActors(config.scenarios);
         const actors = createHttpScenarioActors({
             apiUrl: env.apiUrl,
             secret,
-            actors: config.scenarios?.actors ?? {},
+            actors: scenarioActors,
             signInPath: env.signInPath,
             rpcPath: env.rpcPath,
         });
-        await loadUserBootstrap(resolve(config.rootDir, config.outDir));
+        const functionsMeta = state.functions?.meta ?? {};
+        const scenarioNames = new Set(groups.flatMap((group) => group.entries.map((e) => e.scenarioName)));
+        const browserStepsByFlow = new Map([...scenarioNames]
+            .map((name) => [
+            name,
+            scenarioBrowserSteps(state.workflows?.meta?.[name], functionsMeta),
+        ])
+            .filter(([, steps]) => steps.length > 0));
+        // Two reasons a scenario is held back, both reported as SKIP rather than
+        // failed. `--no-browser` is the direct replacement for cucumber's `@console`
+        // tag, so a standard run stays green on a machine with no browser; a `skip`
+        // on the scenario itself is the project quarantining it, and the plan has
+        // already cleared that reason for anything named directly with `--flows`.
+        const skipReasonFor = (entry) => {
+            if (entry.skip)
+                return entry.skip;
+            if (!browser && browserStepsByFlow.has(entry.scenarioName)) {
+                return 'browser steps, --no-browser';
+            }
+            return undefined;
+        };
+        const skipped = [];
+        groups = groups
+            .map((group) => ({
+            ...group,
+            entries: group.entries.filter((entry) => {
+                const reason = skipReasonFor(entry);
+                if (!reason)
+                    return true;
+                skipped.push({ name: entry.scenarioName, reason });
+                return false;
+            }),
+        }))
+            .filter((group) => group.entries.length > 0);
         const workflowService = new InMemoryWorkflowService();
+        const scenarioService = workflowService.setRunExtension((engine) => new PikkuScenarioService(engine));
+        scenarioService.setScenarioEnvironment({
+            apiUrl: env.apiUrl,
+            appUrl: env.appUrl,
+        });
         pikkuState(null, 'package', 'singletonServices', {
             logger,
             workflowService,
@@ -86,7 +222,51 @@ export const scenarioRun = pikkuSessionlessFunc({
                     `'${environment}' (${env.apiUrl}), not local services.`);
             },
         };
+        const needsBrowser = groups.some((group) => group.entries.some((entry) => browserStepsByFlow.has(entry.scenarioName)));
+        const failureDir = join(resolve(config.rootDir, config.outDir), 'scenario-failures');
+        const browserLifecycle = scenarioBrowserLifecycle(needsBrowser
+            ? await (async () => {
+                const provider = await resolveScenarioBrowserProvider({
+                    environment,
+                    apiUrl: env.apiUrl,
+                    appUrl: env.appUrl,
+                    secret,
+                    actors: scenarioActors,
+                    signInPath: env.signInPath,
+                    failureDir,
+                    browserScenarios: [...browserStepsByFlow.keys()],
+                    driver: config.scenarios?.browserDriver,
+                });
+                scenarioService.setScenarioBrowserProvider(provider);
+                return provider;
+            })()
+            : undefined);
         const results = [];
+        /**
+         * The step ladder is read back off the recorded run, so it needs no live
+         * step events — it is the same data the console renders. Joining it to the
+         * declared prose happens here, where the inspector state is; laying it out
+         * is the formatter's job.
+         */
+        const readRunSteps = async (service, runId, flowName) => {
+            const prose = collectScenarioStepProse(state.workflows?.meta?.[flowName], functionsMeta);
+            const steps = (await service.getRunSteps(runId)).map((step) => ({
+                stepName: step.stepName,
+                status: step.status,
+                durationMs: step.succeededAt
+                    ? step.succeededAt.getTime() - step.createdAt.getTime()
+                    : undefined,
+                error: step.error?.message,
+                stack: step.error?.stack,
+                expected: step.error?.expected,
+                input: step.data,
+                stepFunc: step.rpcName,
+            }));
+            return {
+                rows: scenarioStepRows(steps, prose),
+                failure: scenarioFailureFromSteps(steps, prose),
+            };
+        };
         const coverageActor = coverage ? Object.values(actors)[0] : undefined;
         let coverageActive = Boolean(coverageActor);
         if (coverage && !coverageActor) {
@@ -106,8 +286,22 @@ export const scenarioRun = pikkuSessionlessFunc({
                 return null;
             }
         };
-        for (const flow of selected) {
+        /**
+         * A feature hook is not a pikku function and not a run — the feature is a
+         * grouping, not something durable. It gets the same three arguments a
+         * scenario body gets, the CLI's own singletons included, and its result is
+         * discarded.
+         */
+        const singletonServices = pikkuState(null, 'package', 'singletonServices');
+        const runFeatureHook = async (hook) => {
+            await hook(singletonServices, undefined, { actors });
+        };
+        const hookFailures = [];
+        const runEntry = async (label, scenarioName, data) => {
             const startedAt = Date.now();
+            // Before the scenario, not after it: the last scenario's window is left
+            // open for headed debugging, while this one still starts clean.
+            await browserLifecycle.reset();
             if (coverageActive) {
                 const reset = await invokeCoverage('pikkuScenarioResetLiveCoverage');
                 if (reset && reset.enabled === false) {
@@ -119,20 +313,27 @@ export const scenarioRun = pikkuSessionlessFunc({
                 await coverageActor?.invoke('pikkuScenarioResetStubs', null);
             }
             catch { }
+            let runId;
+            let runError;
             try {
-                const { runId } = await workflowService.startWorkflow(flow.name, undefined, { type: 'cli' }, guardRpc, { actors });
+                // The id comes back through the callback rather than the return value
+                // because a failing scenario throws instead of returning — and a failed
+                // run is exactly the one whose steps are worth reading.
+                ;
+                ({ runId } = await workflowService.startWorkflow(scenarioName, data, { type: 'cli' }, guardRpc, { actors, onRunCreated: (id) => (runId = id) }));
                 const run = await workflowService.getRun(runId);
                 if (run?.status === 'completed') {
                     results.push({
-                        name: flow.name,
+                        name: label,
                         status: 'passed',
                         durationMs: Date.now() - startedAt,
                         output: run.output,
                     });
                 }
                 else {
+                    runError = run?.error;
                     results.push({
-                        name: flow.name,
+                        name: label,
                         status: 'failed',
                         durationMs: Date.now() - startedAt,
                         error: run?.error?.message ?? `status: ${run?.status}`,
@@ -140,22 +341,90 @@ export const scenarioRun = pikkuSessionlessFunc({
                 }
             }
             catch (e) {
+                runError = { stack: e?.stack };
                 results.push({
-                    name: flow.name,
+                    name: label,
                     status: 'failed',
                     durationMs: Date.now() - startedAt,
                     error: e?.message ?? String(e),
                 });
             }
+            const result = results[results.length - 1];
+            let stepFailure;
+            if (runId) {
+                const read = await readRunSteps(workflowService, runId, scenarioName);
+                result.steps = read.rows;
+                stepFailure = read.failure;
+            }
+            if (result.status === 'failed') {
+                result.failure = {
+                    // A scenario can also fail outside any step — a hook, or the start
+                    // itself — and then the run's own error is all there is to report.
+                    ...(stepFailure ?? {
+                        message: result.error ?? 'unknown failure',
+                        stack: runError?.stack,
+                        expected: runError?.expected,
+                    }),
+                    browser: await browserLifecycle.captureFailure(label),
+                };
+            }
             if (coverageActive) {
                 const report = await invokeCoverage('pikkuScenarioTakeLiveCoverage');
                 if (report) {
-                    scenarioCoverage[flow.name] = report;
+                    scenarioCoverage[label] = report;
                     const covered = report.functions?.filter((f) => f.status === 'covered' || f.status === 'partial');
-                    logger.info(`  coverage: ${covered?.length ?? 0}/${report.summary?.total ?? 0} functions exercised by '${flow.name}'`);
+                    logger.info(`  coverage: ${covered?.length ?? 0}/${report.summary?.total ?? 0} functions exercised by '${label}'`);
+                }
+            }
+        };
+        for (const group of groups) {
+            const groupName = group.featureName ?? group.featureId;
+            const label = (entry) => {
+                const data = entry.data ? ` ${JSON.stringify(entry.data)}` : '';
+                return groupName
+                    ? `${groupName} › ${entry.scenarioName}${data}`
+                    : entry.scenarioName;
+            };
+            let beforeError;
+            if (group.before) {
+                try {
+                    await runFeatureHook(group.before);
+                }
+                catch (e) {
+                    beforeError = e;
+                }
+            }
+            try {
+                if (beforeError) {
+                    // Setup failed, so nothing in the group ran. Reporting them as failed
+                    // rather than skipped is the honest reading: they did not pass.
+                    for (const entry of group.entries) {
+                        results.push({
+                            name: label(entry),
+                            status: 'failed',
+                            durationMs: 0,
+                            error: `feature '${groupName}' before hook failed: ${beforeError?.message ?? beforeError}`,
+                        });
+                    }
+                }
+                else {
+                    for (const entry of group.entries) {
+                        await runEntry(label(entry), entry.scenarioName, entry.data);
+                    }
+                }
+            }
+            finally {
+                if (group.after) {
+                    try {
+                        await runFeatureHook(group.after);
+                    }
+                    catch (e) {
+                        hookFailures.push(`feature '${groupName}' after hook failed: ${e?.message ?? e}`);
+                    }
                 }
             }
         }
+        await browserLifecycle.close();
         if (coverage && Object.keys(scenarioCoverage).length > 0) {
             const coverageDir = join(resolve(config.rootDir, config.outDir), 'coverage');
             mkdirSync(coverageDir, { recursive: true });
@@ -167,17 +436,15 @@ export const scenarioRun = pikkuSessionlessFunc({
             }, null, 2) + '\n');
             logger.info(`Scenario coverage → ${outFile}`);
         }
-        const failed = results.filter((r) => r.status === 'failed');
-        for (const r of results) {
-            if (r.status === 'passed') {
-                logger.info(`PASS ${r.name} (${r.durationMs}ms)${r.output !== undefined ? ` → ${JSON.stringify(r.output)}` : ''}`);
-            }
-            else {
-                logger.error(`FAIL ${r.name} (${r.durationMs}ms): ${r.error}`);
-            }
+        const report = { environment, results, skipped, hookFailures };
+        for (const { level, text } of formatScenarioReport(report, {
+            trace,
+            projectRoot: config.rootDir,
+        })) {
+            logger[level](text);
         }
-        logger.info(`${results.length - failed.length}/${results.length} scenarios passed against '${environment}'`);
-        if (failed.length > 0) {
+        const failed = results.filter((r) => r.status === 'failed');
+        if (failed.length > 0 || hookFailures.length > 0) {
             process.exitCode = 1;
         }
     },

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

@@ -11,6 +11,7 @@ import { resolveDb, createKysely, parseDatabaseUrl, } from '../db/local-db.js';
 import { loadUserBootstrap, loadUserModule } from './load-user-project.js';
 import { createDevAIAgentRunner } from './dev-ai-runner.js';
 import { resolveConsoleMount } from './serve-console.js';
+import { serverReadyLine } from '../../server/server-ready.js';
 export const serve = pikkuSessionlessFunc({
     remote: true,
     func: async ({ logger, config, getInspectorState, variables, devServerRunner }, { port, console: serveConsole }) => {
@@ -136,6 +137,7 @@ export const serve = pikkuSessionlessFunc({
         if (consoleMount) {
             logger.info(`Pikku Console available at http://${hostname}:${resolvedPort}${consoleMount.urlPrefix}`);
         }
+        logger.info(serverReadyLine(hostname, resolvedPort));
         process.once('SIGINT', async () => {
             logger.info('Stopping server...');
             try {

package/dist/src/functions/db/db-migrator.d.ts

@@ -1,3 +1,15 @@
+/**
+ * The migrator's own bookkeeping table, which belongs to no dialect and to no
+ * project's schema.
+ *
+ * Every introspector hides it for that reason. Leaving it visible on one
+ * dialect and not the other is not cosmetic: a schema source exported from a
+ * database that has been migrated would publish `sql_migrations` as one of its
+ * own tables, and the consumer — which also has it — would then read the source
+ * as partially covered and emit column deltas instead of the source's own SQL,
+ * silently dropping its primary keys, indexes and constraints.
+ */
+export declare const MIGRATION_TRACKING_TABLE = "sql_migrations";
 export declare class MigrationDriftError extends Error {
     readonly file: string;
     readonly recordedHash: string;
@@ -23,10 +35,29 @@ export interface MigrationExecutor {
     ensureTrackingTable(): Promise<void>;
     getApplied(): Promise<AppliedMigration[]>;
     runMigration(sql: string, name: string, hash: string): Promise<void>;
+    /**
+     * Record a migration as applied without running its SQL.
+     *
+     * For a database that already contains what the migration describes, because
+     * something created those tables before anyone wrote them down. Only ever
+     * called once the caller has confirmed that is actually true — recording a
+     * migration whose tables are absent leaves a database permanently behind with
+     * no pending migration to reveal it.
+     */
+    recordMigration(name: string, hash: string): Promise<void>;
 }
+export declare function migrate(executor: MigrationExecutor, migrationsDir: string): Promise<MigrateResult>;
 /**
- * Apply pending migrations from `migrationsDir/*.sql` using the supplied
- * executor. Hashes raw file bytes on apply; subsequent runs re-hash and bail
- * with `MigrationDriftError` if any applied file has changed on disk.
+ * Record every pending migration as applied, without running any of it.
+ *
+ * The escape hatch for a database that already has the tables a migration
+ * creates — the shape you get when a runtime bootstrapped its own schema at
+ * boot and the migration writing it down was authored afterwards. Running that
+ * migration would fail on every existing deployment; skipping it forever would
+ * leave the history lying. Recording it says what is true.
+ *
+ * Deliberately unconditional here. Whether the database really does match is a
+ * question about schemas, not migration files, so the caller answers it first
+ * and this only runs once it has.
  */
-export declare function migrate(executor: MigrationExecutor, migrationsDir: string): Promise<MigrateResult>;
+export declare function baselineMigrations(executor: MigrationExecutor, migrationsDir: string): Promise<string[]>;

package/dist/src/functions/db/db-migrator.js

@@ -1,6 +1,18 @@
 import { createHash } from 'node:crypto';
-import { readFileSync, readdirSync } from 'node:fs';
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
 import { join } from 'node:path';
+/**
+ * The migrator's own bookkeeping table, which belongs to no dialect and to no
+ * project's schema.
+ *
+ * Every introspector hides it for that reason. Leaving it visible on one
+ * dialect and not the other is not cosmetic: a schema source exported from a
+ * database that has been migrated would publish `sql_migrations` as one of its
+ * own tables, and the consumer — which also has it — would then read the source
+ * as partially covered and emit column deltas instead of the source's own SQL,
+ * silently dropping its primary keys, indexes and constraints.
+ */
+export const MIGRATION_TRACKING_TABLE = 'sql_migrations';
 export class MigrationDriftError extends Error {
     file;
     recordedHash;
@@ -31,9 +43,25 @@ function sha256(bytes) {
  * executor. Hashes raw file bytes on apply; subsequent runs re-hash and bail
  * with `MigrationDriftError` if any applied file has changed on disk.
  */
-export async function migrate(executor, migrationsDir) {
-    await executor.ensureTrackingTable();
-    const applied = await executor.getApplied();
+/**
+ * The migrations on disk, or none.
+ *
+ * A project that has never generated a migration has no directory to read, and
+ * that is the ordinary first-run state rather than a failure — it is precisely
+ * the project `db generate` exists to serve.
+ */
+const migrationFiles = (migrationsDir) => existsSync(migrationsDir)
+    ? readdirSync(migrationsDir)
+        .filter((f) => f.endsWith('.sql'))
+        .sort()
+    : [];
+/**
+ * Re-hash every applied migration and bail if one has changed on disk.
+ *
+ * Applies to baselining as much as to migrating: recording a file as applied
+ * only means anything if the file is still the one that was applied.
+ */
+function assertNoDrift(applied, migrationsDir) {
     for (const row of applied) {
         let currentHash = null;
         try {
@@ -46,13 +74,15 @@ export async function migrate(executor, migrationsDir) {
             throw new MigrationDriftError(row.name, row.hash, currentHash, row.applied_at, migrationsDir);
         }
     }
-    const appliedSet = new Set(applied.map((r) => r.name));
-    const files = readdirSync(migrationsDir)
-        .filter((f) => f.endsWith('.sql'))
-        .sort();
+}
+export async function migrate(executor, migrationsDir) {
+    await executor.ensureTrackingTable();
+    const applied = await executor.getApplied();
+    assertNoDrift(applied, migrationsDir);
+    const appliedNames = new Set(applied.map((r) => r.name));
     const result = { applied: [], skipped: [] };
-    for (const name of files) {
-        if (appliedSet.has(name)) {
+    for (const name of migrationFiles(migrationsDir)) {
+        if (appliedNames.has(name)) {
             result.skipped.push(name);
             continue;
         }
@@ -63,3 +93,30 @@ export async function migrate(executor, migrationsDir) {
     }
     return result;
 }
+/**
+ * Record every pending migration as applied, without running any of it.
+ *
+ * The escape hatch for a database that already has the tables a migration
+ * creates — the shape you get when a runtime bootstrapped its own schema at
+ * boot and the migration writing it down was authored afterwards. Running that
+ * migration would fail on every existing deployment; skipping it forever would
+ * leave the history lying. Recording it says what is true.
+ *
+ * Deliberately unconditional here. Whether the database really does match is a
+ * question about schemas, not migration files, so the caller answers it first
+ * and this only runs once it has.
+ */
+export async function baselineMigrations(executor, migrationsDir) {
+    await executor.ensureTrackingTable();
+    const applied = await executor.getApplied();
+    assertNoDrift(applied, migrationsDir);
+    const appliedNames = new Set(applied.map((r) => r.name));
+    const recorded = [];
+    for (const name of migrationFiles(migrationsDir)) {
+        if (appliedNames.has(name))
+            continue;
+        await executor.recordMigration(name, sha256(readFileSync(join(migrationsDir, name))));
+        recorded.push(name);
+    }
+    return recorded;
+}