@pikku/core 0.9.11 → 0.10.0

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;

package/dist/wirings/cli/command-parser.js

@@ -0,0 +1,403 @@
+/**
+ * Parses raw CLI arguments into structured data for a specific program
+ */
+export function parseCLIArguments(args, programName, allMeta) {
+    const result = {
+        program: programName,
+        commandPath: [],
+        positionals: {},
+        options: {},
+        errors: [],
+    };
+    const meta = allMeta.programs[programName];
+    if (!meta) {
+        result.errors.push(`Program not found: ${programName}`);
+        return result;
+    }
+    let currentIndex = 0;
+    let currentMeta = meta;
+    // Parse command path (non-flag arguments at the beginning)
+    while (currentIndex < args.length && !args[currentIndex].startsWith('-')) {
+        const arg = args[currentIndex];
+        // Check if this is a known subcommand
+        if (currentMeta.commands && currentMeta.commands[arg]) {
+            result.commandPath.push(arg);
+            currentMeta = {
+                program: currentMeta.program,
+                commands: currentMeta.commands[arg].subcommands || {},
+                options: {
+                    ...currentMeta.options,
+                    ...currentMeta.commands[arg].options,
+                },
+                defaultRenderName: currentMeta.commands[arg].renderName || currentMeta.defaultRenderName,
+            };
+            currentIndex++;
+        }
+        else {
+            // Not a subcommand, must be a positional argument
+            break;
+        }
+    }
+    // If no command was parsed, check for a default command
+    // Only use default if user didn't provide any non-flag arguments
+    const hasNonFlagArgs = args.some((arg, idx) => idx >= currentIndex && !arg.startsWith('-'));
+    if (result.commandPath.length === 0 && meta.commands && !hasNonFlagArgs) {
+        for (const [name, cmd] of Object.entries(meta.commands)) {
+            if (cmd.isDefault) {
+                result.commandPath.push(name);
+                currentMeta = {
+                    program: currentMeta.program,
+                    commands: cmd.subcommands || {},
+                    options: {
+                        ...currentMeta.options,
+                        ...cmd.options,
+                    },
+                    defaultRenderName: cmd.renderName || currentMeta.defaultRenderName,
+                };
+                break;
+            }
+        }
+    }
+    // Get the final command metadata
+    const commandMeta = getCommandMeta(meta, result.commandPath);
+    if (!commandMeta) {
+        // If we have no command path but there are non-flag args, the first arg is likely an unknown command
+        if (result.commandPath.length === 0 &&
+            hasNonFlagArgs &&
+            args.length > 0 &&
+            !args[0].startsWith('-')) {
+            result.errors.push(`Unknown command: ${args[0]}`);
+        }
+        else {
+            result.errors.push(`Unknown command: ${result.commandPath.join(' ')}`);
+        }
+        return result;
+    }
+    // Collect all available options (global + inherited)
+    const availableOptions = collectAvailableOptions(meta, result.commandPath);
+    // Parse remaining arguments as positionals and options
+    const positionalArgs = [];
+    const optionArgs = {};
+    while (currentIndex < args.length) {
+        const arg = args[currentIndex];
+        if (arg.startsWith('--')) {
+            // Long option
+            const equalIndex = arg.indexOf('=');
+            if (equalIndex > 0) {
+                // --option=value format
+                const key = arg.slice(2, equalIndex);
+                const optionDef = availableOptions[key];
+                // Unknown options are allowed for forward compatibility
+                const value = arg.slice(equalIndex + 1);
+                optionArgs[key] = parseOptionValue(value, optionDef);
+            }
+            else {
+                // --option value format
+                const key = arg.slice(2);
+                const optionDef = availableOptions[key];
+                // Unknown options are allowed for forward compatibility
+                if (optionDef && optionDef.array) {
+                    // Array option - collect all following non-flag values
+                    currentIndex++;
+                    const values = [];
+                    while (currentIndex < args.length &&
+                        !args[currentIndex].startsWith('-')) {
+                        values.push(parseOptionValue(args[currentIndex], optionDef));
+                        currentIndex++;
+                    }
+                    currentIndex--; // Back up one since we'll increment at loop end
+                    optionArgs[key] = values;
+                }
+                else if (currentIndex + 1 < args.length &&
+                    !args[currentIndex + 1].startsWith('-')) {
+                    // Next arg is the value
+                    currentIndex++;
+                    optionArgs[key] = parseOptionValue(args[currentIndex], optionDef);
+                }
+                else {
+                    // Boolean flag
+                    optionArgs[key] = true;
+                }
+            }
+        }
+        else if (arg.startsWith('-') && arg.length > 1) {
+            // Short option(s)
+            for (let i = 1; i < arg.length; i++) {
+                const shortFlag = arg[i];
+                // Find the corresponding long option
+                const longOption = findLongOption(shortFlag, availableOptions);
+                if (longOption) {
+                    // Check if this is the last character and there's a value
+                    if (i === arg.length - 1 &&
+                        currentIndex + 1 < args.length &&
+                        !args[currentIndex + 1].startsWith('-')) {
+                        currentIndex++;
+                        optionArgs[longOption] = parseOptionValue(args[currentIndex], availableOptions[longOption]);
+                    }
+                    else {
+                        // Boolean flag
+                        optionArgs[longOption] = true;
+                    }
+                }
+                else {
+                    result.errors.push(`Unknown option: -${shortFlag}`);
+                }
+            }
+        }
+        else {
+            // Positional argument
+            positionalArgs.push(arg);
+        }
+        currentIndex++;
+    }
+    // Map positional arguments to named parameters
+    mapPositionalArguments(commandMeta.positionals, positionalArgs, result);
+    // Apply option defaults and validation
+    applyOptionDefaults(availableOptions, optionArgs, result);
+    result.options = optionArgs;
+    return result;
+}
+/**
+ * Gets the command metadata for a given path
+ */
+function getCommandMeta(meta, path) {
+    if (path.length === 0) {
+        return null;
+    }
+    let current = meta.commands[path[0]];
+    if (!current) {
+        return null;
+    }
+    for (let i = 1; i < path.length; i++) {
+        if (!current.subcommands || !current.subcommands[path[i]]) {
+            return null;
+        }
+        current = current.subcommands[path[i]];
+    }
+    return current;
+}
+/**
+ * Collects all available options through the inheritance chain
+ */
+function collectAvailableOptions(meta, path) {
+    let options = { ...meta.options };
+    if (path.length === 0) {
+        return options;
+    }
+    // Walk through the command path, merging options
+    let current = meta.commands[path[0]];
+    if (current) {
+        options = { ...options, ...current.options };
+        for (let i = 1; i < path.length; i++) {
+            if (current.subcommands && current.subcommands[path[i]]) {
+                current = current.subcommands[path[i]];
+                options = { ...options, ...current.options };
+            }
+        }
+    }
+    return options;
+}
+/**
+ * Finds the long option name for a short flag
+ */
+function findLongOption(shortFlag, options) {
+    for (const [name, option] of Object.entries(options)) {
+        if (option.short === shortFlag) {
+            return name;
+        }
+    }
+    return null;
+}
+/**
+ * Parses an option value based on its definition
+ */
+function parseOptionValue(value, optionDef) {
+    if (!optionDef) {
+        // No definition, try to infer type
+        if (value === 'true')
+            return true;
+        if (value === 'false')
+            return false;
+        if (/^\d+$/.test(value))
+            return parseInt(value, 10);
+        if (/^\d*\.\d+$/.test(value))
+            return parseFloat(value);
+        return value;
+    }
+    // Use default type from option definition
+    const defaultValue = optionDef.default;
+    if (typeof defaultValue === 'boolean') {
+        return value === 'true' || value === '1' || value === 'yes';
+    }
+    if (typeof defaultValue === 'number') {
+        return parseFloat(value);
+    }
+    // Check choices
+    if (optionDef.choices && !optionDef.choices.includes(value)) {
+        // Invalid choice, but return anyway (validation will catch it)
+        return value;
+    }
+    return value;
+}
+/**
+ * Maps positional arguments to named parameters
+ */
+function mapPositionalArguments(positionalDefs, args, result) {
+    let argIndex = 0;
+    for (const def of positionalDefs) {
+        if (def.variadic) {
+            // Collect all remaining arguments
+            if (argIndex < args.length) {
+                result.positionals[def.name] = args.slice(argIndex);
+                argIndex = args.length;
+            }
+            else if (def.required) {
+                result.errors.push(`Missing required argument: ${def.name}`);
+            }
+            else {
+                result.positionals[def.name] = [];
+            }
+        }
+        else {
+            // Single argument
+            if (argIndex < args.length) {
+                result.positionals[def.name] = args[argIndex];
+                argIndex++;
+            }
+            else if (def.required) {
+                result.errors.push(`Missing required argument: ${def.name}`);
+            }
+        }
+    }
+    // Check for extra positional arguments
+    if (argIndex < args.length) {
+        result.errors.push(`Unexpected arguments: ${args.slice(argIndex).join(' ')}`);
+    }
+}
+/**
+ * Applies option defaults and validates choices
+ */
+function applyOptionDefaults(optionDefs, options, result) {
+    for (const [name, def] of Object.entries(optionDefs)) {
+        // Apply default if not provided
+        if (!(name in options) && def.default !== undefined) {
+            options[name] = def.default;
+        }
+        // Check required
+        if (def.required && !(name in options)) {
+            result.errors.push(`Missing required option: --${name}`);
+        }
+        // Validate choices
+        if (def.choices && name in options) {
+            const value = options[name];
+            if (Array.isArray(value)) {
+                for (const v of value) {
+                    if (!def.choices.includes(v)) {
+                        result.errors.push(`Invalid value for --${name}: ${v}. Valid choices: ${def.choices.join(', ')}`);
+                    }
+                }
+            }
+            else if (!def.choices.includes(value)) {
+                result.errors.push(`Invalid value for --${name}: ${value}. Valid choices: ${def.choices.join(', ')}`);
+            }
+        }
+    }
+}
+/**
+ * Generates help text for a command in a specific program
+ */
+export function generateCommandHelp(programName, allMeta, commandPath = []) {
+    const lines = [];
+    const meta = allMeta.programs[programName];
+    if (!meta) {
+        return `Program not found: ${programName}`;
+    }
+    if (commandPath.length === 0) {
+        // Root help for the program
+        lines.push(`Usage: ${programName} <command> [options]`);
+        lines.push('');
+        lines.push('Commands:');
+        for (const [name, cmd] of Object.entries(meta.commands)) {
+            const desc = cmd.description || '';
+            const defaultMarker = cmd.isDefault ? ' (default)' : '';
+            lines.push(`  ${name.padEnd(20)} ${desc}${defaultMarker}`);
+        }
+        if (Object.keys(meta.options).length > 0) {
+            lines.push('');
+            lines.push('Options:');
+            formatOptions(meta.options, lines);
+        }
+    }
+    else {
+        // Command-specific help
+        const commandMeta = getCommandMeta(meta, commandPath);
+        if (!commandMeta) {
+            return `Unknown command: ${commandPath.join(' ')}`;
+        }
+        // Usage line
+        let usage = `${programName} ${commandPath.join(' ')}`;
+        if (commandMeta.parameters) {
+            usage += ' ' + commandMeta.parameters;
+        }
+        lines.push(`Usage: ${usage} [options]`);
+        if (commandMeta.description) {
+            lines.push('');
+            lines.push(commandMeta.description);
+        }
+        // Positional arguments
+        if (commandMeta.positionals.length > 0) {
+            lines.push('');
+            lines.push('Arguments:');
+            for (const pos of commandMeta.positionals) {
+                const marker = pos.required ? '<required>' : '[optional]';
+                const variadic = pos.variadic ? '...' : '';
+                lines.push(`  ${pos.name}${variadic} ${marker}`);
+            }
+        }
+        // Subcommands
+        if (commandMeta.subcommands &&
+            Object.keys(commandMeta.subcommands).length > 0) {
+            lines.push('');
+            lines.push('Subcommands:');
+            for (const [name, sub] of Object.entries(commandMeta.subcommands)) {
+                const desc = sub.description || '';
+                lines.push(`  ${name.padEnd(20)} ${desc}`);
+            }
+        }
+        // Options
+        const availableOptions = collectAvailableOptions(meta, commandPath);
+        if (Object.keys(availableOptions).length > 0) {
+            lines.push('');
+            lines.push('Options:');
+            formatOptions(availableOptions, lines);
+        }
+    }
+    return lines.join('\n');
+}
+/**
+ * Formats options for help text
+ */
+function formatOptions(options, lines) {
+    for (const [name, opt] of Object.entries(options)) {
+        let line = '  ';
+        if (opt.short) {
+            line += `-${opt.short}, `;
+        }
+        else {
+            line += '    ';
+        }
+        line += `--${name}`;
+        if (opt.default !== undefined && typeof opt.default !== 'boolean') {
+            line += ` <value>`;
+        }
+        line = line.padEnd(30);
+        line += opt.description || '';
+        if (opt.default !== undefined) {
+            line += ` (default: ${JSON.stringify(opt.default)})`;
+        }
+        if (opt.choices) {
+            line += ` [choices: ${opt.choices.join(', ')}]`;
+        }
+        lines.push(line);
+    }
+}

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

@@ -0,0 +1,5 @@
+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';

package/dist/wirings/cli/index.js

@@ -0,0 +1,5 @@
+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';

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

@@ -1,18 +1,67 @@
 import { CoreHTTPFunctionWiring, RunHTTPWiringOptions, RunHTTPWiringParams, PikkuHTTP, PikkuHTTPRequest, PikkuHTTPResponse } from './http.types.js';
-import { CorePikkuMiddleware } from '../../types/core.types.js';
+import { CorePikkuFunction, CorePikkuFunctionSessionless, CorePikkuPermission, CorePermissionGroup } from '../../function/functions.types.js';
+import { CorePikkuMiddleware, CorePikkuMiddlewareGroup } from '../../types/core.types.js';
 import { PikkuFetchHTTPResponse } from './pikku-fetch-http-response.js';
 /**
- * Registers middleware either globally or for a specific route.
+ * Registers HTTP middleware for a specific route pattern.
  *
- * When a string route pattern is provided along with middleware, the middleware
- * is applied only to that route. Otherwise, if an array is provided, it is treated
- * as global middleware (applied to all routes).
+ * This function registers middleware at runtime that will be applied to
+ * HTTP routes matching the specified pattern.
+ *
+ * For tree-shaking benefits, wrap in a factory function:
+ * `export const x = () => addHTTPMiddleware('pattern', [...])`
  *
  * @template PikkuMiddleware The middleware type.
- * @param {PikkuMiddleware[] | string} routeOrMiddleware - Either a global middleware array or a route pattern string.
- * @param {PikkuMiddleware[]} [middleware] - The middleware array to apply when a route pattern is specified.
+ * @param {string} pattern - Route pattern (e.g., '*' for all routes, '/api/*' for specific routes).
+ * @param {CorePikkuMiddlewareGroup} middleware - Array of middleware for this route pattern.
+ *
+ * @returns {CorePikkuMiddlewareGroup} The middleware array (for chaining/wrapping).
+ *
+ * @example
+ * ```typescript
+ * // Recommended: tree-shakeable
+ * export const httpGlobal = () => addHTTPMiddleware('*', [
+ *   corsMiddleware,
+ *   loggingMiddleware
+ * ])
+ *
+ * // Also works: no tree-shaking
+ * export const apiMiddleware = addHTTPMiddleware('/api/*', [
+ *   authMiddleware
+ * ])
+ * ```
+ */
+export declare const addHTTPMiddleware: <PikkuMiddleware extends CorePikkuMiddleware>(pattern: string, middleware: CorePikkuMiddlewareGroup) => CorePikkuMiddlewareGroup;
+/**
+ * Registers HTTP permissions for a specific route pattern.
+ *
+ * This function registers permissions at runtime that will be applied to
+ * HTTP routes matching the specified pattern.
+ *
+ * For tree-shaking benefits, wrap in a factory function:
+ * `export const x = () => addHTTPPermission('pattern', [...])`
+ *
+ * @template PikkuPermission The permission type.
+ * @param {string} pattern - Route pattern (e.g., '*' for all routes, '/api/*' for specific routes).
+ * @param {CorePermissionGroup | CorePikkuPermission[]} permissions - Permissions for this route pattern.
+ *
+ * @returns {CorePermissionGroup | CorePikkuPermission[]} The permissions (for chaining/wrapping).
+ *
+ * @example
+ * ```typescript
+ * // Recommended: tree-shakeable
+ * export const httpGlobalPermissions = () => addHTTPPermission('*', [
+ *   authenticatedPermission,
+ *   rateLimitPermission
+ * ])
+ *
+ * // Also works: no tree-shaking
+ * export const apiPermissions = addHTTPPermission('/api/*', [
+ *   adminPermission
+ * ])
+ * ```
  */
-export declare const addHTTPMiddleware: <PikkuMiddleware extends CorePikkuMiddleware>(routeOrMiddleware: PikkuMiddleware[] | string, middleware?: PikkuMiddleware[]) => void;
+export declare const addHTTPPermission: <PikkuPermission extends CorePikkuPermission>(pattern: string, permissions: CorePermissionGroup | CorePikkuPermission[]) => CorePermissionGroup | CorePikkuPermission[];
 /**
  * Adds a new route to the global HTTP route registry.
  *
@@ -28,7 +77,7 @@ export declare const addHTTPMiddleware: <PikkuMiddleware extends CorePikkuMiddle
  * @template PikkuMiddleware Middleware type to be used with the route.
  * @param {CoreHTTPFunctionWiring<In, Out, Route, PikkuFunction, PikkuFunctionSessionless, PikkuPermission, PikkuMiddleware>} httpWiring - The HTTP wiring configuration object.
  */
-export declare const wireHTTP: <In, Out, Route extends string, PikkuFunction, PikkuFunctionSessionless, PikkuPermissionGroup, PikkuMiddleware>(httpWiring: CoreHTTPFunctionWiring<In, Out, Route, PikkuFunction, PikkuFunctionSessionless, PikkuPermissionGroup, PikkuMiddleware>) => void;
+export declare const wireHTTP: <In, Out, Route extends string, PikkuFunction extends CorePikkuFunction<In, Out> = CorePikkuFunction<In, Out>, PikkuFunctionSessionless extends CorePikkuFunctionSessionless<In, Out> = CorePikkuFunctionSessionless<In, Out>, PikkuPermissionGroup extends CorePikkuPermission<In> = CorePikkuPermission<In>, PikkuMiddleware extends CorePikkuMiddleware = CorePikkuMiddleware>(httpWiring: CoreHTTPFunctionWiring<In, Out, Route, PikkuFunction, PikkuFunctionSessionless, PikkuPermissionGroup, PikkuMiddleware>) => void;
 /**
  * Combines the request and response objects into a single HTTP interaction object.
  *
@@ -87,4 +136,4 @@ export declare const pikkuFetch: <In, Out>(request: Request | PikkuHTTPRequest,
  * @param {RunHTTPWiringOptions & RunHTTPWiringParams} options - Options such as singleton services, session handling, and error configuration.
  * @returns {Promise<Out | void>} The output from the route handler or void if an error occurred.
  */
-export declare const fetchData: <In, Out>(request: Request | PikkuHTTPRequest, response: PikkuHTTPResponse, { singletonServices, createSessionServices, skipUserSession, respondWith404, logWarningsForStatusCodes, coerceDataFromSchema, bubbleErrors, generateRequestId, ignoreMiddleware, }: RunHTTPWiringOptions & RunHTTPWiringParams) => Promise<Out | void>;
+export declare const fetchData: <In, Out>(request: Request | PikkuHTTPRequest, response: PikkuHTTPResponse, { singletonServices, createSessionServices, skipUserSession, respondWith404, logWarningsForStatusCodes, coerceDataFromSchema, bubbleErrors, generateRequestId, }: RunHTTPWiringOptions & RunHTTPWiringParams) => Promise<Out | void>;