@pikku/cli 0.12.20 → 0.12.22

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

@@ -12,12 +12,16 @@ export const serializeFunctionTypes = (userSessionTypeImport, userSessionTypeNam
  * Core function, middleware, and permission types for all wirings
  */
 
-import type { CorePikkuMiddleware, CorePermissionGroup, PikkuWire, PickRequired } from '@pikku/core'
+import type { CorePikkuMiddleware, CorePermissionGroup, ListInput, ListOutput, PikkuWire, PickRequired } from '@pikku/core'
 import type { CorePikkuFunctionConfig, CorePikkuAuth, CorePikkuAuthConfig, CorePikkuPermission } from '@pikku/core/function'
 import { pikkuAuth as pikkuAuthCore } from '@pikku/core/function'
-import { addMiddleware as addMiddlewareCore, addPermission as addPermissionCore } from '@pikku/core/middleware'
+import {
+  addTagMiddleware as addTagMiddlewareCore,
+  addGlobalMiddleware as addGlobalMiddlewareCore,
+  addTagPermission as addTagPermissionCore,
+  addGlobalPermission as addGlobalPermissionCore,
+} from '@pikku/core/middleware'
 import { pikkuState as __pikkuState, CreateWireServices } from '@pikku/core/internal'
-import { PikkuError } from '@pikku/core/errors'
 import type { NodeType } from '@pikku/core/node'
 import type { StandardSchemaV1 } from '@standard-schema/spec'
 import { CorePikkuFunction, CorePikkuFunctionSessionless } from '@pikku/core/function'
@@ -332,34 +336,36 @@ export type PikkuFunctionConfig<
  * Use this when you want to define input/output schemas using Zod.
  * Types are automatically inferred from the schemas.
  */
+type SchemaInferred<S, Fallback = unknown> = S extends StandardSchemaV1
+  ? InferSchemaOutput<S>
+  : Fallback
+
+/**
+ * Schema-overload variant for pikkuFunc. Derived from CorePikkuFunctionConfig
+ * so adding a field on the core type automatically propagates here.
+ */
 export type PikkuFunctionConfigWithSchema<
   InputSchema extends StandardSchemaV1 | undefined = undefined,
   OutputSchema extends StandardSchemaV1 | undefined = undefined,
   RequiredWires extends keyof PikkuWire = never
-> = {
-  name?: string
-  tags?: string[]
-  expose?: boolean
-  mcp?: boolean
-  internal?: boolean
-  approvalRequired?: boolean
-  approvalDescription?: InputSchema extends StandardSchemaV1 ? PikkuApprovalDescription<InferSchemaOutput<InputSchema>> : never
-  func: PikkuFunction<
-    InputSchema extends StandardSchemaV1 ? InferSchemaOutput<InputSchema> : unknown,
-    OutputSchema extends StandardSchemaV1 ? InferSchemaOutput<OutputSchema> : unknown,
-    RequiredWires
-  > | PikkuFunctionSessionless<
-    InputSchema extends StandardSchemaV1 ? InferSchemaOutput<InputSchema> : unknown,
-    OutputSchema extends StandardSchemaV1 ? InferSchemaOutput<OutputSchema> : unknown,
-    RequiredWires
-  >
-  auth?: boolean
-  permissions?: InputSchema extends StandardSchemaV1 ? CorePermissionGroup<PikkuPermission<InferSchemaOutput<InputSchema>>> : undefined
-  middleware?: PikkuMiddleware[]
+> = Omit<
+  CorePikkuFunctionConfig<
+    | PikkuFunction<SchemaInferred<InputSchema>, SchemaInferred<OutputSchema>, RequiredWires>
+    | PikkuFunctionSessionless<SchemaInferred<InputSchema>, SchemaInferred<OutputSchema>, RequiredWires>
+  >,
+  'func' | 'input' | 'output' | 'permissions' | 'approvalDescription'
+> & {
+  func:
+    | PikkuFunction<SchemaInferred<InputSchema>, SchemaInferred<OutputSchema>, RequiredWires>
+    | PikkuFunctionSessionless<SchemaInferred<InputSchema>, SchemaInferred<OutputSchema>, RequiredWires>
   input?: InputSchema
   output?: OutputSchema
-  node?: NodeConfig
-  errors?: Array<typeof PikkuError>
+  permissions?: InputSchema extends StandardSchemaV1
+    ? CorePermissionGroup<PikkuPermission<InferSchemaOutput<InputSchema>>>
+    : undefined
+  approvalDescription?: InputSchema extends StandardSchemaV1
+    ? PikkuApprovalDescription<InferSchemaOutput<InputSchema>>
+    : never
 }
 
 /**
@@ -415,35 +421,62 @@ export function pikkuFunc(func: any) {
   return typeof func === 'function' ? { func } : func
 }
 
+export type PikkuListFunction<
+  F extends Record<string, unknown> = {},
+  Row = unknown,
+  S extends string = never
+> =
+  | PikkuFunction<ListInput<F, S>, ListOutput<Row>, 'session' | 'rpc'>
+  | PikkuFunctionSessionless<
+      ListInput<F, S>,
+      ListOutput<Row>,
+      'session' | 'rpc'
+    >
+
+export const pikkuListFunc = <
+  F extends Record<string, unknown> = {},
+  Row = unknown,
+  S extends string = never
+>(
+  config: PikkuFunctionConfig<
+    ListInput<F, S>,
+    ListOutput<Row>,
+    'session' | 'rpc'
+  >
+): PikkuFunctionConfig<ListInput<F, S>, ListOutput<Row>, 'session' | 'rpc'> => {
+  return pikkuFunc(config)
+}
+
 /**
  * Configuration object for sessionless Pikku functions with Zod schema validation.
  */
+/**
+ * Schema-overload variant for pikkuSessionlessFunc. Derived from
+ * CorePikkuFunctionConfig to stay in sync with the generic-typed config.
+ */
 export type PikkuFunctionSessionlessConfigWithSchema<
   InputSchema extends StandardSchemaV1 | undefined = undefined,
   OutputSchema extends StandardSchemaV1 | undefined = undefined,
   RequiredWires extends keyof PikkuWire = never
-> = {
-  name?: string
-  description?: string
-  tags?: string[]
-  expose?: boolean
-  mcp?: boolean
-  internal?: boolean
-  remote?: boolean
-  approvalRequired?: boolean
-  approvalDescription?: InputSchema extends StandardSchemaV1 ? PikkuApprovalDescription<InferSchemaOutput<InputSchema>> : never
+> = Omit<
+  CorePikkuFunctionConfig<
+    PikkuFunctionSessionless<SchemaInferred<InputSchema>, SchemaInferred<OutputSchema>, RequiredWires>
+  >,
+  'func' | 'input' | 'output' | 'permissions' | 'approvalDescription'
+> & {
   func: PikkuFunctionSessionless<
-    InputSchema extends StandardSchemaV1 ? InferSchemaOutput<InputSchema> : unknown,
-    OutputSchema extends StandardSchemaV1 ? InferSchemaOutput<OutputSchema> : unknown,
+    SchemaInferred<InputSchema>,
+    SchemaInferred<OutputSchema>,
     RequiredWires
   >
-  auth?: boolean
-  permissions?: InputSchema extends StandardSchemaV1 ? CorePermissionGroup<PikkuPermission<InferSchemaOutput<InputSchema>>> : undefined
-  middleware?: PikkuMiddleware[]
   input?: InputSchema
   output?: OutputSchema
-  node?: NodeConfig
-  errors?: Array<typeof PikkuError>
+  permissions?: InputSchema extends StandardSchemaV1
+    ? CorePermissionGroup<PikkuPermission<InferSchemaOutput<InputSchema>>>
+    : undefined
+  approvalDescription?: InputSchema extends StandardSchemaV1
+    ? PikkuApprovalDescription<InferSchemaOutput<InputSchema>>
+    : never
 }
 
 /**
@@ -634,57 +667,49 @@ export const pikkuWireServices = (
 }
 
 /**
- * Adds global middleware for a specific tag.
- *
- * This function allows you to register middleware that will be applied to
- * any wiring (HTTP, Channel, Queue, Scheduler, MCP) that includes the matching tag.
- *
- * @param tag - The tag that the middleware should apply to.
- * @param middleware - The middleware array to apply for the specified tag.
- *
- * @throws Error if middleware for the tag already exists.
+ * Tag-scoped middleware. Applies to any wiring that carries the matching tag.
  *
  * @example
- * \`\`\`typescript
- * // Add admin middleware for admin endpoints
- * addMiddleware('admin', [adminMiddleware])
- *
- * // Add authentication middleware for auth endpoints
- * addMiddleware('auth', [authMiddleware])
- *
- * // Add logging middleware for all API endpoints
- * addMiddleware('api', [loggingMiddleware])
- * \`\`\`
+ * addTagMiddleware('admin', [adminMiddleware])
  */
-export const addMiddleware = (tag: string, middleware: PikkuMiddleware[]) => {
-  addMiddlewareCore(tag, middleware as any, ${packageNameValue})
+export const addTagMiddleware = (tag: string, middleware: PikkuMiddleware[]) => {
+  addTagMiddlewareCore(tag, middleware as any, ${packageNameValue})
 }
 
 /**
- * Adds global permissions for a specific tag.
+ * Wire-agnostic global middleware. Runs at the top of every wiring's
+ * middleware chain — before wire-, tag-, and function-level entries.
  *
- * This function allows you to register permissions that will be applied to
- * any wiring (HTTP, Channel, Queue, Scheduler, MCP) that includes the matching tag.
+ * Resolution order: global -> wire -> tag -> function.
  *
- * @param tag - The tag that the permissions should apply to.
- * @param permissions - The permissions array or object to apply for the specified tag.
- *
- * @throws Error if permissions for the tag already exist.
+ * @example
+ * addGlobalMiddleware([telemetryMiddleware])
+ */
+export const addGlobalMiddleware = (middleware: PikkuMiddleware[]) => {
+  addGlobalMiddlewareCore(middleware as any, ${packageNameValue})
+}
+
+/**
+ * Tag-scoped permissions. Applies to any wiring that carries the matching tag.
  *
  * @example
- * \`\`\`typescript
- * // Add admin permissions for admin endpoints
- * addPermission('admin', [adminPermission])
+ * addTagPermission('admin', [adminPermission])
+ */
+export const addTagPermission = <In = unknown>(tag: string, permissions: CorePermissionGroup<PikkuPermission<In>> | PikkuPermission<In>[]) => {
+  addTagPermissionCore(tag, permissions as any, ${packageNameValue})
+}
+
+/**
+ * Wire-agnostic global permissions. Runs at the top of every wiring's
+ * permission resolution — before wire-, tag-, and function-level entries.
  *
- * // Add authentication permissions for auth endpoints
- * addPermission('auth', [authPermission])
+ * Resolution order: global -> wire -> tag -> function.
  *
- * // Add read permissions for all API endpoints (as object)
- * addPermission('api', { read: readPermission })
- * \`\`\`
+ * @example
+ * addGlobalPermission([signedInUser])
  */
-export const addPermission = <In = unknown>(tag: string, permissions: CorePermissionGroup<PikkuPermission<In>> | PikkuPermission<In>[]) => {
-  addPermissionCore(tag, permissions as any, ${packageNameValue})
+export const addGlobalPermission = <In = unknown>(permissions: CorePermissionGroup<PikkuPermission<In>> | PikkuPermission<In>[]) => {
+  addGlobalPermissionCore(permissions as any, ${packageNameValue})
 }
 
 export { wireAddon } from '@pikku/core/rpc'

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

@@ -1 +1 @@
-export declare const pikkuGateway: import("#pikku").PikkuFunctionConfig<void, boolean | undefined, "session" | "rpc", import("#pikku").PikkuFunctionSessionless<void, boolean | undefined, "session" | "rpc", import("#pikku").Services> | import("#pikku").PikkuFunction<void, boolean | undefined, "session" | "rpc", import("#pikku").Services>, undefined, undefined>;
+export declare const pikkuGateway: import("#pikku").PikkuFunctionConfig<void, boolean | undefined, "rpc" | "session", import("#pikku").PikkuFunctionSessionless<void, boolean | undefined, "rpc" | "session", import("#pikku").Services> | import("#pikku").PikkuFunction<void, boolean | undefined, "rpc" | "session", import("#pikku").Services>, undefined, undefined>;

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

@@ -1 +1 @@
-export declare const pikkuHTTPMap: import("#pikku").PikkuFunctionConfig<void, void, "session" | "rpc", import("#pikku").PikkuFunctionSessionless<void, void, "session" | "rpc", import("#pikku").Services> | import("#pikku").PikkuFunction<void, void, "session" | "rpc", import("#pikku").Services>, undefined, undefined>;
+export declare const pikkuHTTPMap: import("#pikku").PikkuFunctionConfig<void, void, "rpc" | "session", import("#pikku").PikkuFunctionSessionless<void, void, "rpc" | "session", import("#pikku").Services> | import("#pikku").PikkuFunction<void, void, "rpc" | "session", import("#pikku").Services>, undefined, undefined>;

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

@@ -1 +1 @@
-export declare const pikkuHTTP: import("#pikku").PikkuFunctionConfig<void, boolean | undefined, "session" | "rpc", import("#pikku").PikkuFunctionSessionless<void, boolean | undefined, "session" | "rpc", import("#pikku").Services> | import("#pikku").PikkuFunction<void, boolean | undefined, "session" | "rpc", import("#pikku").Services>, undefined, undefined>;
+export declare const pikkuCommandHTTP: import("#pikku").PikkuFunctionConfig<void, boolean | undefined, "rpc" | "session", import("#pikku").PikkuFunctionSessionless<void, boolean | undefined, "rpc" | "session", import("#pikku").Services> | import("#pikku").PikkuFunction<void, boolean | undefined, "rpc" | "session", import("#pikku").Services>, undefined, undefined>;

package/dist/src/functions/wirings/http/pikku-command-http-routes.js

@@ -4,7 +4,7 @@ import { writeFileInDir } from '../../../utils/file-writer.js';
 import { logCommandInfoAndTime } from '../../../middleware/log-command-info-and-time.js';
 import { getFileImportRelativePath } from '../../../utils/file-import-path.js';
 import { stripVerboseFields, hasVerboseFields, } from '../../../utils/strip-verbose-meta.js';
-export const pikkuHTTP = pikkuSessionlessFunc({
+export const pikkuCommandHTTP = pikkuSessionlessFunc({
     func: async ({ logger, config, getInspectorState }) => {
         const visitState = await getInspectorState();
         const { httpWiringsFile, httpWiringMetaFile, httpWiringMetaJsonFile, packageMappings, schema, } = config;

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

@@ -1 +1 @@
-export declare const pikkuHTTPTypes: import("#pikku").PikkuFunctionConfig<void, void, "session" | "rpc", import("#pikku").PikkuFunctionSessionless<void, void, "session" | "rpc", import("#pikku").Services> | import("#pikku").PikkuFunction<void, void, "session" | "rpc", import("#pikku").Services>, undefined, undefined>;
+export declare const pikkuHTTPTypes: import("#pikku").PikkuFunctionConfig<void, void, "rpc" | "session", import("#pikku").PikkuFunctionSessionless<void, void, "rpc" | "session", import("#pikku").Services> | import("#pikku").PikkuFunction<void, void, "rpc" | "session", import("#pikku").Services>, undefined, undefined>;

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

@@ -1 +1 @@
-export declare const pikkuOpenAPI: import("#pikku").PikkuFunctionConfig<void, void, "session" | "rpc", import("#pikku").PikkuFunctionSessionless<void, void, "session" | "rpc", import("#pikku").Services> | import("#pikku").PikkuFunction<void, void, "session" | "rpc", import("#pikku").Services>, undefined, undefined>;
+export declare const pikkuOpenAPI: import("#pikku").PikkuFunctionConfig<void, void, "rpc" | "session", import("#pikku").PikkuFunctionSessionless<void, void, "rpc" | "session", import("#pikku").Services> | import("#pikku").PikkuFunction<void, void, "rpc" | "session", import("#pikku").Services>, undefined, undefined>;

package/dist/src/functions/wirings/http/pikku-http-routes.d.ts

@@ -1 +1 @@
-export declare const pikkuHTTP: import("#pikku").PikkuFunctionConfig<void, boolean, "session" | "rpc", import("#pikku").PikkuFunctionSessionless<void, boolean, "session" | "rpc", import("#pikku").Services> | import("#pikku").PikkuFunction<void, boolean, "session" | "rpc", import("#pikku").Services>, undefined, undefined>;
+export declare const pikkuHTTP: import("#pikku").PikkuFunctionConfig<void, boolean, "rpc" | "session", import("#pikku").PikkuFunctionSessionless<void, boolean, "rpc" | "session", import("#pikku").Services> | import("#pikku").PikkuFunction<void, boolean, "rpc" | "session", import("#pikku").Services>, undefined, undefined>;

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

@@ -1 +1 @@
-export declare const pikkuMCPJSON: import("#pikku").PikkuFunctionConfig<void, void, "session" | "rpc", import("#pikku").PikkuFunctionSessionless<void, void, "session" | "rpc", import("#pikku").Services> | import("#pikku").PikkuFunction<void, void, "session" | "rpc", import("#pikku").Services>, undefined, undefined>;
+export declare const pikkuMCPJSON: import("#pikku").PikkuFunctionConfig<void, void, "rpc" | "session", import("#pikku").PikkuFunctionSessionless<void, void, "rpc" | "session", import("#pikku").Services> | import("#pikku").PikkuFunction<void, void, "rpc" | "session", import("#pikku").Services>, undefined, undefined>;

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

@@ -1 +1 @@
-export declare const pikkuMCPTypes: import("#pikku").PikkuFunctionConfig<void, void, "session" | "rpc", import("#pikku").PikkuFunctionSessionless<void, void, "session" | "rpc", import("#pikku").Services> | import("#pikku").PikkuFunction<void, void, "session" | "rpc", import("#pikku").Services>, undefined, undefined>;
+export declare const pikkuMCPTypes: import("#pikku").PikkuFunctionConfig<void, void, "rpc" | "session", import("#pikku").PikkuFunctionSessionless<void, void, "rpc" | "session", import("#pikku").Services> | import("#pikku").PikkuFunction<void, void, "rpc" | "session", import("#pikku").Services>, undefined, undefined>;

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

@@ -1 +1 @@
-export declare const pikkuMCP: import("#pikku").PikkuFunctionConfig<void, boolean | undefined, "session" | "rpc", import("#pikku").PikkuFunctionSessionless<void, boolean | undefined, "session" | "rpc", import("#pikku").Services> | import("#pikku").PikkuFunction<void, boolean | undefined, "session" | "rpc", import("#pikku").Services>, undefined, undefined>;
+export declare const pikkuMCP: import("#pikku").PikkuFunctionConfig<void, boolean | undefined, "rpc" | "session", import("#pikku").PikkuFunctionSessionless<void, boolean | undefined, "rpc" | "session", import("#pikku").Services> | import("#pikku").PikkuFunction<void, boolean | undefined, "rpc" | "session", import("#pikku").Services>, undefined, undefined>;

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

@@ -1 +1 @@
-export declare const pikkuMiddleware: import("#pikku").PikkuFunctionConfig<void, boolean | undefined, "session" | "rpc", import("#pikku").PikkuFunctionSessionless<void, boolean | undefined, "session" | "rpc", import("#pikku").Services> | import("#pikku").PikkuFunction<void, boolean | undefined, "session" | "rpc", import("#pikku").Services>, undefined, undefined>;
+export declare const pikkuMiddleware: import("#pikku").PikkuFunctionConfig<void, boolean | undefined, "rpc" | "session", import("#pikku").PikkuFunctionSessionless<void, boolean | undefined, "rpc" | "session", import("#pikku").Services> | import("#pikku").PikkuFunction<void, boolean | undefined, "rpc" | "session", import("#pikku").Services>, undefined, undefined>;

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

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

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

@@ -1 +1 @@
-export declare const pikkuPackage: import("#pikku").PikkuFunctionConfig<void, boolean | undefined, "session" | "rpc", import("#pikku").PikkuFunctionSessionless<void, boolean | undefined, "session" | "rpc", import("#pikku").Services> | import("#pikku").PikkuFunction<void, boolean | undefined, "session" | "rpc", import("#pikku").Services>, undefined, undefined>;
+export declare const pikkuPackage: import("#pikku").PikkuFunctionConfig<void, boolean | undefined, "rpc" | "session", import("#pikku").PikkuFunctionSessionless<void, boolean | undefined, "rpc" | "session", import("#pikku").Services> | import("#pikku").PikkuFunction<void, boolean | undefined, "rpc" | "session", import("#pikku").Services>, undefined, undefined>;

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

@@ -1 +1 @@
-export declare const pikkuPermissions: import("#pikku").PikkuFunctionConfig<void, boolean | undefined, "session" | "rpc", import("#pikku").PikkuFunctionSessionless<void, boolean | undefined, "session" | "rpc", import("#pikku").Services> | import("#pikku").PikkuFunction<void, boolean | undefined, "session" | "rpc", import("#pikku").Services>, undefined, undefined>;
+export declare const pikkuPermissions: import("#pikku").PikkuFunctionConfig<void, boolean | undefined, "rpc" | "session", import("#pikku").PikkuFunctionSessionless<void, boolean | undefined, "rpc" | "session", import("#pikku").Services> | import("#pikku").PikkuFunction<void, boolean | undefined, "rpc" | "session", import("#pikku").Services>, undefined, undefined>;

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

@@ -1 +1 @@
-export declare const pikkuQueueMap: import("#pikku").PikkuFunctionConfig<void, void, "session" | "rpc", import("#pikku").PikkuFunctionSessionless<void, void, "session" | "rpc", import("#pikku").Services> | import("#pikku").PikkuFunction<void, void, "session" | "rpc", import("#pikku").Services>, undefined, undefined>;
+export declare const pikkuCommandQueueMap: import("#pikku").PikkuFunctionConfig<void, void, "rpc" | "session", import("#pikku").PikkuFunctionSessionless<void, void, "rpc" | "session", import("#pikku").Services> | import("#pikku").PikkuFunction<void, void, "rpc" | "session", import("#pikku").Services>, undefined, undefined>;

package/dist/src/functions/wirings/queue/pikku-command-queue-map.js

@@ -2,7 +2,7 @@ import { pikkuSessionlessFunc } from '#pikku';
 import { writeFileInDir } from '../../../utils/file-writer.js';
 import { logCommandInfoAndTime } from '../../../middleware/log-command-info-and-time.js';
 import { serializeQueueMap } from './serialize-queue-map.js';
-export const pikkuQueueMap = pikkuSessionlessFunc({
+export const pikkuCommandQueueMap = pikkuSessionlessFunc({
     func: async ({ logger, config, getInspectorState }) => {
         const { queueWorkers, functions, resolvedIOTypes } = await getInspectorState();
         const { queueMapDeclarationFile, packageMappings } = config;

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

@@ -1 +1 @@
-export declare const pikkuQueueService: import("#pikku").PikkuFunctionConfig<void, void, "session" | "rpc", import("#pikku").PikkuFunctionSessionless<void, void, "session" | "rpc", import("#pikku").Services> | import("#pikku").PikkuFunction<void, void, "session" | "rpc", import("#pikku").Services>, undefined, undefined>;
+export declare const pikkuQueueService: import("#pikku").PikkuFunctionConfig<void, void, "rpc" | "session", import("#pikku").PikkuFunctionSessionless<void, void, "rpc" | "session", import("#pikku").Services> | import("#pikku").PikkuFunction<void, void, "rpc" | "session", import("#pikku").Services>, undefined, undefined>;

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

@@ -1 +1 @@
-export declare const pikkuQueueTypes: import("#pikku").PikkuFunctionConfig<void, void, "session" | "rpc", import("#pikku").PikkuFunctionSessionless<void, void, "session" | "rpc", import("#pikku").Services> | import("#pikku").PikkuFunction<void, void, "session" | "rpc", import("#pikku").Services>, undefined, undefined>;
+export declare const pikkuQueueTypes: import("#pikku").PikkuFunctionConfig<void, void, "rpc" | "session", import("#pikku").PikkuFunctionSessionless<void, void, "rpc" | "session", import("#pikku").Services> | import("#pikku").PikkuFunction<void, void, "rpc" | "session", import("#pikku").Services>, undefined, undefined>;

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

@@ -1 +1 @@
-export declare const pikkuQueue: import("#pikku").PikkuFunctionConfig<void, boolean | undefined, "session" | "rpc", import("#pikku").PikkuFunctionSessionless<void, boolean | undefined, "session" | "rpc", import("#pikku").Services> | import("#pikku").PikkuFunction<void, boolean | undefined, "session" | "rpc", import("#pikku").Services>, undefined, undefined>;
+export declare const pikkuCommandQueue: import("#pikku").PikkuFunctionConfig<void, boolean | undefined, "rpc" | "session", import("#pikku").PikkuFunctionSessionless<void, boolean | undefined, "rpc" | "session", import("#pikku").Services> | import("#pikku").PikkuFunction<void, boolean | undefined, "rpc" | "session", import("#pikku").Services>, undefined, undefined>;

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

@@ -5,7 +5,7 @@ import { logCommandInfoAndTime } from '../../../middleware/log-command-info-and-
 import { serializeQueueMeta, serializeQueueMetaTS, } from './serialize-queue-meta.js';
 import { getFileImportRelativePath } from '../../../utils/file-import-path.js';
 import { stripVerboseFields, hasVerboseFields, } from '../../../utils/strip-verbose-meta.js';
-export const pikkuQueue = pikkuSessionlessFunc({
+export const pikkuCommandQueue = pikkuSessionlessFunc({
     func: async ({ logger, config, getInspectorState }) => {
         const visitState = await getInspectorState();
         const { queueWorkersWiringFile, queueWorkersWiringMetaFile, queueWorkersWiringMetaJsonFile, packageMappings, schema, } = config;

package/dist/src/functions/wirings/queue/pikku-queue-map.d.ts

@@ -1 +1 @@
-export declare const pikkuQueueMap: import("#pikku").PikkuFunctionConfig<void, void, "session" | "rpc", import("#pikku").PikkuFunctionSessionless<void, void, "session" | "rpc", import("#pikku").Services> | import("#pikku").PikkuFunction<void, void, "session" | "rpc", import("#pikku").Services>, undefined, undefined>;
+export declare const pikkuQueueMap: import("#pikku").PikkuFunctionConfig<void, void, "rpc" | "session", import("#pikku").PikkuFunctionSessionless<void, void, "rpc" | "session", import("#pikku").Services> | import("#pikku").PikkuFunction<void, void, "rpc" | "session", import("#pikku").Services>, undefined, undefined>;

package/dist/src/functions/wirings/queue/pikku-queue.d.ts

@@ -1 +1 @@
-export declare const pikkuQueue: import("#pikku").PikkuFunctionConfig<void, boolean, "session" | "rpc", import("#pikku").PikkuFunctionSessionless<void, boolean, "session" | "rpc", import("#pikku").Services> | import("#pikku").PikkuFunction<void, boolean, "session" | "rpc", import("#pikku").Services>, undefined, undefined>;
+export declare const pikkuQueue: import("#pikku").PikkuFunctionConfig<void, boolean, "rpc" | "session", import("#pikku").PikkuFunctionSessionless<void, boolean, "rpc" | "session", import("#pikku").Services> | import("#pikku").PikkuFunction<void, boolean, "rpc" | "session", import("#pikku").Services>, undefined, undefined>;

package/dist/src/functions/wirings/realtime/pikku-command-events-scaffold.d.ts

@@ -0,0 +1 @@
+export declare const pikkuEventsScaffold: import("#pikku").PikkuFunctionConfig<void, boolean, "rpc" | "session", import("#pikku").PikkuFunctionSessionless<void, boolean, "rpc" | "session", import("#pikku").Services> | import("#pikku").PikkuFunction<void, boolean, "rpc" | "session", import("#pikku").Services>, undefined, undefined>;

package/dist/src/functions/wirings/realtime/pikku-command-events-scaffold.js

@@ -0,0 +1,26 @@
+import { pikkuSessionlessFunc } from '#pikku';
+import { getFileImportRelativePath } from '../../../utils/file-import-path.js';
+import { writeFileInDir } from '../../../utils/file-writer.js';
+import { logCommandInfoAndTime } from '../../../middleware/log-command-info-and-time.js';
+import { serializeEventsScaffold } from './serialize-events-scaffold.js';
+export const pikkuEventsScaffold = pikkuSessionlessFunc({
+    func: async ({ logger, config }) => {
+        if (!config.scaffold?.events || !config.eventsChannelFile) {
+            logger.debug({
+                message: 'Skipping events scaffold (set scaffold.events in pikku.config.json to enable).',
+                type: 'skip',
+            });
+            return false;
+        }
+        const authRequired = config.scaffold.events === 'auth';
+        const pikkuTypesImportPath = getFileImportRelativePath(config.eventsChannelFile, config.typesDeclarationFile, config.packageMappings);
+        await writeFileInDir(logger, config.eventsChannelFile, serializeEventsScaffold(authRequired, pikkuTypesImportPath));
+        return true;
+    },
+    middleware: [
+        logCommandInfoAndTime({
+            commandStart: 'Generating events channel scaffold',
+            commandEnd: 'Generated events channel scaffold',
+        }),
+    ],
+});

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

@@ -0,0 +1 @@
+export declare const pikkuRealtime: import("#pikku").PikkuFunctionConfig<void, void, "rpc" | "session", import("#pikku").PikkuFunctionSessionless<void, void, "rpc" | "session", import("#pikku").Services> | import("#pikku").PikkuFunction<void, void, "rpc" | "session", import("#pikku").Services>, undefined, undefined>;

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

@@ -0,0 +1,35 @@
+import { pikkuSessionlessFunc } from '#pikku';
+import { getFileImportRelativePath } from '../../../utils/file-import-path.js';
+import { writeFileInDir } from '../../../utils/file-writer.js';
+import { logCommandInfoAndTime } from '../../../middleware/log-command-info-and-time.js';
+import { serializeRealtimeClient } from './serialize-realtime-client.js';
+export const pikkuRealtime = pikkuSessionlessFunc({
+    func: async ({ logger, config }) => {
+        const realtimeFile = config.clientFiles?.realtimeFile;
+        const fetchFile = config.clientFiles?.fetchFile;
+        if (!realtimeFile) {
+            logger.debug({
+                message: 'Skipping realtime client (set clientFiles.realtimeFile in pikku.config.json to enable).',
+                type: 'skip',
+            });
+            return;
+        }
+        if (!fetchFile) {
+            logger.debug({
+                message: 'Skipping realtime client (clientFiles.fetchFile is required so PikkuRealtime can wrap PikkuFetch).',
+                type: 'skip',
+            });
+            return;
+        }
+        const topicsImport = config.clientFiles?.realtimeEventHubTopicsImport;
+        const fetchImportPath = getFileImportRelativePath(realtimeFile, fetchFile, config.packageMappings);
+        const content = serializeRealtimeClient(topicsImport, fetchImportPath);
+        await writeFileInDir(logger, realtimeFile, content);
+    },
+    middleware: [
+        logCommandInfoAndTime({
+            commandStart: 'Generating realtime client',
+            commandEnd: 'Generated realtime client',
+        }),
+    ],
+});

package/dist/src/functions/wirings/realtime/serialize-events-scaffold.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Generates the server-side `events.gen.ts` scaffold.
+ *
+ * This file lives in the user's project and wires two transports against the
+ * project's `eventHub` service:
+ *
+ *   1. WebSocket channel at `/events` — bidirectional. Clients send
+ *      `{action: 'subscribe' | 'unsubscribe', topic}` over the same socket;
+ *      multiple topic subscriptions per connection. On disconnect the
+ *      eventHub's onChannelClosed hook auto-cleans subscriptions.
+ *
+ *   2. SSE endpoint at `GET /events/:topic` — one connection = one topic.
+ *      Subscribes the channel, returns; the eventHub fans out via
+ *      `channel.send` until the client closes. onChannelClosed cleans up.
+ *
+ * Both routes call `eventHub.subscribe`/`unsubscribe` with the channel id;
+ * publish-side ergonomics (envelope shape) are documented in the
+ * pikku-realtime skill.
+ *
+ * Uses TypeScript generics (not named Zod schema constants) so schemas and
+ * wiring calls can safely coexist in a single generated file.
+ */
+export declare const serializeEventsScaffold: (authRequired: boolean, pikkuTypesImportPath: string) => string;

package/dist/src/functions/wirings/realtime/serialize-events-scaffold.js

@@ -0,0 +1,98 @@
+/**
+ * Generates the server-side `events.gen.ts` scaffold.
+ *
+ * This file lives in the user's project and wires two transports against the
+ * project's `eventHub` service:
+ *
+ *   1. WebSocket channel at `/events` — bidirectional. Clients send
+ *      `{action: 'subscribe' | 'unsubscribe', topic}` over the same socket;
+ *      multiple topic subscriptions per connection. On disconnect the
+ *      eventHub's onChannelClosed hook auto-cleans subscriptions.
+ *
+ *   2. SSE endpoint at `GET /events/:topic` — one connection = one topic.
+ *      Subscribes the channel, returns; the eventHub fans out via
+ *      `channel.send` until the client closes. onChannelClosed cleans up.
+ *
+ * Both routes call `eventHub.subscribe`/`unsubscribe` with the channel id;
+ * publish-side ergonomics (envelope shape) are documented in the
+ * pikku-realtime skill.
+ *
+ * Uses TypeScript generics (not named Zod schema constants) so schemas and
+ * wiring calls can safely coexist in a single generated file.
+ */
+export const serializeEventsScaffold = (authRequired, pikkuTypesImportPath) => {
+    const auth = authRequired ? 'true' : 'false';
+    return `import {
+  pikkuChannelFunc,
+  pikkuSessionlessFunc,
+  wireChannel,
+  wireHTTP,
+  defineChannelRoutes,
+} from '${pikkuTypesImportPath}'
+
+/**
+ * Topic envelope clients receive: \`{ topic, data }\`. Functions that publish
+ * events should send this shape:
+ *
+ *   await eventHub.publish('todo-created', null, { topic: 'todo-created', data: { todo } })
+ *
+ * The pikku-realtime skill covers a thin \`publishEvent\` helper to remove
+ * the duplication; pick whichever style your project prefers.
+ */
+
+export const realtimeSubscribe = pikkuChannelFunc<{ topic: string }>({
+  func: async ({ eventHub }, { topic }, { channel }) => {
+    await eventHub?.subscribe(topic, channel.channelId)
+  },
+})
+
+export const realtimeUnsubscribe = pikkuChannelFunc<{ topic: string }>({
+  func: async ({ eventHub }, { topic }, { channel }) => {
+    await eventHub?.unsubscribe(topic, channel.channelId)
+  },
+})
+
+// Pikku dispatches by the \`action\` field; client sends
+//   { action: 'subscribe',   topic: 'todo-created' }
+//   { action: 'unsubscribe', topic: 'todo-created' }
+export const realtimeRoutes = defineChannelRoutes({
+  subscribe: realtimeSubscribe,
+  unsubscribe: realtimeUnsubscribe,
+})
+
+wireChannel({
+  name: 'events',
+  route: '/events',
+  auth: ${auth},
+  onMessageWiring: {
+    action: realtimeRoutes,
+  },
+  tags: ['pikku:realtime'],
+})
+
+/**
+ * SSE per-topic stream. One connection = one subscription. The eventHub
+ * cleans up automatically when the channel closes (onChannelClosed).
+ */
+export const realtimeEventStream = pikkuSessionlessFunc<{ topic: string }, void>({
+  description: 'Auto-generated SSE stream for a single event-hub topic',
+  func: async ({ eventHub }, { topic }, { channel }) => {
+    if (!channel) {
+      throw new Error('Realtime SSE handler invoked without a channel')
+    }
+    await eventHub?.subscribe(topic, channel.channelId)
+    // Function returns; eventHub continues pushing via channel.send until
+    // the client disconnects, at which point onChannelClosed unsubscribes.
+  },
+})
+
+wireHTTP({
+  method: 'get',
+  route: '/events/:topic',
+  func: realtimeEventStream,
+  auth: ${auth},
+  sse: true,
+  tags: ['pikku:realtime', 'sse'],
+})
+`;
+};

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

@@ -0,0 +1,22 @@
+/**
+ * Generates the client-side `realtime.gen.ts`.
+ *
+ * `PikkuRealtime` mirrors the `PikkuRPC` pattern: it wraps the project's
+ * generated `PikkuFetch` (so server URL + auth come from one place) and
+ * exposes:
+ *
+ *   - `subscribe(topic, handler)` / `unsubscribe(topic)` — typed pub/sub
+ *     over the websocket at `/events`. Multi-topic per connection.
+ *   - `subscribeToTopic(topic, handler)` — same shape but via SSE
+ *     (one EventSource per topic, auto-cleanup on close).
+ *   - `subscribeToSSE(path, handler)` — generic SSE subscribe for any
+ *     `sse: true` route (workflow streams, agent streams, etc.).
+ *   - `connectToChannel(channelRoute, protocols?)` — open a raw WebSocket
+ *     for any wireChannel route, ready to wrap in
+ *     `PikkuWebSocket<'channel-name'>` for typed subscribe/send.
+ *
+ * Topic types come from `EventHubTopics` if the user supplies an import
+ * via `clientFiles.realtimeEventHubTopicsImport`. Otherwise topics fall
+ * back to `Record<string, unknown>`.
+ */
+export declare const serializeRealtimeClient: (topicsImport: string | undefined, fetchImportPath: string) => string;