@pikku/cli 0.12.92 → 0.12.96

package/dist/src/functions/wirings/cli/serialize-channel-cli-client.d.ts

@@ -5,7 +5,11 @@ import type { Config } from '../../../../types/application-types.js';
  */
 export declare function collectRendererNames(programMeta: CLIProgramMeta): Set<string>;
 /**
- * Serializes a CLI-over-Channel client bootstrap file
- * Similar to local CLI bootstrap but uses WebSocket connection
+ * Serializes a CLI-over-Channel client bootstrap file.
+ *
+ * The client deliberately does NOT import the CLI bootstrap: loading the
+ * command tree here would bind the client's version to the server's, which is
+ * the coupling running commands remotely exists to remove. Renderers are the
+ * only local artefact, and they are optional.
  */
-export declare function serializeChannelCLIClient(programName: string, programMeta: CLIProgramMeta, clientFile: string, config: Config, cliBootstrapPath: string, channelRoute?: string, renderersMeta?: Record<string, any>): string;
+export declare function serializeChannelCLIClient(programName: string, programMeta: CLIProgramMeta, clientFile: string, config: Config, _cliBootstrapPath: string, channelRoute?: string, renderersMeta?: Record<string, any>): string;

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

@@ -65,14 +65,16 @@ function buildRenderersMap(programMeta, renderersMeta) {
     return `{\n${entries.join(',\n')}\n  }`;
 }
 /**
- * Serializes a CLI-over-Channel client bootstrap file
- * Similar to local CLI bootstrap but uses WebSocket connection
+ * Serializes a CLI-over-Channel client bootstrap file.
+ *
+ * The client deliberately does NOT import the CLI bootstrap: loading the
+ * command tree here would bind the client's version to the server's, which is
+ * the coupling running commands remotely exists to remove. Renderers are the
+ * only local artefact, and they are optional.
  */
-export function serializeChannelCLIClient(programName, programMeta, clientFile, config, cliBootstrapPath, channelRoute, renderersMeta) {
+export function serializeChannelCLIClient(programName, programMeta, clientFile, config, _cliBootstrapPath, channelRoute, renderersMeta) {
     const capitalizedName = programName.charAt(0).toUpperCase() + programName.slice(1).replace(/-/g, '');
     const finalChannelRoute = channelRoute || `/cli/${programName}`;
-    // Get relative import path to CLI bootstrap (for metadata)
-    const bootstrapImportPath = getFileImportRelativePath(clientFile, cliBootstrapPath, config.packageMappings);
     // Collect all unique renderer names from CLI metadata (populated by inspector)
     const rendererNames = collectRendererNames(programMeta);
     // Generate renderer imports from their source files
@@ -108,29 +110,40 @@ export function serializeChannelCLIClient(programName, programMeta, clientFile,
         ? `,\n    defaultRenderer: ${defaultRendererBinding}`
         : '';
     return `
-import { executeCLIViaChannel } from '@pikku/core/cli/channel'
+import { executeRawCLIViaChannel } from '@pikku/core/cli/channel'
+import type { Capabilities } from '@pikku/core/channel'
 import { CorePikkuWebsocket } from '@pikku/websocket'
-import '${bootstrapImportPath}'
 ${rendererImports}
 /**
  * ${capitalizedName} CLI Client (via WebSocket Channel)
- * Executes CLI commands over a WebSocket connection
+ *
+ * Forwards argv to the server untouched — the command tree is never parsed
+ * here, so this client stays valid as the server's commands change. Renderers
+ * are matched by the command id the server reports; anything it doesn't
+ * recognise falls back to JSON.
+ *
+ * \`capabilities\` are the functions this client agrees to run on the server's
+ * behalf (a git sha, a local path). It is an allowlist, not a convenience —
+ * nothing outside it is reachable from the server. A bare function is
+ * unclassified and so needs approval before every call; write
+ * \`{ execute, needsApproval: false }\` for one that may run unattended.
  */
 export async function ${capitalizedName}CLIClient(
   ws: WebSocket,
-  args?: string[]
-): Promise<void> {
+  args?: string[],
+  capabilities: Capabilities = {}
+): Promise<number> {
   // Create Pikku WebSocket wrapper
   const pikkuWS = new CorePikkuWebsocket(ws)
 
   // Register renderers for CLI commands
   const renderers = ${renderersMap}
 
-  await executeCLIViaChannel({
-    programName: '${programName}',
+  return executeRawCLIViaChannel({
     pikkuWS,
     args,
-    renderers${defaultRendererCode},
+    renderers,
+    capabilities${defaultRendererCode},
   })
 }
 
@@ -183,11 +196,12 @@ if (import.meta.url === \`file://\${process.argv[1]}\`) {
     ws = new WebSocket(url)
   }
 
-  ${capitalizedName}CLIClient(ws, process.argv.slice(2)).catch(error => {
-    console.error('Fatal channel CLI error:', error)
-    // TODO: We get an error code even when it exists cleanly, investigate
-    // process.exit(1)
-  })
+  ${capitalizedName}CLIClient(ws, process.argv.slice(2))
+    .then((exitCode) => process.exit(exitCode))
+    .catch(error => {
+      console.error('Fatal channel CLI error:', error)
+      process.exit(1)
+    })
 }
 `;
 }

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/credentials/serialize-credentials-types.js

@@ -1,5 +1,12 @@
 import { validateAndBuildCredentialDefinitionsMeta } from '@pikku/core/credential';
 import { getFileImportRelativePath } from '../../../utils/file-import-path.js';
+/**
+ * A display name is the human-facing label a developer wrote, so an apostrophe
+ * in it is ordinary. `JSON.stringify` emits a valid, escaped TypeScript string
+ * literal; interpolating the raw text into a quoted one terminates the string
+ * and the generated file stops parsing.
+ */
+const literal = (value) => JSON.stringify(value);
 export const serializeCredentialsTypes = ({ definitions, schemaLookup, credentialsFile, packageMappings, }) => {
     const credentials = validateAndBuildCredentialDefinitionsMeta(definitions, schemaLookup);
     const credentialEntries = Object.entries(credentials);
@@ -22,7 +29,7 @@ export const serializeCredentialsTypes = ({ definitions, schemaLookup, credentia
         }
         const metaParts = [
             `name: '${name}'`,
-            `displayName: '${meta.displayName}'`,
+            `displayName: ${literal(meta.displayName)}`,
             `type: '${meta.type}'`,
         ];
         if (meta.oauth2) {

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',
+        }),
+    ],
+});