@pikku/core 0.11.1 → 0.12.0

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.js

@@ -4,10 +4,11 @@ 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, }) => {
     let wireServices;
+    let closedWireServices = false;
     let channelHandler;
     const userSession = new PikkuSessionService();
     let http;
@@ -39,10 +40,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 +66,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 +88,7 @@ export const runLocalChannel = async ({ singletonServices, channelId, request, r
                             lifecycleType: 'disconnect',
                             services,
                             channel,
+                            channelMiddlewareMeta: meta.channelMiddleware,
                         });
                     }
                     catch (e) {
@@ -83,9 +96,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 +114,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/log-channels.js

@@ -4,7 +4,7 @@ import { pikkuState } from '../../pikku-state.js';
  * @param logger - A logger for logging information.
  */
 export const logChannels = (logger) => {
-    const channels = pikkuState('channel', 'channels');
+    const channels = pikkuState(null, 'channel', 'channels');
     if (channels.size === 0) {
         logger.info('No channels added');
         return;

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.js

@@ -3,14 +3,14 @@ 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 { PikkuSessionService, createMiddlewareSessionWireProps, } from '../../../services/user-session-service.js';
 import { 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, }) => {
-    const channels = pikkuState('channel', 'channels');
+    const channels = pikkuState(null, 'channel', 'channels');
     const channelConfig = channels.get(channelName);
-    const channelsMeta = pikkuState('channel', 'meta');
+    const channelsMeta = pikkuState(null, 'channel', 'meta');
     const meta = channelsMeta[channelName];
     if (!channelConfig) {
         throw new Error(`Channel not found: ${channelName}`);
@@ -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);
@@ -106,7 +110,10 @@ export const runChannelDisconnect = async ({ singletonServices, ...params }) =>
     });
     const userSession = new PikkuSessionService(params.channelStore, params.channelId);
     userSession.setInitial(session);
-    const wire = { channel, session: userSession };
+    const wire = {
+        channel,
+        ...createMiddlewareSessionWireProps(userSession),
+    };
     if (!wireServices && params.createWireServices) {
         wireServices = await params.createWireServices(singletonServices, wire);
     }
@@ -123,6 +130,7 @@ export const runChannelDisconnect = async ({ singletonServices, ...params }) =>
                 lifecycleType: 'disconnect',
                 services,
                 channel,
+                channelMiddlewareMeta: meta.channelMiddleware,
             });
         }
         catch (e) {
@@ -144,7 +152,10 @@ export const runChannelMessage = async ({ singletonServices, ...params }, data)
     });
     const userSession = new PikkuSessionService(params.channelStore, params.channelId);
     userSession.setInitial(session);
-    const wire = { channel, session: userSession };
+    const wire = {
+        channel,
+        ...createMiddlewareSessionWireProps(userSession),
+    };
     if (params.createWireServices) {
         wireServices = await params.createWireServices(singletonServices, wire);
     }

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

@@ -12,10 +12,11 @@ const defaultJSONRenderer = (_services, data) => {
  */
 export async function executeCLIViaChannel({ programName, pikkuWS, args = process.argv.slice(2), renderers = {}, defaultRenderer, }) {
     // Get CLI metadata from state
-    const allCLIMeta = pikkuState('cli', 'meta');
-    if (!allCLIMeta) {
+    const cliMeta = pikkuState(null, 'cli', 'meta');
+    if (!cliMeta || !('programs' in cliMeta)) {
         throw new Error('[PKU342] CLI metadata not found. No CLI wirings were registered. See https://pikku.dev/docs/pikku-cli/errors/pku342 for more information.');
     }
+    const allCLIMeta = cliMeta;
     const programMeta = allCLIMeta.programs[programName];
     if (!programMeta) {
         console.error(`Error: CLI program "${programName}" not found`);

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

@@ -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';
 /**
@@ -27,12 +27,12 @@ const defaultJSONRenderer = (_services, data) => {
  */
 export const wireCLI = (cli) => {
     // Get the existing metadata that was generated during inspection
-    const cliMeta = pikkuState('cli', 'meta') || {};
+    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('cli', 'programs') || {};
+    const programs = pikkuState(null, 'cli', 'programs') || {};
     programs[cli.program] = {
         defaultRenderer: (cli.render ||
             defaultJSONRenderer),
@@ -40,7 +40,7 @@ export const wireCLI = (cli) => {
         renderers: {},
         tags: cli.tags,
     };
-    pikkuState('cli', 'programs', programs);
+    pikkuState(null, 'cli', 'programs', programs);
     // Register all command functions recursively
     registerCLICommands(cli.commands, [], cli.options || {}, cli.program);
 };
@@ -72,7 +72,7 @@ function unwrapFunc(command) {
  */
 function registerCLICommands(commands, path = [], inheritedOptions = {}, program) {
     // Get the CLI metadata to find actual function names
-    const cliMeta = pikkuState('cli', 'meta').programs[program];
+    const cliMeta = pikkuState(null, 'cli', 'meta').programs[program];
     for (const [name, command] of Object.entries(commands)) {
         const fullPath = [...path, name];
         const commandId = fullPath.join('.');
@@ -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
@@ -96,7 +96,7 @@ function registerCLICommands(commands, path = [], inheritedOptions = {}, program
         const commandOptions = typeof command === 'object' ? command.options || {} : {};
         const mergedOptions = { ...inheritedOptions, ...commandOptions };
         // Store the options and middleware in program state for use during execution
-        const programs = pikkuState('cli', 'programs');
+        const programs = pikkuState(null, 'cli', 'programs');
         if (programs[program]) {
             if (!programs[program].commandOptions) {
                 programs[program].commandOptions = {};
@@ -127,10 +127,10 @@ function registerCLICommands(commands, path = [], inheritedOptions = {}, program
  * Plucks only the data that the function expects based on its schema
  */
 function pluckCLIData(mergedData, funcName, availableOptions) {
-    const funcMeta = pikkuState('function', 'meta')[funcName];
+    const funcMeta = pikkuState(null, 'function', 'meta')[funcName];
     const schemaName = funcMeta?.inputSchemaName;
     const schema = schemaName
-        ? pikkuState('misc', 'schemas').get(schemaName)
+        ? pikkuState(null, 'misc', 'schemas').get(schemaName)
         : null;
     if (schema && schema.properties) {
         // If we have a schema, only include fields that are in the schema
@@ -156,7 +156,7 @@ function pluckCLIData(mergedData, funcName, availableOptions) {
  */
 export async function runCLICommand({ program, commandPath, data, singletonServices, createWireServices, }) {
     // Get the command metadata to find the function name
-    const cliMeta = pikkuState('cli', 'meta');
+    const cliMeta = pikkuState(null, 'cli', 'meta');
     const programMeta = cliMeta.programs?.[program];
     if (!programMeta) {
         throw new NotFoundError(`Program not found: ${program}`);
@@ -173,9 +173,9 @@ 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('cli', 'programs') || {};
+    const programs = pikkuState(null, 'cli', 'programs') || {};
     const programData = programs[program];
     // Combine program middleware + command middleware from the hierarchy
     const allWireMiddleware = [
@@ -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;
@@ -266,7 +268,7 @@ export async function executeCLI({ programName, args, createConfig, createSingle
     }
     try {
         // Get CLI metadata from state
-        const allCLIMeta = pikkuState('cli', 'meta');
+        const allCLIMeta = pikkuState(null, 'cli', 'meta');
         if (!allCLIMeta) {
             throw new Error('[PKU342] CLI metadata not found. No CLI wirings were registered. See https://pikku.dev/docs/pikku-cli/errors/pku342 for more information.');
         }
@@ -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

@@ -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.
@@ -140,6 +140,7 @@ export type ExtractFunctionOutput<Func> = Func extends CorePikkuFunctionConfig<i
 export type CoreCLICommandConfig<FuncConfig, PikkuMiddleware extends CorePikkuMiddleware<any, any> = CorePikkuMiddleware<any, any>, PikkuCLIRender extends CorePikkuCLIRender<any, any, any> = CorePikkuCLIRender<any, any>, Params extends string = string> = {
     parameters?: ValidateParameters<Params, ExtractFunctionInput<FuncConfig>>;
     func?: FuncConfig;
+    title?: string;
     description?: string;
     render?: PikkuCLIRender;
     options?: {
@@ -158,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>;
@@ -176,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/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;

package/dist/wirings/cli/define-cli-commands.js

@@ -0,0 +1,20 @@
+/**
+ * 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 function defineCLICommands(commands) {
+    return commands;
+}

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

@@ -1,5 +1,4 @@
-export * from './cli.types.js';
-export * from './cli-runner.js';
-export * from './command-parser.js';
 export { wireCLI, runCLICommand, pikkuCLIRender, executeCLI, CLIError, } from './cli-runner.js';
 export { parseCLIArguments, generateCommandHelp } from './command-parser.js';
+export { defineCLICommands } from './define-cli-commands.js';
+export type { CLIMeta, CLICommandMeta, CLIProgramMeta, CoreCLI, CoreCLICommandConfig, CorePikkuCLIRender, } from './cli.types.js';

package/dist/wirings/cli/index.js

@@ -1,5 +1,3 @@
-export * from './cli.types.js';
-export * from './cli-runner.js';
-export * from './command-parser.js';
 export { wireCLI, runCLICommand, pikkuCLIRender, executeCLI, CLIError, } from './cli-runner.js';
 export { parseCLIArguments, generateCommandHelp } from './command-parser.js';
+export { defineCLICommands } from './define-cli-commands.js';

package/dist/wirings/http/http-routes.d.ts

@@ -0,0 +1,69 @@
+import type { HTTPRouteMap, HTTPRouteContract, HTTPRoutesGroupConfig, WireHTTPRoutesConfig } from './http.types.js';
+/**
+ * Type-safe helper for defining route contracts that can be composed.
+ * Supports optional group-level config that cascades to all routes.
+ *
+ * @example
+ * ```typescript
+ * // Simple routes without group config
+ * export const todosRoutes = defineHTTPRoutes({
+ *   list: { method: 'get', route: '/todos', func: listTodos },
+ *   get: { method: 'get', route: '/todos/:id', func: getTodo },
+ * })
+ *
+ * // Routes with group-level config
+ * export const todosRoutes = defineHTTPRoutes({
+ *   auth: true,
+ *   tags: ['todos'],
+ *   routes: {
+ *     list: { method: 'get', route: '/todos', func: listTodos },
+ *     get: { method: 'get', route: '/todos/:id', func: getTodo },
+ *   }
+ * })
+ * ```
+ */
+export declare function defineHTTPRoutes<T extends HTTPRouteMap>(routes: T): HTTPRouteContract<T>;
+export declare function defineHTTPRoutes<T extends HTTPRouteMap>(config: HTTPRoutesGroupConfig & {
+    routes: T;
+}): HTTPRouteContract<T>;
+/**
+ * Wires multiple HTTP routes from a nested map or array configuration.
+ * Inspired by ts-rest's contract pattern, provides a single place to wire an entire API.
+ *
+ * @example
+ * ```typescript
+ * // Nested object format
+ * wireHTTPRoutes({
+ *   basePath: '/api/v1',
+ *   tags: ['api'],
+ *   routes: {
+ *     todos: {
+ *       list: { method: 'get', route: '/todos', func: listTodos },
+ *       get: { method: 'get', route: '/todos/:id', func: getTodo },
+ *     },
+ *     auth: {
+ *       login: { method: 'post', route: '/auth/login', func: login, auth: false },
+ *     },
+ *   },
+ * })
+ *
+ * // Flat array format
+ * wireHTTPRoutes({
+ *   basePath: '/api',
+ *   routes: [
+ *     { method: 'get', route: '/todos', func: listTodos },
+ *     { method: 'post', route: '/todos', func: createTodo },
+ *   ],
+ * })
+ *
+ * // Composing route contracts
+ * wireHTTPRoutes({
+ *   basePath: '/api/v1',
+ *   routes: {
+ *     todos: todosRoutes,  // from defineHTTPRoutes()
+ *     auth: authRoutes,    // from defineHTTPRoutes()
+ *   },
+ * })
+ * ```
+ */
+export declare const wireHTTPRoutes: (config: WireHTTPRoutesConfig) => void;