@pikku/core 0.9.11 → 0.9.12-next.0

package/dist/pikku-state.js

@@ -10,7 +10,6 @@ export const resetPikkuState = () => {
         },
         http: {
             permissions: new Map(),
-            middleware: new Map(),
             routes: new Map(),
             meta: {},
         },
@@ -34,6 +33,16 @@ export const resetPikkuState = () => {
             prompts: new Map(),
             promptsMeta: {},
         },
+        cli: {
+            meta: {},
+            programs: {},
+        },
+        middleware: {
+            tagGroup: {},
+            httpGroup: {},
+            tagGroupMeta: {},
+            httpGroupMeta: {},
+        },
         misc: {
             errors: globalThis.pikkuState?.misc?.errors || new Map(),
             schemas: new Map(),

package/dist/services/content-service.d.ts

@@ -1,4 +1,3 @@
-import { ReadStream } from 'fs';
 export interface ContentService {
     /**
      * Signs a content key to generate a secure, time-limited access URL.
@@ -36,7 +35,7 @@ export interface ContentService {
      * @param stream - A readable stream of the file contents.
      * @returns A boolean indicating success.
      */
-    writeFile(assetKey: string, stream: ReadStream): Promise<boolean>;
+    writeFile(assetKey: string, stream: ReadableStream | NodeJS.ReadableStream): Promise<boolean>;
     /**
      * Copies a file from a local absolute path into storage under a new asset key.
      * @param assetKey - The destination key.
@@ -49,5 +48,5 @@ export interface ContentService {
      * @param assetKey - The key of the file to read.
      * @returns A readable file stream.
      */
-    readFile(assetKey: string): Promise<ReadStream>;
+    readFile(assetKey: string): Promise<ReadableStream | NodeJS.ReadableStream>;
 }

package/dist/services/index.d.ts

@@ -11,4 +11,3 @@ export * from './user-session-service.js';
 export * from './local-secrets.js';
 export * from './local-variables.js';
 export * from './logger-console.js';
-export * from './local-content.js';

package/dist/services/index.js

@@ -13,4 +13,3 @@ export * from './user-session-service.js';
 export * from './local-secrets.js';
 export * from './local-variables.js';
 export * from './logger-console.js';
-export * from './local-content.js';

package/dist/services/local-content.d.ts

@@ -1,6 +1,4 @@
-import { ReadStream } from 'fs';
 import { ContentService, Logger } from '@pikku/core/services';
-import { Readable } from 'stream';
 export interface LocalContentConfig {
     localFileUploadPath: string;
     uploadUrlPrefix: string;
@@ -19,9 +17,9 @@ export declare class LocalContent implements ContentService {
         uploadUrl: string;
         assetKey: string;
     }>;
-    writeFile(assetKey: string, stream: Readable): Promise<boolean>;
+    writeFile(assetKey: string, stream: ReadableStream | NodeJS.ReadableStream): Promise<boolean>;
     copyFile(assetKey: string, fromAbsolutePath: string): Promise<boolean>;
-    readFile(assetKey: string): Promise<ReadStream>;
+    readFile(assetKey: string): Promise<ReadableStream | NodeJS.ReadableStream>;
     deleteFile(assetKey: string): Promise<boolean>;
     private createDirectoryForFile;
 }

package/dist/types/core.types.d.ts

@@ -8,18 +8,37 @@ import { PikkuRPC } from '../wirings/rpc/rpc-types.js';
 import { PikkuMCP } from '../wirings/mcp/mcp.types.js';
 import { PikkuScheduledTask } from '../wirings/scheduler/scheduler.types.js';
 import { PikkuQueue } from '../wirings/queue/queue.types.js';
+import { PikkuCLI } from '../wirings/cli/cli.types.js';
 export declare enum PikkuWiringTypes {
     http = "http",
     scheduler = "scheduler",
     channel = "channel",
     rpc = "rpc",
     queue = "queue",
-    mcp = "mcp"
+    mcp = "mcp",
+    cli = "cli"
 }
 export interface FunctionServicesMeta {
     optimized: boolean;
     services: string[];
 }
+/**
+ * Metadata for middleware at any level
+ * - type: 'http' = HTTP route middleware group (references httpGroup in pikkuState)
+ * - type: 'tag' = Tag-based middleware group (references tagGroup in pikkuState)
+ * - type: 'wire' = Wire-level individual middleware
+ */
+export type MiddlewareMetadata = {
+    type: 'http';
+    route: string;
+} | {
+    type: 'tag';
+    tag: string;
+} | {
+    type: 'wire';
+    name: string;
+    inline?: boolean;
+};
 export type FunctionRuntimeMeta = {
     pikkuFuncName: string;
     inputSchemaName: string | null;
@@ -34,6 +53,7 @@ export type FunctionMeta = FunctionRuntimeMeta & Partial<{
     tags: string[];
     docs: PikkuDocs;
     isDirectFunction: boolean;
+    middleware: MiddlewareMetadata[];
 }>;
 export type FunctionsRuntimeMeta = Record<string, FunctionRuntimeMeta>;
 export type FunctionsMeta = Record<string, FunctionMeta>;
@@ -99,6 +119,7 @@ export type PikkuInteraction<In = unknown, Out = unknown> = Partial<{
     channel: PikkuChannel<unknown, Out>;
     scheduledTask: PikkuScheduledTask;
     queue: PikkuQueue;
+    cli: PikkuCLI;
 }>;
 /**
  * A function that can wrap an interaction and be called before or after
@@ -106,10 +127,38 @@ export type PikkuInteraction<In = unknown, Out = unknown> = Partial<{
 export type CorePikkuMiddleware<SingletonServices extends CoreSingletonServices = CoreSingletonServices, UserSession extends CoreUserSession = CoreUserSession> = (services: SingletonServices & {
     userSession: UserSessionService<UserSession>;
 }, interactions: PikkuInteraction, next: () => Promise<void>) => Promise<void>;
+/**
+ * A factory function that takes input and returns middleware
+ * Used when middleware needs configuration/input parameters
+ */
+export type CorePikkuMiddlewareFactory<In = any, SingletonServices extends CoreSingletonServices = CoreSingletonServices, UserSession extends CoreUserSession = CoreUserSession> = (input: In) => CorePikkuMiddleware<SingletonServices, UserSession>;
+/**
+ * A group of middleware (combination of regular middleware and factories)
+ * Used with addMiddleware() and addHTTPMiddleware() to group related middleware together
+ */
+export type CorePikkuMiddlewareGroup<SingletonServices extends CoreSingletonServices = CoreSingletonServices, UserSession extends CoreUserSession = CoreUserSession> = Array<CorePikkuMiddleware<SingletonServices, UserSession> | CorePikkuMiddlewareFactory<any, SingletonServices, UserSession>>;
 /**
  * Factory function for creating middleware with tree-shaking support
  */
 export declare const pikkuMiddleware: <SingletonServices extends CoreSingletonServices = CoreSingletonServices, UserSession extends CoreUserSession = CoreUserSession>(middleware: CorePikkuMiddleware<SingletonServices, UserSession>) => CorePikkuMiddleware<SingletonServices, UserSession>;
+/**
+ * Factory function for creating middleware factories
+ * Use this when your middleware needs configuration/input parameters
+ *
+ * @example
+ * ```typescript
+ * export const logMiddleware = pikkuMiddlewareFactory<LogOptions>(({
+ *   message,
+ *   level = 'info'
+ * }) => {
+ *   return pikkuMiddleware(async ({ logger }, _interaction, next) => {
+ *     logger[level](message)
+ *     await next()
+ *   })
+ * })
+ * ```
+ */
+export declare const pikkuMiddlewareFactory: <In = any>(factory: CorePikkuMiddlewareFactory<In>) => CorePikkuMiddlewareFactory<In>;
 /**
  * Represents the core services used by Pikku, including singleton services and the request/response interaction.
  */
@@ -128,7 +177,7 @@ export type CreateSessionServices<SingletonServices extends CoreSingletonService
 /**
  * Defines a function type for creating config.
  */
-export type CreateConfig<Config extends CoreConfig> = (variables?: VariablesService) => Promise<Config>;
+export type CreateConfig<Config extends CoreConfig, RemainingArgs extends any[] = unknown[]> = (variables?: VariablesService, ...args: RemainingArgs) => Promise<Config>;
 /**
  * Represents the documentation for a route, including summary, description, tags, and errors.
  */

package/dist/types/core.types.js

@@ -6,6 +6,7 @@ export var PikkuWiringTypes;
     PikkuWiringTypes["rpc"] = "rpc";
     PikkuWiringTypes["queue"] = "queue";
     PikkuWiringTypes["mcp"] = "mcp";
+    PikkuWiringTypes["cli"] = "cli";
 })(PikkuWiringTypes || (PikkuWiringTypes = {}));
 /**
  * Factory function for creating middleware with tree-shaking support
@@ -13,3 +14,23 @@ export var PikkuWiringTypes;
 export const pikkuMiddleware = (middleware) => {
     return middleware;
 };
+/**
+ * Factory function for creating middleware factories
+ * Use this when your middleware needs configuration/input parameters
+ *
+ * @example
+ * ```typescript
+ * export const logMiddleware = pikkuMiddlewareFactory<LogOptions>(({
+ *   message,
+ *   level = 'info'
+ * }) => {
+ *   return pikkuMiddleware(async ({ logger }, _interaction, next) => {
+ *     logger[level](message)
+ *     await next()
+ *   })
+ * })
+ * ```
+ */
+export const pikkuMiddlewareFactory = (factory) => {
+    return factory;
+};

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

@@ -1,3 +1,3 @@
-import { CoreServices, CoreUserSession } from '../../types/core.types.js';
+import { CoreServices } from '../../types/core.types.js';
 import { CoreChannel, PikkuChannelHandler } from './channel.types.js';
-export declare const processMessageHandlers: (services: CoreServices, session: CoreUserSession | undefined, channelConfig: CoreChannel<any, any>, channelHandler: PikkuChannelHandler) => (rawData: any) => Promise<unknown>;
+export declare const processMessageHandlers: (services: CoreServices, channelConfig: CoreChannel<any, any>, channelHandler: PikkuChannelHandler) => (rawData: any) => Promise<unknown>;

package/dist/wirings/channel/channel-handler.js

@@ -32,10 +32,10 @@ const validateAuth = (requiresSession, session, onMessage) => {
     }
     return true;
 };
-export const processMessageHandlers = (services, session, channelConfig, channelHandler) => {
+export const processMessageHandlers = (services, channelConfig, channelHandler) => {
     const logger = services.logger;
     const requiresSession = channelConfig.auth !== false;
-    const processMessage = async (data, onMessage, session, routingProperty, routerValue) => {
+    const processMessage = async (data, onMessage, routingProperty, routerValue) => {
         if (!validateAuth(requiresSession, channelHandler, onMessage)) {
             const routeMessage = routingProperty
                 ? `route '${routingProperty}:${routerValue}'`
@@ -45,19 +45,22 @@ export const processMessageHandlers = (services, session, channelConfig, channel
             channelHandler.getChannel().send(`Unauthorized for ${routeMessage}`);
             return;
         }
-        const { pikkuFuncName } = getRouteMeta(channelConfig.name, routingProperty, routerValue);
+        const { pikkuFuncName, middleware: inheritedMiddleware } = getRouteMeta(channelConfig.name, routingProperty, routerValue);
         const permissions = typeof onMessage === 'function' ? {} : onMessage.permissions;
         const middleware = typeof onMessage === 'function' ? [] : onMessage.middleware;
         return await runPikkuFunc(PikkuWiringTypes.channel, channelConfig.name, pikkuFuncName, {
+            singletonServices: services,
             getAllServices: () => ({
                 ...services,
                 channel: channelHandler.getChannel(),
             }),
-            data,
-            session,
+            data: () => data,
+            userSession: services.userSession,
             permissions,
-            middleware,
+            inheritedMiddleware,
+            wireMiddleware: middleware,
             tags: channelConfig.tags,
+            interaction: { channel: channelHandler.getChannel() },
         });
     };
     const onMessage = async (rawData) => {
@@ -72,14 +75,14 @@ export const processMessageHandlers = (services, session, channelConfig, channel
                     const routerValue = messageData[routingProperty];
                     if (routerValue && routes[routerValue]) {
                         processed = true;
-                        result = await processMessage(messageData, routes[routerValue], session, routingProperty, routerValue);
+                        result = await processMessage(messageData, routes[routerValue], routingProperty, routerValue);
                         break;
                     }
                 }
                 // Default handler if no routes matched but json data was parsed
                 if (!processed && channelConfig.onMessage) {
                     processed = true;
-                    result = await processMessage(messageData, channelConfig.onMessage, session);
+                    result = await processMessage(messageData, channelConfig.onMessage);
                 }
             }
             catch (error) {
@@ -89,7 +92,7 @@ export const processMessageHandlers = (services, session, channelConfig, channel
         // Default handler if no routes matched and json data wasn't parsed
         if (!processed && channelConfig.onMessage) {
             processed = true;
-            result = await processMessage(rawData, channelConfig.onMessage, session);
+            result = await processMessage(rawData, channelConfig.onMessage);
         }
         if (!processed) {
             logger.error(`No handler found for message in channel ${channelConfig.name} for ${JSON.stringify(rawData)}`);

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

@@ -1,5 +1,4 @@
 import { UserSessionService } from '../../services/user-session-service.js';
-import { CorePikkuMiddleware } from '../../types/core.types.js';
 import { ChannelMeta, CoreChannel, RunChannelOptions, RunChannelParams } from './channel.types.js';
 /**
  * Adds a channel and registers all functions referenced in it using the
@@ -12,5 +11,4 @@ export declare const openChannel: ({ route, singletonServices, coerceDataFromSch
     openingData: unknown;
     channelConfig: CoreChannel<unknown, any>;
     meta: ChannelMeta;
-    httpMiddleware: CorePikkuMiddleware[] | undefined;
 }>;

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

@@ -85,7 +85,6 @@ const getMatchingChannelConfig = (request) => {
         channelConfig,
         schemaName: channelMeta.input,
         meta: channelMeta,
-        httpMiddleware: matchedPath.middleware,
     };
 };
 export const openChannel = async ({ route, singletonServices, coerceDataFromSchema = true, request, }) => {
@@ -94,7 +93,7 @@ export const openChannel = async ({ route, singletonServices, coerceDataFromSche
         singletonServices.logger.info(`Channel not found: ${route}`);
         throw new NotFoundError(`Channel not found: ${route}`);
     }
-    const { params, channelConfig, schemaName, meta, httpMiddleware } = matchingChannel;
+    const { params, channelConfig, schemaName, meta } = matchingChannel;
     const requiresSession = channelConfig.auth !== false;
     request?.setParams(params);
     singletonServices.logger.info(`Matched channel: ${channelConfig.name} | route: ${channelConfig.route} | auth: ${requiresSession.toString()}`);
@@ -106,5 +105,5 @@ export const openChannel = async ({ route, singletonServices, coerceDataFromSche
         }
         await validateSchema(singletonServices.logger, singletonServices.schema, schemaName, openingData);
     }
-    return { openingData, channelConfig, meta, httpMiddleware };
+    return { openingData, channelConfig, meta };
 };

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

@@ -1,6 +1,6 @@
 import { PikkuError } from '../../errors/error-handler.js';
 import { HTTPFunctionMetaInputTypes, PikkuHTTPRequest, PikkuHTTPResponse } from '../http/http.types.js';
-import { PikkuDocs, CoreSingletonServices, CreateSessionServices, CorePikkuMiddleware } from '../../types/core.types.js';
+import { PikkuDocs, CoreSingletonServices, CreateSessionServices, CorePikkuMiddleware, MiddlewareMetadata } from '../../types/core.types.js';
 import { CorePikkuFunction, CorePikkuFunctionSessionless, CorePikkuPermission } from '../../function/functions.types.js';
 export type RunChannelOptions = Partial<{
     skipUserSession: boolean;
@@ -19,6 +19,7 @@ export type RunChannelParams<ChannelData> = {
 export interface ChannelMessageMeta {
     pikkuFuncName: string;
     docs?: PikkuDocs;
+    middleware?: MiddlewareMetadata[];
 }
 export interface ChannelMeta {
     name: string;
@@ -33,9 +34,10 @@ export interface ChannelMeta {
     messageWirings: Record<string, Record<string, ChannelMessageMeta>>;
     docs?: PikkuDocs;
     tags?: string[];
+    middleware?: MiddlewareMetadata[];
 }
 export type ChannelsMeta = Record<string, ChannelMeta>;
-export type CoreChannel<ChannelData, Channel extends string, ChannelConnect = CorePikkuFunction<void, unknown, ChannelData> | CorePikkuFunctionSessionless<void, unknown, ChannelData>, ChannelDisconnect = CorePikkuFunction<void, void, ChannelData> | CorePikkuFunctionSessionless<void, void, ChannelData>, ChannelFunctionMessage = CorePikkuFunction<unknown, unknown, ChannelData> | CorePikkuFunctionSessionless<unknown, unknown, ChannelData>, PikkuPermission = CorePikkuPermission<ChannelData>> = {
+export type CoreChannel<ChannelData, Channel extends string, ChannelConnect = CorePikkuFunction<void, unknown, ChannelData> | CorePikkuFunctionSessionless<void, unknown, ChannelData>, ChannelDisconnect = CorePikkuFunction<void, void, ChannelData> | CorePikkuFunctionSessionless<void, void, ChannelData>, ChannelFunctionMessage = CorePikkuFunction<unknown, unknown, ChannelData> | CorePikkuFunctionSessionless<unknown, unknown, ChannelData>, PikkuPermission = CorePikkuPermission<ChannelData>, PikkuMiddleware = CorePikkuMiddleware> = {
     name: string;
     route: Channel;
     onConnect?: ChannelConnect;
@@ -50,7 +52,7 @@ export type CoreChannel<ChannelData, Channel extends string, ChannelConnect = Co
         permissions?: Record<string, PikkuPermission[] | PikkuPermission>;
         auth?: boolean;
     }>>;
-    middleware?: CorePikkuMiddleware[];
+    middleware?: PikkuMiddleware[];
     permissions?: Record<string, PikkuPermission[] | PikkuPermission>;
     auth?: boolean;
     docs?: Partial<{

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

@@ -3,7 +3,7 @@ import { createHTTPInteraction } from '../../http/http-runner.js';
 import { closeSessionServices } from '../../../utils.js';
 import { processMessageHandlers } from '../channel-handler.js';
 import { PikkuLocalChannelHandler } from './local-channel-handler.js';
-import { PikkuWiringTypes } from '../../../types/core.types.js';
+import { PikkuWiringTypes, } from '../../../types/core.types.js';
 import { handleHTTPError } from '../../../handle-error.js';
 import { combineMiddleware, runMiddleware } from '../../../middleware-runner.js';
 import { PikkuUserSessionService } from '../../../services/user-session-service.js';
@@ -18,10 +18,10 @@ export const runLocalChannel = async ({ singletonServices, channelId, request, r
         http = createHTTPInteraction(request, response);
         route = http?.request?.path();
     }
-    let openingData, channelConfig, meta, httpMiddleware;
+    let openingData, channelConfig, meta;
     try {
         ;
-        ({ openingData, channelConfig, meta, httpMiddleware } = await openChannel({
+        ({ openingData, channelConfig, meta } = await openChannel({
             channelId,
             createSessionServices,
             respondWith404,
@@ -46,25 +46,26 @@ export const runLocalChannel = async ({ singletonServices, channelId, request, r
             if (createSessionServices) {
                 sessionServices = await createSessionServices(singletonServices, { http, channel }, session);
             }
-            const allServices = rpcService.injectRPCService({
+            const getAllServices = (channel, requiresAuth) => rpcService.injectRPCService({
                 ...singletonServices,
                 ...sessionServices,
-                userSession: userSession,
-            });
+                userSession,
+            }, interaction, requiresAuth);
+            const interaction = { channel };
             channelHandler.registerOnOpen(() => {
                 if (channelConfig.onConnect && meta.connect) {
-                    runPikkuFuncDirectly(meta.connect.pikkuFuncName, { ...allServices, channel }, openingData);
+                    runPikkuFuncDirectly(meta.connect.pikkuFuncName, getAllServices(channel, false), openingData);
                 }
             });
             channelHandler.registerOnClose(async () => {
                 if (channelConfig.onDisconnect && meta.disconnect) {
-                    runPikkuFuncDirectly(meta.disconnect.pikkuFuncName, { ...allServices, channel }, openingData);
+                    runPikkuFuncDirectly(meta.disconnect.pikkuFuncName, getAllServices(channel, false), openingData);
                 }
                 if (sessionServices) {
                     await closeSessionServices(singletonServices.logger, sessionServices);
                 }
             });
-            channelHandler.registerOnMessage(processMessageHandlers(allServices, session, channelConfig, channelHandler));
+            channelHandler.registerOnMessage(processMessageHandlers(getAllServices(channel), channelConfig, channelHandler));
         }
         catch (e) {
             handleHTTPError(e, http, channelId, singletonServices.logger, logWarningsForStatusCodes, respondWith404, bubbleErrors);
@@ -79,9 +80,8 @@ export const runLocalChannel = async ({ singletonServices, channelId, request, r
         ...singletonServices,
         userSession,
     }, { http }, combineMiddleware(PikkuWiringTypes.channel, channelConfig.name, {
-        wiringMiddleware: channelConfig.middleware,
-        wiringTags: channelConfig.tags,
-        httpMiddleware,
+        wireInheritedMiddleware: meta.middleware,
+        wireMiddleware: channelConfig.middleware,
     }), main);
     return channelHandler;
 };

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

@@ -35,7 +35,7 @@ export const runChannelConnect = async ({ singletonServices, channelId, channelO
         http = createHTTPInteraction(new PikkuFetchHTTPRequest(request), response);
     }
     const userSession = new PikkuUserSessionService(channelStore, channelId);
-    const { channelConfig, openingData, meta, httpMiddleware } = await openChannel({
+    const { channelConfig, openingData, meta } = await openChannel({
         channelId,
         createSessionServices,
         request,
@@ -78,9 +78,8 @@ export const runChannelConnect = async ({ singletonServices, channelId, channelO
         ...singletonServices,
         userSession,
     }, { http }, combineMiddleware(PikkuWiringTypes.channel, channelConfig.name, {
-        wiringMiddleware: channelConfig.middleware,
-        wiringTags: channelConfig.tags,
-        httpMiddleware,
+        wireInheritedMiddleware: meta.middleware,
+        wireMiddleware: channelConfig.middleware,
     }), main);
 };
 export const runChannelDisconnect = async ({ singletonServices, ...params }) => {
@@ -92,7 +91,7 @@ export const runChannelDisconnect = async ({ singletonServices, ...params }) =>
         channelName,
     });
     if (!sessionServices && params.createSessionServices) {
-        sessionServices = await params.createSessionServices(singletonServices, {}, session);
+        sessionServices = await params.createSessionServices(singletonServices, { channel }, session);
     }
     if (channelConfig.onDisconnect && meta.disconnect) {
         await runPikkuFuncDirectly(meta.disconnect.pikkuFuncName, { ...singletonServices, ...sessionServices, channel }, undefined);
@@ -105,17 +104,17 @@ export const runChannelDisconnect = async ({ singletonServices, ...params }) =>
 export const runChannelMessage = async ({ singletonServices, ...params }, data) => {
     let sessionServices;
     const { openingData, channelName, session } = await params.channelStore.getChannelAndSession(params.channelId);
-    const { channelHandler, channelConfig } = getVariablesForChannel({
+    const { channel, channelHandler, channelConfig } = getVariablesForChannel({
         ...params,
         openingData,
         channelName,
     });
     if (params.createSessionServices) {
-        sessionServices = await params.createSessionServices(singletonServices, {}, session);
+        sessionServices = await params.createSessionServices(singletonServices, { channel }, session);
     }
     let response;
     try {
-        const onMessage = processMessageHandlers({ ...singletonServices, ...sessionServices }, session, channelConfig, channelHandler);
+        const onMessage = processMessageHandlers({ ...singletonServices, ...sessionServices }, channelConfig, channelHandler);
         response = await onMessage(data);
     }
     finally {

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

@@ -0,0 +1,12 @@
+import { CorePikkuCLIRender } from '../cli.types.js';
+/**
+ * Execute a CLI program via WebSocket channel
+ * This is the main entry point for CLI-over-Channel clients
+ */
+export declare function executeCLIViaChannel({ programName, pikkuWS, args, renderers, defaultRenderer, }: {
+    programName: string;
+    pikkuWS: any;
+    args?: string[];
+    renderers?: Record<string, CorePikkuCLIRender<any>>;
+    defaultRenderer?: CorePikkuCLIRender<any>;
+}): Promise<void>;

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

@@ -0,0 +1,80 @@
+import { pikkuState } from '../../../pikku-state.js';
+import { generateCommandHelp, parseCLIArguments } from '../command-parser.js';
+/**
+ * Default JSON renderer for CLI output
+ */
+const defaultJSONRenderer = (_services, data) => {
+    console.log(JSON.stringify(data, null, 2));
+};
+/**
+ * Execute a CLI program via WebSocket channel
+ * This is the main entry point for CLI-over-Channel clients
+ */
+export async function executeCLIViaChannel({ programName, pikkuWS, args = process.argv.slice(2), renderers = {}, defaultRenderer, }) {
+    // Get CLI metadata from state
+    const allCLIMeta = pikkuState('cli', 'meta') || {};
+    const programMeta = allCLIMeta[programName];
+    if (!programMeta) {
+        console.error(`Error: CLI program "${programName}" not found`);
+        process.exit(1);
+    }
+    // Parse arguments for this specific program
+    const parsed = parseCLIArguments(args, programName, allCLIMeta);
+    // Handle help (check after parsing to support subcommand help)
+    if (args.includes('--help') || args.includes('-h') || args.length === 0) {
+        const helpText = generateCommandHelp(programName, allCLIMeta, parsed.commandPath);
+        console.log(helpText);
+        return;
+    }
+    if (parsed.errors.length > 0) {
+        // Check if any error is about an unknown command
+        const hasUnknownCommand = parsed.errors.some((error) => error.startsWith('Unknown command:') ||
+            error.startsWith('Command not found:'));
+        if (hasUnknownCommand) {
+            // Show help instead of error for unknown commands
+            const helpText = generateCommandHelp(programName, allCLIMeta, parsed.commandPath);
+            console.log(helpText);
+            process.exit(1);
+        }
+        else {
+            // Show errors for other types of errors
+            console.error('Errors:');
+            parsed.errors.forEach((error) => console.error(`  ${error}`));
+            process.exit(1);
+        }
+    }
+    // Merge positionals and options into single data object
+    const data = { ...parsed.positionals, ...parsed.options };
+    // Get the renderer for this command
+    const commandId = parsed.commandPath.join('.');
+    const renderer = renderers[commandId] || defaultRenderer || defaultJSONRenderer;
+    return new Promise((resolve, reject) => {
+        // Subscribe to responses for this command
+        const commandRoute = pikkuWS.getRoute('command');
+        const responseHandler = (response) => {
+            // Call renderer for any output
+            renderer(null, response, undefined);
+        };
+        commandRoute.subscribe(commandId, responseHandler);
+        // Handle connection close
+        pikkuWS.ws.addEventListener('close', () => {
+            commandRoute.unsubscribe(commandId, responseHandler);
+            resolve(undefined);
+        });
+        pikkuWS.ws.addEventListener('error', (error) => {
+            commandRoute.unsubscribe(commandId, responseHandler);
+            reject(error);
+        });
+        // Send the command once connected
+        if (pikkuWS.ws.readyState === 1) {
+            // Already open
+            commandRoute.send(commandId, data);
+        }
+        else {
+            // Wait for open
+            pikkuWS.ws.addEventListener('open', () => {
+                commandRoute.send(commandId, data);
+            });
+        }
+    });
+}

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

@@ -0,0 +1 @@
+export * from './cli-channel-runner.js';

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

@@ -0,0 +1 @@
+export * from './cli-channel-runner.js';

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

@@ -0,0 +1,32 @@
+import { CorePikkuMiddleware, CoreUserSession } from '../../types/core.types.js';
+import { CoreCLI, CorePikkuCLIRender, CoreCLICommandConfig } from './cli.types.js';
+import type { CoreSingletonServices, CoreServices, CreateSessionServices, CreateConfig, CreateSingletonServices } from '../../types/core.types.js';
+/**
+ * Registers a CLI command tree and all its functions
+ */
+export declare const wireCLI: <Commands extends Record<string, CoreCLICommandConfig<any, any, any>>, GlobalOptions, PikkuMiddleware extends CorePikkuMiddleware, GlobalOutput>(cli: CoreCLI<Commands, GlobalOptions, PikkuMiddleware, GlobalOutput>) => void;
+/**
+ * Executes a CLI command for a specific program
+ */
+export declare function runCLICommand({ program, commandPath, data, singletonServices, createSessionServices, }: {
+    program: string;
+    commandPath: string[];
+    data: Record<string, any>;
+    singletonServices: CoreSingletonServices;
+    createSessionServices?: CreateSessionServices;
+}): Promise<any>;
+/**
+ * Factory function for CLI-specific renderers
+ */
+export declare const pikkuCLIRender: <Data, Services extends CoreSingletonServices = CoreServices, Session extends CoreUserSession = CoreUserSession>(renderer: (services: Services, data: Data, session?: Session) => void | Promise<void>) => CorePikkuCLIRender<Data, Services, Session>;
+/**
+ * Execute a CLI program with the given arguments
+ * This is the main entry point for CLI programs
+ */
+export declare function executeCLI({ programName, args, createConfig, createSingletonServices, createSessionServices, }: {
+    programName: string;
+    args?: string[];
+    createConfig: CreateConfig<any, any>;
+    createSingletonServices: CreateSingletonServices<any, any>;
+    createSessionServices?: CreateSessionServices<any, any>;
+}): Promise<void>;