@pikku/core 0.12.20 → 0.12.22

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

@@ -2,7 +2,13 @@ import { test, describe, beforeEach, afterEach } from 'node:test'
 import * as assert from 'assert'
 import { NotFoundError } from '../../errors/errors.js'
 import type { CorePikkuMiddleware } from '../../types/core.types.js'
-import { wireCLI, runCLICommand, pikkuCLIRender } from './cli-runner.js'
+import {
+  CLIError,
+  executeCLI,
+  wireCLI,
+  runCLICommand,
+  pikkuCLIRender,
+} from './cli-runner.js'
 import { pikkuState, resetPikkuState } from '../../pikku-state.js'
 import { addFunction } from '../../function/function-runner.js'
 
@@ -49,7 +55,14 @@ describe('CLI Runner', () => {
         programs: {
           'test-cli': {
             program: 'test-cli',
-            commands: {},
+            commands: {
+              greet: {
+                command: 'greet <name>',
+                pikkuFuncId: 'greetFunc',
+                positionals: [{ name: 'name', required: true }],
+                options: {},
+              },
+            },
             options: {},
           },
         },
@@ -401,4 +414,244 @@ describe('CLI Runner', () => {
       assert.deepStrictEqual(receivedData, { test: 'value' })
     })
   })
+
+  describe('executeCLI', () => {
+    test('should require args to be provided', async () => {
+      await assert.rejects(
+        () =>
+          executeCLI({
+            programName: 'test-cli',
+            createSingletonServices: async () => singletonServices,
+          }),
+        /CLI arguments are required/
+      )
+    })
+
+    test('should throw CLIError when the program is missing from cli metadata', async () => {
+      await assert.rejects(
+        () =>
+          executeCLI({
+            programName: 'test-cli',
+            args: [],
+            createSingletonServices: async () => singletonServices,
+          }),
+        /CLI program "test-cli" not found/
+      )
+    })
+
+    test('should print help and return when --help is requested', async () => {
+      const logs: string[] = []
+      const originalLog = console.log
+      console.log = (message?: any) => {
+        logs.push(String(message))
+      }
+
+      pikkuState(null, 'cli', 'meta', {
+        programs: {
+          'test-cli': {
+            program: 'test-cli',
+            description: 'Test CLI',
+            commands: {
+              greet: {
+                command: 'greet <name>',
+                description: 'Greets someone',
+                pikkuFuncId: 'greetFunc',
+                positionals: [{ name: 'name', required: true }],
+                options: {},
+              },
+            },
+            options: {},
+          },
+        },
+        renderers: {},
+      })
+
+      try {
+        await executeCLI({
+          programName: 'test-cli',
+          args: ['--help'],
+          createSingletonServices: async () => singletonServices,
+        })
+      } finally {
+        console.log = originalLog
+      }
+
+      assert.ok(logs[0]?.includes('test-cli'))
+      assert.ok(logs[0]?.includes('greet'))
+    })
+
+    test('should show help and throw CLIError for unknown commands', async () => {
+      const logs: string[] = []
+      const originalLog = console.log
+      console.log = (message?: any) => {
+        logs.push(String(message))
+      }
+
+      pikkuState(null, 'cli', 'meta', {
+        programs: {
+          'test-cli': {
+            program: 'test-cli',
+            commands: {
+              greet: {
+                command: 'greet <name>',
+                description: 'Greets someone',
+                pikkuFuncId: 'greetFunc',
+                positionals: [{ name: 'name', required: true }],
+                options: {},
+              },
+            },
+            options: {},
+          },
+        },
+        renderers: {},
+      })
+
+      try {
+        await assert.rejects(
+          () =>
+            executeCLI({
+              programName: 'test-cli',
+              args: ['unknown'],
+              createSingletonServices: async () => singletonServices,
+            }),
+          (error: any) => {
+            assert.ok(error instanceof CLIError)
+            assert.strictEqual(error.message, 'Unknown command')
+            assert.strictEqual(error.exitCode, 1)
+            return true
+          }
+        )
+      } finally {
+        console.log = originalLog
+      }
+
+      assert.ok(logs[0]?.includes('test-cli'))
+    })
+
+    test('should print parse errors and throw CLIError', async () => {
+      const errors: string[] = []
+      const originalError = console.error
+      console.error = (message?: any) => {
+        errors.push(String(message))
+      }
+
+      pikkuState(null, 'cli', 'meta', {
+        programs: {
+          'test-cli': {
+            program: 'test-cli',
+            commands: {
+              greet: {
+                command: 'greet <name>',
+                pikkuFuncId: 'greetFunc',
+                positionals: [{ name: 'name', required: true }],
+                options: {},
+              },
+            },
+            options: {},
+          },
+        },
+        renderers: {},
+      })
+
+      try {
+        await assert.rejects(
+          () =>
+            executeCLI({
+              programName: 'test-cli',
+              args: ['greet'],
+              createSingletonServices: async () => singletonServices,
+            }),
+          (error: any) => {
+            assert.ok(error instanceof CLIError)
+            assert.ok(error.message.includes('Missing required argument: name'))
+            return true
+          }
+        )
+      } finally {
+        console.error = originalError
+      }
+
+      assert.strictEqual(errors[0], 'Errors:')
+      assert.ok(errors[1]?.includes('Missing required argument: name'))
+    })
+
+    test('should create config and singleton services with parsed data and execute the command', async () => {
+      let receivedConfigData: any
+      let receivedConfig: any
+      let executed = false
+
+      pikkuState(null, 'cli', 'meta', {
+        programs: {
+          'test-cli': {
+            program: 'test-cli',
+            commands: {
+              greet: {
+                command: 'greet <name>',
+                pikkuFuncId: 'greetFunc',
+                positionals: [{ name: 'name', required: true }],
+                options: {
+                  loud: {
+                    description: 'Use loud greeting',
+                    short: 'l',
+                    default: false,
+                  },
+                },
+              },
+            },
+            options: {},
+          },
+        },
+        renderers: {},
+      })
+
+      pikkuState(null, 'cli', 'programs', {
+        'test-cli': {
+          defaultRenderer: undefined,
+          middleware: [],
+          renderers: {},
+        },
+      })
+
+      pikkuState(null, 'function', 'meta', {
+        greetFunc: {
+          pikkuFuncId: 'greetFunc',
+          inputSchemaName: null,
+          outputSchemaName: null,
+          sessionless: true,
+        },
+      })
+
+      addFunction('greetFunc', {
+        func: async () => {
+          executed = true
+          return undefined
+        },
+        auth: false,
+      })
+
+      await executeCLI({
+        programName: 'test-cli',
+        args: ['greet', 'Alice', '--loud'],
+        createConfig: async (_variables, data) => {
+          receivedConfigData = data
+          return { config: true }
+        },
+        createSingletonServices: async (config) => {
+          receivedConfig = config
+          return singletonServices
+        },
+      })
+
+      assert.deepStrictEqual(receivedConfigData, {
+        name: 'Alice',
+        loud: true,
+      })
+      assert.deepStrictEqual(receivedConfig, { config: true })
+      assert.strictEqual(executed, true)
+      assert.strictEqual(
+        pikkuState(null, 'package', 'singletonServices'),
+        singletonServices
+      )
+    })
+  })
 })

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

@@ -324,6 +324,7 @@ export async function runCLICommand({
     programData?.renderers[commandId] || programData?.defaultRenderer
 
   // Create a CLI channel for progressive output
+  let cliState: unknown
   const channel: PikkuChannel<unknown, unknown> = {
     channelId: `cli:${program}:${commandId}`,
     openingData: pluckedData,
@@ -341,6 +342,13 @@ export async function runCLICommand({
       }
     },
     state: 'open',
+    setState: (s) => {
+      cliState = s
+    },
+    getState: () => cliState as any,
+    clearState: () => {
+      cliState = undefined
+    },
   }
 
   const userSession = new PikkuSessionService<CoreUserSession>(
@@ -374,16 +382,28 @@ export async function runCLICommand({
       packageName: currentCommand.packageName,
     })
 
-    // Apply renderer one final time with the final output (if renderer exists)
-    // Skip if result is undefined (void functions handle their own output)
-    if (renderer && result !== undefined) {
-      await Promise.resolve(
-        renderer(
-          singletonServices,
-          result,
-          userSession.get() as CoreUserSession | undefined
+    // Render the final result. `--json` / `--output json` routes the result
+    // through the global JSON renderer, but only for commands that opted into
+    // result-rendering by declaring a `render` — inline-printing commands (no
+    // per-command renderer) keep emitting their own output untouched.
+    // Skip if result is undefined (void functions handle their own output).
+    if (result !== undefined) {
+      const commandRenderer = programData?.renderers[commandId]
+      const jsonMode =
+        (data as any).json === true || (data as any).output === 'json'
+      const finalRenderer: CorePikkuCLIRender<any> | undefined =
+        jsonMode && commandRenderer !== undefined
+          ? defaultJSONRenderer
+          : (commandRenderer ?? programData?.defaultRenderer)
+      if (finalRenderer !== undefined) {
+        await Promise.resolve(
+          finalRenderer(
+            singletonServices,
+            result,
+            userSession.get() as CoreUserSession | undefined
+          )
         )
-      )
+      }
     }
 
     return result
@@ -476,7 +496,8 @@ export async function executeCLI({
       const hasUnknownCommand = parsed.errors.some(
         (error) =>
           error.startsWith('Unknown command:') ||
-          error.startsWith('Command not found:')
+          error.startsWith('Command not found:') ||
+          error.startsWith('Missing subcommand:')
       )
 
       if (hasUnknownCommand) {

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

@@ -256,10 +256,8 @@ export interface CoreCLICommand<
   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>>,
+  Subcommands extends Record<string, CoreCLICommandConfig<any, any, any>> =
+    Record<string, CoreCLICommandConfig<any, any, any>>,
 > {
   parameters?: string
   func: PikkuFunctionConfig
@@ -301,10 +299,8 @@ export type CLICommandDefinition<
   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>>,
+  Subcommands extends Record<string, CoreCLICommandConfig<any, any, any>> =
+    Record<string, CoreCLICommandConfig<any, any, any>>,
 > =
   | CoreCLICommand<
       In,

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

@@ -172,6 +172,23 @@ describe('Command Parser', () => {
       })
     })
 
+    test('should report missing subcommand for a group node with no func', () => {
+      const result = parseCLIArguments(['user'], 'test-cli', testMeta)
+
+      assert.deepStrictEqual(result.commandPath, ['user'])
+      assert.ok(
+        result.errors.some((error) => error.startsWith('Missing subcommand:')),
+        `expected a "Missing subcommand:" error, got: ${JSON.stringify(result.errors)}`
+      )
+    })
+
+    test('should not flag a runnable command as a missing subcommand', () => {
+      const result = parseCLIArguments(['greet', 'Alice'], 'test-cli', testMeta)
+
+      assert.deepStrictEqual(result.commandPath, ['greet'])
+      assert.strictEqual(result.errors.length, 0)
+    })
+
     test('should parse variadic positionals', () => {
       const result = parseCLIArguments(
         ['files', 'file1.txt', 'file2.txt', 'file3.txt'],
@@ -442,4 +459,70 @@ describe('Command Parser', () => {
       assert.ok(help.includes('Unknown command'))
     })
   })
+
+  describe('camelCase ↔ kebab-case options', () => {
+    const kebabMeta: CLIMeta = {
+      programs: {
+        'test-cli': {
+          program: 'test-cli',
+          options: {},
+          commands: {
+            deploy: {
+              pikkuFuncId: 'deployFunc',
+              positionals: [],
+              options: {
+                autoApply: {
+                  description: 'Deploy without the confirmation prompt',
+                  default: false,
+                },
+                apiUrl: { description: 'Override the API URL' },
+                token: { description: 'Auth token', required: true },
+              },
+            },
+          },
+        },
+      },
+      renderers: {},
+    }
+
+    test('renders camelCase option keys as kebab-case in help', () => {
+      const help = generateCommandHelp('test-cli', kebabMeta, ['deploy'])
+
+      assert.ok(help.includes('--auto-apply'), 'expected --auto-apply')
+      assert.ok(help.includes('--api-url'), 'expected --api-url')
+      assert.ok(!help.includes('--autoApply'), 'should not show camelCase')
+      assert.ok(!help.includes('--apiUrl'), 'should not show camelCase')
+    })
+
+    test('accepts the kebab-case form and maps it to the camelCase field', () => {
+      const result = parseCLIArguments(
+        ['deploy', '--auto-apply', '--api-url', 'https://x'],
+        'test-cli',
+        kebabMeta
+      )
+
+      assert.strictEqual(result.options.autoApply, true)
+      assert.strictEqual(result.options.apiUrl, 'https://x')
+    })
+
+    test('still accepts the camelCase form (back-compat)', () => {
+      const result = parseCLIArguments(
+        ['deploy', '--autoApply', '--apiUrl', 'https://x'],
+        'test-cli',
+        kebabMeta
+      )
+
+      assert.strictEqual(result.options.autoApply, true)
+      assert.strictEqual(result.options.apiUrl, 'https://x')
+    })
+
+    test('renders missing-required-option errors in kebab-case', () => {
+      const result = parseCLIArguments(['deploy'], 'test-cli', kebabMeta)
+
+      assert.ok(
+        result.errors.some((e) => e.includes('--token')),
+        'expected a missing --token error'
+      )
+    })
+  })
 })

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

@@ -11,6 +11,13 @@ function toCamelCase(str: string): string {
   return str.replace(/-([a-z])/g, (_, c) => c.toUpperCase())
 }
 
+/** Convert camelCase to kebab-case for display: "autoApply" → "auto-apply".
+ *  Flags are stored camelCase (matching the function input field) but shown
+ *  kebab; the parser accepts both forms via toCamelCase. */
+function toKebabCase(str: string): string {
+  return str.replace(/([a-z0-9])([A-Z])/g, '$1-$2').toLowerCase()
+}
+
 /**
  * Result of parsing CLI arguments
  */
@@ -111,6 +118,18 @@ export function parseCLIArguments(
     return result
   }
 
+  // A group/parent command — has subcommands but no runnable function of its
+  // own — cannot be executed directly. Surface a routable error so the runner
+  // shows its subcommand help instead of attempting to run a missing function.
+  if (
+    !commandMeta.pikkuFuncId &&
+    commandMeta.subcommands &&
+    Object.keys(commandMeta.subcommands).length > 0
+  ) {
+    result.errors.push(`Missing subcommand: ${result.commandPath.join(' ')}`)
+    return result
+  }
+
   // Collect all available options (global + inherited)
   const availableOptions = collectAvailableOptions(meta, result.commandPath)
 
@@ -366,7 +385,7 @@ function applyOptionDefaults(
 
     // Check required
     if (def.required && !(name in options)) {
-      result.errors.push(`Missing required option: --${name}`)
+      result.errors.push(`Missing required option: --${toKebabCase(name)}`)
     }
 
     // Validate choices
@@ -376,13 +395,13 @@ function applyOptionDefaults(
         for (const v of value) {
           if (!def.choices.includes(v)) {
             result.errors.push(
-              `Invalid value for --${name}: ${v}. Valid choices: ${def.choices.join(', ')}`
+              `Invalid value for --${toKebabCase(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(', ')}`
+          `Invalid value for --${toKebabCase(name)}: ${value}. Valid choices: ${def.choices.join(', ')}`
         )
       }
     }
@@ -487,7 +506,7 @@ function formatOptions(options: Record<string, CLIOption>, lines: string[]) {
     } else {
       line += '    '
     }
-    line += `--${name}`
+    line += `--${toKebabCase(name)}`
 
     if (opt.default !== undefined && typeof opt.default !== 'boolean') {
       line += ` <value>`