@pikku/cli 0.12.90 → 0.12.92

package/dist/src/functions/wirings/workflow/serialize-workflow-types.js

@@ -1,4 +1,4 @@
-export const serializeWorkflowTypes = (functionTypesImportPath, rpcMapImportPath, workflowMapImportPath, agentMapImportPath, scopesImportPath) => {
+export const serializeWorkflowTypes = (functionTypesImportPath, rpcMapImportPath, workflowMapImportPath, agentMapImportPath, scopesImportPath, scenarioStepMapImportPath = './pikku-scenario-step-map.gen.js', scenarioActorsImportPath = './pikku-scenario-actors.gen.js') => {
     return `import { WorkflowCancelledException } from '@pikku/core/workflow'
 import { template } from '@pikku/core/workflow'
 import {
@@ -6,13 +6,17 @@ import {
   type PikkuWorkflowGraphConfig,
   type PikkuWorkflowGraphResult,
 } from '@pikku/core/workflow'
-import type { PikkuWorkflowWire, PikkuScenarioWire, WorkflowStepOptions } from '@pikku/core/workflow'
+import type { PikkuWorkflowWire, PikkuScenarioWire, WorkflowStepOptions, ScenarioStepOptions } from '@pikku/core/workflow'
 
 export { WorkflowCancelledException }
 import type { PikkuFunctionSessionless, PikkuFunctionConfig } from '${functionTypesImportPath}'
 import type { FlattenedRPCMap } from '${rpcMapImportPath}'
 import type { FlattenedWorkflowMap } from '${workflowMapImportPath}'
 import type { AgentMap as FlattenedAgentMap } from '${agentMapImportPath}'
+import type { FlattenedScenarioStepMap } from '${scenarioStepMapImportPath}'
+import type { TypedScenarioActors } from '${scenarioActorsImportPath}'
+
+export type { TypedScenarioActors }
 
 export { template }
 
@@ -38,7 +42,44 @@ export interface TypedWorkflow extends PikkuWorkflowWire {
   ): Promise<T>
 }
 
-export type TypedScenario = TypedWorkflow & Omit<PikkuScenarioWire, keyof PikkuWorkflowWire>
+/**
+ * The typed half of a scenario wire: \`step\` and its \`given\`/\`when\`/\`then\`
+ * sugar, narrowed to the names declared by \`pikkuScenarioStep\` in this project.
+ * The phase only changes the prose the reporter renders.
+ */
+export interface TypedScenarioSteps {
+  step<K extends keyof FlattenedScenarioStepMap>(
+    stepName: string,
+    stepFunc: K,
+    data?: FlattenedScenarioStepMap[K]['input'],
+    options?: ScenarioStepOptions
+  ): Promise<FlattenedScenarioStepMap[K]['output']>
+
+  given<K extends keyof FlattenedScenarioStepMap>(
+    stepName: string,
+    stepFunc: K,
+    data?: FlattenedScenarioStepMap[K]['input'],
+    options?: ScenarioStepOptions
+  ): Promise<FlattenedScenarioStepMap[K]['output']>
+
+  when<K extends keyof FlattenedScenarioStepMap>(
+    stepName: string,
+    stepFunc: K,
+    data?: FlattenedScenarioStepMap[K]['input'],
+    options?: ScenarioStepOptions
+  ): Promise<FlattenedScenarioStepMap[K]['output']>
+
+  then<K extends keyof FlattenedScenarioStepMap>(
+    stepName: string,
+    stepFunc: K,
+    data?: FlattenedScenarioStepMap[K]['input'],
+    options?: ScenarioStepOptions
+  ): Promise<FlattenedScenarioStepMap[K]['output']>
+}
+
+export type TypedScenario = TypedWorkflow &
+  Omit<PikkuScenarioWire, keyof PikkuWorkflowWire | keyof TypedScenarioSteps> &
+  TypedScenarioSteps
 
 import type { StandardSchemaV1 } from '@standard-schema/spec'
 import type { InferSchemaOutput, PikkuPermission, PikkuMiddleware, NodeConfig, PikkuApprovalDescription } from '${functionTypesImportPath}'
@@ -129,6 +170,49 @@ export type PikkuScenarioConfigWithSchema<
     InputSchema extends StandardSchemaV1 ? InferSchemaOutput<InputSchema> : unknown,
     OutputSchema extends StandardSchemaV1 ? InferSchemaOutput<OutputSchema> : unknown
   >
+  /**
+   * Runs before the scenario body. Same signature as \`func\`, but its return
+   * value is discarded — a hook is setup, not a step, so it is never recorded
+   * on the ladder. Throwing skips the body and fails the run; \`after\` still
+   * runs.
+   */
+  before?: PikkuScenarioHook<InputSchema>
+  /**
+   * Always runs after the scenario body, in a \`finally\`, whether it passed or
+   * failed. Throwing fails a run that would otherwise have passed; on an
+   * already-failed run it attaches as the \`cause\` and never replaces the
+   * original error.
+   */
+  after?: PikkuScenarioHook<InputSchema>
+  /**
+   * Why this scenario is held out of a default run, stated where the scenario
+   * is. The scenario still appears in the plan and is reported as skipped
+   * rather than quietly omitted; naming it directly with \`--flows\` runs it
+   * anyway.
+   */
+  skip?: string
+}
+
+/**
+ * A scenario lifecycle hook: the scenario's own \`(services, data, wire)\`
+ * signature with its result discarded.
+ */
+export type PikkuScenarioHook<
+  InputSchema extends StandardSchemaV1 | undefined = undefined
+> = PikkuFunctionScenario<
+  InputSchema extends StandardSchemaV1 ? InferSchemaOutput<InputSchema> : unknown,
+  void
+>
+
+/**
+ * Declares a scenario hook. Returns the function verbatim — a hook is never
+ * registered, so this exists purely to give an inline hook a call site to be
+ * contextually typed from, the way every other pikku primitive is.
+ */
+export function pikkuScenarioHook<In = unknown>(
+  hook: PikkuFunctionScenario<In, void>
+): PikkuFunctionScenario<In, void> {
+  return hook
 }
 
 /**
@@ -152,6 +236,151 @@ export function pikkuScenario(func: any) {
   return typeof func === 'function' ? { func } : func
 }
 
+/**
+ * A scenario as a feature references it. Any \`pikkuScenario\` export is
+ * assignable; \`In\` is recovered from it so the paired form's \`data\` is
+ * checked against that scenario's own input.
+ */
+export type PikkuScenarioRef<In = any, Out = any> = PikkuFunctionConfig<
+  In,
+  Out,
+  'scenario' | 'actors',
+  PikkuFunctionScenario<In, Out>,
+  any,
+  any
+>
+
+/**
+ * One entry in a feature's \`scenarios\` list, validated against itself: a bare
+ * scenario, or a scenario paired with the input to run it with. The paired form
+ * is gherkin's \`Examples:\` written as an ordinary loop.
+ */
+export type PikkuFeatureEntry<Entry> = Entry extends {
+  scenario: PikkuScenarioRef<infer In>
+}
+  ? { scenario: PikkuScenarioRef<In>; data: In }
+  : Entry extends PikkuScenarioRef
+    ? Entry
+    : never
+
+export type PikkuFeatureConfig<Scenarios extends readonly unknown[]> = {
+  /** Human-readable name. The export identifier is the id. */
+  name: string
+  description?: string
+  tags?: string[]
+  scenarios: { [K in keyof Scenarios]: PikkuFeatureEntry<Scenarios[K]> }
+  /**
+   * Runs ONCE before the whole group — not before each scenario. Per-scenario
+   * setup is the scenario's own \`before\`; gherkin's \`Background:\` is
+   * deliberately not expressible here.
+   */
+  before?: PikkuScenarioHook
+  after?: PikkuScenarioHook
+}
+
+/**
+ * A feature: an ordered group of scenarios, mirroring gherkin's Feature ↔
+ * Scenario structure. Scenarios are referenced by imported identifier, so a
+ * renamed or deleted scenario is a compile error rather than a silent skip.
+ *
+ * A scenario does not have to belong to a feature — a void-input scenario
+ * still runs standalone.
+ *
+ * \`\`\`ts
+ * export const credentialFeature = pikkuFeature({
+ *   name: 'Credential API',
+ *   tags: ['credential'],
+ *   before: startsMockOAuthServer,
+ *   after: stopsMockOAuthServer,
+ *   scenarios: [
+ *     credentialLazyLoadScenario,
+ *     ...['stripe', 'google'].map((name) => ({
+ *       scenario: credentialRoundTripScenario,
+ *       data: { name },
+ *     })),
+ *   ],
+ * })
+ * \`\`\`
+ */
+export function pikkuFeature<const Scenarios extends readonly unknown[]>(
+  config: PikkuFeatureConfig<Scenarios>
+): PikkuFeatureConfig<Scenarios> {
+  return config
+}
+
+export type PikkuFunctionScenarioStep<
+  In = unknown,
+  Out = never,
+  B extends boolean = false
+> = PikkuFunctionSessionless<In, Out, B extends true ? 'scenarioStep' | 'browser' : 'scenarioStep'>
+
+export type PikkuScenarioStepConfigWithSchema<
+  InputSchema extends StandardSchemaV1 | undefined = undefined,
+  OutputSchema extends StandardSchemaV1 | undefined = undefined,
+  B extends boolean = false
+> = {
+  /** Registered name — this is the string \`scenario.step()\` references. */
+  name: string
+  /**
+   * What this step does, for the console and for whoever reads the source. It
+   * is also the fallback prose when no \`template\` is declared, in which case a
+   * reporter renders "Given the shopper buys an apple". Defaults to the call
+   * site's step name.
+   */
+  description?: string
+  /**
+   * The prose a reporter renders for this step, with \`{placeholders}\` filled
+   * from the input the step was called with — \`'sees {packageName}'\` reports as
+   * "Then the admin sees @pikku/addon-todos". Every input field should appear,
+   * so the report names the values under test rather than repeating one
+   * sentence per call site.
+   */
+  template?: string
+  /**
+   * This step drives a browser. The runner provisions one for the step's actor
+   * before calling it — which also makes an actor mandatory — and \`wire.browser\`
+   * is non-optional inside \`func\`.
+   */
+  browser?: B
+  title?: string
+  tags?: string[]
+  input?: InputSchema
+  output?: OutputSchema
+  errors?: Array<typeof PikkuError>
+  func: PikkuFunctionScenarioStep<
+    InputSchema extends StandardSchemaV1 ? InferSchemaOutput<InputSchema> : unknown,
+    OutputSchema extends StandardSchemaV1 ? InferSchemaOutput<OutputSchema> : unknown,
+    B
+  >
+}
+
+export type PikkuScenarioStepConfig<In, Out, B extends boolean = false> =
+  Omit<PikkuScenarioStepConfigWithSchema<undefined, undefined, B>, 'func' | 'input' | 'output'> & {
+    func: PikkuFunctionScenarioStep<In, Out, B>
+  }
+
+/**
+ * A named, reusable scenario step. Unlike \`scenario.do\`, which can only name an
+ * RPC, a step's body is an ordinary pikku function — so it may drive a browser,
+ * invoke RPCs as its actor, or run a workflow.
+ *
+ * Steps are deliberately NOT registered as RPCs: a browser-driving step must
+ * never be network-callable.
+ */
+export function pikkuScenarioStep<
+  InputSchema extends StandardSchemaV1 | undefined = undefined,
+  OutputSchema extends StandardSchemaV1 | undefined = undefined,
+  B extends boolean = false
+>(
+  config: PikkuScenarioStepConfigWithSchema<InputSchema, OutputSchema, B>
+): PikkuFunctionConfig<InputSchema extends StandardSchemaV1 ? InferSchemaOutput<InputSchema> : unknown, OutputSchema extends StandardSchemaV1 ? InferSchemaOutput<OutputSchema> : unknown, B extends true ? 'scenarioStep' | 'browser' : 'scenarioStep', PikkuFunctionScenarioStep<InputSchema extends StandardSchemaV1 ? InferSchemaOutput<InputSchema> : unknown, OutputSchema extends StandardSchemaV1 ? InferSchemaOutput<OutputSchema> : unknown, B>, InputSchema, OutputSchema>
+export function pikkuScenarioStep<In, Out = unknown, B extends boolean = false>(
+  config: PikkuScenarioStepConfig<In, Out, B>
+): PikkuFunctionConfig<In, Out, B extends true ? 'scenarioStep' | 'browser' : 'scenarioStep'>
+export function pikkuScenarioStep(config: any) {
+  return config
+}
+
 type TypedRef<T> = { $ref: string; path?: string } & { __phantomType?: T }
 
 type TemplateString = {

package/dist/src/functions/workflows/all.workflow.js

@@ -1,7 +1,7 @@
 import { existsSync } from 'fs';
 import { pikkuWorkflowComplexFunc } from '#pikku/workflow/pikku-workflow-types.gen.js';
 import { assertSingleCoreVersion } from '../../utils/assert-single-core-version.js';
-import { pruneLegacyScaffoldFiles } from '../../utils/remove-legacy-scaffold-file.js';
+import { pruneLegacyScaffoldFiles, removeRetiredScaffoldFiles, } from '../../utils/remove-legacy-scaffold-file.js';
 import { PikkuTypecheckFailedError, renderTscFull, renderTscSummary, runProjectTypecheck, } from '../../utils/tsc-check.js';
 const scaffoldFiles = (config) => {
     const files = [];
@@ -17,11 +17,6 @@ const scaffoldFiles = (config) => {
             file: config.consoleFunctionsFile,
             generator: 'pikkuConsoleFunctions',
         });
-    if (config.scaffold?.scenarios && config.scenariosFunctionsFile)
-        files.push({
-            file: config.scenariosFunctionsFile,
-            generator: 'pikkuScenarioFunctions',
-        });
     if (config.scaffold?.userAdmin && config.userAdminFunctionsFile)
         files.push({
             file: config.userAdminFunctionsFile,
@@ -46,6 +41,7 @@ export const allWorkflow = pikkuWorkflowComplexFunc({
         // (workflows/RPCs "disappear"), so refuse to codegen against it.
         await assertSingleCoreVersion(config.rootDir, logger);
         await pruneLegacyScaffoldFiles(config);
+        await removeRetiredScaffoldFiles(config);
         const allImports = [];
         let typesDeclarationFileExists = true;
         if (!existsSync(config.outDir)) {
@@ -150,7 +146,6 @@ export const allWorkflow = pikkuWorkflowComplexFunc({
             workflow.do('Graph wirings', 'pikkuGraphWirings', null),
             workflow.do('Public RPC', 'pikkuPublicRPC', null),
             workflow.do('Console functions', 'pikkuConsoleFunctions', null),
-            workflow.do('Scenario functions', 'pikkuScenarioFunctions', null),
             workflow.do('User admin functions', 'pikkuUserAdminFunctions', null),
             workflow.do('Events scaffold', 'pikkuEventsScaffold', null),
             workflow.do('Emails', 'pikkuEmails', null),

package/dist/src/server/server-ready.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Printed once the server is listening AND the project's `afterStart`
+ * lifecycle has resolved.
+ *
+ * The runtime's own `listening on …` line is emitted inside `server.start()`,
+ * which runs *before* `afterStart` — so anything a project seeds there (users,
+ * scopes, fixtures) is still pending when it appears, and a parent process
+ * that treats it as readiness races the seed. This marker is the point at
+ * which the server is actually usable, and it is what `--spawn` waits for.
+ */
+export declare const SERVER_READY_MARKER = "pikku: ready";
+export declare const serverReadyLine: (hostname: string, port: number) => string;

package/dist/src/server/server-ready.js

@@ -0,0 +1,12 @@
+/**
+ * Printed once the server is listening AND the project's `afterStart`
+ * lifecycle has resolved.
+ *
+ * The runtime's own `listening on …` line is emitted inside `server.start()`,
+ * which runs *before* `afterStart` — so anything a project seeds there (users,
+ * scopes, fixtures) is still pending when it appears, and a parent process
+ * that treats it as readiness races the seed. This marker is the point at
+ * which the server is actually usable, and it is what `--spawn` waits for.
+ */
+export const SERVER_READY_MARKER = 'pikku: ready';
+export const serverReadyLine = (hostname, port) => `${SERVER_READY_MARKER} on http://${hostname}:${port}`;

package/dist/src/server/spawn-dev-server.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Rejects if anything is already listening on `port`.
+ *
+ * A readiness check cannot tell "my server" from "someone else's": both answer
+ * on the same address once spawned, so a stale server left on the target port
+ * silently absorbs a whole run and reports failures that belong to code nobody
+ * is looking at. A TCP-level check before spawning is the only point at which
+ * the two are distinguishable.
+ */
+export declare const assertPortFree: (port: number, host?: string, timeoutMs?: number) => Promise<void>;
+export interface ReadyBarrier {
+    /** Feed a chunk of the child's output. */
+    observe: (text: string) => void;
+    /** Record that the child exited, so the wait fails fast instead of timing out. */
+    markExited: (code: number | null) => void;
+    wait: (options?: {
+        timeoutMs?: number;
+        pollMs?: number;
+    }) => Promise<void>;
+}
+/**
+ * Watches a spawned server's output for the ready marker. Separated from the
+ * spawn so the three outcomes that matter — ready, the child died, nothing
+ * happened for long enough — are testable without a real process.
+ */
+export declare const createReadyBarrier: (label: string) => ReadyBarrier;
+export interface SpawnedServer {
+    /** Kills the whole process group, so the server's own children go with it. */
+    stop: () => void;
+    /** Resolves on the ready marker; rejects if the server dies or never reports. */
+    waitUntilReady: (options?: {
+        timeoutMs?: number;
+    }) => Promise<void>;
+}
+export interface SpawnDevServerOptions {
+    cwd: string;
+    port: number;
+    hostname?: string;
+    coverage?: boolean;
+    /** Passed through as `--test`, which sets PIKKU_TEST_RUN for isTestRun(). */
+    test?: boolean;
+    env?: NodeJS.ProcessEnv;
+    /** Where the server's own output goes. Defaults to this process's streams. */
+    onOutput?: (text: string) => void;
+}
+/**
+ * Start `pikku dev` as its own process group and stream its output under a
+ * `[server]` prefix. Does not wait — call `waitUntilReady`.
+ */
+export declare const spawnDevServer: (options: SpawnDevServerOptions) => Promise<SpawnedServer>;

package/dist/src/server/spawn-dev-server.js

@@ -0,0 +1,112 @@
+import { spawn } from 'node:child_process';
+import { connect } from 'node:net';
+import { SERVER_READY_MARKER } from './server-ready.js';
+/**
+ * Rejects if anything is already listening on `port`.
+ *
+ * A readiness check cannot tell "my server" from "someone else's": both answer
+ * on the same address once spawned, so a stale server left on the target port
+ * silently absorbs a whole run and reports failures that belong to code nobody
+ * is looking at. A TCP-level check before spawning is the only point at which
+ * the two are distinguishable.
+ */
+export const assertPortFree = (port, host = '127.0.0.1', timeoutMs = 1000) => new Promise((resolve, reject) => {
+    const socket = connect({ port, host });
+    const settle = (error) => {
+        socket.removeAllListeners();
+        socket.destroy();
+        error ? reject(error) : resolve();
+    };
+    socket.setTimeout(timeoutMs);
+    socket.on('connect', () => settle(new Error(`Port ${port} is already in use — something is already listening on ${host}:${port}. ` +
+        `Stop it, or point this environment's apiUrl at a free port.`)));
+    // Nothing listening, or unreachable: either way this process is free to bind.
+    socket.on('error', () => settle());
+    socket.on('timeout', () => settle());
+});
+/**
+ * Watches a spawned server's output for the ready marker. Separated from the
+ * spawn so the three outcomes that matter — ready, the child died, nothing
+ * happened for long enough — are testable without a real process.
+ */
+export const createReadyBarrier = (label) => {
+    let ready = false;
+    let exit;
+    // Stdout arrives in arbitrary chunks, so the marker can straddle two of them.
+    // Keep just enough of the tail to rejoin a split marker.
+    let tail = '';
+    return {
+        observe: (text) => {
+            if (ready)
+                return;
+            const window = tail + text;
+            if (window.includes(SERVER_READY_MARKER)) {
+                ready = true;
+                tail = '';
+                return;
+            }
+            tail = window.slice(-SERVER_READY_MARKER.length);
+        },
+        markExited: (code) => {
+            exit = { code };
+        },
+        wait: async ({ timeoutMs = 120_000, pollMs = 100 } = {}) => {
+            const deadline = Date.now() + timeoutMs;
+            while (Date.now() < deadline) {
+                if (ready)
+                    return;
+                if (exit) {
+                    throw new Error(`${label} exited with code ${exit.code} before it was ready`);
+                }
+                await new Promise((r) => setTimeout(r, pollMs));
+            }
+            throw new Error(`${label} did not report ready within ${timeoutMs / 1000} seconds`);
+        },
+    };
+};
+/**
+ * Start `pikku dev` as its own process group and stream its output under a
+ * `[server]` prefix. Does not wait — call `waitUntilReady`.
+ */
+export const spawnDevServer = async (options) => {
+    const { cwd, port, hostname = '127.0.0.1', coverage, test = true, env, onOutput = (text) => process.stdout.write(text), } = options;
+    await assertPortFree(port, hostname);
+    const args = ['pikku', 'dev', '--port', String(port)];
+    if (coverage)
+        args.push('--coverage');
+    if (test)
+        args.push('--test');
+    const child = spawn('npx', args, {
+        cwd,
+        env: { ...process.env, ...env },
+        stdio: 'pipe',
+        detached: true,
+    });
+    const barrier = createReadyBarrier('Server');
+    const forward = (chunk) => {
+        const text = chunk.toString();
+        barrier.observe(text);
+        onOutput(text
+            .split('\n')
+            .map((line) => (line ? `[server] ${line}` : line))
+            .join('\n'));
+    };
+    child.stdout?.on('data', forward);
+    child.stderr?.on('data', forward);
+    child.on('exit', (code) => barrier.markExited(code));
+    return {
+        waitUntilReady: barrier.wait,
+        stop: () => {
+            child.stdout?.destroy();
+            child.stderr?.destroy();
+            if (child.pid) {
+                try {
+                    process.kill(-child.pid, 'SIGTERM');
+                }
+                catch {
+                    // Process group may already be gone
+                }
+            }
+        },
+    };
+};

package/dist/src/services.js

@@ -149,7 +149,14 @@ export const createSingletonServices = async (config) => {
     let unfilteredStateIsSetupOnly = false;
     let inspectedTsGeneration;
     let inspectorInvalidated = false;
-    const getInspectorState = async (refresh = false, setupOnly = false, bootstrapMode = false) => {
+    /**
+     * `unfiltered` is for commands that RUN the project rather than generate from
+     * it. The CLI filters narrow what gets written out, which is meaningless to a
+     * runner and actively wrong for one: `--tags` on `pikku scenario run` selects
+     * which scenarios to run, and if it also narrowed the state the runner would
+     * lose the very step functions it is about to call.
+     */
+    const getInspectorState = async (refresh = false, setupOnly = false, bootstrapMode = false, unfiltered = false) => {
         // In bootstrap mode, return a minimal "zero state" with core types
         // This allows bootstrap to run immediately without inspecting the codebase
         if (bootstrapMode) {
@@ -240,6 +247,7 @@ export const createSingletonServices = async (config) => {
                 rootDir,
                 isAddon: !!config.addon,
                 oldProgram,
+                tsconfig: config.tsconfig,
                 types: {
                     configFileType: config.configFile,
                     userSessionType: config.userSessionType,
@@ -287,6 +295,9 @@ export const createSingletonServices = async (config) => {
                 }
             }
         }
+        if (unfiltered) {
+            return unfilteredState;
+        }
         // Apply filters as a post-processing step
         const filteredState = filterInspectorState(unfilteredState, filters, logger);
         return filteredState;

package/dist/src/utils/file-writer.js

@@ -1,5 +1,5 @@
 import { dirname, join } from 'path';
-import { mkdir, readFile, writeFile, rm } from 'fs/promises';
+import { mkdir, readFile, rename, writeFile, rm } from 'fs/promises';
 import { existsSync } from 'fs';
 import { getCLIVersion } from './get-cli-version.js';
 export const DO_NOT_MODIFY_COMMENT = `/**
@@ -36,7 +36,19 @@ export const writeFileInDir = async (logger, path, content, { ignoreModifyCommen
     // Only write if content has changed or file doesn't exist
     if (existingContent !== content) {
         await mkdir(dirname(path), { recursive: true });
-        await writeFile(path, content, 'utf-8');
+        // Atomically, because generated files are read while they are generated:
+        // `pikku scenario run --spawn` bundles the registers while the dev server it
+        // spawned is regenerating them, and `writeFile` truncates before it writes —
+        // a reader that lands in that window gets an empty file, not an old one.
+        const tmp = `${path}.${process.pid}.tmp`;
+        try {
+            await writeFile(tmp, content, 'utf-8');
+            await rename(tmp, path);
+        }
+        catch (e) {
+            await rm(tmp, { force: true }).catch(() => { });
+            throw e;
+        }
         if (TS_FILE_REGEX.test(path)) {
             tsWriteGeneration++;
         }

package/dist/src/utils/meta-diff.js

@@ -19,7 +19,7 @@ const UNWRAP = {
     email: 'templates',
     agent: 'agentsMeta',
 };
-// Workflows (incl. userflows/scenarios) are written one file per workflow under
+// Workflows (incl. scenarios) are written one file per workflow under
 // this dir; the file basename (sans `.gen.json`) is the id, `-verbose` excluded.
 const WORKFLOW_META_DIR = 'workflow/meta';
 function readJson(path) {
@@ -40,7 +40,10 @@ function readSingle(outDir, category, relPath) {
     const unwrapKey = UNWRAP[category];
     if (unwrapKey) {
         const inner = raw[unwrapKey];
-        raw = inner && typeof inner === 'object' && !Array.isArray(inner) ? inner : {};
+        raw =
+            inner && typeof inner === 'object' && !Array.isArray(inner)
+                ? inner
+                : {};
     }
     if (category !== 'http')
         return raw;

package/dist/src/utils/pikku-cli-config.d.ts

@@ -1,4 +1,18 @@
 import type { PikkuCLIConfig } from '../../types/config.js';
 import type { CLILogger } from '../services/cli-logger.service.js';
 export declare const getPikkuCLIConfig: (logger: CLILogger, configFile: string | undefined, requiredFields: Array<keyof PikkuCLIConfig>, exitProcess?: boolean, outDirOverride?: string) => Promise<PikkuCLIConfig>;
+/** A config that was found and parsed, but says something impossible. */
+export declare class PikkuCLIConfigError extends Error {
+}
+/**
+ * The two schema registers must be two directories.
+ *
+ * `saveSchemas` owns whatever directory it is given: it writes `register.gen.ts`
+ * and prunes every schema file that its own required-set does not name. Point the
+ * scenario write at `schemaDirectory` and the second call overwrites the app's
+ * register with the scenario-only one and deletes the app's schema files — the
+ * exact leak the split exists to prevent, silently, and only in a deployed
+ * bundle. Nothing downstream can detect it, so it is rejected here.
+ */
+export declare const assertSchemaDirectoriesAreDistinct: (config: Pick<PikkuCLIConfig, "schemaDirectory" | "scenarioSchemaDirectory">) => void;
 export declare const validateCLIConfig: (cliConfig: PikkuCLIConfig, required: Array<keyof PikkuCLIConfig>) => void;