@pikku/core 0.11.2 → 0.12.1

package/dist/wirings/channel/channel.types.d.ts

@@ -1,7 +1,9 @@
-import { PikkuError } from '../../errors/error-handler.js';
-import { HTTPFunctionMetaInputTypes, PikkuHTTPRequest, PikkuHTTPResponse } from '../http/http.types.js';
-import { CoreSingletonServices, CreateWireServices, CorePikkuMiddleware, MiddlewareMetadata, PermissionMetadata } from '../../types/core.types.js';
-import { CorePermissionGroup, CorePikkuFunction, CorePikkuFunctionConfig, CorePikkuFunctionSessionless, CorePikkuPermission } from '../../function/functions.types.js';
+import type { PikkuError } from '../../errors/error-handler.js';
+import type { HTTPFunctionMetaInputTypes, PikkuHTTPRequest, PikkuHTTPResponse } from '../http/http.types.js';
+import type { CorePikkuMiddleware, MiddlewareMetadata, PermissionMetadata } from '../../types/core.types.js';
+export type CorePikkuChannelMiddleware<Services = any, Event = unknown> = (services: Services, event: Event, next: (event: Event | Event[] | null) => Promise<void> | void) => Promise<void> | void;
+export type CorePikkuChannelMiddlewareFactory<In = any, Services = any, Event = unknown> = (input: In) => CorePikkuChannelMiddleware<Services, Event>;
+import type { CorePermissionGroup, CorePikkuFunction, CorePikkuFunctionConfig, CorePikkuFunctionSessionless, CorePikkuPermission } from '../../function/functions.types.js';
 export type RunChannelOptions = Partial<{
     skipUserSession: boolean;
     respondWith404: boolean;
@@ -11,13 +13,11 @@ export type RunChannelOptions = Partial<{
 }>;
 export type RunChannelParams<ChannelData> = {
     channelId: string;
-    singletonServices: CoreSingletonServices;
     request?: PikkuHTTPRequest<ChannelData>;
     response?: PikkuHTTPResponse;
-    createWireServices?: CreateWireServices;
 };
 export interface ChannelMessageMeta {
-    pikkuFuncName: string;
+    pikkuFuncId: string;
     summary?: string;
     description?: string;
     errors?: string[];
@@ -42,6 +42,7 @@ export interface ChannelMeta {
     tags?: string[];
     middleware?: MiddlewareMetadata[];
     permissions?: PermissionMetadata[];
+    channelMiddleware?: MiddlewareMetadata[];
 }
 export type ChannelsMeta = Record<string, ChannelMeta>;
 export type CoreChannel<ChannelData, Channel extends string, ChannelConnect = CorePikkuFunctionConfig<CorePikkuFunction<void, unknown> | CorePikkuFunctionSessionless<void, unknown>, CorePikkuPermission<void>, CorePikkuMiddleware>, ChannelDisconnect = CorePikkuFunctionConfig<CorePikkuFunction<void, void> | CorePikkuFunctionSessionless<void, void>, CorePikkuPermission<void>, CorePikkuMiddleware>, ChannelFunctionMessage = CorePikkuFunctionConfig<CorePikkuFunction<unknown, unknown> | CorePikkuFunctionSessionless<unknown, unknown>, CorePikkuPermission<unknown>, CorePikkuMiddleware>, PikkuPermission = CorePikkuPermission<ChannelData>, PikkuMiddleware = CorePikkuMiddleware> = {
@@ -63,6 +64,7 @@ export type CoreChannel<ChannelData, Channel extends string, ChannelConnect = Co
         middleware?: PikkuMiddleware[];
     }>>;
     middleware?: PikkuMiddleware[];
+    channelMiddleware?: Array<CorePikkuChannelMiddleware | CorePikkuChannelMiddlewareFactory>;
     permissions?: CorePermissionGroup<PikkuPermission>;
     auth?: boolean;
     docs?: Partial<{

package/dist/wirings/channel/define-channel-routes.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Type-safe helper for defining channel message routes that can be composed.
+ * Returns the routes record as-is (identity function) for use with `wireChannel`.
+ *
+ * @example
+ * ```typescript
+ * export const chatRoutes = defineChannelRoutes({
+ *   greet: pikkuChannelFunc({ func: greetFunc }),
+ *   farewell: pikkuChannelFunc({ func: farewellFunc }),
+ * })
+ *
+ * wireChannel({
+ *   name: 'chat',
+ *   route: '/ws/chat',
+ *   onMessageWiring: {
+ *     command: chatRoutes,
+ *   }
+ * })
+ * ```
+ */
+export declare function defineChannelRoutes<T extends Record<string, any>>(routes: T): T;

package/dist/wirings/channel/define-channel-routes.js

@@ -0,0 +1,23 @@
+/**
+ * Type-safe helper for defining channel message routes that can be composed.
+ * Returns the routes record as-is (identity function) for use with `wireChannel`.
+ *
+ * @example
+ * ```typescript
+ * export const chatRoutes = defineChannelRoutes({
+ *   greet: pikkuChannelFunc({ func: greetFunc }),
+ *   farewell: pikkuChannelFunc({ func: farewellFunc }),
+ * })
+ *
+ * wireChannel({
+ *   name: 'chat',
+ *   route: '/ws/chat',
+ *   onMessageWiring: {
+ *     command: chatRoutes,
+ *   }
+ * })
+ * ```
+ */
+export function defineChannelRoutes(routes) {
+    return routes;
+}

package/dist/wirings/channel/index.d.ts

@@ -1,8 +1,10 @@
-export * from './channel-runner.js';
-export * from './channel.types.js';
-export * from './log-channels.js';
-export * from './pikku-abstract-channel-handler.js';
-export * from './eventhub-service.js';
-export * from './eventhub-service.js';
-export * from './channel-store.js';
-export * from './eventhub-store.js';
+export { wireChannel, openChannel } from './channel-runner.js';
+export { addChannelMiddleware, combineChannelMiddleware, wrapChannelWithMiddleware, } from './channel-middleware-runner.js';
+export { logChannels } from './log-channels.js';
+export { PikkuAbstractChannelHandler } from './pikku-abstract-channel-handler.js';
+export type { EventHubService } from './eventhub-service.js';
+export { ChannelStore } from './channel-store.js';
+export type { Channel } from './channel-store.js';
+export { EventHubStore } from './eventhub-store.js';
+export type { ChannelsMeta, CoreChannel, CorePikkuChannelMiddleware, CorePikkuChannelMiddlewareFactory, ChannelMessageMeta, ChannelMeta, PikkuChannel, PikkuChannelHandlerFactory, } from './channel.types.js';
+export { defineChannelRoutes } from './define-channel-routes.js';

package/dist/wirings/channel/index.js

@@ -1,8 +1,7 @@
-export * from './channel-runner.js';
-export * from './channel.types.js';
-export * from './log-channels.js';
-export * from './pikku-abstract-channel-handler.js';
-export * from './eventhub-service.js';
-export * from './eventhub-service.js';
-export * from './channel-store.js';
-export * from './eventhub-store.js';
+export { wireChannel, openChannel } from './channel-runner.js';
+export { addChannelMiddleware, combineChannelMiddleware, wrapChannelWithMiddleware, } from './channel-middleware-runner.js';
+export { logChannels } from './log-channels.js';
+export { PikkuAbstractChannelHandler } from './pikku-abstract-channel-handler.js';
+export { ChannelStore } from './channel-store.js';
+export { EventHubStore } from './eventhub-store.js';
+export { defineChannelRoutes } from './define-channel-routes.js';

package/dist/wirings/channel/local/index.d.ts

@@ -1,3 +1,3 @@
-export * from './local-channel-handler.js';
-export * from './local-channel-runner.js';
-export * from './local-eventhub-service.js';
+export { PikkuLocalChannelHandler } from './local-channel-handler.js';
+export { runLocalChannel } from './local-channel-runner.js';
+export { LocalEventHubService } from './local-eventhub-service.js';

package/dist/wirings/channel/local/index.js

@@ -1,3 +1,3 @@
-export * from './local-channel-handler.js';
-export * from './local-channel-runner.js';
-export * from './local-eventhub-service.js';
+export { PikkuLocalChannelHandler } from './local-channel-handler.js';
+export { runLocalChannel } from './local-channel-runner.js';
+export { LocalEventHubService } from './local-eventhub-service.js';

package/dist/wirings/channel/local/local-channel-runner.d.ts

@@ -1,3 +1,8 @@
-import { CoreChannel, RunChannelOptions, RunChannelParams } from '../channel.types.js';
+import type { CoreChannel, RunChannelOptions } from '../channel.types.js';
 import { PikkuLocalChannelHandler } from './local-channel-handler.js';
-export declare const runLocalChannel: ({ singletonServices, channelId, request, response, route, createWireServices, skipUserSession, respondWith404, coerceDataFromSchema, logWarningsForStatusCodes, bubbleErrors, }: Partial<Pick<CoreChannel<unknown, any>, "route">> & RunChannelOptions & RunChannelParams<unknown>) => Promise<PikkuLocalChannelHandler | void>;
+import type { PikkuHTTPRequest, PikkuHTTPResponse } from '../../http/http.types.js';
+export declare const runLocalChannel: ({ channelId, request, response, route, skipUserSession, respondWith404, coerceDataFromSchema, logWarningsForStatusCodes, bubbleErrors, }: Partial<Pick<CoreChannel<unknown, any>, "route">> & RunChannelOptions & {
+    channelId: string;
+    request?: PikkuHTTPRequest;
+    response?: PikkuHTTPResponse;
+}) => Promise<PikkuLocalChannelHandler | void>;

package/dist/wirings/channel/local/local-channel-runner.js

@@ -4,10 +4,14 @@ import { closeWireServices } from '../../../utils.js';
 import { processMessageHandlers } from '../channel-handler.js';
 import { PikkuLocalChannelHandler } from './local-channel-handler.js';
 import { handleHTTPError } from '../../../handle-error.js';
-import { PikkuSessionService } from '../../../services/user-session-service.js';
+import { PikkuSessionService, createMiddlewareSessionWireProps, } from '../../../services/user-session-service.js';
 import { runChannelLifecycleWithMiddleware } from '../channel-common.js';
-export const runLocalChannel = async ({ singletonServices, channelId, request, response, route, createWireServices, skipUserSession = false, respondWith404 = true, coerceDataFromSchema = true, logWarningsForStatusCodes = [], bubbleErrors = false, }) => {
+import { getSingletonServices, getCreateWireServices, } from '../../../pikku-state.js';
+export const runLocalChannel = async ({ channelId, request, response, route, skipUserSession = false, respondWith404 = true, coerceDataFromSchema = true, logWarningsForStatusCodes = [], bubbleErrors = false, }) => {
+    const singletonServices = getSingletonServices();
+    const createWireServices = getCreateWireServices();
     let wireServices;
+    let closedWireServices = false;
     let channelHandler;
     const userSession = new PikkuSessionService();
     let http;
@@ -20,12 +24,10 @@ export const runLocalChannel = async ({ singletonServices, channelId, request, r
         ;
         ({ openingData, channelConfig, meta } = await openChannel({
             channelId,
-            createWireServices,
             respondWith404,
             request,
             response,
             route,
-            singletonServices,
             skipUserSession,
             coerceDataFromSchema,
             userSession,
@@ -39,10 +41,20 @@ export const runLocalChannel = async ({ singletonServices, channelId, request, r
         try {
             channelHandler = new PikkuLocalChannelHandler(channelId, channelConfig.name, openingData);
             const channel = channelHandler.getChannel();
-            const wire = { channel, session: userSession };
+            const wire = {
+                channel,
+                ...createMiddlewareSessionWireProps(userSession),
+            };
             if (createWireServices) {
                 wireServices = await createWireServices(singletonServices, wire);
             }
+            const closeServices = async () => {
+                if (!wireServices || closedWireServices) {
+                    return;
+                }
+                closedWireServices = true;
+                await closeWireServices(singletonServices.logger, wireServices);
+            };
             const services = { ...singletonServices, ...wireServices };
             channelHandler.registerOnOpen(async () => {
                 if (channelConfig.onConnect && meta.connect) {
@@ -55,6 +67,7 @@ export const runLocalChannel = async ({ singletonServices, channelId, request, r
                             services,
                             channel,
                             data: openingData,
+                            channelMiddlewareMeta: meta.channelMiddleware,
                         });
                         if (result !== undefined) {
                             await channel.send(result);
@@ -76,6 +89,7 @@ export const runLocalChannel = async ({ singletonServices, channelId, request, r
                             lifecycleType: 'disconnect',
                             services,
                             channel,
+                            channelMiddlewareMeta: meta.channelMiddleware,
                         });
                     }
                     catch (e) {
@@ -83,9 +97,7 @@ export const runLocalChannel = async ({ singletonServices, channelId, request, r
                         channel.send({ error: e.message || 'Unknown error' });
                     }
                 }
-                if (wireServices) {
-                    await closeWireServices(singletonServices.logger, wireServices);
-                }
+                await closeServices();
             });
             const onMessage = processMessageHandlers(services, channelConfig, channelHandler, userSession);
             channelHandler.registerOnMessage(async (data) => {
@@ -103,7 +115,8 @@ export const runLocalChannel = async ({ singletonServices, channelId, request, r
             handleHTTPError(e, http, channelId, singletonServices.logger, logWarningsForStatusCodes, respondWith404, bubbleErrors);
         }
         finally {
-            if (wireServices) {
+            if (!channelHandler && wireServices && !closedWireServices) {
+                closedWireServices = true;
                 await closeWireServices(singletonServices.logger, wireServices);
             }
         }

package/dist/wirings/channel/local/local-eventhub-service.d.ts

@@ -1,5 +1,5 @@
-import { PikkuChannelHandler } from '../channel.types.js';
-import { EventHubService } from '../eventhub-service.js';
+import type { PikkuChannelHandler } from '../channel.types.js';
+import type { EventHubService } from '../eventhub-service.js';
 /**
  * Implementation of the SubscriptionService interface.
  * Manages subscriptions and publishes messages to subscribers.

package/dist/wirings/channel/log-channels.d.ts

@@ -1,4 +1,4 @@
-import { Logger } from '../../services/index.js';
+import type { Logger } from '../../services/index.js';
 /**
  * Logs all the loaded channels.
  * @param logger - A logger for logging information.

package/dist/wirings/channel/pikku-abstract-channel-handler.d.ts

@@ -1,4 +1,4 @@
-import { PikkuChannel, PikkuChannelHandler } from './channel.types.js';
+import type { PikkuChannel, PikkuChannelHandler } from './channel.types.js';
 export declare abstract class PikkuAbstractChannelHandler<OpeningData = unknown, Out = unknown> implements PikkuChannelHandler<OpeningData, Out> {
     channelId: string;
     channelName: string;

package/dist/wirings/channel/serverless/index.d.ts

@@ -1 +1 @@
-export * from './serverless-channel-runner.js';
+export { runChannelConnect, runChannelDisconnect, runChannelMessage, } from './serverless-channel-runner.js';

package/dist/wirings/channel/serverless/index.js

@@ -1 +1 @@
-export * from './serverless-channel-runner.js';
+export { runChannelConnect, runChannelDisconnect, runChannelMessage, } from './serverless-channel-runner.js';

package/dist/wirings/channel/serverless/serverless-channel-runner.d.ts

@@ -1,10 +1,10 @@
 import type { CoreChannel, RunChannelOptions, RunChannelParams, PikkuChannelHandlerFactory } from '../channel.types.js';
-import { ChannelStore } from '../channel-store.js';
+import type { ChannelStore } from '../channel-store.js';
 export interface RunServerlessChannelParams<ChannelData> extends RunChannelParams<ChannelData> {
     channelStore: ChannelStore;
     channelHandlerFactory: PikkuChannelHandlerFactory;
     channelObject?: unknown;
 }
-export declare const runChannelConnect: ({ singletonServices, channelId, channelObject, request, response, route, createWireServices, channelStore, channelHandlerFactory, coerceDataFromSchema, logWarningsForStatusCodes, respondWith404, bubbleErrors, }: Pick<CoreChannel<unknown, any>, "route"> & RunChannelOptions & RunServerlessChannelParams<unknown>) => Promise<void>;
-export declare const runChannelDisconnect: ({ singletonServices, ...params }: RunServerlessChannelParams<unknown>) => Promise<void>;
-export declare const runChannelMessage: ({ singletonServices, ...params }: RunServerlessChannelParams<unknown>, data: unknown) => Promise<unknown>;
+export declare const runChannelConnect: ({ channelId, channelObject, request, response, route, channelStore, channelHandlerFactory, coerceDataFromSchema, logWarningsForStatusCodes, respondWith404, bubbleErrors, }: Pick<CoreChannel<unknown, any>, "route"> & RunChannelOptions & RunServerlessChannelParams<unknown>) => Promise<void>;
+export declare const runChannelDisconnect: ({ channelId, channelStore, channelHandlerFactory, }: RunServerlessChannelParams<unknown>) => Promise<void>;
+export declare const runChannelMessage: ({ channelId, channelStore, channelHandlerFactory, }: RunServerlessChannelParams<unknown>, data: unknown) => Promise<unknown>;

package/dist/wirings/channel/serverless/serverless-channel-runner.js

@@ -3,8 +3,8 @@ import { processMessageHandlers } from '../channel-handler.js';
 import { openChannel } from '../channel-runner.js';
 import { createHTTPWire } from '../../http/http-runner.js';
 import { handleHTTPError } from '../../../handle-error.js';
-import { PikkuSessionService } from '../../../services/user-session-service.js';
-import { pikkuState } from '../../../pikku-state.js';
+import { PikkuSessionService, createMiddlewareSessionWireProps, } from '../../../services/user-session-service.js';
+import { getSingletonServices, getCreateWireServices, pikkuState, } from '../../../pikku-state.js';
 import { PikkuFetchHTTPRequest } from '../../http/pikku-fetch-http-request.js';
 import { runChannelLifecycleWithMiddleware } from '../channel-common.js';
 const getVariablesForChannel = ({ channelId, channelName, channelHandlerFactory, openingData, }) => {
@@ -26,7 +26,9 @@ const getVariablesForChannel = ({ channelId, channelName, channelHandlerFactory,
         meta,
     };
 };
-export const runChannelConnect = async ({ singletonServices, channelId, channelObject, request, response, route, createWireServices, channelStore, channelHandlerFactory, coerceDataFromSchema = true, logWarningsForStatusCodes = [], respondWith404 = true, bubbleErrors = false, }) => {
+export const runChannelConnect = async ({ channelId, channelObject, request, response, route, channelStore, channelHandlerFactory, coerceDataFromSchema = true, logWarningsForStatusCodes = [], respondWith404 = true, bubbleErrors = false, }) => {
+    const singletonServices = getSingletonServices();
+    const createWireServices = getCreateWireServices();
     let wireServices;
     let http;
     if (request instanceof Request) {
@@ -35,10 +37,8 @@ export const runChannelConnect = async ({ singletonServices, channelId, channelO
     const userSession = new PikkuSessionService(channelStore, channelId);
     const { channelConfig, openingData, meta } = await openChannel({
         channelId,
-        createWireServices,
         request,
         route,
-        singletonServices,
         coerceDataFromSchema,
         userSession,
     });
@@ -54,7 +54,10 @@ export const runChannelConnect = async ({ singletonServices, channelId, channelO
             channelHandlerFactory,
             channelName: channelConfig.name,
         });
-        const wire = { channel, session: userSession };
+        const wire = {
+            channel,
+            ...createMiddlewareSessionWireProps(userSession),
+        };
         if (createWireServices) {
             wireServices = await createWireServices(singletonServices, wire);
         }
@@ -71,6 +74,7 @@ export const runChannelConnect = async ({ singletonServices, channelId, channelO
                 services,
                 channel,
                 data: openingData,
+                channelMiddlewareMeta: meta.channelMiddleware,
             });
         }
         http?.response?.status(101);
@@ -84,7 +88,9 @@ export const runChannelConnect = async ({ singletonServices, channelId, channelO
         }
     }
 };
-export const runChannelDisconnect = async ({ singletonServices, ...params }) => {
+export const runChannelDisconnect = async ({ channelId, channelStore, channelHandlerFactory, }) => {
+    const singletonServices = getSingletonServices();
+    const createWireServices = getCreateWireServices();
     let wireServices;
     // Try to get channel from store. In serverless environments (especially with
     // serverless-offline or worker threads), disconnect can be called multiple times
@@ -92,23 +98,27 @@ export const runChannelDisconnect = async ({ singletonServices, ...params }) =>
     // there's nothing to disconnect, so we can return early.
     let channelData;
     try {
-        channelData = await params.channelStore.getChannelAndSession(params.channelId);
+        channelData = await channelStore.getChannelAndSession(channelId);
     }
-    catch (error) {
-        singletonServices.logger.info(`Channel ${params.channelId} not found during disconnect - already cleaned up`);
+    catch {
+        singletonServices.logger.info(`Channel ${channelId} not found during disconnect - already cleaned up`);
         return;
     }
     const { openingData, channelName, session } = channelData;
     const { channel, channelConfig, meta } = getVariablesForChannel({
-        ...params,
+        channelId,
+        channelHandlerFactory,
         openingData,
         channelName,
     });
-    const userSession = new PikkuSessionService(params.channelStore, params.channelId);
+    const userSession = new PikkuSessionService(channelStore, channelId);
     userSession.setInitial(session);
-    const wire = { channel, session: userSession };
-    if (!wireServices && params.createWireServices) {
-        wireServices = await params.createWireServices(singletonServices, wire);
+    const wire = {
+        channel,
+        ...createMiddlewareSessionWireProps(userSession),
+    };
+    if (createWireServices) {
+        wireServices = await createWireServices(singletonServices, wire);
     }
     const services = {
         ...singletonServices,
@@ -123,30 +133,37 @@ export const runChannelDisconnect = async ({ singletonServices, ...params }) =>
                 lifecycleType: 'disconnect',
                 services,
                 channel,
+                channelMiddlewareMeta: meta.channelMiddleware,
             });
         }
         catch (e) {
             singletonServices.logger.error(`Error handling onDisconnect: ${e.message || e}`);
         }
     }
-    await params.channelStore.removeChannels([channel.channelId]);
+    await channelStore.removeChannels([channel.channelId]);
     if (wireServices) {
         await closeWireServices(singletonServices.logger, wireServices);
     }
 };
-export const runChannelMessage = async ({ singletonServices, ...params }, data) => {
+export const runChannelMessage = async ({ channelId, channelStore, channelHandlerFactory, }, data) => {
+    const singletonServices = getSingletonServices();
+    const createWireServices = getCreateWireServices();
     let wireServices;
-    const { openingData, channelName, session } = await params.channelStore.getChannelAndSession(params.channelId);
+    const { openingData, channelName, session } = await channelStore.getChannelAndSession(channelId);
     const { channel, channelHandler, channelConfig } = getVariablesForChannel({
-        ...params,
+        channelId,
+        channelHandlerFactory,
         openingData,
         channelName,
     });
-    const userSession = new PikkuSessionService(params.channelStore, params.channelId);
+    const userSession = new PikkuSessionService(channelStore, channelId);
     userSession.setInitial(session);
-    const wire = { channel, session: userSession };
-    if (params.createWireServices) {
-        wireServices = await params.createWireServices(singletonServices, wire);
+    const wire = {
+        channel,
+        ...createMiddlewareSessionWireProps(userSession),
+    };
+    if (createWireServices) {
+        wireServices = await createWireServices(singletonServices, wire);
     }
     const services = {
         ...singletonServices,

package/dist/wirings/cli/channel/cli-channel-runner.d.ts

@@ -1,4 +1,4 @@
-import { CorePikkuCLIRender } from '../cli.types.js';
+import type { CorePikkuCLIRender } from '../cli.types.js';
 /**
  * Execute a CLI program via WebSocket channel
  * This is the main entry point for CLI-over-Channel clients

package/dist/wirings/cli/channel/index.d.ts

@@ -1 +1 @@
-export * from './cli-channel-runner.js';
+export { executeCLIViaChannel } from './cli-channel-runner.js';

package/dist/wirings/cli/channel/index.js

@@ -1 +1 @@
-export * from './cli-channel-runner.js';
+export { executeCLIViaChannel } from './cli-channel-runner.js';

package/dist/wirings/cli/cli-runner.d.ts

@@ -1,5 +1,5 @@
-import { CorePikkuMiddleware, CoreUserSession } from '../../types/core.types.js';
-import { CoreCLI, CorePikkuCLIRender, CoreCLICommandConfig } from './cli.types.js';
+import type { CorePikkuMiddleware, CoreUserSession } from '../../types/core.types.js';
+import type { CoreCLI, CorePikkuCLIRender, CoreCLICommandConfig } from './cli.types.js';
 import type { CoreSingletonServices, CoreServices, CreateWireServices, CreateConfig, CreateSingletonServices } from '../../types/core.types.js';
 /**
  * CLI command execution error - thrown when CLI execution fails
@@ -36,7 +36,7 @@ export declare const pikkuCLIRender: <Data, Services extends CoreSingletonServic
 export declare function executeCLI({ programName, args, createConfig, createSingletonServices, createWireServices, }: {
     programName: string;
     args?: string[];
-    createConfig: CreateConfig<any, any>;
+    createConfig?: CreateConfig<any, any>;
     createSingletonServices: CreateSingletonServices<any, any>;
     createWireServices?: CreateWireServices<any, any, any>;
 }): Promise<void>;

package/dist/wirings/cli/cli-runner.js

@@ -1,7 +1,7 @@
-import { NotFoundError } from '../../errors/errors.js';
+import { NotFoundError, PikkuMissingMetaError } from '../../errors/errors.js';
 import { addFunction, runPikkuFunc } from '../../function/function-runner.js';
 import { pikkuState } from '../../pikku-state.js';
-import { PikkuSessionService } from '../../services/user-session-service.js';
+import { PikkuSessionService, createMiddlewareSessionWireProps, } from '../../services/user-session-service.js';
 import { LocalVariablesService } from '../../services/local-variables.js';
 import { generateCommandHelp, parseCLIArguments } from './command-parser.js';
 /**
@@ -29,7 +29,7 @@ export const wireCLI = (cli) => {
     // Get the existing metadata that was generated during inspection
     const cliMeta = pikkuState(null, 'cli', 'meta') || {};
     if (!cliMeta.programs?.[cli.program]) {
-        throw new Error(`CLI metadata not found for program '${cli.program}'. Did you run 'pikku all'?`);
+        throw new PikkuMissingMetaError(`CLI metadata not found for program '${cli.program}'`);
     }
     // Get existing programs state and add this program
     const programs = pikkuState(null, 'cli', 'programs') || {};
@@ -81,7 +81,7 @@ function registerCLICommands(commands, path = [], inheritedOptions = {}, program
         for (let i = 1; i < fullPath.length; i++) {
             currentMeta = currentMeta?.subcommands?.[fullPath[i]];
         }
-        const funcName = currentMeta?.pikkuFuncName;
+        const funcName = currentMeta?.pikkuFuncId;
         // Skip if no function name (could be a command group)
         if (!funcName) {
             // Recursively register subcommands if they exist
@@ -173,7 +173,7 @@ export async function runCLICommand({ program, commandPath, data, singletonServi
         }
         currentCommand = currentCommand.subcommands[commandPath[i]];
     }
-    const funcName = currentCommand.pikkuFuncName;
+    const funcName = currentCommand.pikkuFuncId;
     // Get program-specific data
     const programs = pikkuState(null, 'cli', 'programs') || {};
     const programData = programs[program];
@@ -222,7 +222,7 @@ export async function runCLICommand({ program, commandPath, data, singletonServi
             data: pluckedData,
             channel,
         },
-        session: userSession,
+        ...createMiddlewareSessionWireProps(userSession),
     };
     try {
         const result = await runPikkuFunc('cli', commandId, funcName, {
@@ -236,9 +236,11 @@ export async function runCLICommand({ program, commandPath, data, singletonServi
             wirePermissions: undefined,
             tags: programData?.tags,
             wire,
+            sessionService: userSession,
         });
         // Apply renderer one final time with the final output (if renderer exists)
-        if (renderer) {
+        // Skip if result is undefined (void functions handle their own output)
+        if (renderer && result !== undefined) {
             await Promise.resolve(renderer(singletonServices, result, userSession.get()));
         }
         return result;
@@ -306,7 +308,9 @@ export async function executeCLI({ programName, args, createConfig, createSingle
         // Merge positionals and options into single data object
         const data = { ...parsed.positionals, ...parsed.options };
         // Create config (pass data in case it needs to use any parsed options)
-        const config = await createConfig(new LocalVariablesService(), data);
+        const config = createConfig
+            ? await createConfig(new LocalVariablesService(), data)
+            : {};
         // Create services with config
         const singletonServices = await createSingletonServices(config);
         // Execute the command

package/dist/wirings/cli/cli.types.d.ts

@@ -1,6 +1,6 @@
-import { CorePikkuMiddleware, CoreSingletonServices, CoreUserSession, CoreServices, MiddlewareMetadata, PermissionMetadata } from '../../types/core.types.js';
-import { CorePikkuFunctionConfig, CorePikkuPermission, CorePikkuFunction, CorePikkuFunctionSessionless } from '../../function/functions.types.js';
-import { PikkuChannel } from '../channel/channel.types.js';
+import type { CorePikkuMiddleware, CoreSingletonServices, CoreUserSession, CoreServices, MiddlewareMetadata, PermissionMetadata } from '../../types/core.types.js';
+import type { CorePikkuFunctionConfig, CorePikkuPermission, CorePikkuFunction, CorePikkuFunctionSessionless } from '../../function/functions.types.js';
+import type { PikkuChannel } from '../channel/channel.types.js';
 /**
  * CLI option definition
  */
@@ -51,7 +51,7 @@ export interface CLIProgramState {
  */
 export interface CLICommandMeta {
     parameters?: string;
-    pikkuFuncName: string;
+    pikkuFuncId: string;
     positionals: CLIPositional[];
     options: Record<string, CLIOption>;
     renderName?: string;
@@ -100,7 +100,7 @@ export type CorePikkuCLIRender<Data, Services extends CoreSingletonServices = Co
 /**
  * Extract input parameters from a Pikku function config type
  */
-export type ExtractFunctionInput<Func> = Func extends CorePikkuFunctionConfig<infer FuncType, any, any> ? FuncType extends CorePikkuFunction<infer Input, any, any, any> | CorePikkuFunctionSessionless<infer Input, any, any, any> ? Input : never : never;
+export type ExtractFunctionInput<Func> = Func extends CorePikkuFunctionConfig<infer FuncType, any, any> ? FuncType extends CorePikkuFunction<infer Input, any, any, any, any> | CorePikkuFunctionSessionless<infer Input, any, any, any, any> ? Input : never : never;
 /**
  * Strip < > [ ] characters from a string
  */
@@ -132,7 +132,7 @@ export type ValidateParameters<Params extends string, Input> = AllParamsValid<Ex
 /**
  * Extract output type from a Pikku function config type
  */
-export type ExtractFunctionOutput<Func> = Func extends CorePikkuFunctionConfig<infer FuncType, any, any> ? FuncType extends CorePikkuFunction<any, infer Output, any, any> | CorePikkuFunctionSessionless<any, infer Output, any, any> ? Output : never : never;
+export type ExtractFunctionOutput<Func> = Func extends CorePikkuFunctionConfig<infer FuncType, any, any> ? FuncType extends CorePikkuFunction<any, infer Output, any, any, any> | CorePikkuFunctionSessionless<any, infer Output, any, any, any> ? Output : never : never;
 /**
  * CLI command configuration that infers options from function input type.
  * This is a helper type for creating type-safe CLI commands.
@@ -159,7 +159,7 @@ export type CoreCLICommandConfig<FuncConfig, PikkuMiddleware extends CorePikkuMi
 /**
  * CLI command definition
  */
-export interface CoreCLICommand<In, Out, PikkuFunctionConfig extends CorePikkuFunctionConfig<CorePikkuFunction<In, Out, any, any> | CorePikkuFunctionSessionless<In, Out, any, any>>, PikkuPermission extends CorePikkuPermission<any, any, any>, PikkuMiddleware extends CorePikkuMiddleware, Options = any, Subcommands extends Record<string, CoreCLICommandConfig<any, any, any>> = Record<string, CoreCLICommandConfig<any, any, any>>> {
+export interface CoreCLICommand<In, Out, PikkuFunctionConfig extends CorePikkuFunctionConfig<CorePikkuFunction<In, Out, any, any, any> | CorePikkuFunctionSessionless<In, Out, any, any, any>>, PikkuPermission extends CorePikkuPermission<any, any, any>, PikkuMiddleware extends CorePikkuMiddleware, Options = any, Subcommands extends Record<string, CoreCLICommandConfig<any, any, any>> = Record<string, CoreCLICommandConfig<any, any, any>>> {
     parameters?: string;
     func: PikkuFunctionConfig;
     render?: CorePikkuCLIRender<Out>;
@@ -177,11 +177,11 @@ export interface CoreCLICommand<In, Out, PikkuFunctionConfig extends CorePikkuFu
 /**
  * Shorthand command definition (just a function)
  */
-export type CLICommandShorthand<In, Out, PikkuFunctionConfig extends CorePikkuFunctionConfig<CorePikkuFunction<In, Out, any, any> | CorePikkuFunctionSessionless<In, Out, any, any>>> = PikkuFunctionConfig;
+export type CLICommandShorthand<In, Out, PikkuFunctionConfig extends CorePikkuFunctionConfig<CorePikkuFunction<In, Out, any, any, any> | CorePikkuFunctionSessionless<In, Out, any, any, any>>> = PikkuFunctionConfig;
 /**
  * Command definition (either full or shorthand)
  */
-export type CLICommandDefinition<In, Out, PikkuFunctionConfig extends CorePikkuFunctionConfig<CorePikkuFunction<In, Out, any, any> | CorePikkuFunctionSessionless<In, Out, any, any>>, PikkuPermission extends CorePikkuPermission<any, any, any>, PikkuMiddleware extends CorePikkuMiddleware, Options = any, Subcommands extends Record<string, CoreCLICommandConfig<any, any, any>> = Record<string, CoreCLICommandConfig<any, any, any>>> = CoreCLICommand<In, Out, PikkuFunctionConfig, PikkuPermission, PikkuMiddleware, Options, Subcommands> | CLICommandShorthand<In, Out, PikkuFunctionConfig>;
+export type CLICommandDefinition<In, Out, PikkuFunctionConfig extends CorePikkuFunctionConfig<CorePikkuFunction<In, Out, any, any, any> | CorePikkuFunctionSessionless<In, Out, any, any, any>>, PikkuPermission extends CorePikkuPermission<any, any, any>, PikkuMiddleware extends CorePikkuMiddleware, Options = any, Subcommands extends Record<string, CoreCLICommandConfig<any, any, any>> = Record<string, CoreCLICommandConfig<any, any, any>>> = CoreCLICommand<In, Out, PikkuFunctionConfig, PikkuPermission, PikkuMiddleware, Options, Subcommands> | CLICommandShorthand<In, Out, PikkuFunctionConfig>;
 /**
  * CLI wiring configuration
  */

package/dist/wirings/cli/command-parser.d.ts

@@ -1,4 +1,4 @@
-import { CLIMeta } from './cli.types.js';
+import type { CLIMeta } from './cli.types.js';
 /**
  * Result of parsing CLI arguments
  */

package/dist/wirings/cli/define-cli-commands.d.ts

@@ -0,0 +1,19 @@
+import type { CoreCLICommandConfig } from './cli.types.js';
+/**
+ * Type-safe helper for defining CLI commands that can be composed.
+ * Returns the commands record as-is (identity function) for use with `wireCLI`.
+ *
+ * @example
+ * ```typescript
+ * export const chatCommands = defineCLICommands({
+ *   chat: pikkuCLICommand({ func: chatFunc }),
+ *   'chat:history': pikkuCLICommand({ func: historyFunc }),
+ * })
+ *
+ * wireCLI({
+ *   program: 'my-app',
+ *   commands: { ...chatCommands, other: pikkuCLICommand({ func: otherFunc }) }
+ * })
+ * ```
+ */
+export declare function defineCLICommands<T extends Record<string, CoreCLICommandConfig<any, any, any, any>>>(commands: T): T;