@pikku/cli 0.12.93 → 0.12.99

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

@@ -1,4 +1,4 @@
-export const serializeWorkflowTypes = (functionTypesImportPath, rpcMapImportPath, workflowMapImportPath, agentMapImportPath, scopesImportPath, scenarioStepMapImportPath = './pikku-scenario-step-map.gen.js', scenarioActorsImportPath = './pikku-scenario-actors.gen.js') => {
+export const serializeWorkflowTypes = (functionTypesImportPath, rpcMapImportPath, workflowMapImportPath, agentMapImportPath, scopesImportPath, scenarioStepMapImportPath = './pikku-scenario-step-map.gen.js', scenarioActorsImportPath = './pikku-personas.gen.js') => {
     return `import { WorkflowCancelledException } from '@pikku/core/workflow'
 import { template } from '@pikku/core/workflow'
 import {
@@ -14,9 +14,9 @@ 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}'
+import type { TypedPersonas } from '${scenarioActorsImportPath}'
 
-export type { TypedScenarioActors }
+export type { TypedPersonas }
 
 export { template }
 
@@ -43,18 +43,12 @@ export interface TypedWorkflow extends 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.
+ * The typed half of a scenario wire: \`given\`/\`when\`/\`then\`, narrowed to the
+ * names declared by \`pikkuScenarioStep\` in this project. \`given\` and \`when\`
+ * differ only in the prose the reporter renders; \`then\` additionally makes the
+ * step's bindings witnesses rather than alternatives.
  */
 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,
@@ -308,18 +302,28 @@ export function pikkuFeature<const Scenarios extends readonly unknown[]>(
   return config
 }
 
+/**
+ * One surface's implementation of a step.
+ *
+ * Each binding is typed independently, so a browser binding gets a non-optional
+ * \`wire.browser\` and a cli binding a non-optional \`wire.cli\` without either
+ * leaking into the other.
+ */
 export type PikkuFunctionScenarioStep<
   In = unknown,
   Out = never,
-  B extends boolean = false
-> = PikkuFunctionSessionless<In, Out, B extends true ? 'scenarioStep' | 'browser' : 'scenarioStep'>
+  Surface extends 'browser' | 'cli' | 'default' = 'default'
+> = PikkuFunctionSessionless<
+  In,
+  Out,
+  Surface extends 'default' ? 'scenarioStep' : 'scenarioStep' | Surface
+>
 
 export type PikkuScenarioStepConfigWithSchema<
   InputSchema extends StandardSchemaV1 | undefined = undefined,
-  OutputSchema extends StandardSchemaV1 | undefined = undefined,
-  B extends boolean = false
+  OutputSchema extends StandardSchemaV1 | undefined = undefined
 > = {
-  /** Registered name — this is the string \`scenario.step()\` references. */
+  /** Registered name — this is the string \`scenario.given()\` references. */
   name: string
   /**
    * What this step does, for the console and for whoever reads the source. It
@@ -336,49 +340,175 @@ export type PikkuScenarioStepConfigWithSchema<
    * 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<
+  /**
+   * Drive this step through a real browser, as a human would. The runner
+   * provisions a window for the step's actor first — which makes an actor
+   * mandatory — and \`wire.browser\` is non-optional inside it.
+   *
+   * Compose shared utilities here rather than writing raw clicks: the step says
+   * what the actor is doing, the utilities say how.
+   */
+  browser?: PikkuFunctionScenarioStep<
+    InputSchema extends StandardSchemaV1 ? InferSchemaOutput<InputSchema> : unknown,
+    OutputSchema extends StandardSchemaV1 ? InferSchemaOutput<OutputSchema> : unknown,
+    'browser'
+  >
+  /** Drive this step remotely, over the websocket. */
+  cli?: PikkuFunctionScenarioStep<
+    InputSchema extends StandardSchemaV1 ? InferSchemaOutput<InputSchema> : unknown,
+    OutputSchema extends StandardSchemaV1 ? InferSchemaOutput<OutputSchema> : unknown,
+    'cli'
+  >
+  /**
+   * The server-side path — the fast suite, and the floor every other surface
+   * falls back to.
+   *
+   * On a \`then\`, this is not an alternative to the other bindings but a second
+   * **witness**: the run executes every binding it has and fails if they
+   * disagree, because "the row says paid" and "the page says paid" are different
+   * claims and the gap between them is the bug nobody catches.
+   */
+  default?: PikkuFunctionScenarioStep<
     InputSchema extends StandardSchemaV1 ? InferSchemaOutput<InputSchema> : unknown,
     OutputSchema extends StandardSchemaV1 ? InferSchemaOutput<OutputSchema> : unknown,
-    B
+    'default'
   >
 }
 
-export type PikkuScenarioStepConfig<In, Out, B extends boolean = false> =
-  Omit<PikkuScenarioStepConfigWithSchema<undefined, undefined, B>, 'func' | 'input' | 'output'> & {
-    func: PikkuFunctionScenarioStep<In, Out, B>
+export type PikkuScenarioStepConfig<In, Out> =
+  Omit<PikkuScenarioStepConfigWithSchema<undefined, undefined>, 'browser' | 'cli' | 'default' | 'input' | 'output'> & {
+    browser?: PikkuFunctionScenarioStep<In, Out, 'browser'>
+    cli?: PikkuFunctionScenarioStep<In, Out, 'cli'>
+    default?: PikkuFunctionScenarioStep<In, Out, 'default'>
   }
 
 /**
- * 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.
+ * A named, reusable scenario step, declaring one implementation per surface an
+ * actor can drive it through.
+ *
+ * The step's identity is what the actor is trying to do; which surface carries
+ * it out is a binding. That is what lets one ladder run through a real browser,
+ * over the websocket, or entirely server-side — and what makes "how much of this
+ * flow can a human actually reach" a number rather than a guess.
  *
  * 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
+  OutputSchema extends StandardSchemaV1 | undefined = undefined
 >(
-  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'>
+  config: PikkuScenarioStepConfigWithSchema<InputSchema, OutputSchema>
+): PikkuFunctionConfig<InputSchema extends StandardSchemaV1 ? InferSchemaOutput<InputSchema> : unknown, OutputSchema extends StandardSchemaV1 ? InferSchemaOutput<OutputSchema> : unknown, 'scenarioStep' | 'browser' | 'cli', PikkuFunctionScenarioStep<InputSchema extends StandardSchemaV1 ? InferSchemaOutput<InputSchema> : unknown, OutputSchema extends StandardSchemaV1 ? InferSchemaOutput<OutputSchema> : unknown, 'browser' | 'cli' | 'default'>, InputSchema, OutputSchema>
+export function pikkuScenarioStep<In, Out = unknown>(
+  config: PikkuScenarioStepConfig<In, Out>
+): PikkuFunctionConfig<In, Out, 'scenarioStep' | 'browser' | 'cli'>
 export function pikkuScenarioStep(config: any) {
-  return config
+  const surfaces = (['browser', 'cli', 'default'] as const).filter(
+    (surface) => typeof config[surface] === 'function'
+  )
+  if (surfaces.length === 0) {
+    throw new Error(
+      \`[scenario] step '\${config.name}' declares no surface bindings. Add at least a \\\`default\\\` (server-side) implementation.\`
+    )
+  }
+  return {
+    ...config,
+    surfaces,
+    // The runner sets the surface on the wire and calls this once per binding it
+    // resolved — every witness of a \`then\`, exactly one for an action step.
+    func: (services: any, data: any, wire: any) => {
+      const surface = wire?.scenarioStep?.surface ?? 'default'
+      const binding = config[surface] ?? config.default
+      return binding(services, data, wire)
+    },
+  }
+}
+
+/**
+ * What a step declares when nobody drives it: one implementation, and no
+ * surfaces to choose between.
+ *
+ * \`func\` rather than \`default\` is the point. \`default\` means *the fallback when
+ * no other surface applies*, which implies others could exist; \`func\` says
+ * structurally that there is one way this happens. That also keeps the phase
+ * rule coherent — an assertion runs every witness it has and fails if they
+ * disagree, and this has exactly one by construction.
+ */
+export type PikkuSubjectScenarioStepConfigWithSchema<
+  InputSchema extends StandardSchemaV1 | undefined = undefined,
+  OutputSchema extends StandardSchemaV1 | undefined = undefined
+> = Omit<
+  PikkuScenarioStepConfigWithSchema<InputSchema, OutputSchema>,
+  'browser' | 'cli' | 'default'
+> & {
+  func: PikkuFunctionScenarioStep<
+    InputSchema extends StandardSchemaV1 ? InferSchemaOutput<InputSchema> : unknown,
+    OutputSchema extends StandardSchemaV1 ? InferSchemaOutput<OutputSchema> : unknown,
+    'default'
+  >
+}
+
+export type PikkuSubjectScenarioStepConfig<In, Out> =
+  Omit<PikkuScenarioStepConfig<In, Out>, 'browser' | 'cli' | 'default'> & {
+    func: PikkuFunctionScenarioStep<In, Out, 'default'>
+  }
+
+/**
+ * A step in which the app acts on itself — "Given the platform has expired the
+ * trial".
+ *
+ * The grammatical subject of that sentence is not a user of your app; it **is**
+ * your app, which is why it is its own declaration rather than a persona with an
+ * asterisk. A persona is a person.
+ *
+ * Local-test-only, and never in a virtual user's catalogue: a virtual user that
+ * could expire its own trial is manufacturing the outcome it exists to discover.
+ */
+export function pikkuPlatformScenarioStep<
+  InputSchema extends StandardSchemaV1 | undefined = undefined,
+  OutputSchema extends StandardSchemaV1 | undefined = undefined
+>(
+  config: PikkuSubjectScenarioStepConfigWithSchema<InputSchema, OutputSchema>
+): PikkuFunctionConfig<InputSchema extends StandardSchemaV1 ? InferSchemaOutput<InputSchema> : unknown, OutputSchema extends StandardSchemaV1 ? InferSchemaOutput<OutputSchema> : unknown, 'scenarioStep', PikkuFunctionScenarioStep<InputSchema extends StandardSchemaV1 ? InferSchemaOutput<InputSchema> : unknown, OutputSchema extends StandardSchemaV1 ? InferSchemaOutput<OutputSchema> : unknown, 'default'>, InputSchema, OutputSchema>
+export function pikkuPlatformScenarioStep<In, Out = unknown>(
+  config: PikkuSubjectScenarioStepConfig<In, Out>
+): PikkuFunctionConfig<In, Out, 'scenarioStep'>
+export function pikkuPlatformScenarioStep(config: any) {
+  return { ...config, surfaces: ['default'] }
+}
+
+/**
+ * A step in which a third-party system acts — "Given Stripe's webhook arrives",
+ * "When Mailgun bounces it".
+ *
+ * \`addon\` names the addon that wraps that service, the same name its
+ * \`wireAddon\` declares. These steps *are* the mock its consumers currently
+ * hand-write: shipped by the addon author, maintained with the addon, and the
+ * same artifact that appears in the prose.
+ *
+ * Note that arranging and asserting are different — "Stripe's webhook arrives"
+ * stubs, "Then Stripe was charged" asserts, and only the first is a stub.
+ *
+ * Local-test-only, and never in a virtual user's catalogue: one that could
+ * invoke this would forge its own payment success.
+ */
+export function pikkuAddonScenarioStep<
+  InputSchema extends StandardSchemaV1 | undefined = undefined,
+  OutputSchema extends StandardSchemaV1 | undefined = undefined
+>(
+  config: PikkuSubjectScenarioStepConfigWithSchema<InputSchema, OutputSchema> & { addon: string }
+): PikkuFunctionConfig<InputSchema extends StandardSchemaV1 ? InferSchemaOutput<InputSchema> : unknown, OutputSchema extends StandardSchemaV1 ? InferSchemaOutput<OutputSchema> : unknown, 'scenarioStep', PikkuFunctionScenarioStep<InputSchema extends StandardSchemaV1 ? InferSchemaOutput<InputSchema> : unknown, OutputSchema extends StandardSchemaV1 ? InferSchemaOutput<OutputSchema> : unknown, 'default'>, InputSchema, OutputSchema>
+export function pikkuAddonScenarioStep<In, Out = unknown>(
+  config: PikkuSubjectScenarioStepConfig<In, Out> & { addon: string }
+): PikkuFunctionConfig<In, Out, 'scenarioStep'>
+export function pikkuAddonScenarioStep(config: any) {
+  return { ...config, surfaces: ['default'] }
 }
 
 type TypedRef<T> = { $ref: string; path?: string } & { __phantomType?: T }

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

@@ -22,6 +22,11 @@ const scaffoldFiles = (config) => {
             file: config.userAdminFunctionsFile,
             generator: 'pikkuUserAdminFunctions',
         });
+    if (config.scaffold?.virtualUser && config.virtualUserFunctionsFile)
+        files.push({
+            file: config.virtualUserFunctionsFile,
+            generator: 'pikkuVirtualUserFunctions',
+        });
     if (config.scaffold?.agent && config.publicAgentFile)
         files.push({
             file: config.publicAgentFile,
@@ -46,13 +51,27 @@ export const allWorkflow = pikkuWorkflowComplexFunc({
         let typesDeclarationFileExists = true;
         if (!existsSync(config.outDir)) {
             logger.debug(`• .pikku directory not found, running bootstrap first...`);
-            await workflow.do('Bootstrap inspect', async () => getInspectorState(false, true, true));
+            // Every `getInspectorState` step below discards its result on purpose. A
+            // step's return value is stored as the step result and stays reachable for
+            // the life of the run, and an InspectorState holds a whole ts.Program — so
+            // returning it pins one TypeScript program per inspection instead of
+            // letting the previous one be collected. On a large project that is the
+            // difference between ~1.7GB and ~2.6GB peak RSS, i.e. between fitting in a
+            // 2GB CI heap and dying in it. Callers that need the state call
+            // `getInspectorState()` directly (it caches), never through a step.
+            await workflow.do('Bootstrap inspect', async () => {
+                await getInspectorState(false, true, true);
+            });
             // Both before function types: pikku-types.gen.ts re-exports the scope
             // definition types and imports ScopeId from the scopes codegen, so any
             // later import of '#pikku' — the inspector reading a project's zod
             // schemas, for one — fails until these two files exist.
             await workflow.do('Bootstrap scope definition types', 'pikkuScopeDefinitionTypes', null);
             await workflow.do('Bootstrap scopes', 'pikkuScopes', { bootstrap: true });
+            await workflow.do('Bootstrap roles', 'pikkuRoles', { bootstrap: true });
+            await workflow.do('Bootstrap personas', 'pikkuPersonas', {
+                bootstrap: true,
+            });
             await workflow.do('Bootstrap function types split', 'pikkuFunctionTypesSplit', { bootstrap: true });
             // Pre-write a stub auth.types.ts (if the project uses better-auth) so the
             // pikkuBetterAuth re-export resolves before any user file is imported.
@@ -86,7 +105,9 @@ export const allWorkflow = pikkuWorkflowComplexFunc({
                     bootstrap: true,
                 });
             }
-            await workflow.do('Bootstrap re-inspect', async () => getInspectorState(true, true));
+            await workflow.do('Bootstrap re-inspect', async () => {
+                await getInspectorState(true, true);
+            });
         }
         if (!existsSync(config.typesDeclarationFile)) {
             typesDeclarationFileExists = false;
@@ -100,7 +121,9 @@ export const allWorkflow = pikkuWorkflowComplexFunc({
         await workflow.do('Generate function types', 'pikkuFunctionTypes', {});
         if (!typesDeclarationFileExists || missingScaffolds.length > 0) {
             logger.debug(`• Type file or scaffolds first created, inspecting again...`);
-            await workflow.do('Re-inspect after types', async () => getInspectorState(true));
+            await workflow.do('Re-inspect after types', async () => {
+                await getInspectorState(true);
+            });
         }
         // Type generators are independent of each other
         const typeGenerators = [
@@ -147,6 +170,7 @@ export const allWorkflow = pikkuWorkflowComplexFunc({
             workflow.do('Public RPC', 'pikkuPublicRPC', null),
             workflow.do('Console functions', 'pikkuConsoleFunctions', null),
             workflow.do('User admin functions', 'pikkuUserAdminFunctions', null),
+            workflow.do('Virtual user functions', 'pikkuVirtualUserFunctions', null),
             workflow.do('Events scaffold', 'pikkuEventsScaffold', null),
             workflow.do('Emails', 'pikkuEmails', null),
             workflow.do('Secret definition types', 'pikkuSecretDefinitionTypes', null),
@@ -155,6 +179,8 @@ export const allWorkflow = pikkuWorkflowComplexFunc({
             workflow.do('Credentials', 'pikkuCredentials', null),
             workflow.do('Scope definition types', 'pikkuScopeDefinitionTypes', null),
             workflow.do('Scopes', 'pikkuScopes', {}),
+            workflow.do('Roles', 'pikkuRoles', {}),
+            workflow.do('Personas', 'pikkuPersonas', {}),
             workflow.do('Variable definition types', 'pikkuVariableDefinitionTypes', null),
             workflow.do('Variables', 'pikkuVariables', null),
             workflow.do('Addon types', 'pikkuAddonTypes', null),
@@ -163,18 +189,25 @@ export const allWorkflow = pikkuWorkflowComplexFunc({
             allImports.push(config.rpcInternalWiringMetaFile);
         }
         if (agents || !config.addon) {
-            await workflow.do('Re-inspect after agents', async () => getInspectorState(true));
+            await workflow.do('Re-inspect after agents', async () => {
+                await getInspectorState(true);
+            });
         }
-        // pikkuAuth generates auth-secrets.gen.ts (with wireSecret calls) inside the
-        // Promise.all above, but pikkuSecrets runs concurrently from the pre-auth
-        // inspector state. Re-run secret/credential/variable codegen now so that the
-        // freshly-generated auth-secrets.gen.ts (just picked up by Re-inspect above)
-        // is reflected in pikku-secrets-meta.gen.json.
-        if ((await getInspectorState()).auth.definition) {
+        // pikkuAuth generates auth-secrets.gen.ts and pikkuPersonas generates
+        // pikku-personas-secrets.gen.ts (both full of defineSecret calls) inside the
+        // Promise.all above, but pikkuSecrets runs concurrently from the inspector
+        // state as it was before either wrote anything. Re-run secret/credential/
+        // variable codegen now so those freshly-generated files — just picked up by
+        // Re-inspect above — are reflected in pikku-secrets-meta.gen.json. Without
+        // this the declaration only lands on a second `pikku` run, and a cold
+        // project deploys without ever being asked for the value.
+        const stateAfterScaffold = await getInspectorState();
+        if (stateAfterScaffold.auth.definition ||
+            stateAfterScaffold.personas.definitions.length > 0) {
             await Promise.all([
-                workflow.do('Secrets (post-auth)', 'pikkuSecrets', null),
-                workflow.do('Credentials (post-auth)', 'pikkuCredentials', null),
-                workflow.do('Variables (post-auth)', 'pikkuVariables', null),
+                workflow.do('Secrets (post-scaffold)', 'pikkuSecrets', null),
+                workflow.do('Credentials (post-scaffold)', 'pikkuCredentials', null),
+                workflow.do('Variables (post-scaffold)', 'pikkuVariables', null),
             ]);
         }
         const schemas = await workflow.do('Schemas', 'pikkuSchemas', null);
@@ -198,7 +231,9 @@ export const allWorkflow = pikkuWorkflowComplexFunc({
             }
         }
         if (workflows || remoteRPC || webhook || workflowRoutes) {
-            await workflow.do('Re-inspect after workflows', async () => getInspectorState(true));
+            await workflow.do('Re-inspect after workflows', async () => {
+                await getInspectorState(true);
+            });
             const regeneratedSchemas = await workflow.do('Re-generate schemas', 'pikkuSchemas', null);
             if (regeneratedSchemas && !schemas) {
                 allImports.push(`${config.schemaDirectory}/register.gen.ts`);
@@ -276,7 +311,9 @@ export const allWorkflow = pikkuWorkflowComplexFunc({
                 const cliChannelGenerated = await workflow.do('CLI entry', 'pikkuCLIEntry', null);
                 allImports.push(config.cliWiringMetaFile, config.cliWiringsFile);
                 if (cliChannelGenerated) {
-                    await workflow.do('Re-inspect after CLI channel', async () => getInspectorState(true));
+                    await workflow.do('Re-inspect after CLI channel', async () => {
+                        await getInspectorState(true);
+                    });
                     const cliChannels = await workflow.do('Channels after CLI', 'pikkuCommandChannels', null);
                     await workflow.do('Functions after CLI', 'pikkuFunctions', null);
                     await workflow.do('Schemas after CLI', 'pikkuSchemas', null);
@@ -296,7 +333,9 @@ export const allWorkflow = pikkuWorkflowComplexFunc({
         }
         if (config.openAPI) {
             logger.debug(`• OpenAPI requires a reinspection to pickup new generated types..`);
-            await workflow.do('OpenAPI re-inspect', async () => getInspectorState(true));
+            await workflow.do('OpenAPI re-inspect', async () => {
+                await getInspectorState(true);
+            });
             await workflow.do('OpenAPI', 'pikkuOpenAPI', null);
         }
         await workflow.do('Versions update', 'pikkuVersionsUpdate', null);

package/dist/src/server/bun-server-runner.d.ts

@@ -8,10 +8,10 @@
  */
 import type { EventHubService } from '@pikku/core';
 import type { Logger } from '@pikku/core/services';
-import type { DevServerRunner, DevServerInstance, DevServerConfig } from './dev-server-runner.interface.js';
+import type { DevServerRunner, DevServerInstance, DevServerConfig, DevServerOptions } from './dev-server-runner.interface.js';
 export declare class BunServerRunner implements DevServerRunner {
     private mod?;
     private eventHub?;
     createEventHub(): Promise<EventHubService<any>>;
-    createServer(config: DevServerConfig, logger: Logger): DevServerInstance;
+    createServer(config: DevServerConfig, logger: Logger, options?: DevServerOptions): DevServerInstance;
 }

package/dist/src/server/bun-server-runner.js

@@ -14,12 +14,16 @@ export class BunServerRunner {
         this.eventHub = new this.mod.BunEventHubService();
         return this.eventHub;
     }
-    createServer(config, logger) {
+    createServer(config, logger, options = {}) {
         if (!this.mod || !this.eventHub) {
             throw new Error('createEventHub() must be called before createServer()');
         }
         return new this.mod.PikkuBunServer(config, logger, {
             eventHub: this.eventHub,
+            // Dropped here until now, which silently disabled signed asset reads for
+            // every Bun project: `config.content` arrived, but the service that
+            // verifies its signatures did not.
+            contentSigningJWT: options.contentSigningJWT,
         });
     }
 }

package/dist/src/server/content-signing-jwt.d.ts

@@ -0,0 +1,13 @@
+/**
+ * `pikku dev` and `pikku serve` construct the local content service themselves,
+ * so they must supply the key its signed asset URLs are signed and verified
+ * with — a project is not required to wire a JWTService just to serve uploads
+ * in development.
+ *
+ * The key is random and per-process: URLs signed by one dev server mean
+ * nothing to the next. That is the right lifetime for a development secret,
+ * and it lets the runtime reject any signature it cannot verify instead of
+ * waving through requests when no key is configured.
+ */
+import type { JWTService } from '@pikku/core/services';
+export declare const createEphemeralContentSigningJWT: () => JWTService;

package/dist/src/server/content-signing-jwt.js

@@ -0,0 +1,51 @@
+/**
+ * `pikku dev` and `pikku serve` construct the local content service themselves,
+ * so they must supply the key its signed asset URLs are signed and verified
+ * with — a project is not required to wire a JWTService just to serve uploads
+ * in development.
+ *
+ * The key is random and per-process: URLs signed by one dev server mean
+ * nothing to the next. That is the right lifetime for a development secret,
+ * and it lets the runtime reject any signature it cannot verify instead of
+ * waving through requests when no key is configured.
+ */
+import { createHmac, randomBytes, timingSafeEqual } from 'node:crypto';
+import { getRelativeTimeOffsetFromNow } from '@pikku/core';
+export const createEphemeralContentSigningJWT = () => {
+    const key = randomBytes(32);
+    const sign = (body) => createHmac('sha256', key).update(body).digest('base64url');
+    return {
+        encode: async (expiresIn, payload) => {
+            const envelope = {
+                exp: getRelativeTimeOffsetFromNow(expiresIn).getTime(),
+                payload,
+            };
+            const body = Buffer.from(JSON.stringify(envelope), 'utf8').toString('base64url');
+            return `${body}.${sign(body)}`;
+        },
+        decode: async (hash, invalidHashError) => {
+            const invalid = invalidHashError ?? new Error('Invalid content signature');
+            const [body, signature] = hash.split('.');
+            if (!body || !signature) {
+                throw invalid;
+            }
+            const expected = Buffer.from(sign(body), 'utf8');
+            const actual = Buffer.from(signature, 'utf8');
+            if (expected.length !== actual.length ||
+                !timingSafeEqual(expected, actual)) {
+                throw invalid;
+            }
+            let envelope;
+            try {
+                envelope = JSON.parse(Buffer.from(body, 'base64url').toString('utf8'));
+            }
+            catch {
+                throw invalid;
+            }
+            if (typeof envelope.exp !== 'number' || Date.now() > envelope.exp) {
+                throw invalid;
+            }
+            return envelope.payload;
+        },
+    };
+};

package/dist/src/server/dev-server-runner.interface.d.ts

@@ -9,7 +9,7 @@
  * `services.ts` and injected — no `typeof Bun` checks in the dev command.
  */
 import type { EventHubService } from '@pikku/core';
-import type { Logger } from '@pikku/core/services';
+import type { JWTService, Logger } from '@pikku/core/services';
 import type { NodeHTTPServerConfig } from '@pikku/node-http-server';
 export interface DevServerInstance {
     init(): Promise<void>;
@@ -19,6 +19,14 @@ export interface DevServerInstance {
 }
 /** Config shape both runtimes accept (Core config + host/port/content). */
 export type DevServerConfig = NodeHTTPServerConfig;
+export type DevServerOptions = {
+    /**
+     * The JWTService the dev server's content service signs asset URLs with.
+     * The transport verifies signed asset reads with it, so it must be the same
+     * instance — otherwise every signed URL is rejected.
+     */
+    contentSigningJWT?: JWTService;
+};
 export interface DevServerRunner {
     /**
      * Create the EventHub for this runtime. Shared into singleton services so
@@ -27,5 +35,5 @@ export interface DevServerRunner {
      */
     createEventHub(): Promise<EventHubService<any>>;
     /** Create the dev HTTP/WS server. Must be called after `createEventHub`. */
-    createServer(config: DevServerConfig, logger: Logger): DevServerInstance;
+    createServer(config: DevServerConfig, logger: Logger, options?: DevServerOptions): DevServerInstance;
 }

package/dist/src/server/node-server-runner.d.ts

@@ -5,8 +5,8 @@
  */
 import type { EventHubService } from '@pikku/core';
 import type { Logger } from '@pikku/core/services';
-import type { DevServerRunner, DevServerInstance, DevServerConfig } from './dev-server-runner.interface.js';
+import type { DevServerRunner, DevServerInstance, DevServerConfig, DevServerOptions } from './dev-server-runner.interface.js';
 export declare class NodeServerRunner implements DevServerRunner {
     createEventHub(): Promise<EventHubService<any>>;
-    createServer(config: DevServerConfig, logger: Logger): DevServerInstance;
+    createServer(config: DevServerConfig, logger: Logger, options?: DevServerOptions): DevServerInstance;
 }

package/dist/src/server/node-server-runner.js

@@ -11,12 +11,13 @@ export class NodeServerRunner {
     async createEventHub() {
         return new LocalEventHubService();
     }
-    createServer(config, logger) {
+    createServer(config, logger, options = {}) {
         const wss = new WebSocketServer({ noServer: true });
         const server = new PikkuNodeHTTPServer(config, logger, {
             configureServer: (httpServer) => {
                 pikkuWebsocketHandler({ server: httpServer, wss, logger });
             },
+            contentSigningJWT: options.contentSigningJWT,
         });
         return {
             init: () => server.init(),

package/dist/src/services/cli-logger.service.d.ts

@@ -1,7 +1,17 @@
 import type { Logger } from '@pikku/core/services';
+import type { Safe } from '@pikku/core';
 import { LogLevel } from '@pikku/core/services';
 import type { ErrorCode, DiagnosticSeverity, CodedDiagnostic } from '@pikku/inspector';
 export type CLIOutputMode = 'text' | 'json';
+/**
+ * The structured form a CLI log line may take. The `Record<string, any>` arm
+ * mirrors the `Logger` interface, which admits any object as a message.
+ */
+export type CLILogMessage = string | {
+    message: string;
+    type?: string;
+    data?: Record<string, unknown>;
+} | Record<string, any>;
 export declare class CLILogger implements Logger {
     private silent;
     private level;
@@ -23,25 +33,27 @@ export declare class CLILogger implements Logger {
     private ensureJSONFlushHook;
     flushJSONBuffer(): void;
     private emit;
-    info(message: string | {
-        message: string;
-        type?: string;
-        data?: Record<string, unknown>;
+    /**
+     * Splits a log line into the parts `emit` needs.
+     *
+     * The public methods declare their message as `Safe<M>`, which distributes
+     * over the `CLILogMessage` union and cannot be narrowed by `typeof`. The
+     * guard's job is done once the call site has been checked, so the message is
+     * converted back to its domain type here — in one place rather than in each
+     * method.
+     */
+    private messageParts;
+    info<M extends CLILogMessage, A extends unknown[]>(message: Safe<M>, ...__meta: {
+        [K in keyof A]: Safe<A[K]>;
     }): void;
-    error(message: string | Error | {
-        message: string;
-        type?: string;
-        data?: Record<string, unknown>;
+    error<M extends CLILogMessage | Error, A extends unknown[]>(message: Safe<M>, ...__meta: {
+        [K in keyof A]: Safe<A[K]>;
     }): void;
-    warn(message: string | {
-        message: string;
-        type?: string;
-        data?: Record<string, unknown>;
+    warn<M extends CLILogMessage, A extends unknown[]>(message: Safe<M>, ...__meta: {
+        [K in keyof A]: Safe<A[K]>;
     }): void;
-    debug(message: string | {
-        message: string;
-        type?: string;
-        data?: Record<string, unknown>;
+    debug<M extends CLILogMessage, A extends unknown[]>(message: Safe<M>, ...__meta: {
+        [K in keyof A]: Safe<A[K]>;
     }): void;
     diagnostic({ severity, code, message }: CodedDiagnostic): void;
     /** Sugar for `diagnostic({ severity: 'critical', code, message })`. */