@pikku/cli 0.12.93 → 0.12.96

package/dist/src/functions/wirings/cli/serialize-channel-cli.js

@@ -60,7 +60,7 @@ export function serializeChannelCLI(programName, programMeta, channelFile, funct
 import { wireChannel } from '${channelTypesPath}'
 import { pikkuMiddleware${hasAddonFuncs ? ', ref' : ''}, pikkuSessionlessFunc } from '${functionTypesPath}'
 import { generateCommandHelp } from '@pikku/core/cli'
-import { handleRawCLI } from '@pikku/core/cli/channel'
+import { handleRawCLI, type RawCLIFrame } from '@pikku/core/cli/channel'
 import { pikkuState } from '@pikku/core/internal'
 ${imports}
 
@@ -97,22 +97,79 @@ export const cliHelp = pikkuSessionlessFunc<{ args?: string[] }, { help: string
   },
 })
 
-export const cliRaw = pikkuSessionlessFunc<{ args: string[] }, { help?: string; result?: unknown; error?: string }>({
+/**
+ * Raw entry point: the client forwards argv untouched and this side owns
+ * parsing, so a client binary never carries the command tree and its version
+ * is free to drift from the server's.
+ *
+ * Progressive output is streamed on the same channel rather than returned,
+ * and the terminating control frame carries the exit code so the client
+ * process can exit non-zero.
+ */
+export const cliRaw = pikkuSessionlessFunc<{ args: string[] }, RawCLIFrame>({
   auth: false,
-  func: async (services, data: { args: string[] }) => {
-    return handleRawCLI({
+  func: async (services, data: { args: string[] }, { channel, session }) => {
+    const { help, result, error, exitCode, commandId } = await handleRawCLI({
       programName: '${programName}',
       args: data.args,
       singletonServices: services as any,
+      createWireServices: pikkuState(null, 'package', 'factories')?.createWireServices,
+      // The connection authenticated during its upgrade — commands run as it.
+      session,
+      // The socket the command arrived on, so \`channel.remote(...)\` inside a
+      // command reaches the client that invoked it.
+      transport: channel,
+      onOutput: (output, commandId) =>
+        channel?.send({ action: 'cli-output', commandId, data: output }),
     })
+
+    // A failed parse carries both: the error says what was wrong, the help
+    // says what was available. The error goes last so it is the line still on
+    // screen after the help text has scrolled past.
+    if (help !== undefined) {
+      await channel?.send({ action: 'cli-help', help })
+      if (error !== undefined) {
+        await channel?.send({ action: 'cli-error', error })
+      }
+    } else if (error !== undefined) {
+      await channel?.send({ action: 'cli-error', error })
+    } else if (result !== undefined) {
+      await channel?.send({ action: 'cli-result', commandId, result })
+    }
+
+    // Returned rather than sent so the runtime tags it with the routing key,
+    // and so the terminal frame cannot be emitted before the ones above it.
+    return { action: 'cli-control', event: 'complete', exitCode }
   },
 })
 
+${programMeta.auth === true
+        ? `/**
+ * Refuses a connection that arrives without a session.
+ *
+ * A CLI authenticates once, when it connects — there is no later message that
+ * would establish a session, so a connection that starts anonymous can never
+ * run anything. Saying so immediately and hanging up gives the caller a
+ * non-zero exit instead of a socket that silently refuses every command.
+ */
+export const cliRequireSession = pikkuSessionlessFunc<void, RawCLIFrame | void>({
+  auth: false,
+  func: async (_services, _data, { channel, session }) => {
+    if (session) {
+      return
+    }
+    await channel?.send({ action: 'cli-error', error: 'Authentication required' })
+    await channel?.send({ action: 'cli-control', event: 'complete', exitCode: 1 })
+    await channel?.close()
+  },
+})
+`
+        : ''}
 wireChannel({
   name: '${finalChannelName}',
   route: '${finalChannelRoute}',
-  auth: false,
-  onMessageWiring: {
+  auth: ${programMeta.auth === true},
+${programMeta.auth === true ? '  onConnect: cliRequireSession,\n' : ''}  onMessageWiring: {
     command: {
       '__help': {
         func: cliHelp,

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

@@ -40,6 +40,7 @@ import {
 } from './console.schemas.gen.js'
 
 export const pikkuConsoleSetSecret = pikkuFunc({
+  secretBroker: true,
   tags: ['pikku'],
   description: 'Set the value of a secret',
   expose: true,
@@ -89,6 +90,7 @@ export const pikkuConsoleSetVariable = pikkuFunc({
 })
 
 export const pikkuConsoleHasSecret = pikkuFunc({
+  secretBroker: true,
   tags: ['pikku'],
   description: 'Check if a secret exists without reading its value',
   expose: true,
@@ -101,6 +103,7 @@ export const pikkuConsoleHasSecret = pikkuFunc({
 })
 
 export const pikkuConsoleGetSecret = pikkuFunc({
+  secretBroker: true,
   tags: ['pikku'],
   description: 'Get the current value of a secret',
   expose: true,
@@ -129,13 +132,7 @@ export const consoleRoutes = defineHTTPRoutes({
   },
 })
 
-// The console addon's functions have no authorization of their own. An app
-// gates the whole privileged surface (credential read/write, source editing,
-// package install) with a single package-scoped global permission —
-// addGlobalPermission([isAdmin], '@pikku/addon-console') — which is resolved in
-// the addon's package namespace, so it applies to every one of its functions at
-// once. Apps that don't register one are unaffected (no globals => allow).
-wireAddon({ name: 'console', package: '@pikku/addon-console' })
+wireAddon({ name: 'console', package: '@pikku/addon-console', scopes: ['admin'] })
 wireHTTPRoutes({ basePath: '${globalHTTPPrefix}', routes: { console: consoleRoutes } })
 `;
     return { schemas, functions };

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,7 +15,7 @@ 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 { CorePikkuMiddleware, CorePermissionGroup, ListInput, ListOutput, PikkuWire, PickRequired, SecretlessServices, SecretService } from '@pikku/core'
 import type { CorePikkuFunctionConfig, CorePikkuAuth, CorePikkuAuthConfig, CorePikkuPermission } from '@pikku/core/function'
 import { pikkuAuth as pikkuAuthCore } from '@pikku/core/function'
 import {
@@ -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,7 +353,7 @@ 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>
@@ -361,11 +374,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 +389,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 +427,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
@@ -464,17 +484,19 @@ export const pikkuListFunc = <
 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>
+    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 +534,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>
+    | PikkuFunctionConfig<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
@@ -584,6 +607,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/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/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,43 @@
+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 { 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);
+        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-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/realtime/pikku-command-events-scaffold.js

@@ -4,6 +4,7 @@ import { writeFileInDir } from '../../../utils/file-writer.js';
 import { logCommandInfoAndTime } from '../../../middleware/log-command-info-and-time.js';
 import { removeLegacyScaffoldFile } from '../../../utils/remove-legacy-scaffold-file.js';
 import { serializeEventsScaffold } from './serialize-events-scaffold.js';
+import { resolveScaffoldFeature } from '../../../utils/resolve-scaffold-feature.js';
 export const pikkuEventsScaffold = pikkuSessionlessFunc({
     func: async ({ logger, config }) => {
         if (!config.scaffold?.events ||
@@ -15,7 +16,7 @@ export const pikkuEventsScaffold = pikkuSessionlessFunc({
             });
             return false;
         }
-        const authRequired = config.scaffold.events === 'auth';
+        const authRequired = resolveScaffoldFeature('events', config.scaffold.events).auth;
         const pikkuTypesImportPath = getFileImportRelativePath(config.eventsChannelFile, config.typesDeclarationFile, config.packageMappings);
         const { schemas, functions } = serializeEventsScaffold(authRequired, pikkuTypesImportPath);
         await writeFileInDir(logger, config.eventsSchemasFile, schemas);

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

@@ -0,0 +1,7 @@
+export declare const pikkuRoles: 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>;