@pikku/core 0.9.12-next.0 → 0.10.0

package/src/wirings/cli/cli-runner.ts

@@ -15,6 +15,7 @@ import {
   CLIProgramState,
   CorePikkuCLIRender,
   CoreCLICommandConfig,
+  CLIMeta,
 } from './cli.types.js'
 import type {
   CoreSingletonServices,
@@ -30,6 +31,20 @@ 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 {
+  constructor(
+    message: string,
+    public exitCode: number = 1
+  ) {
+    super(message)
+    this.name = 'CLIError'
+  }
+}
+
 /**
  * Default JSON renderer for CLI output
  */
@@ -51,7 +66,7 @@ export const wireCLI = <
   // 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'?`
     )
@@ -122,7 +137,7 @@ function registerCLICommands(
   program: string
 ) {
   // 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]
@@ -242,7 +257,7 @@ export async function runCLICommand({
 }): Promise<any> {
   // 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}`)
   }
@@ -346,14 +361,6 @@ export async function runCLICommand({
     )
   }
 
-  // Build inherited middleware from tags
-  const inheritedMiddleware: any[] = []
-  if (programData?.tags) {
-    for (const tag of programData.tags) {
-      inheritedMiddleware.push({ type: 'tag', tag })
-    }
-  }
-
   try {
     const result = await runPikkuFunc(
       PikkuWiringTypes.cli,
@@ -365,8 +372,11 @@ export async function runCLICommand({
         data: pluckedData,
         auth: false,
         userSession,
-        inheritedMiddleware,
+        inheritedMiddleware: currentCommand.middleware,
         wireMiddleware: allWireMiddleware,
+        inheritedPermissions: currentCommand.permissions,
+        wirePermissions: undefined,
+        tags: programData?.tags,
         interaction,
       }
     )
@@ -410,10 +420,12 @@ export const pikkuCLIRender = <
 /**
  * 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),
+  args,
   createConfig,
   createSingletonServices,
   createSessionServices,
@@ -424,21 +436,39 @@ export async function executeCLI({
   createSingletonServices: CreateSingletonServices<any, any>
   createSessionServices?: CreateSessionServices<any, any>
 }): Promise<void> {
+  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') as unknown as
+      | CLIMeta
+      | undefined
+    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,
@@ -464,12 +494,12 @@ export async function executeCLI({
           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)
       }
     }
 
@@ -491,6 +521,12 @@ export async function executeCLI({
       createSessionServices,
     })
   } catch (error: any) {
+    // 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
@@ -498,6 +534,6 @@ export async function executeCLI({
       console.error('Stack trace:', error.stack)
     }
 
-    process.exit(1)
+    throw new CLIError(error.message || String(error), 1)
   }
 }

package/src/wirings/cli/cli.types.ts

@@ -5,6 +5,7 @@ import {
   PikkuDocs,
   CoreServices,
   MiddlewareMetadata,
+  PermissionMetadata,
 } from '../../types/core.types.js'
 import {
   CorePikkuFunctionConfig,
@@ -78,6 +79,8 @@ export interface CLICommandMeta {
   tags?: string[]
   subcommands?: Record<string, CLICommandMeta>
   middleware?: MiddlewareMetadata[] // Pre-resolved middleware chain (tag + explicit)
+  permissions?: PermissionMetadata[] // Pre-resolved permission chain (tag + explicit)
+  isDefault?: boolean
 }
 
 /**
@@ -90,10 +93,28 @@ export type CLIProgramMeta = {
   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 type CLIMeta = Record<string, CLIProgramMeta>
+export interface CLIMeta {
+  programs: Record<string, CLIProgramMeta>
+  renderers: RenderersMeta
+}
 
 /**
  * CLI-specific renderer that outputs to console
@@ -108,7 +129,7 @@ export type CorePikkuCLIRender<
  * Extract input parameters from a Pikku function config type
  */
 export type ExtractFunctionInput<Func> =
-  Func extends CorePikkuFunctionConfig<infer FuncType>
+  Func extends CorePikkuFunctionConfig<infer FuncType, any, any>
     ? FuncType extends
         | CorePikkuFunction<infer Input, any, any, any, any>
         | CorePikkuFunctionSessionless<infer Input, any, any, any, any>
@@ -135,30 +156,47 @@ type SplitBySpace<S extends string> = S extends `${infer First} ${infer Rest}`
     : [S]
 
 /**
- * Extract parameter names from CLI parameter string
+ * 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> = {
-  [K in keyof SplitBySpace<S>]: SplitBySpace<S>[K] extends string
-    ? StripBrackets<SplitBySpace<S>[K]>
-    : never
-}
+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> =
-  ExtractParameterNames<Params> extends (infer P)[]
-    ? P extends keyof Input
-      ? Params
-      : never
+  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>
+  Func extends CorePikkuFunctionConfig<infer FuncType, any, any>
     ? FuncType extends
         | CorePikkuFunction<any, infer Output, any, any, any>
         | CorePikkuFunctionSessionless<any, infer Output, any, any, any>
@@ -170,43 +208,34 @@ export type ExtractFunctionOutput<Func> =
  * 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,
+export type CoreCLICommandConfig<
+  FuncConfig,
   PikkuMiddleware extends CorePikkuMiddleware<any> = CorePikkuMiddleware<any>,
   PikkuCLIRender extends CorePikkuCLIRender<any, any, any> = CorePikkuCLIRender<
     any,
     any
   >,
-> {
-  parameters?: ValidateParameters<string, ExtractFunctionInput<Func>>
-  func?: Func
+  Params extends string = string,
+> = {
+  parameters?: ValidateParameters<Params, ExtractFunctionInput<FuncConfig>>
+  func?: FuncConfig
   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
-      }
-    >
+  options?: {
+    [K in keyof ExtractFunctionInput<FuncConfig>]?: {
+      description?: string
+      short?: string
+      default?: ExtractFunctionInput<FuncConfig>[K]
+    }
+  }
   middleware?: PikkuMiddleware[]
   subcommands?: Record<
     string,
-    CoreCLICommandConfig<any, PikkuMiddleware, PikkuCLIRender>
+    CoreCLICommandConfig<any, PikkuMiddleware, PikkuCLIRender, any>
   >
   auth?: boolean
   permissions?: any[]
+  isDefault?: boolean
 }
 
 /**
@@ -215,7 +244,7 @@ export interface CoreCLICommandConfig<
 export interface CoreCLICommand<
   In,
   Out,
-  PikkuFunction extends CorePikkuFunctionConfig<
+  PikkuFunctionConfig extends CorePikkuFunctionConfig<
     | CorePikkuFunction<In, Out, any, any, any>
     | CorePikkuFunctionSessionless<In, Out, any, any, any>
   >,
@@ -228,7 +257,7 @@ export interface CoreCLICommand<
   > = Record<string, CoreCLICommandConfig<any, any, any>>,
 > {
   parameters?: string
-  func: PikkuFunction
+  func: PikkuFunctionConfig
   render?: CorePikkuCLIRender<Out>
   description?: string
   options?: CLIOptions<Options>
@@ -237,6 +266,7 @@ export interface CoreCLICommand<
   auth?: boolean
   docs?: PikkuDocs
   subcommands?: Subcommands
+  isDefault?: boolean
 }
 
 /**
@@ -245,11 +275,11 @@ export interface CoreCLICommand<
 export type CLICommandShorthand<
   In,
   Out,
-  PikkuFunction extends CorePikkuFunctionConfig<
+  PikkuFunctionConfig extends CorePikkuFunctionConfig<
     | CorePikkuFunction<In, Out, any, any, any>
     | CorePikkuFunctionSessionless<In, Out, any, any, any>
   >,
-> = PikkuFunction
+> = PikkuFunctionConfig
 
 /**
  * Command definition (either full or shorthand)
@@ -257,7 +287,7 @@ export type CLICommandShorthand<
 export type CLICommandDefinition<
   In,
   Out,
-  PikkuFunction extends CorePikkuFunctionConfig<
+  PikkuFunctionConfig extends CorePikkuFunctionConfig<
     | CorePikkuFunction<In, Out, any, any, any>
     | CorePikkuFunctionSessionless<In, Out, any, any, any>
   >,
@@ -272,13 +302,13 @@ export type CLICommandDefinition<
   | CoreCLICommand<
       In,
       Out,
-      PikkuFunction,
+      PikkuFunctionConfig,
       PikkuPermission,
       PikkuMiddleware,
       Options,
       Subcommands
     >
-  | CLICommandShorthand<In, Out, PikkuFunction>
+  | CLICommandShorthand<In, Out, PikkuFunctionConfig>
 
 /**
  * CLI wiring configuration

package/src/wirings/cli/command-parser.test.ts

@@ -4,78 +4,80 @@ import { parseCLIArguments, generateCommandHelp } from './command-parser.js'
 import { CLIMeta } from './cli.types.js'
 
 const testMeta: CLIMeta = {
-  'test-cli': {
-    program: 'test-cli',
-    options: {
-      verbose: {
-        description: 'Enable verbose output',
-        short: 'v',
-        default: false,
+  programs: {
+    'test-cli': {
+      program: 'test-cli',
+      options: {
+        verbose: {
+          description: 'Enable verbose output',
+          short: 'v',
+          default: false,
+        },
       },
-    },
-    commands: {
-      greet: {
-        command: 'greet <name>',
-        pikkuFuncName: 'greetFunc',
-        positionals: [{ name: 'name', required: true }],
-        options: {
-          loud: {
-            description: 'Use loud greeting',
-            short: 'l',
-            default: false,
+      commands: {
+        greet: {
+          parameters: '<name>',
+          pikkuFuncName: 'greetFunc',
+          positionals: [{ name: 'name', required: true }],
+          options: {
+            loud: {
+              description: 'Use loud greeting',
+              short: 'l',
+              default: false,
+            },
           },
         },
-      },
-      user: {
-        command: 'user',
-        pikkuFuncName: '',
-        positionals: [],
-        options: {},
-        subcommands: {
-          create: {
-            command: 'create <name> <email>',
-            pikkuFuncName: 'createUserFunc',
-            positionals: [
-              { name: 'name', required: true },
-              { name: 'email', required: true },
-            ],
-            options: {
-              role: {
-                description: 'User role',
-                short: 'r',
-                default: 'user',
-                choices: ['admin', 'user', 'guest'],
+        user: {
+          pikkuFuncName: '',
+          positionals: [],
+          options: {},
+          subcommands: {
+            create: {
+              parameters: '<name> <email>',
+              pikkuFuncName: 'createUserFunc',
+              positionals: [
+                { name: 'name', required: true },
+                { name: 'email', required: true },
+              ],
+              options: {
+                role: {
+                  description: 'User role',
+                  short: 'r',
+                  default: 'user',
+                  choices: ['admin', 'user', 'guest'],
+                },
               },
             },
-          },
-          delete: {
-            command: 'delete <id>',
-            pikkuFuncName: 'deleteUserFunc',
-            positionals: [{ name: 'id', required: true }],
-            options: {
-              force: {
-                description: 'Force delete',
-                short: 'f',
-                default: false,
+            delete: {
+              parameters: '<id>',
+              pikkuFuncName: 'deleteUserFunc',
+              positionals: [{ name: 'id', required: true }],
+              options: {
+                force: {
+                  description: 'Force delete',
+                  short: 'f',
+                  default: false,
+                },
               },
             },
           },
         },
-      },
-      files: {
-        command: 'files <paths...>',
-        pikkuFuncName: 'filesFunc',
-        positionals: [{ name: 'paths', required: true, variadic: true }],
-        options: {},
-      },
-      optional: {
-        command: 'optional [name]',
-        pikkuFuncName: 'optionalFunc',
-        positionals: [{ name: 'name', required: false }],
-        options: {},
+        files: {
+          parameters: '<paths...>',
+          pikkuFuncName: 'filesFunc',
+          positionals: [{ name: 'paths', required: true, variadic: true }],
+          options: {},
+        },
+        optional: {
+          parameters: '[name]',
+          pikkuFuncName: 'optionalFunc',
+          positionals: [{ name: 'name', required: false }],
+          options: {},
+        },
       },
     },
   },
+  renderers: {},
 }
 
 describe('Command Parser', () => {
@@ -291,23 +293,25 @@ describe('Command Parser', () => {
 
     test('should parse number values correctly', () => {
       const metaWithNumber: CLIMeta = {
-        'num-cli': {
-          program: 'num-cli',
-          options: {},
-          commands: {
-            test: {
-              command: 'test',
-              pikkuFuncName: 'testFunc',
-              positionals: [],
-              options: {
-                port: {
-                  description: 'Port number',
-                  default: 3000,
+        programs: {
+          'num-cli': {
+            program: 'num-cli',
+            options: {},
+            commands: {
+              test: {
+                pikkuFuncName: 'testFunc',
+                positionals: [],
+                options: {
+                  port: {
+                    description: 'Port number',
+                    default: 3000,
+                  },
                 },
               },
             },
           },
         },
+        renderers: {},
       }
 
       const result = parseCLIArguments(
@@ -349,8 +353,7 @@ describe('Command Parser', () => {
       assert.ok(help.includes('--verbose'))
     })
 
-    // TODO: Fix this test - help generation issue
-    test.skip('should generate help for specific command', () => {
+    test('should generate help for specific command', () => {
       const help = generateCommandHelp('test-cli', testMeta, ['greet'])
 
       assert.ok(help.includes('Usage: test-cli greet'))
@@ -359,8 +362,7 @@ describe('Command Parser', () => {
       assert.ok(help.includes('Use loud greeting'))
     })
 
-    // TODO: Fix this test - help generation issue
-    test.skip('should generate help for subcommand', () => {
+    test('should generate help for subcommand', () => {
       const help = generateCommandHelp('test-cli', testMeta, ['user', 'create'])
 
       assert.ok(help.includes('Usage: test-cli user create'))
@@ -371,19 +373,22 @@ describe('Command Parser', () => {
 
     test('should show command description if available', () => {
       const metaWithDesc: CLIMeta = {
-        'test-cli': {
-          program: 'test-cli',
-          options: {},
-          commands: {
-            greet: {
-              command: 'greet <name>',
-              pikkuFuncName: 'greetFunc',
-              description: 'Greet a user',
-              positionals: [{ name: 'name', required: true }],
-              options: {},
+        programs: {
+          'test-cli': {
+            program: 'test-cli',
+            options: {},
+            commands: {
+              greet: {
+                parameters: '<name>',
+                pikkuFuncName: 'greetFunc',
+                description: 'Greet a user',
+                positionals: [{ name: 'name', required: true }],
+                options: {},
+              },
             },
           },
         },
+        renderers: {},
       }
 
       const help = generateCommandHelp('test-cli', metaWithDesc, ['greet'])