@pikku/core 0.9.11 → 0.10.0

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

@@ -0,0 +1,83 @@
+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');
+    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);
+    }
+    // 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,42 @@
+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
+ */
+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
+ *
+ * @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;
+    args?: string[];
+    createConfig: CreateConfig<any, any>;
+    createSingletonServices: CreateSingletonServices<any, any>;
+    createSessionServices?: CreateSessionServices<any, any>;
+}): Promise<void>;

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

@@ -0,0 +1,352 @@
+import { NotFoundError } from '../../errors/errors.js';
+import { addFunction, runPikkuFunc } from '../../function/function-runner.js';
+import { pikkuState } from '../../pikku-state.js';
+import { PikkuWiringTypes, } from '../../types/core.types.js';
+import { closeSessionServices } from '../../utils.js';
+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
+ */
+const defaultJSONRenderer = (_services, data) => {
+    console.log(JSON.stringify(data, null, 2));
+};
+/**
+ * Registers a CLI command tree and all its functions
+ */
+export const wireCLI = (cli) => {
+    // Get the existing metadata that was generated during inspection
+    const cliMeta = pikkuState('cli', 'meta') || {};
+    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
+    const programs = pikkuState('cli', 'programs') || {};
+    programs[cli.program] = {
+        defaultRenderer: (cli.render ||
+            defaultJSONRenderer),
+        middleware: cli.middleware || [],
+        renderers: {},
+        tags: cli.tags,
+    };
+    pikkuState('cli', 'programs', programs);
+    // Register all command functions recursively
+    registerCLICommands(cli.commands, [], cli.options || {}, cli.program);
+};
+/**
+ * Unwraps a function from pikku wrappers (pikkuFunc, pikkuSessionlessFunc, etc.)
+ * These wrappers return { func, middleware, ... } but we need the actual function
+ */
+function unwrapFunc(command) {
+    if (typeof command === 'function') {
+        return { func: command };
+    }
+    // If command has a func property that's an object with func, unwrap it
+    if (command.func &&
+        typeof command.func === 'object' &&
+        'func' in command.func) {
+        return {
+            func: command.func.func,
+            middleware: command.func.middleware,
+            auth: command.func.auth,
+            permissions: command.func.permissions,
+            tags: command.func.tags,
+        };
+    }
+    // Otherwise return as-is
+    return command;
+}
+/**
+ * Registers CLI commands and their functions recursively
+ */
+function registerCLICommands(commands, path = [], inheritedOptions = {}, program) {
+    // Get the CLI metadata to find actual function names
+    const cliMeta = pikkuState('cli', 'meta').programs[program];
+    for (const [name, command] of Object.entries(commands)) {
+        const fullPath = [...path, name];
+        const commandId = fullPath.join('.');
+        // Navigate metadata to find the actual function name
+        let currentMeta = cliMeta?.commands[fullPath[0]];
+        for (let i = 1; i < fullPath.length; i++) {
+            currentMeta = currentMeta?.subcommands?.[fullPath[i]];
+        }
+        const funcName = currentMeta?.pikkuFuncName;
+        // Skip if no function name (could be a command group)
+        if (!funcName) {
+            // Recursively register subcommands if they exist
+            if (typeof command === 'object' && command.subcommands) {
+                const commandOptions = command.options || {};
+                const mergedOptions = { ...inheritedOptions, ...commandOptions };
+                registerCLICommands(command.subcommands, fullPath, mergedOptions, program);
+            }
+            continue;
+        }
+        // Merge options (inherited + local)
+        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');
+        if (programs[program]) {
+            if (!programs[program].commandOptions) {
+                programs[program].commandOptions = {};
+            }
+            programs[program].commandOptions[commandId] = mergedOptions;
+            // Store command middleware from the wire config
+            if (typeof command === 'object' && command.middleware) {
+                if (!programs[program].commandMiddleware) {
+                    programs[program].commandMiddleware = {};
+                }
+                programs[program].commandMiddleware[commandId] = command.middleware;
+            }
+        }
+        addFunction(funcName, unwrapFunc(command));
+        // Register renderer if provided
+        if (typeof command === 'object' && command.render) {
+            if (programs[program]) {
+                programs[program].renderers[commandId] = command.render;
+            }
+        }
+        // Recursively register subcommands
+        if (typeof command === 'object' && command.subcommands) {
+            registerCLICommands(command.subcommands, fullPath, mergedOptions, 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 schemaName = funcMeta?.inputSchemaName;
+    const schema = schemaName
+        ? pikkuState('misc', 'schemas').get(schemaName)
+        : null;
+    if (schema && schema.properties) {
+        // If we have a schema, only include fields that are in the schema
+        const result = {};
+        for (const key of Object.keys(schema.properties)) {
+            if (key in mergedData) {
+                result[key] = mergedData[key];
+            }
+            else if (availableOptions[key]?.default !== undefined) {
+                // Apply default if not provided
+                result[key] = availableOptions[key].default;
+            }
+        }
+        return result;
+    }
+    else {
+        // No schema, include all data
+        return { ...mergedData };
+    }
+}
+/**
+ * Executes a CLI command for a specific program
+ */
+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.programs?.[program];
+    if (!programMeta) {
+        throw new NotFoundError(`Program not found: ${program}`);
+    }
+    // Navigate command tree to find the function name
+    let currentCommand = programMeta.commands[commandPath[0]];
+    if (!currentCommand) {
+        throw new NotFoundError(`Command not found: ${commandPath.join(' ')}`);
+    }
+    for (let i = 1; i < commandPath.length; i++) {
+        if (!currentCommand.subcommands ||
+            !currentCommand.subcommands[commandPath[i]]) {
+            throw new NotFoundError(`Command not found: ${commandPath.join(' ')}`);
+        }
+        currentCommand = currentCommand.subcommands[commandPath[i]];
+    }
+    const funcName = currentCommand.pikkuFuncName;
+    // Get program-specific data
+    const programs = pikkuState('cli', 'programs') || {};
+    const programData = programs[program];
+    // Combine program middleware + command middleware from the hierarchy
+    const allWireMiddleware = [
+        ...(programData?.middleware || []),
+    ];
+    // Walk through the command path and collect middleware from the runtime config
+    const commandParts = [];
+    for (const part of commandPath) {
+        commandParts.push(part);
+        const commandId = commandParts.join('.');
+        const middleware = programData?.commandMiddleware?.[commandId];
+        if (middleware) {
+            allWireMiddleware.push(...middleware);
+        }
+    }
+    // Get command ID and options
+    const commandId = commandPath.join('.');
+    const availableOptions = programData?.commandOptions?.[commandId] || {};
+    // Pluck only the fields the function expects
+    const pluckedData = () => pluckCLIData(data, funcName, availableOptions);
+    // Get the renderer
+    const renderer = programData?.renderers[commandId] || programData?.defaultRenderer;
+    // Create a CLI channel for progressive output
+    const channel = {
+        channelId: `cli:${program}:${commandId}`,
+        openingData: pluckedData,
+        send: async (data) => {
+            if (renderer) {
+                await Promise.resolve(renderer(singletonServices, data, undefined));
+            }
+        },
+        close: () => {
+            if (channel) {
+                channel.state = 'closed';
+            }
+        },
+        state: 'open',
+    };
+    const userSession = new PikkuUserSessionService();
+    let sessionServices;
+    const interaction = {
+        cli: {
+            program,
+            command: commandPath,
+            data: pluckedData,
+            channel,
+        },
+    };
+    const getAllServices = async (session) => {
+        // Create session-specific services for handling the command
+        sessionServices = await createSessionServices?.(singletonServices, interaction, session);
+        return rpcService.injectRPCService({
+            ...singletonServices,
+            ...sessionServices,
+            userSession,
+            channel,
+        }, interaction, false);
+    };
+    try {
+        const result = await runPikkuFunc(PikkuWiringTypes.cli, commandId, funcName, {
+            singletonServices,
+            getAllServices,
+            data: pluckedData,
+            auth: false,
+            userSession,
+            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)
+        if (renderer) {
+            await Promise.resolve(renderer(singletonServices, result, userSession.get()));
+        }
+        return result;
+    }
+    finally {
+        // Close the channel
+        channel.close();
+        // Clean up session services
+        if (sessionServices) {
+            await closeSessionServices(singletonServices.logger, sessionServices);
+        }
+    }
+}
+/**
+ * Factory function for CLI-specific renderers
+ */
+export const pikkuCLIRender = (renderer) => {
+    return 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, 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');
+        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) {
+            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)
+        // 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;
+        }
+        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);
+                throw new CLIError('Unknown command', 1);
+            }
+            else {
+                // Show errors for other types of errors
+                console.error('Errors:');
+                parsed.errors.forEach((error) => console.error(`  ${error}`));
+                throw new CLIError(parsed.errors.join('\n'), 1);
+            }
+        }
+        // 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);
+        // Create services with config
+        const singletonServices = await createSingletonServices(config);
+        // Execute the command
+        await runCLICommand({
+            program: programName,
+            commandPath: parsed.commandPath,
+            data,
+            singletonServices,
+            createSessionServices,
+        });
+    }
+    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);
+        }
+        throw new CLIError(error.message || String(error), 1);
+    }
+}

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

@@ -0,0 +1,204 @@
+import { CorePikkuMiddleware, CoreSingletonServices, CoreUserSession, PikkuDocs, 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';
+/**
+ * CLI option definition
+ */
+export interface CLIOption<T = any> {
+    description: string;
+    short?: string;
+    default?: T;
+    choices?: T[];
+    array?: boolean;
+    required?: boolean;
+}
+/**
+ * CLI options collection
+ */
+export type CLIOptions<T> = {
+    [K in keyof T]: CLIOption<T[K]>;
+};
+/**
+ * Positional argument definition
+ */
+export interface CLIPositional {
+    name: string;
+    required: boolean;
+    variadic?: boolean;
+}
+/**
+ * CLI interaction context
+ */
+export type PikkuCLI = {
+    program: string;
+    command: string[];
+    data: Record<string, any>;
+    channel: PikkuChannel<unknown, unknown>;
+};
+/**
+ * Runtime CLI program state
+ */
+export interface CLIProgramState {
+    defaultRenderer?: CorePikkuCLIRender<any>;
+    middleware: CorePikkuMiddleware[];
+    renderers: Record<string, CorePikkuCLIRender<any>>;
+    commandOptions?: Record<string, Record<string, CLIOption>>;
+    commandMiddleware?: Record<string, CorePikkuMiddleware[]>;
+    tags?: string[];
+}
+/**
+ * CLI command metadata for runtime
+ */
+export interface CLICommandMeta {
+    parameters?: string;
+    pikkuFuncName: string;
+    positionals: CLIPositional[];
+    options: Record<string, CLIOption>;
+    renderName?: string;
+    description?: string;
+    docs?: PikkuDocs;
+    tags?: string[];
+    subcommands?: Record<string, CLICommandMeta>;
+    middleware?: MiddlewareMetadata[];
+    permissions?: PermissionMetadata[];
+    isDefault?: boolean;
+}
+/**
+ * CLI metadata collection (per program)
+ */
+export type CLIProgramMeta = {
+    program: string;
+    commands: Record<string, CLICommandMeta>;
+    options: Record<string, CLIOption>;
+    defaultRenderName?: string;
+};
+/**
+ * Renderer metadata for CLI commands
+ */
+export interface RendererMeta {
+    name: string;
+    exportedName?: string;
+    services: {
+        optimized: boolean;
+        services: string[];
+    };
+    filePath: string;
+}
+export type RenderersMeta = Record<string, RendererMeta>;
+/**
+ * All CLI programs metadata
+ */
+export interface CLIMeta {
+    programs: Record<string, CLIProgramMeta>;
+    renderers: RenderersMeta;
+}
+/**
+ * CLI-specific renderer that outputs to console
+ */
+export type CorePikkuCLIRender<Data, Services extends CoreSingletonServices = CoreServices, Session extends CoreUserSession = CoreUserSession> = CorePikkuRender<Data, void, Services, Session>;
+/**
+ * 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, any> | CorePikkuFunctionSessionless<infer Input, any, any, any, any> ? Input : never : never;
+/**
+ * Strip < > [ ] characters from a string
+ */
+type StripBrackets<S extends string> = S extends `<${infer Inner}>` ? Inner : S extends `[${infer Inner}]` ? Inner : S;
+/**
+ * Split string by spaces
+ */
+type SplitBySpace<S extends string> = S extends `${infer First} ${infer Rest}` ? [First, ...SplitBySpace<Rest>] : S extends '' ? [] : [S];
+/**
+ * Recursively build a tuple by stripping brackets from each element
+ */
+type BuildParamsTuple<Parts extends readonly string[]> = Parts extends readonly [
+    infer First extends string,
+    ...infer Rest extends string[]
+] ? [StripBrackets<First>, ...BuildParamsTuple<Rest>] : [];
+/**
+ * Extract parameter names from CLI parameter string into a tuple
+ * Example: "<env> [region]" => ["env", "region"]
+ */
+type ExtractParameterNames<S extends string> = BuildParamsTuple<SplitBySpace<S>>;
+/**
+ * Check if all elements of a tuple are valid keys of Input
+ */
+type AllParamsValid<Params extends readonly any[], Input> = Params extends readonly [infer First, ...infer Rest] ? First extends keyof Input ? AllParamsValid<Rest, Input> : false : true;
+/**
+ * Validate that all parameter names are valid keys of the function input
+ */
+export type ValidateParameters<Params extends string, Input> = AllParamsValid<ExtractParameterNames<Params>, Input> extends true ? Params : never;
+/**
+ * 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, 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.
+ */
+export type CoreCLICommandConfig<FuncConfig, PikkuMiddleware extends CorePikkuMiddleware<any> = CorePikkuMiddleware<any>, PikkuCLIRender extends CorePikkuCLIRender<any, any, any> = CorePikkuCLIRender<any, any>, Params extends string = string> = {
+    parameters?: ValidateParameters<Params, ExtractFunctionInput<FuncConfig>>;
+    func?: FuncConfig;
+    description?: string;
+    render?: PikkuCLIRender;
+    options?: {
+        [K in keyof ExtractFunctionInput<FuncConfig>]?: {
+            description?: string;
+            short?: string;
+            default?: ExtractFunctionInput<FuncConfig>[K];
+        };
+    };
+    middleware?: PikkuMiddleware[];
+    subcommands?: Record<string, CoreCLICommandConfig<any, PikkuMiddleware, PikkuCLIRender, any>>;
+    auth?: boolean;
+    permissions?: any[];
+    isDefault?: boolean;
+};
+/**
+ * CLI command definition
+ */
+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>;
+    description?: string;
+    options?: CLIOptions<Options>;
+    middleware?: PikkuMiddleware[];
+    permissions?: Record<string, PikkuPermission | PikkuPermission[]>;
+    auth?: boolean;
+    docs?: PikkuDocs;
+    subcommands?: Subcommands;
+    isDefault?: boolean;
+}
+/**
+ * Shorthand command definition (just a function)
+ */
+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, 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
+ */
+export interface CoreCLI<Commands extends Record<string, CoreCLICommandConfig<any, any, any>>, Options, PikkuMiddleware, PikkuCLIRender> {
+    program: string;
+    description?: string;
+    commands: Commands;
+    options?: CLIOptions<Options>;
+    middleware?: PikkuMiddleware[];
+    render?: PikkuCLIRender;
+    docs?: PikkuDocs;
+    tags?: string[];
+}
+/**
+ * Generic renderer type that can transform data into any output format.
+ * Can be used across different wirings for flexible output handling.
+ *
+ * @template Data - The input data type to be rendered
+ * @template Output - The output type after rendering
+ * @template Services - The services available to the renderer
+ * @template Session - The user session type
+ */
+export type CorePikkuRender<Data, Output, Services extends CoreSingletonServices = CoreServices, Session extends CoreUserSession = CoreUserSession> = (services: Services, data: Data, session?: Session) => Output | Promise<Output>;
+export {};