@pikku/core 0.9.12-next.0 → 0.10.1

package/dist/pikku-state.d.ts

@@ -6,7 +6,7 @@ import { ErrorDetails, PikkuError } from './errors/error-handler.js';
 import { CorePermissionGroup, CorePikkuFunctionConfig, CorePikkuPermission } from './function/functions.types.js';
 import { queueWorkersMeta, CoreQueueWorker } from './wirings/queue/queue.types.js';
 import { CoreMCPResource, CoreMCPTool, CoreMCPPrompt, MCPResourceMeta, MCPToolMeta, MCPPromptMeta } from './wirings/mcp/mcp.types.js';
-import { CLIProgramMeta, CLIProgramState } from './wirings/cli/cli.types.js';
+import { CLIMeta, CLIProgramState } from './wirings/cli/cli.types.js';
 interface PikkuState {
     function: {
         meta: FunctionsMeta;
@@ -46,7 +46,7 @@ interface PikkuState {
         promptsMeta: MCPPromptMeta;
     };
     cli: {
-        meta: Record<string, CLIProgramMeta>;
+        meta: CLIMeta | Record<string, any>;
         programs: Record<string, CLIProgramState>;
     };
     middleware: {
@@ -69,6 +69,26 @@ interface PikkuState {
             isFactory: boolean;
         }>;
     };
+    permissions: {
+        tagGroup: Record<string, CorePermissionGroup | CorePikkuPermission[]>;
+        httpGroup: Record<string, CorePermissionGroup | CorePikkuPermission[]>;
+        tagGroupMeta: Record<string, {
+            exportName: string | null;
+            sourceFile: string;
+            position: number;
+            services: FunctionServicesMeta;
+            permissionCount: number;
+            isFactory: boolean;
+        }>;
+        httpGroupMeta: Record<string, {
+            exportName: string | null;
+            sourceFile: string;
+            position: number;
+            services: FunctionServicesMeta;
+            permissionCount: number;
+            isFactory: boolean;
+        }>;
+    };
     misc: {
         errors: Map<PikkuError, ErrorDetails>;
         schemas: Map<string, any>;

package/dist/pikku-state.js

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

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

@@ -1,6 +1,7 @@
 import type { Logger, LogLevel } from '../services/logger.js';
 import { VariablesService } from '../services/variables-service.js';
 import { SchemaService } from '../services/schema-service.js';
+import { JWTService } from '../services/jwt-service.js';
 import { PikkuHTTP } from '../wirings/http/http.types.js';
 import { UserSessionService } from '../services/user-session-service.js';
 import { PikkuChannel } from '../wirings/channel/channel.types.js';
@@ -39,6 +40,23 @@ export type MiddlewareMetadata = {
     name: string;
     inline?: boolean;
 };
+/**
+ * Metadata for permissions at any level
+ * - type: 'http' = HTTP route permission group (references httpGroup in pikkuState)
+ * - type: 'tag' = Tag-based permission group (references tagGroup in pikkuState)
+ * - type: 'wire' = Wire-level individual permission
+ */
+export type PermissionMetadata = {
+    type: 'http';
+    route: string;
+} | {
+    type: 'tag';
+    tag: string;
+} | {
+    type: 'wire';
+    name: string;
+    inline?: boolean;
+};
 export type FunctionRuntimeMeta = {
     pikkuFuncName: string;
     inputSchemaName: string | null;
@@ -54,6 +72,7 @@ export type FunctionMeta = FunctionRuntimeMeta & Partial<{
     docs: PikkuDocs;
     isDirectFunction: boolean;
     middleware: MiddlewareMetadata[];
+    permissions: PermissionMetadata[];
 }>;
 export type FunctionsRuntimeMeta = Record<string, FunctionRuntimeMeta>;
 export type FunctionsMeta = Record<string, FunctionMeta>;
@@ -102,6 +121,8 @@ export interface CoreUserSession {
 export interface CoreSingletonServices<Config extends CoreConfig = CoreConfig> {
     /** The schema library used to validate data */
     schema?: SchemaService;
+    /** The JWT service used to encode and decode tokens */
+    jwt?: JWTService;
     /** The core configuration for the application. */
     config: Config;
     /** The logger used by the application. */
@@ -127,6 +148,20 @@ 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>;
+/**
+ * Configuration object for creating middleware with metadata
+ *
+ * @template SingletonServices - The singleton services type
+ * @template UserSession - The user session type
+ */
+export type CorePikkuMiddlewareConfig<SingletonServices extends CoreSingletonServices = CoreSingletonServices, UserSession extends CoreUserSession = CoreUserSession> = {
+    /** The middleware function */
+    func: CorePikkuMiddleware<SingletonServices, UserSession>;
+    /** Optional human-readable name for the middleware */
+    name?: string;
+    /** Optional description of what the middleware does */
+    description?: string;
+};
 /**
  * A factory function that takes input and returns middleware
  * Used when middleware needs configuration/input parameters
@@ -139,8 +174,30 @@ export type CorePikkuMiddlewareFactory<In = any, SingletonServices extends CoreS
 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
+ * Supports both direct function and configuration object syntax
+ *
+ * @example
+ * ```typescript
+ * // Direct function syntax
+ * export const logMiddleware = pikkuMiddleware(
+ *   async ({ logger }, _interaction, next) => {
+ *     logger.info('Request started')
+ *     await next()
+ *   }
+ * )
+ *
+ * // Configuration object syntax with metadata
+ * export const logMiddleware = pikkuMiddleware({
+ *   name: 'Request Logger',
+ *   description: 'Logs request information',
+ *   func: async ({ logger }, _interaction, next) => {
+ *     logger.info('Request started')
+ *     await next()
+ *   }
+ * })
+ * ```
  */
-export declare const pikkuMiddleware: <SingletonServices extends CoreSingletonServices = CoreSingletonServices, UserSession extends CoreUserSession = CoreUserSession>(middleware: CorePikkuMiddleware<SingletonServices, UserSession>) => CorePikkuMiddleware<SingletonServices, UserSession>;
+export declare const pikkuMiddleware: <SingletonServices extends CoreSingletonServices = CoreSingletonServices, UserSession extends CoreUserSession = CoreUserSession>(middleware: CorePikkuMiddleware<SingletonServices, UserSession> | CorePikkuMiddlewareConfig<SingletonServices, UserSession>) => CorePikkuMiddleware<SingletonServices, UserSession>;
 /**
  * Factory function for creating middleware factories
  * Use this when your middleware needs configuration/input parameters

package/dist/types/core.types.js

@@ -10,9 +10,31 @@ export var PikkuWiringTypes;
 })(PikkuWiringTypes || (PikkuWiringTypes = {}));
 /**
  * Factory function for creating middleware with tree-shaking support
+ * Supports both direct function and configuration object syntax
+ *
+ * @example
+ * ```typescript
+ * // Direct function syntax
+ * export const logMiddleware = pikkuMiddleware(
+ *   async ({ logger }, _interaction, next) => {
+ *     logger.info('Request started')
+ *     await next()
+ *   }
+ * )
+ *
+ * // Configuration object syntax with metadata
+ * export const logMiddleware = pikkuMiddleware({
+ *   name: 'Request Logger',
+ *   description: 'Logs request information',
+ *   func: async ({ logger }, _interaction, next) => {
+ *     logger.info('Request started')
+ *     await next()
+ *   }
+ * })
+ * ```
  */
 export const pikkuMiddleware = (middleware) => {
-    return middleware;
+    return typeof middleware === 'function' ? middleware : middleware.func;
 };
 /**
  * Factory function for creating middleware factories

package/dist/utils.d.ts

@@ -2,4 +2,4 @@ import { Logger } from './services/logger.js';
 export declare const closeSessionServices: (logger: Logger, sessionServices: Record<string, any>) => Promise<void>;
 export declare const createWeakUID: () => string;
 export declare const isSerializable: (data: any) => boolean;
-export declare const freezeDedupe: <T extends Function>(arr?: readonly T[] | T[] | undefined) => readonly T[];
+export declare const freezeDedupe: <T>(arr?: readonly T[] | T[] | undefined) => readonly T[];

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

@@ -45,9 +45,9 @@ export const processMessageHandlers = (services, channelConfig, channelHandler)
             channelHandler.getChannel().send(`Unauthorized for ${routeMessage}`);
             return;
         }
-        const { pikkuFuncName, middleware: inheritedMiddleware } = getRouteMeta(channelConfig.name, routingProperty, routerValue);
-        const permissions = typeof onMessage === 'function' ? {} : onMessage.permissions;
-        const middleware = typeof onMessage === 'function' ? [] : onMessage.middleware;
+        const { pikkuFuncName, middleware: inheritedMiddleware, permissions: inheritedPermissions, } = getRouteMeta(channelConfig.name, routingProperty, routerValue);
+        const wirePermissions = typeof onMessage === 'function' ? undefined : onMessage.permissions;
+        const wireMiddleware = typeof onMessage === 'function' ? [] : onMessage.middleware;
         return await runPikkuFunc(PikkuWiringTypes.channel, channelConfig.name, pikkuFuncName, {
             singletonServices: services,
             getAllServices: () => ({
@@ -56,9 +56,10 @@ export const processMessageHandlers = (services, channelConfig, channelHandler)
             }),
             data: () => data,
             userSession: services.userSession,
-            permissions,
             inheritedMiddleware,
-            wireMiddleware: middleware,
+            wireMiddleware,
+            inheritedPermissions,
+            wirePermissions,
             tags: channelConfig.tags,
             interaction: { channel: channelHandler.getChannel() },
         });

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

@@ -1,10 +1,12 @@
+import { CorePikkuPermission } from '../../function/functions.types.js';
 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
  * function names already stored in the channel metadata
  */
-export declare const wireChannel: <In, Channel extends string, ChannelFunction, ChannelFunctionSessionless, PikkuPermission>(channel: CoreChannel<In, Channel, ChannelFunction, PikkuPermission>) => void;
+export declare const wireChannel: <In, Channel extends string, PikkuPermission extends CorePikkuPermission<In>, PikkuMiddleware extends CorePikkuMiddleware, ChannelFunction>(channel: CoreChannel<In, Channel, PikkuPermission, PikkuMiddleware, ChannelFunction>) => void;
 export declare const openChannel: ({ route, singletonServices, coerceDataFromSchema, request, }: Pick<CoreChannel<unknown, string>, "route"> & RunChannelParams<unknown> & {
     userSession: UserSessionService<any>;
 } & RunChannelOptions) => Promise<{

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

@@ -17,24 +17,15 @@ export const wireChannel = (channel) => {
     pikkuState('channel', 'channels').set(channel.name, channel);
     // Register onConnect function if provided
     if (channel.onConnect && channelMeta.connect) {
-        addFunction(channelMeta.connect.pikkuFuncName, {
-            func: channel.onConnect,
-        });
+        addFunction(channelMeta.connect.pikkuFuncName, channel.onConnect);
     }
     // Register onDisconnect function if provided
     if (channel.onDisconnect && channelMeta.disconnect) {
-        addFunction(channelMeta.disconnect.pikkuFuncName, {
-            func: channel.onDisconnect,
-        });
+        addFunction(channelMeta.disconnect.pikkuFuncName, channel.onDisconnect);
     }
     // Register onMessage function if provided
     if (channel.onMessage && channelMeta.message?.pikkuFuncName) {
-        const messageFunc = typeof channel.onMessage === 'function'
-            ? channel.onMessage
-            : channel.onMessage.func;
-        addFunction(channelMeta.message.pikkuFuncName, {
-            func: messageFunc,
-        });
+        addFunction(channelMeta.message.pikkuFuncName, channel.onMessage);
     }
     // Register functions in onMessageWiring
     if (channel.onMessageWiring && channelMeta.messageWirings) {
@@ -48,16 +39,8 @@ export const wireChannel = (channel) => {
                 const wiringMeta = channelWirings[wiringKey];
                 if (!wiringMeta)
                     return;
-                // Extract the function from the handler
-                const wiringFunc = typeof handler === 'function'
-                    ? { func: handler }
-                    : {
-                        func: handler.func,
-                        auth: handler.auth,
-                        permissions: handler.permissions,
-                    };
                 // Register the function using the pikku name from metadata
-                addFunction(wiringMeta.pikkuFuncName, wiringFunc);
+                addFunction(wiringMeta.pikkuFuncName, handler);
             });
         });
     }

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

@@ -1,7 +1,7 @@
 import { PikkuError } from '../../errors/error-handler.js';
 import { HTTPFunctionMetaInputTypes, PikkuHTTPRequest, PikkuHTTPResponse } from '../http/http.types.js';
-import { PikkuDocs, CoreSingletonServices, CreateSessionServices, CorePikkuMiddleware, MiddlewareMetadata } from '../../types/core.types.js';
-import { CorePikkuFunction, CorePikkuFunctionSessionless, CorePikkuPermission } from '../../function/functions.types.js';
+import { PikkuDocs, CoreSingletonServices, CreateSessionServices, CorePikkuMiddleware, MiddlewareMetadata, PermissionMetadata } from '../../types/core.types.js';
+import { CorePermissionGroup, CorePikkuFunction, CorePikkuFunctionConfig, CorePikkuFunctionSessionless, CorePikkuPermission } from '../../function/functions.types.js';
 export type RunChannelOptions = Partial<{
     skipUserSession: boolean;
     respondWith404: boolean;
@@ -20,6 +20,7 @@ export interface ChannelMessageMeta {
     pikkuFuncName: string;
     docs?: PikkuDocs;
     middleware?: MiddlewareMetadata[];
+    permissions?: PermissionMetadata[];
 }
 export interface ChannelMeta {
     name: string;
@@ -35,25 +36,23 @@ export interface ChannelMeta {
     docs?: PikkuDocs;
     tags?: string[];
     middleware?: MiddlewareMetadata[];
+    permissions?: PermissionMetadata[];
 }
 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>, PikkuMiddleware = CorePikkuMiddleware> = {
+export type CoreChannel<ChannelData, Channel extends string, ChannelConnect = CorePikkuFunctionConfig<CorePikkuFunction<void, unknown, ChannelData> | CorePikkuFunctionSessionless<void, unknown, ChannelData>, CorePikkuPermission<void>, CorePikkuMiddleware>, ChannelDisconnect = CorePikkuFunctionConfig<CorePikkuFunction<void, void, ChannelData> | CorePikkuFunctionSessionless<void, void, ChannelData>, CorePikkuPermission<void>, CorePikkuMiddleware>, ChannelFunctionMessage = CorePikkuFunctionConfig<CorePikkuFunction<unknown, unknown, ChannelData> | CorePikkuFunctionSessionless<unknown, unknown, ChannelData>, CorePikkuPermission<unknown>, CorePikkuMiddleware>, PikkuPermission = CorePikkuPermission<ChannelData>, PikkuMiddleware = CorePikkuMiddleware> = {
     name: string;
     route: Channel;
     onConnect?: ChannelConnect;
     onDisconnect?: ChannelDisconnect;
-    onMessage?: {
-        func: ChannelFunctionMessage;
-        permissions?: Record<string, PikkuPermission[] | PikkuPermission>;
-        auth?: boolean;
-    } | ChannelFunctionMessage;
+    onMessage?: ChannelFunctionMessage;
     onMessageWiring?: Record<string, Record<string, ChannelFunctionMessage | {
         func: ChannelFunctionMessage;
-        permissions?: Record<string, PikkuPermission[] | PikkuPermission>;
+        permissions?: CorePermissionGroup<PikkuPermission>;
         auth?: boolean;
+        middleware?: PikkuMiddleware[];
     }>>;
     middleware?: PikkuMiddleware[];
-    permissions?: Record<string, PikkuPermission[] | PikkuPermission>;
+    permissions?: CorePermissionGroup<PikkuPermission>;
     auth?: boolean;
     docs?: Partial<{
         description: string;
@@ -63,11 +62,11 @@ export type CoreChannel<ChannelData, Channel extends string, ChannelConnect = Co
     }>;
     tags?: string[];
 };
-export interface PikkuChannel<OpeningData, Out> {
+export interface PikkuChannel<OpeningData, out Out> {
     channelId: string;
     openingData: OpeningData;
-    send: (data: Out, isBinary?: boolean) => Promise<void> | void;
-    close: () => Promise<void> | void;
+    send(data: Out, isBinary?: boolean): Promise<void> | void;
+    close(): Promise<void> | void;
     state: 'initial' | 'open' | 'closed';
 }
 export interface PikkuChannelHandler<OpeningData = unknown, Out = unknown> {

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

@@ -12,8 +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') || {};
-    const programMeta = allCLIMeta[programName];
+    const allCLIMeta = pikkuState('cli', 'meta');
+    if (!allCLIMeta) {
+        throw new Error('[PKU342] CLI metadata not found. No CLI wirings were registered. See https://pikku.dev/errors/pku342 for more information.');
+    }
+    const programMeta = allCLIMeta.programs[programName];
     if (!programMeta) {
         console.error(`Error: CLI program "${programName}" not found`);
         process.exit(1);

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

@@ -1,6 +1,14 @@
 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';
+/**
+ * CLI command execution error - thrown when CLI execution fails
+ * Should be caught by the wrapper to call process.exit()
+ */
+export declare class CLIError extends Error {
+    exitCode: number;
+    constructor(message: string, exitCode?: number);
+}
 /**
  * Registers a CLI command tree and all its functions
  */
@@ -22,6 +30,8 @@ export declare const pikkuCLIRender: <Data, Services extends CoreSingletonServic
 /**
  * Execute a CLI program with the given arguments
  * This is the main entry point for CLI programs
+ *
+ * @throws {CLIError} When CLI execution fails - should be caught by wrapper to call process.exit()
  */
 export declare function executeCLI({ programName, args, createConfig, createSingletonServices, createSessionServices, }: {
     programName: string;

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

@@ -7,6 +7,18 @@ import { rpcService } from '../rpc/rpc-runner.js';
 import { PikkuUserSessionService } from '../../services/user-session-service.js';
 import { LocalVariablesService } from '../../services/local-variables.js';
 import { generateCommandHelp, parseCLIArguments } from './command-parser.js';
+/**
+ * CLI command execution error - thrown when CLI execution fails
+ * Should be caught by the wrapper to call process.exit()
+ */
+export class CLIError extends Error {
+    exitCode;
+    constructor(message, exitCode = 1) {
+        super(message);
+        this.exitCode = exitCode;
+        this.name = 'CLIError';
+    }
+}
 /**
  * Default JSON renderer for CLI output
  */
@@ -19,7 +31,7 @@ const defaultJSONRenderer = (_services, data) => {
 export const wireCLI = (cli) => {
     // Get the existing metadata that was generated during inspection
     const cliMeta = pikkuState('cli', 'meta') || {};
-    if (!cliMeta[cli.program]) {
+    if (!cliMeta.programs?.[cli.program]) {
         throw new Error(`CLI metadata not found for program '${cli.program}'. Did you run 'pikku all'?`);
     }
     // Get existing programs state and add this program
@@ -63,7 +75,7 @@ function unwrapFunc(command) {
  */
 function registerCLICommands(commands, path = [], inheritedOptions = {}, program) {
     // Get the CLI metadata to find actual function names
-    const cliMeta = pikkuState('cli', 'meta')[program];
+    const cliMeta = pikkuState('cli', 'meta').programs[program];
     for (const [name, command] of Object.entries(commands)) {
         const fullPath = [...path, name];
         const commandId = fullPath.join('.');
@@ -148,7 +160,7 @@ function pluckCLIData(mergedData, funcName, availableOptions) {
 export async function runCLICommand({ program, commandPath, data, singletonServices, createSessionServices, }) {
     // Get the command metadata to find the function name
     const cliMeta = pikkuState('cli', 'meta');
-    const programMeta = cliMeta[program];
+    const programMeta = cliMeta.programs?.[program];
     if (!programMeta) {
         throw new NotFoundError(`Program not found: ${program}`);
     }
@@ -225,13 +237,6 @@ export async function runCLICommand({ program, commandPath, data, singletonServi
             channel,
         }, interaction, false);
     };
-    // Build inherited middleware from tags
-    const inheritedMiddleware = [];
-    if (programData?.tags) {
-        for (const tag of programData.tags) {
-            inheritedMiddleware.push({ type: 'tag', tag });
-        }
-    }
     try {
         const result = await runPikkuFunc(PikkuWiringTypes.cli, commandId, funcName, {
             singletonServices,
@@ -239,8 +244,11 @@ export async function runCLICommand({ program, commandPath, data, singletonServi
             data: pluckedData,
             auth: false,
             userSession,
-            inheritedMiddleware,
+            inheritedMiddleware: currentCommand.middleware,
             wireMiddleware: allWireMiddleware,
+            inheritedPermissions: currentCommand.permissions,
+            wirePermissions: undefined,
+            tags: programData?.tags,
             interaction,
         });
         // Apply renderer one final time with the final output (if renderer exists)
@@ -267,20 +275,31 @@ export const pikkuCLIRender = (renderer) => {
 /**
  * Execute a CLI program with the given arguments
  * This is the main entry point for CLI programs
+ *
+ * @throws {CLIError} When CLI execution fails - should be caught by wrapper to call process.exit()
  */
-export async function executeCLI({ programName, args = process.argv.slice(2), createConfig, createSingletonServices, createSessionServices, }) {
+export async function executeCLI({ programName, args, createConfig, createSingletonServices, createSessionServices, }) {
+    if (!args) {
+        throw new Error('CLI arguments are required, this is to satisfy release diffs');
+    }
     try {
         // Get CLI metadata from state
-        const allCLIMeta = pikkuState('cli', 'meta') || {};
-        const programMeta = allCLIMeta[programName];
+        const allCLIMeta = pikkuState('cli', 'meta');
+        if (!allCLIMeta) {
+            throw new Error('[PKU342] CLI metadata not found. No CLI wirings were registered. See https://pikku.dev/errors/pku342 for more information.');
+        }
+        const programMeta = allCLIMeta.programs[programName];
         if (!programMeta) {
-            console.error(`Error: CLI program "${programName}" not found`);
-            process.exit(1);
+            throw new CLIError(`CLI program "${programName}" not found`, 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) {
+        // Show help if --help/-h is present, or if no args AND no default command
+        const shouldShowHelp = args.includes('--help') ||
+            args.includes('-h') ||
+            (args.length === 0 && parsed.commandPath.length === 0);
+        if (shouldShowHelp) {
             const helpText = generateCommandHelp(programName, allCLIMeta, parsed.commandPath);
             console.log(helpText);
             return;
@@ -293,13 +312,13 @@ export async function executeCLI({ programName, args = process.argv.slice(2), cr
                 // Show help instead of error for unknown commands
                 const helpText = generateCommandHelp(programName, allCLIMeta, parsed.commandPath);
                 console.log(helpText);
-                process.exit(1);
+                throw new CLIError('Unknown command', 1);
             }
             else {
                 // Show errors for other types of errors
                 console.error('Errors:');
                 parsed.errors.forEach((error) => console.error(`  ${error}`));
-                process.exit(1);
+                throw new CLIError(parsed.errors.join('\n'), 1);
             }
         }
         // Merge positionals and options into single data object
@@ -318,11 +337,16 @@ export async function executeCLI({ programName, args = process.argv.slice(2), cr
         });
     }
     catch (error) {
+        // Re-throw CLIError as-is
+        if (error instanceof CLIError) {
+            throw error;
+        }
+        // Wrap other errors in CLIError
         console.error('Error:', error);
         // Show stack trace in verbose mode
         if (args.includes('--verbose') || args.includes('-v')) {
             console.error('Stack trace:', error.stack);
         }
-        process.exit(1);
+        throw new CLIError(error.message || String(error), 1);
     }
 }