@pikku/cli 0.12.93 → 0.12.99

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

@@ -7,7 +7,7 @@ export const serializeFunctionTypes = (userSessionTypeImport, userSessionTypeNam
         ? nodeCategories.map((c) => `'${c}'`).join(' | ')
         : 'string';
     const workflowImport = workflowTypesImport ||
-        `import type { TypedWorkflow, TypedScenario, TypedScenarioActors } from '../workflow/pikku-workflow-types.gen.js'`;
+        `import type { TypedWorkflow, TypedScenario, TypedPersonas } from '../workflow/pikku-workflow-types.gen.js'`;
     // Falls back to `string` when a project has no scopes codegen, so that
     // `scopes` stays usable rather than resolving to an unbound type name.
     const scopesImport = scopesTypeImport || `type ScopeId = string`;
@@ -15,8 +15,8 @@ export const serializeFunctionTypes = (userSessionTypeImport, userSessionTypeNam
  * Core function, middleware, and permission types for all wirings
  */
 
-import type { CorePikkuMiddleware, CorePermissionGroup, ListInput, ListOutput, PikkuWire, PickRequired } from '@pikku/core'
-import type { CorePikkuFunctionConfig, CorePikkuAuth, CorePikkuAuthConfig, CorePikkuPermission } from '@pikku/core/function'
+import type { CorePikkuMiddleware, CorePermissionGroup, ListInput, ListOutput, PikkuWire, PickRequired, SecretlessServices, SecretService } from '@pikku/core'
+import type { CorePikkuFunctionConfig, CorePikkuSessionlessFunctionConfig, CorePikkuAuth, CorePikkuAuthConfig, CorePikkuPermission } from '@pikku/core/function'
 import { pikkuAuth as pikkuAuthCore } from '@pikku/core/function'
 import {
   addTagMiddleware as addTagMiddlewareCore,
@@ -51,7 +51,20 @@ ${configTypeImport.includes('Config type not found') ? 'export type Config = any
  * why an \`if (!service)\` guard inside a function body is always dead code.
  */
 export type WiredSingletonServices = RequiredSingletonServices & SingletonServices
-export type WiredServices = RequiredSingletonServices & Services
+export type WiredServices = SecretlessServices<RequiredSingletonServices & Services>
+
+/** \`WiredSingletonServices\` without \`secrets\`, for auth gates. */
+export type WiredAuthServices = SecretlessServices<WiredSingletonServices>
+
+/**
+ * \`WiredServices\` with \`secrets\` restored, for the console's secret-admin
+ * functions. Reached by declaring \`secretBroker: true\` on a \`pikkuFunc\` config.
+ *
+ * Declaring it does not grant the service. The runner hands out the real
+ * \`SecretService\` only to the functions the inspector marks as secret brokers;
+ * every other function still receives the throwing accessor.
+ */
+export type WiredSecretBrokerServices = WiredServices & { secrets: SecretService }
 
 /**
  * Inline node configuration for function definitions.
@@ -70,7 +83,7 @@ export type NodeConfig = {
  * @template In - The input type that the permission check will receive
  * @template RequiredServices - The services required for this permission check
  */
-export type PikkuPermission<In = unknown, RequiredServices extends Services = WiredServices> = CorePikkuPermission<In, RequiredServices, PikkuWire<In, never, false, Session>>
+export type PikkuPermission<In = unknown, RequiredServices extends SecretlessServices<Services> = WiredServices> = CorePikkuPermission<In, RequiredServices, PikkuWire<In, never, false, Session>>
 
 /**
  * Type-safe middleware definition that can access your application's services and session.
@@ -83,7 +96,7 @@ export type PikkuMiddleware<RequiredServices extends SingletonServices = WiredSi
 /**
  * Configuration object for creating a permission with metadata
  */
-export type PikkuPermissionConfig<In = unknown, RequiredServices extends Services = WiredServices> = {
+export type PikkuPermissionConfig<In = unknown, RequiredServices extends SecretlessServices<Services> = WiredServices> = {
   /** The permission function */
   func: PikkuPermission<In, RequiredServices>
   /** Optional human-readable name for the permission */
@@ -128,12 +141,12 @@ export const pikkuPermission = <In>(
  *
  * @template RequiredServices - The services required for this auth check
  */
-export type PikkuAuth<RequiredServices extends SingletonServices = WiredSingletonServices> = CorePikkuAuth<RequiredServices, Session>
+export type PikkuAuth<RequiredServices extends SecretlessServices<SingletonServices> = WiredAuthServices> = CorePikkuAuth<RequiredServices, Session>
 
 /**
  * Configuration object for creating an auth permission with metadata
  */
-export type PikkuAuthConfig<RequiredServices extends SingletonServices = WiredSingletonServices> = CorePikkuAuthConfig<RequiredServices, Session>
+export type PikkuAuthConfig<RequiredServices extends SecretlessServices<SingletonServices> = WiredAuthServices> = CorePikkuAuthConfig<RequiredServices, Session>
 
 /**
  * Factory function for creating auth-only permissions with tree-shaking support.
@@ -155,7 +168,7 @@ export type PikkuAuthConfig<RequiredServices extends SingletonServices = WiredSi
  * })
  * \\\`\\\`\\\`
  */
-export const pikkuAuth = <RequiredServices extends SingletonServices = WiredSingletonServices>(
+export const pikkuAuth = <RequiredServices extends SecretlessServices<SingletonServices> = WiredAuthServices>(
   auth: PikkuAuth<RequiredServices> | PikkuAuthConfig<RequiredServices>
 ): PikkuPermission<any, any> => {
   return pikkuAuthCore(auth as any) as any
@@ -257,7 +270,7 @@ export const pikkuPermissionFactory = <In = any>(
  * @template In - The input type (same as the function it describes)
  * @template RequiredServices - The services required for this description function
  */
-export type PikkuApprovalDescription<In = unknown, RequiredServices extends Services = WiredServices> = (
+export type PikkuApprovalDescription<In = unknown, RequiredServices extends SecretlessServices<Services> = WiredServices> = (
   services: RequiredServices,
   data: In
 ) => Promise<string>
@@ -275,7 +288,7 @@ export type PikkuApprovalDescription<In = unknown, RequiredServices extends Serv
  * )
  * \`\`\`
  */
-export const pikkuApprovalDescription = <In = unknown, RequiredServices extends Services = WiredServices>(
+export const pikkuApprovalDescription = <In = unknown, RequiredServices extends SecretlessServices<Services> = WiredServices>(
   fn: PikkuApprovalDescription<In, RequiredServices>
 ): PikkuApprovalDescription<In, RequiredServices> => {
   return fn
@@ -293,13 +306,13 @@ export type PikkuFunctionSessionless<
   In = unknown,
   Out = never,
   RequiredWires extends keyof PikkuWire = never,
-  RequiredServices extends Services = WiredServices
+  RequiredServices extends SecretlessServices<Services> = WiredServices
 > = CorePikkuFunctionSessionless<
     In,
     Out,
     RequiredServices,
     Session,
-    PickRequired<PikkuWire<In, Out, false, Session, TypedPikkuRPC, null, any, TypedWorkflow, unknown, TypedScenario, TypedScenarioActors>, RequiredWires>
+    PickRequired<PikkuWire<In, Out, false, Session, TypedPikkuRPC, null, any, TypedWorkflow, unknown, TypedScenario, TypedPersonas>, RequiredWires>
   >
 
 /**
@@ -314,13 +327,13 @@ export type PikkuFunction<
   In = unknown,
   Out = never,
   RequiredWires extends keyof PikkuWire = 'session',
-  RequiredServices extends Services = WiredServices
+  RequiredServices extends SecretlessServices<Services> = WiredServices
 > = CorePikkuFunction<
     In,
     Out,
     RequiredServices,
     Session,
-    PickRequired<PikkuWire<In, Out, true, Session, TypedPikkuRPC, null, any, TypedWorkflow, unknown, TypedScenario, TypedScenarioActors>, RequiredWires>
+    PickRequired<PikkuWire<In, Out, true, Session, TypedPikkuRPC, null, any, TypedWorkflow, unknown, TypedScenario, TypedPersonas>, RequiredWires>
   >
 
 /**
@@ -340,11 +353,24 @@ export type PikkuFunctionConfig<
   In = unknown,
   Out = unknown,
   RequiredWires extends keyof PikkuWire = never,
-  PikkuFunc extends PikkuFunction<In, Out, RequiredWires> | PikkuFunctionSessionless<In, Out, RequiredWires> = PikkuFunction<In, Out, RequiredWires> | PikkuFunctionSessionless<In, Out, RequiredWires>,
+  PikkuFunc extends PikkuFunction<In, Out, RequiredWires, any> | PikkuFunctionSessionless<In, Out, RequiredWires, any> = PikkuFunction<In, Out, RequiredWires> | PikkuFunctionSessionless<In, Out, RequiredWires>,
   InputSchema extends StandardSchemaV1 | undefined = undefined,
   OutputSchema extends StandardSchemaV1 | undefined = undefined
 > = CorePikkuFunctionConfig<PikkuFunc, PikkuPermission<In>, PikkuMiddleware, InputSchema, OutputSchema, ScopeId>
 
+/**
+ * {@link PikkuFunctionConfig} for a function that runs without a session.
+ * Has no \`scopes\`: an anonymous caller holds none, so none can ever be met.
+ */
+export type PikkuFunctionSessionlessConfig<
+  In = unknown,
+  Out = unknown,
+  RequiredWires extends keyof PikkuWire = never,
+  PikkuFunc extends PikkuFunctionSessionless<In, Out, RequiredWires, any> = PikkuFunctionSessionless<In, Out, RequiredWires>,
+  InputSchema extends StandardSchemaV1 | undefined = undefined,
+  OutputSchema extends StandardSchemaV1 | undefined = undefined
+> = CorePikkuSessionlessFunctionConfig<PikkuFunc, PikkuPermission<In>, PikkuMiddleware, InputSchema, OutputSchema>
+
 /**
  * Configuration object for Pikku functions with Zod schema validation.
  * Use this when you want to define input/output schemas using Zod.
@@ -361,11 +387,12 @@ type SchemaInferred<S, Fallback = unknown> = S extends StandardSchemaV1
 export type PikkuFunctionConfigWithSchema<
   InputSchema extends StandardSchemaV1 | undefined = undefined,
   OutputSchema extends StandardSchemaV1 | undefined = undefined,
-  RequiredWires extends keyof PikkuWire = never
+  RequiredWires extends keyof PikkuWire = never,
+  RequiredServices extends SecretlessServices<Services> = WiredServices
 > = Omit<
   CorePikkuFunctionConfig<
-    | PikkuFunction<SchemaInferred<InputSchema>, SchemaInferred<OutputSchema>, RequiredWires>
-    | PikkuFunctionSessionless<SchemaInferred<InputSchema>, SchemaInferred<OutputSchema>, RequiredWires>,
+    | PikkuFunction<SchemaInferred<InputSchema>, SchemaInferred<OutputSchema>, RequiredWires, RequiredServices>
+    | PikkuFunctionSessionless<SchemaInferred<InputSchema>, SchemaInferred<OutputSchema>, RequiredWires, RequiredServices>,
     CorePikkuPermission<any>,
     PikkuMiddleware,
     undefined,
@@ -375,8 +402,8 @@ export type PikkuFunctionConfigWithSchema<
   'func' | 'input' | 'output' | 'permissions' | 'approvalDescription'
 > & {
   func:
-    | PikkuFunction<SchemaInferred<InputSchema>, SchemaInferred<OutputSchema>, RequiredWires>
-    | PikkuFunctionSessionless<SchemaInferred<InputSchema>, SchemaInferred<OutputSchema>, RequiredWires>
+    | PikkuFunction<SchemaInferred<InputSchema>, SchemaInferred<OutputSchema>, RequiredWires, RequiredServices>
+    | PikkuFunctionSessionless<SchemaInferred<InputSchema>, SchemaInferred<OutputSchema>, RequiredWires, RequiredServices>
   input?: InputSchema
   output?: OutputSchema
   permissions?: InputSchema extends StandardSchemaV1
@@ -413,6 +440,12 @@ export type PikkuFunctionConfigWithSchema<
  * })
  * \`\`\`
  */
+export function pikkuFunc<
+  InputSchema extends StandardSchemaV1 | undefined = undefined,
+  OutputSchema extends StandardSchemaV1 | undefined = undefined
+>(
+  config: PikkuFunctionConfigWithSchema<InputSchema, OutputSchema, 'session' | 'rpc', WiredSecretBrokerServices> & { secretBroker: true }
+): PikkuFunctionConfig<InputSchema extends StandardSchemaV1 ? InferSchemaOutput<InputSchema> : unknown, OutputSchema extends StandardSchemaV1 ? InferSchemaOutput<OutputSchema> : unknown, 'session' | 'rpc'>
 export function pikkuFunc<
   InputSchema extends StandardSchemaV1 | undefined = undefined,
   OutputSchema extends StandardSchemaV1 | undefined = undefined
@@ -459,22 +492,25 @@ export const pikkuListFunc = <
  */
 /**
  * Schema-overload variant for pikkuSessionlessFunc. Derived from
- * CorePikkuFunctionConfig to stay in sync with the generic-typed config.
+ * CorePikkuSessionlessFunctionConfig to stay in sync with the generic-typed
+ * config — so it has no \`scopes\` either.
  */
 export type PikkuFunctionSessionlessConfigWithSchema<
   InputSchema extends StandardSchemaV1 | undefined = undefined,
   OutputSchema extends StandardSchemaV1 | undefined = undefined,
-  RequiredWires extends keyof PikkuWire = never
+  RequiredWires extends keyof PikkuWire = never,
+  RequiredServices extends SecretlessServices<Services> = WiredServices
 > = Omit<
-  CorePikkuFunctionConfig<
-    PikkuFunctionSessionless<SchemaInferred<InputSchema>, SchemaInferred<OutputSchema>, RequiredWires>
+  CorePikkuSessionlessFunctionConfig<
+    PikkuFunctionSessionless<SchemaInferred<InputSchema>, SchemaInferred<OutputSchema>, RequiredWires, RequiredServices>
   >,
   'func' | 'input' | 'output' | 'permissions' | 'approvalDescription'
 > & {
   func: PikkuFunctionSessionless<
     SchemaInferred<InputSchema>,
     SchemaInferred<OutputSchema>,
-    RequiredWires
+    RequiredWires,
+    RequiredServices
   >
   input?: InputSchema
   output?: OutputSchema
@@ -512,14 +548,15 @@ export type PikkuFunctionSessionlessConfigWithSchema<
  */
 export function pikkuSessionlessFunc<
   InputSchema extends StandardSchemaV1 | undefined = undefined,
-  OutputSchema extends StandardSchemaV1 | undefined = undefined
+  OutputSchema extends StandardSchemaV1 | undefined = undefined,
+  RequiredServices extends SecretlessServices<Services> = WiredServices
 >(
-  config: PikkuFunctionSessionlessConfigWithSchema<InputSchema, OutputSchema, 'session' | 'rpc'>
+  config: PikkuFunctionSessionlessConfigWithSchema<InputSchema, OutputSchema, 'session' | 'rpc', RequiredServices>
 ): PikkuFunctionConfig<InputSchema extends StandardSchemaV1 ? InferSchemaOutput<InputSchema> : unknown, OutputSchema extends StandardSchemaV1 ? InferSchemaOutput<OutputSchema> : unknown, 'session' | 'rpc'>
-export function pikkuSessionlessFunc<In, Out = unknown>(
+export function pikkuSessionlessFunc<In, Out = unknown, RequiredServices extends SecretlessServices<Services> = WiredServices>(
   func:
-    | PikkuFunctionSessionless<In, Out, 'session' | 'rpc'>
-    | PikkuFunctionConfig<In, Out, 'session' | 'rpc'>
+    | PikkuFunctionSessionless<In, Out, 'session' | 'rpc', RequiredServices>
+    | PikkuFunctionSessionlessConfig<In, Out, 'session' | 'rpc', PikkuFunctionSessionless<In, Out, 'session' | 'rpc', RequiredServices>>
 ): PikkuFunctionConfig<In, Out, 'session' | 'rpc'>
 export function pikkuSessionlessFunc(func: any) {
   return typeof func === 'function' ? { func } : func
@@ -544,7 +581,7 @@ export function pikkuSessionlessFunc(func: any) {
 export const pikkuVoidFunc = (
   func:
     | PikkuFunctionSessionless<void, void, 'session' | 'rpc'>
-    | PikkuFunctionConfig<void, void, 'session' | 'rpc'>
+    | PikkuFunctionSessionlessConfig<void, void, 'session' | 'rpc'>
 ) => {
   return typeof func === 'function' ? { func } : func
 }
@@ -584,6 +621,43 @@ export const ref = <Name extends keyof FlattenedRPCMap>(
   >
 }
 
+/**
+ * Declares a capability the connected client answers, reachable from any
+ * \`wireChannel\` function as \`channel.remote(name, input)\`.
+ *
+ * There is no \`func\`: this side owns the contract, the client owns the body.
+ * The \`description\` is what a person is shown when asked to approve the call,
+ * so write it for them rather than for the caller.
+ *
+ * @example
+ * \`\`\`typescript
+ * export const localCheckoutOutput = z.object({ sha: z.string(), branch: z.string() })
+ *
+ * export const localCheckout = pikkuRemoteChannelFunc({
+ *   description: 'Read the current commit and branch of your working tree',
+ *   output: localCheckoutOutput,
+ * })
+ * \`\`\`
+ */
+export function pikkuRemoteChannelFunc<
+  InputSchema extends StandardSchemaV1 | undefined = undefined,
+  OutputSchema extends StandardSchemaV1 | undefined = undefined
+>(
+  config: Omit<
+    PikkuFunctionSessionlessConfigWithSchema<InputSchema, OutputSchema, 'session' | 'rpc'>,
+    'func'
+  >
+): PikkuFunctionConfig<SchemaInferred<InputSchema>, SchemaInferred<OutputSchema>, 'session' | 'rpc'> {
+  return {
+    ...config,
+    func: async (_services: any, _data: any, _wire: any) => {
+      throw new Error(
+        \`\${config.title ?? 'This'} is a remote channel capability and has no local implementation — reach it with channel.remote() on the channel whose client exposes it.\`
+      )
+    },
+  } as any
+}
+
 /**
  * Creates a Pikku config factory.
  * Use this to define your application's configuration factory.

package/dist/src/functions/wirings/middleware/serialize-middleware-imports.js

@@ -2,16 +2,30 @@ import { getFileImportRelativePath } from '../../../utils/file-import-path.js';
 const collectFactories = (groupMap, outputPath, packageMappings) => {
     const factories = new Map();
     for (const [, groupMeta] of groupMap.entries()) {
-        if (groupMeta.exportName && groupMeta.isFactory) {
-            const filePath = getFileImportRelativePath(outputPath, groupMeta.sourceFile, packageMappings);
-            factories.set(groupMeta.exportName, {
-                exportName: groupMeta.exportName,
-                filePath,
-            });
+        for (const registration of registrationsOf(groupMeta)) {
+            if (registration.exportName && registration.isFactory) {
+                const filePath = getFileImportRelativePath(outputPath, registration.sourceFile, packageMappings);
+                factories.set(registration.exportName, {
+                    exportName: registration.exportName,
+                    filePath,
+                });
+            }
         }
     }
     return factories;
 };
+/**
+ * Every `add*Middleware` call recorded under one pattern or tag.
+ *
+ * A group is keyed by its pattern, and more than one file may register for the
+ * same one. Emitting only the primary registration meant the other file was
+ * never imported, so its middleware never registered — which for a session
+ * bridge or an auth gate fails open and fails silently.
+ */
+const registrationsOf = (groupMeta) => [
+    groupMeta,
+    ...(groupMeta.additionalRegistrations ?? []),
+];
 export const serializeMiddlewareImports = (outputPath, middlewareState, httpState, packageMappings = {}, fullState) => {
     const serializedImports = [];
     const serializedFactoryCalls = [];
@@ -24,9 +38,11 @@ export const serializeMiddlewareImports = (outputPath, middlewareState, httpStat
     const directImports = new Set();
     const collectDirectImports = (groupMap) => {
         for (const [, groupMeta] of groupMap.entries()) {
-            if (!groupMeta.isFactory) {
-                const filePath = getFileImportRelativePath(outputPath, groupMeta.sourceFile, packageMappings);
-                directImports.add(filePath);
+            for (const registration of registrationsOf(groupMeta)) {
+                if (!registration.isFactory) {
+                    const filePath = getFileImportRelativePath(outputPath, registration.sourceFile, packageMappings);
+                    directImports.add(filePath);
+                }
             }
         }
     };

package/dist/src/functions/wirings/package/pikku-command-package-types.d.ts

@@ -1,3 +1,3 @@
-export declare const pikkuSecretDefinitionTypes: import("#pikku").PikkuFunctionConfig<void, void, "rpc" | "session", import("#pikku").PikkuFunctionSessionless<void, void, "rpc" | "session", import("#pikku").WiredServices> | import("#pikku").PikkuFunction<void, void, "rpc" | "session", import("#pikku").WiredServices>, undefined, undefined>;
-export declare const pikkuScopeDefinitionTypes: import("#pikku").PikkuFunctionConfig<void, void, "rpc" | "session", import("#pikku").PikkuFunctionSessionless<void, void, "rpc" | "session", import("#pikku").WiredServices> | import("#pikku").PikkuFunction<void, void, "rpc" | "session", import("#pikku").WiredServices>, undefined, undefined>;
-export declare const pikkuVariableDefinitionTypes: import("#pikku").PikkuFunctionConfig<void, void, "rpc" | "session", import("#pikku").PikkuFunctionSessionless<void, void, "rpc" | "session", import("#pikku").WiredServices> | import("#pikku").PikkuFunction<void, void, "rpc" | "session", import("#pikku").WiredServices>, undefined, undefined>;
+export declare const pikkuSecretDefinitionTypes: import("#pikku").PikkuFunctionSessionlessConfig<void, void, "rpc" | "session", import("#pikku").PikkuFunctionSessionless<void, void, "rpc" | "session", import("#pikku").WiredServices>, undefined, undefined>;
+export declare const pikkuScopeDefinitionTypes: import("#pikku").PikkuFunctionSessionlessConfig<void, void, "rpc" | "session", import("#pikku").PikkuFunctionSessionless<void, void, "rpc" | "session", import("#pikku").WiredServices>, undefined, undefined>;
+export declare const pikkuVariableDefinitionTypes: import("#pikku").PikkuFunctionSessionlessConfig<void, void, "rpc" | "session", import("#pikku").PikkuFunctionSessionless<void, void, "rpc" | "session", import("#pikku").WiredServices>, undefined, undefined>;

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

@@ -1,15 +1,17 @@
 export const serializeSecretDefinitionTypes = () => {
-    return `export { wireSecret } from '@pikku/core/secret'
+    return `export { defineSecret } from '@pikku/core/secret'
 export type { CoreSecret, SecretDefinitionMeta, SecretDefinitionsMeta } from '@pikku/core/secret'
 `;
 };
 export const serializeScopeDefinitionTypes = () => {
-    return `export { wireScope } from '@pikku/core/scope'
+    return `export { defineScope } from '@pikku/core/scope'
 export type { CoreScopes, CoreScopeNode, FlatScope, ScopeDefinitionMeta, ScopeDefinitionsMeta } from '@pikku/core/scope'
+export { defineSystemRole } from '@pikku/core/role'
+export type { CoreSystemRole, CoreSystemRoles, SystemRole, SystemRoleDefinitionMeta, SystemRoleDefinitionsMeta } from '@pikku/core/role'
 `;
 };
 export const serializeVariableDefinitionTypes = () => {
-    return `export { wireVariable } from '@pikku/core/variable'
+    return `export { defineVariable } from '@pikku/core/variable'
 export type { CoreVariable, VariableDefinitionMeta, VariableDefinitionsMeta } from '@pikku/core/variable'
 `;
 };

package/dist/src/functions/wirings/personas/personas-secrets-file.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Where the generated `SCENARIO_ACTOR_SECRET` declaration lives — beside the
+ * personas file, like `auth-secrets.gen.ts` sits beside the auth scaffold.
+ *
+ * Shared with the inspector's scaffold-file list: nothing imports this file, so
+ * it is unreachable through the import graph and has to be inspected explicitly.
+ */
+export declare const personasSecretsFilePath: (personasFile: string) => string;

package/dist/src/functions/wirings/personas/personas-secrets-file.js

@@ -0,0 +1,9 @@
+import { join, dirname } from 'node:path';
+/**
+ * Where the generated `SCENARIO_ACTOR_SECRET` declaration lives — beside the
+ * personas file, like `auth-secrets.gen.ts` sits beside the auth scaffold.
+ *
+ * Shared with the inspector's scaffold-file list: nothing imports this file, so
+ * it is unreachable through the import graph and has to be inspected explicitly.
+ */
+export const personasSecretsFilePath = (personasFile) => join(dirname(personasFile), 'pikku-personas-secrets.gen.ts');

package/dist/src/functions/wirings/personas/pikku-command-personas.d.ts

@@ -0,0 +1,7 @@
+export declare const pikkuPersonas: import("#pikku").PikkuFunctionConfig<{
+    bootstrap?: boolean;
+}, void, "rpc" | "session", import("#pikku").PikkuFunctionSessionless<{
+    bootstrap?: boolean;
+}, void, "rpc" | "session", import("#pikku").WiredServices> | import("#pikku").PikkuFunction<{
+    bootstrap?: boolean;
+}, void, "rpc" | "session", import("#pikku").WiredServices>, undefined, undefined>;

package/dist/src/functions/wirings/personas/pikku-command-personas.js

@@ -0,0 +1,57 @@
+import { existsSync } from 'node:fs';
+import { rm } from 'node:fs/promises';
+import { pikkuSessionlessFunc } from '#pikku';
+import { writeFileInDir } from '../../../utils/file-writer.js';
+import { getFileImportRelativePath } from '../../../utils/file-import-path.js';
+import { logCommandInfoAndTime } from '../../../middleware/log-command-info-and-time.js';
+import { serializePersonasTypes } from './serialize-personas-types.js';
+import { serializePersonasSecrets } from './serialize-personas-secrets.js';
+import { personasSecretsFilePath } from './personas-secrets-file.js';
+import { personaEnvironmentErrors, validateAndBuildPersonasMeta, } from '@pikku/core/persona';
+export const pikkuPersonas = pikkuSessionlessFunc({
+    func: async ({ logger, config, getInspectorState }, data) => {
+        const { personasFile, personasMetaJsonFile, rolesFile, packageMappings } = config;
+        if (!personasFile) {
+            return;
+        }
+        // Same cold-start reasoning as Scopes and Roles: on a bare .pikku this
+        // runs before the app's own types exist, so it takes the zero state. The
+        // file only has to exist so a persona file can import definePersonas.
+        const bootstrap = data?.bootstrap ?? false;
+        const state = await getInspectorState(false, bootstrap, bootstrap);
+        const environments = config.environments ?? {};
+        // Before anything is written. A persona that may not run where it says it
+        // runs is a declaration to fix, not a file to generate — and generating
+        // it anyway would leave a `.pikku` that typechecks while lying.
+        const errors = state.personas.definitions.flatMap((persona) => personaEnvironmentErrors(persona.id, persona, environments));
+        if (errors.length) {
+            throw new Error(errors.join('\n'));
+        }
+        const content = serializePersonasTypes({
+            definitions: state.personas.definitions,
+            rolesImportPath: getFileImportRelativePath(personasFile, rolesFile, packageMappings),
+            environmentNames: Object.keys(environments),
+        });
+        await writeFileInDir(logger, personasFile, content);
+        // The actor sign-in secret only means anything once someone is declared
+        // to sign in. Drop the file again when the last persona goes, so a stale
+        // declaration can't keep asking a deploy for a value nothing reads.
+        const secretsFile = personasSecretsFilePath(personasFile);
+        if (state.personas.definitions.length > 0) {
+            await writeFileInDir(logger, secretsFile, serializePersonasSecrets());
+        }
+        else if (existsSync(secretsFile)) {
+            await rm(secretsFile);
+        }
+        if (personasMetaJsonFile) {
+            const meta = validateAndBuildPersonasMeta(state.personas.definitions);
+            await writeFileInDir(logger, personasMetaJsonFile, JSON.stringify(meta, null, 2));
+        }
+    },
+    middleware: [
+        logCommandInfoAndTime({
+            commandStart: 'Creating PikkuPersonas types',
+            commandEnd: 'Created PikkuPersonas types',
+        }),
+    ],
+});

package/dist/src/functions/wirings/personas/serialize-personas-secrets.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Generates the sibling secrets file for a project that declares personas.
+ *
+ * `SCENARIO_ACTOR_SECRET` is the platform's, not the application's: nothing in
+ * app code reads it. It is consumed by the scenario service when it signs an
+ * actor in, by `pikku scenario` / `pikku persona` / `pikku persona sync`, and by
+ * the Playwright provider. Declaring it here — rather than leaving every project
+ * to hand-write the same `defineSecret` — is the same reasoning that puts
+ * `BETTER_AUTH_SECRET` in the auth scaffold: a value the framework requires
+ * regardless of what the user wired should be collected by the platform, not
+ * discovered missing at the first sign-in.
+ *
+ * The schema is a named const because the inspector only accepts a variable
+ * reference for `schema`, never an inline expression.
+ */
+export declare const serializePersonasSecrets: () => string;

package/dist/src/functions/wirings/personas/serialize-personas-secrets.js

@@ -0,0 +1,34 @@
+/**
+ * Generates the sibling secrets file for a project that declares personas.
+ *
+ * `SCENARIO_ACTOR_SECRET` is the platform's, not the application's: nothing in
+ * app code reads it. It is consumed by the scenario service when it signs an
+ * actor in, by `pikku scenario` / `pikku persona` / `pikku persona sync`, and by
+ * the Playwright provider. Declaring it here — rather than leaving every project
+ * to hand-write the same `defineSecret` — is the same reasoning that puts
+ * `BETTER_AUTH_SECRET` in the auth scaffold: a value the framework requires
+ * regardless of what the user wired should be collected by the platform, not
+ * discovered missing at the first sign-in.
+ *
+ * The schema is a named const because the inspector only accepts a variable
+ * reference for `schema`, never an inline expression.
+ */
+export const serializePersonasSecrets = () => {
+    return `/**
+ * This file was generated by the @pikku/cli
+ */
+import { defineSecret } from '@pikku/core/secret'
+import { z } from 'zod'
+
+export const ScenarioActorSecretSchema = z.string()
+
+defineSecret({
+  name: 'scenarioActorSecret',
+  displayName: 'Scenario Actor Secret',
+  description:
+    'Signing secret that lets scenarios and virtual users sign in as a declared persona',
+  secretId: 'SCENARIO_ACTOR_SECRET',
+  schema: ScenarioActorSecretSchema,
+})
+`;
+};

package/dist/src/functions/wirings/personas/serialize-personas-types.d.ts

@@ -0,0 +1,18 @@
+import type { PersonaDefinitions } from '@pikku/core/persona';
+export interface SerializePersonasOptions {
+    definitions: PersonaDefinitions;
+    /** Relative import path to the generated roles file. */
+    rolesImportPath: string;
+    /** Keys of `environments` in pikku.config.json. */
+    environmentNames: string[];
+}
+/**
+ * Generates the `PersonaId` union and a `definePersonas` whose `roles` are
+ * checked against the declared system roles.
+ *
+ * The wrapper is why this is generated rather than re-exported: `roles` typed
+ * as `string[]` would let a persona name a role nobody declared, and the
+ * failure — a scatter of 403s in a run days later — looks nothing like the
+ * mistake. Typed as `SystemRoleName[]`, it is a red squiggle in the editor.
+ */
+export declare const serializePersonasTypes: ({ definitions, rolesImportPath, environmentNames, }: SerializePersonasOptions) => string;

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

@@ -0,0 +1,76 @@
+const quote = (value) => `'${value.replace(/'/g, "\\'")}'`;
+/**
+ * Generates the `PersonaId` union and a `definePersonas` whose `roles` are
+ * checked against the declared system roles.
+ *
+ * The wrapper is why this is generated rather than re-exported: `roles` typed
+ * as `string[]` would let a persona name a role nobody declared, and the
+ * failure — a scatter of 403s in a run days later — looks nothing like the
+ * mistake. Typed as `SystemRoleName[]`, it is a red squiggle in the editor.
+ */
+export const serializePersonasTypes = ({ definitions, rolesImportPath, environmentNames, }) => {
+    const ids = [...new Set(definitions.map((d) => d.id))].sort();
+    const environmentUnion = environmentNames.length > 0
+        ? `\n${[...environmentNames].sort().map((name) => `  | ${quote(name)}`).join('\n')}`
+        : ' never';
+    const union = ids.length > 0
+        ? `\n${ids.map((id) => `  | ${quote(id)}`).join('\n')}`
+        : ' never';
+    const runnable = definitions
+        .filter((d) => d.runnable)
+        .map((d) => d.id)
+        .sort();
+    const runnableUnion = runnable.length > 0
+        ? `\n${runnable.map((id) => `  | ${quote(id)}`).join('\n')}`
+        : ' never';
+    return `/**
+ * This file was generated by the @pikku/cli
+ */
+import { definePersonas as definePersonasCore } from '@pikku/core/persona'
+import type { CorePersona, PersonaMeta, PersonasMeta } from '@pikku/core/persona'
+import type { SystemRoleName } from '${rolesImportPath}'
+import definitions from './pikku-personas-meta.gen.json' with { type: 'json' }
+
+/** Every declared persona. */
+export type PersonaId =${union}
+
+/**
+ * The personas a virtual user can actually be.
+ *
+ * Excludes anyone whose only login is a provider account — driving a consent
+ * screen needs a human — and anyone declared \`runnable: false\`, who exists to
+ * be acted upon rather than to act.
+ */
+export type RunnablePersonaId =${runnableUnion}
+
+/** Every environment configured in pikku.config.json. */
+export type EnvironmentName =${environmentUnion}
+
+/**
+ * A persona whose roles are checked against \`defineSystemRole\` and whose
+ * environments are checked against the config.
+ *
+ * Omitting \`environments\` means every environment except the ones flagged
+ * \`production: true\`. Naming a production one additionally requires
+ * \`disposition: 'accountable'\`, which the type cannot express and \`pikku\`
+ * refuses at build time.
+ */
+export type TypedPersona = Omit<CorePersona, 'roles' | 'environments'> & {
+  roles?: SystemRoleName[]
+  environments?: EnvironmentName[]
+}
+
+/**
+ * Declare the people who use this application.
+ *
+ * A persona while running is a virtual user; there is no second declaration.
+ */
+export const definePersonas = (personas: Record<string, TypedPersona>): void =>
+  definePersonasCore(personas)
+
+/** Declared personas, keyed by id. Read by the console and \`pikku persona\`. */
+export const PERSONAS: PersonasMeta = definitions as unknown as PersonasMeta
+
+export const PERSONA_LIST: PersonaMeta[] = Object.values(PERSONAS)
+`;
+};

package/dist/src/functions/wirings/queue/serialize-queue-map.js

@@ -13,6 +13,7 @@ ${serializedImportMap}
 ${serializedCustomTypes}
 
 import type { QueueJob } from '@pikku/core/queue'
+import type { Safe } from '@pikku/core'
 
 interface QueueHandler<I, O> {
     input: I;
@@ -23,7 +24,7 @@ ${serializedQueues}
 
 type QueueAdd = <Name extends keyof QueueMap>(
   name: Name,
-  data: QueueMap[Name]['input'],
+  data: Safe<QueueMap[Name]['input']>,
   options?: {
     priority?: number
     delay?: number