@pikku/core 0.9.10 → 0.9.12-next.0

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

@@ -0,0 +1,328 @@
+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';
+/**
+ * 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[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')[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[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);
+    };
+    // 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,
+            getAllServices,
+            data: pluckedData,
+            auth: false,
+            userSession,
+            inheritedMiddleware,
+            wireMiddleware: allWireMiddleware,
+            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
+ */
+export async function executeCLI({ programName, args = process.argv.slice(2), createConfig, createSingletonServices, createSessionServices, }) {
+    try {
+        // 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 };
+        // 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) {
+        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);
+    }
+}

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

@@ -0,0 +1,177 @@
+import { CorePikkuMiddleware, CoreSingletonServices, CoreUserSession, PikkuDocs, CoreServices, MiddlewareMetadata } 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[];
+}
+/**
+ * CLI metadata collection (per program)
+ */
+export type CLIProgramMeta = {
+    program: string;
+    commands: Record<string, CLICommandMeta>;
+    options: Record<string, CLIOption>;
+    defaultRenderName?: string;
+};
+/**
+ * All CLI programs metadata
+ */
+export type CLIMeta = Record<string, CLIProgramMeta>;
+/**
+ * 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> ? 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];
+/**
+ * Extract parameter names from CLI parameter string
+ * Example: "<env> [region]" => ["env", "region"]
+ */
+type ExtractParameterNames<S extends string> = {
+    [K in keyof SplitBySpace<S>]: SplitBySpace<S>[K] extends string ? StripBrackets<SplitBySpace<S>[K]> : never;
+};
+/**
+ * Validate that all parameter names are valid keys of the function input
+ */
+export type ValidateParameters<Params extends string, Input> = ExtractParameterNames<Params> extends (infer P)[] ? P extends keyof Input ? Params : never : never;
+/**
+ * Extract output type from a Pikku function config type
+ */
+export type ExtractFunctionOutput<Func> = Func extends CorePikkuFunctionConfig<infer FuncType> ? 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 interface CoreCLICommandConfig<Func, PikkuMiddleware extends CorePikkuMiddleware<any> = CorePikkuMiddleware<any>, PikkuCLIRender extends CorePikkuCLIRender<any, any, any> = CorePikkuCLIRender<any, any>> {
+    parameters?: ValidateParameters<string, ExtractFunctionInput<Func>>;
+    func?: Func;
+    description?: string;
+    render?: PikkuCLIRender;
+    options?: Partial<Record<keyof ExtractFunctionInput<Func>, {
+        description?: string;
+        short?: string;
+        default?: ExtractFunctionInput<Func>[keyof ExtractFunctionInput<Func>];
+    }>> & Record<string, {
+        description?: string;
+        short?: string;
+        default?: any;
+    }>;
+    middleware?: PikkuMiddleware[];
+    subcommands?: Record<string, CoreCLICommandConfig<any, PikkuMiddleware, PikkuCLIRender>>;
+    auth?: boolean;
+    permissions?: any[];
+}
+/**
+ * CLI command definition
+ */
+export interface CoreCLICommand<In, Out, PikkuFunction 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: PikkuFunction;
+    render?: CorePikkuCLIRender<Out>;
+    description?: string;
+    options?: CLIOptions<Options>;
+    middleware?: PikkuMiddleware[];
+    permissions?: Record<string, PikkuPermission | PikkuPermission[]>;
+    auth?: boolean;
+    docs?: PikkuDocs;
+    subcommands?: Subcommands;
+}
+/**
+ * Shorthand command definition (just a function)
+ */
+export type CLICommandShorthand<In, Out, PikkuFunction extends CorePikkuFunctionConfig<CorePikkuFunction<In, Out, any, any, any> | CorePikkuFunctionSessionless<In, Out, any, any, any>>> = PikkuFunction;
+/**
+ * Command definition (either full or shorthand)
+ */
+export type CLICommandDefinition<In, Out, PikkuFunction 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, PikkuFunction, PikkuPermission, PikkuMiddleware, Options, Subcommands> | CLICommandShorthand<In, Out, PikkuFunction>;
+/**
+ * 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 {};

package/dist/wirings/cli/cli.types.js

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,19 @@
+import { CLIMeta } from './cli.types.js';
+/**
+ * Result of parsing CLI arguments
+ */
+export interface ParsedCommand {
+    program: string;
+    commandPath: string[];
+    positionals: Record<string, any>;
+    options: Record<string, any>;
+    errors: string[];
+}
+/**
+ * Parses raw CLI arguments into structured data for a specific program
+ */
+export declare function parseCLIArguments(args: string[], programName: string, allMeta: CLIMeta): ParsedCommand;
+/**
+ * Generates help text for a command in a specific program
+ */
+export declare function generateCommandHelp(programName: string, allMeta: CLIMeta, commandPath?: string[]): string;