@pikku/core 0.12.83 → 0.12.86

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

@@ -1,7 +1,8 @@
-import { test, describe } from 'node:test'
+import { test, describe, beforeEach, after } from 'node:test'
 import * as assert from 'assert'
 import { parseCLIArguments, generateCommandHelp } from './command-parser.js'
 import type { CLIMeta } from './cli.types.js'
+import { pikkuState, resetPikkuState } from '../../pikku-state.js'
 
 const testMeta: CLIMeta = {
   programs: {
@@ -88,6 +89,30 @@ const testMeta: CLIMeta = {
             },
           },
         },
+        deploy: {
+          pikkuFuncId: 'deployFunc',
+          positionals: [],
+          options: {
+            token: {
+              description: 'Auth token',
+              short: 'k',
+              type: 'string',
+            },
+            tags: {
+              description: 'Tags to include',
+              short: 't',
+              type: 'string[]',
+            },
+            note: {
+              description: 'Free-form note',
+            },
+            dryRun: {
+              description: 'Report without deploying',
+              type: 'boolean',
+              short: 'D',
+            },
+          },
+        },
       },
     },
   },
@@ -730,4 +755,366 @@ describe('Command Parser', () => {
       })
     })
   })
+
+  describe('the option spec drives value consumption', () => {
+    test('a string option takes the next token verbatim, even leading with a dash', () => {
+      const result = parseCLIArguments(
+        ['deploy', '--token', '-PumP_kL0'],
+        'test-cli',
+        testMeta
+      )
+
+      assert.deepStrictEqual(result.errors, [])
+      assert.strictEqual(result.options.token, '-PumP_kL0')
+    })
+
+    test('an untyped option with no boolean/number default is still a string', () => {
+      const result = parseCLIArguments(
+        ['deploy', '--note', '-dash-leading'],
+        'test-cli',
+        testMeta
+      )
+
+      assert.deepStrictEqual(result.errors, [])
+      assert.strictEqual(result.options.note, '-dash-leading')
+    })
+
+    test('a comma list into an array option splits, trims and drops blanks', () => {
+      const result = parseCLIArguments(
+        ['deploy', '--tags', 'alpha, beta ,,gamma'],
+        'test-cli',
+        testMeta
+      )
+
+      assert.deepStrictEqual(result.errors, [])
+      assert.deepStrictEqual(result.options.tags, ['alpha', 'beta', 'gamma'])
+    })
+
+    test('an array option splits the --opt=value form too', () => {
+      const result = parseCLIArguments(
+        ['deploy', '--tags=alpha,beta'],
+        'test-cli',
+        testMeta
+      )
+
+      assert.deepStrictEqual(result.options.tags, ['alpha', 'beta'])
+    })
+
+    test('an array option consumes exactly one token', () => {
+      const result = parseCLIArguments(
+        ['deploy', '--tags', 'alpha,beta', '--note', 'hello'],
+        'test-cli',
+        testMeta
+      )
+
+      assert.deepStrictEqual(result.errors, [])
+      assert.deepStrictEqual(result.options.tags, ['alpha', 'beta'])
+      assert.strictEqual(result.options.note, 'hello')
+    })
+
+    /**
+     * `--tags alpha beta` cannot be told apart from an option followed by a
+     * positional, so consuming tokens until the next flag would make an array
+     * option swallow arguments meant for the command. The two unambiguous
+     * forms — one comma list, or the flag repeated — cover the same ground,
+     * and the leftover token is reported rather than silently dropped.
+     */
+    test('an array option leaves a following bare token to the positionals', () => {
+      const result = parseCLIArguments(
+        ['deploy', '--tags', 'alpha', 'beta'],
+        'test-cli',
+        testMeta
+      )
+
+      assert.deepStrictEqual(result.options.tags, ['alpha'])
+      assert.ok(
+        result.errors.some((error) => error.includes('Unexpected arguments')),
+        `expected the stray token to be reported, got: ${JSON.stringify(result.errors)}`
+      )
+    })
+
+    test('a repeated array option accumulates', () => {
+      const result = parseCLIArguments(
+        ['deploy', '--tags', 'alpha', '--tags', 'beta,gamma'],
+        'test-cli',
+        testMeta
+      )
+
+      assert.deepStrictEqual(result.options.tags, ['alpha', 'beta', 'gamma'])
+    })
+
+    test('an array option takes a dash-leading value verbatim', () => {
+      const result = parseCLIArguments(
+        ['deploy', '--tags', '-alpha,beta'],
+        'test-cli',
+        testMeta
+      )
+
+      assert.deepStrictEqual(result.errors, [])
+      assert.deepStrictEqual(result.options.tags, ['-alpha', 'beta'])
+    })
+
+    test('a comma in a non-array option stays one literal string', () => {
+      const result = parseCLIArguments(
+        ['deploy', '--note', 'alpha,beta'],
+        'test-cli',
+        testMeta
+      )
+
+      assert.strictEqual(result.options.note, 'alpha,beta')
+    })
+
+    test('a boolean option does not consume a following non-literal token', () => {
+      const result = parseCLIArguments(
+        ['deploy', '--dry-run', '--note', 'hello'],
+        'test-cli',
+        testMeta
+      )
+
+      assert.deepStrictEqual(result.errors, [])
+      assert.strictEqual(result.options.dryRun, true)
+      assert.strictEqual(result.options.note, 'hello')
+    })
+
+    test('boolean options take an explicit literal instead of leaking positionals', () => {
+      const devMeta: CLIMeta = {
+        programs: {
+          'dev-cli': {
+            program: 'dev-cli',
+            options: {},
+            commands: {
+              dev: {
+                pikkuFuncId: 'devFunc',
+                positionals: [],
+                options: {
+                  port: {
+                    description: 'Port for the dev server',
+                    default: '3000',
+                    short: 'p',
+                  },
+                  watch: {
+                    description: 'Watch for file changes and regenerate',
+                    default: true,
+                  },
+                  hmr: {
+                    description: 'Enable hot module reload',
+                    default: true,
+                  },
+                },
+              },
+            },
+          },
+        },
+        renderers: {},
+      }
+
+      const result = parseCLIArguments(
+        ['dev', '--port', '4077', '--watch', 'false', '--hmr', 'false'],
+        'dev-cli',
+        devMeta
+      )
+
+      assert.deepStrictEqual(result.errors, [])
+      assert.deepStrictEqual(result.positionals, {})
+      assert.strictEqual(result.options.port, '4077')
+      assert.strictEqual(result.options.watch, false)
+      assert.strictEqual(result.options.hmr, false)
+    })
+
+    test('a typed boolean option with no default takes an explicit literal', () => {
+      const result = parseCLIArguments(
+        ['deploy', '--dry-run', 'false', '--note', 'hello'],
+        'test-cli',
+        testMeta
+      )
+
+      assert.deepStrictEqual(result.errors, [])
+      assert.strictEqual(result.options.dryRun, false)
+      assert.strictEqual(result.options.note, 'hello')
+    })
+
+    test('a boolean option takes an explicit literal in the --opt=value form', () => {
+      const result = parseCLIArguments(
+        ['deploy', '--dry-run=false'],
+        'test-cli',
+        testMeta
+      )
+
+      assert.deepStrictEqual(result.errors, [])
+      assert.strictEqual(result.options.dryRun, false)
+    })
+
+    test('a boolean short flag takes an explicit literal', () => {
+      const result = parseCLIArguments(
+        ['deploy', '-D', 'false'],
+        'test-cli',
+        testMeta
+      )
+
+      assert.deepStrictEqual(result.errors, [])
+      assert.strictEqual(result.options.dryRun, false)
+    })
+
+    test('a short flag follows its option spec for dash-leading values', () => {
+      const result = parseCLIArguments(
+        ['deploy', '-k', '-PumP_kL0'],
+        'test-cli',
+        testMeta
+      )
+
+      assert.deepStrictEqual(result.errors, [])
+      assert.strictEqual(result.options.token, '-PumP_kL0')
+    })
+
+    test('a short flag for an array option splits on commas', () => {
+      const result = parseCLIArguments(
+        ['deploy', '-t', 'alpha,beta'],
+        'test-cli',
+        testMeta
+      )
+
+      assert.deepStrictEqual(result.options.tags, ['alpha', 'beta'])
+    })
+
+    test('a boolean short flag in a cluster does not swallow the next token', () => {
+      const result = parseCLIArguments(
+        ['deploy', '-D', 'positional-would-error'],
+        'test-cli',
+        testMeta
+      )
+
+      assert.strictEqual(result.options.dryRun, true)
+      assert.ok(
+        result.errors.some((e) => e.includes('Unexpected arguments')),
+        `expected the token to stay a positional, got: ${result.errors.join(', ')}`
+      )
+    })
+  })
+})
+
+describe('option types come from the function input schema', () => {
+  const schemaMeta: CLIMeta = {
+    programs: {
+      'test-cli': {
+        program: 'test-cli',
+        options: {},
+        commands: {
+          serve: {
+            pikkuFuncId: 'serveFunc',
+            positionals: [],
+            options: {
+              console: { description: 'Serve the console' },
+              port: { description: 'Port to listen on' },
+              tags: { description: 'Tags to include' },
+              retries: { description: 'How many times to retry' },
+              declared: {
+                description: 'Declared against the schema',
+                type: 'string',
+              },
+            },
+          },
+        },
+      },
+    },
+    renderers: {},
+  }
+
+  const registerSchema = (properties: Record<string, unknown>) => {
+    pikkuState(null, 'function', 'meta')['serveFunc'] = {
+      pikkuFuncId: 'serveFunc',
+      inputSchemaName: 'ServeInput',
+      outputSchemaName: null,
+      sessionless: true,
+    } as any
+    pikkuState(null, 'misc', 'schemas').set('ServeInput', {
+      type: 'object',
+      properties,
+    })
+  }
+
+  beforeEach(() => {
+    resetPikkuState()
+    registerSchema({
+      console: { type: 'boolean' },
+      port: { type: 'string' },
+      tags: { type: 'array', items: { type: 'string' } },
+      retries: { type: 'number' },
+      declared: { type: 'boolean' },
+    })
+  })
+
+  after(() => {
+    resetPikkuState()
+  })
+
+  test('a boolean in the schema is a flag, and does not swallow the next option', () => {
+    const result = parseCLIArguments(
+      ['serve', '--console', '--port', '4077'],
+      'test-cli',
+      schemaMeta
+    )
+
+    assert.deepStrictEqual(result.errors, [])
+    assert.strictEqual(result.options.console, true)
+    assert.strictEqual(result.options.port, '4077')
+  })
+
+  test('an array in the schema splits on commas without being declared', () => {
+    const result = parseCLIArguments(
+      ['serve', '--tags', 'alpha,beta'],
+      'test-cli',
+      schemaMeta
+    )
+
+    assert.deepStrictEqual(result.options.tags, ['alpha', 'beta'])
+  })
+
+  test('a number in the schema is coerced', () => {
+    const result = parseCLIArguments(
+      ['serve', '--retries', '3'],
+      'test-cli',
+      schemaMeta
+    )
+
+    assert.strictEqual(result.options.retries, 3)
+  })
+
+  test('a declared type wins over the schema', () => {
+    const result = parseCLIArguments(
+      ['serve', '--declared', 'true'],
+      'test-cli',
+      schemaMeta
+    )
+
+    assert.strictEqual(result.options.declared, 'true')
+  })
+
+  test('an option the schema does not mention keeps the string default', () => {
+    registerSchema({ console: { type: 'boolean' } })
+
+    const result = parseCLIArguments(
+      ['serve', '--port', '4077'],
+      'test-cli',
+      schemaMeta
+    )
+
+    assert.strictEqual(result.options.port, '4077')
+  })
+
+  test('a command with no input schema parses as it did before', () => {
+    pikkuState(null, 'function', 'meta')['serveFunc'] = {
+      pikkuFuncId: 'serveFunc',
+      inputSchemaName: null,
+      outputSchemaName: null,
+      sessionless: true,
+    } as any
+
+    const result = parseCLIArguments(
+      ['serve', '--tags', 'alpha,beta'],
+      'test-cli',
+      schemaMeta
+    )
+
+    assert.strictEqual(result.options.tags, 'alpha,beta')
+  })
 })

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

@@ -4,7 +4,9 @@ import type {
   CLICommandMeta,
   CLIPositional,
   CLIOption,
+  CLIOptionType,
 } from './cli.types.js'
+import { pikkuState } from '../../pikku-state.js'
 
 /** "from-plan" → "fromPlan"; the parser accepts either spelling. */
 function toCamelCase(str: string): string {
@@ -95,6 +97,136 @@ export interface ParsedCommand {
  */
 const MAX_SHORT_FLAG_CLUSTER = 64
 
+function resolveOptionType(optionDef: CLIOption): CLIOptionType {
+  if (optionDef.type) {
+    return optionDef.type
+  }
+  if (typeof optionDef.default === 'boolean') {
+    return 'boolean'
+  }
+  if (typeof optionDef.default === 'number') {
+    return 'number'
+  }
+  return 'string'
+}
+
+/**
+ * A command's options are keys of its function's input, so the input schema
+ * already records what each one is. Reading it here means a declaration never
+ * has to repeat — or contradict — the type the function is validated against.
+ * An explicit `type` still wins, and an option the schema says nothing about
+ * (a program-level option belonging to no function input) is left untouched.
+ */
+function applySchemaOptionTypes(
+  options: Record<string, CLIOption>,
+  commandMeta: CLICommandMeta
+): Record<string, CLIOption> {
+  const properties = commandInputProperties(commandMeta)
+  if (!properties) {
+    return options
+  }
+
+  const typed: Record<string, CLIOption> = { ...options }
+  for (const [name, option] of Object.entries(typed)) {
+    if (option.type) {
+      continue
+    }
+    const schemaType = optionTypeFromSchema(properties[name])
+    if (schemaType) {
+      typed[name] = { ...option, type: schemaType }
+    }
+  }
+  return typed
+}
+
+function commandInputProperties(
+  commandMeta: CLICommandMeta
+): Record<string, any> | null {
+  const funcMeta = pikkuState(null, 'function', 'meta')[commandMeta.pikkuFuncId]
+  const schemaName = funcMeta?.inputSchemaName
+  if (!schemaName) {
+    return null
+  }
+  const schema = pikkuState(
+    funcMeta.packageName ?? null,
+    'misc',
+    'schemas'
+  ).get(schemaName)
+  const properties = schema?.properties
+  return properties && typeof properties === 'object' ? properties : null
+}
+
+function optionTypeFromSchema(property: any): CLIOptionType | undefined {
+  if (!property || typeof property !== 'object') {
+    return undefined
+  }
+  // An optional field can arrive as a union with null, which is not a shape the
+  // parser can read a value into.
+  const declared = Array.isArray(property.type)
+    ? property.type.filter((entry: unknown) => entry !== 'null')[0]
+    : property.type
+
+  switch (declared) {
+    case 'array':
+      return 'string[]'
+    case 'number':
+    case 'integer':
+      return 'number'
+    case 'boolean':
+      return 'boolean'
+    case 'string':
+      return 'string'
+    default:
+      return undefined
+  }
+}
+
+const BOOLEAN_LITERALS = new Map<string, boolean>([
+  ['true', true],
+  ['false', false],
+  ['1', true],
+  ['0', false],
+  ['yes', true],
+  ['no', false],
+])
+
+/**
+ * A boolean option is a flag, but `--watch false` is how scripts and CI turn a
+ * default-on flag off, so an explicit literal directly after the flag is taken
+ * as its value rather than left behind as a positional.
+ */
+function readBooleanLiteral(raw: string | undefined): boolean | undefined {
+  if (raw === undefined) {
+    return undefined
+  }
+  return BOOLEAN_LITERALS.get(raw.toLowerCase())
+}
+
+function readOptionValue(raw: string, optionDef: CLIOption): any {
+  if (resolveOptionType(optionDef) !== 'string[]') {
+    return parseOptionValue(raw, optionDef)
+  }
+  return raw
+    .split(',')
+    .map((item) => item.trim())
+    .filter((item) => item.length > 0)
+    .map((item) => parseOptionValue(item, optionDef))
+}
+
+/** A repeated array option accumulates rather than replacing. */
+function assignOptionValue(
+  optionArgs: Record<string, any>,
+  key: string,
+  value: any
+) {
+  const existing = optionArgs[key]
+  if (Array.isArray(existing) && Array.isArray(value)) {
+    optionArgs[key] = [...existing, ...value]
+  } else {
+    optionArgs[key] = value
+  }
+}
+
 export function parseCLIArguments(
   args: string[],
   programName: string,
@@ -186,7 +318,10 @@ export function parseCLIArguments(
     return result
   }
 
-  const availableOptions = collectAvailableOptions(meta, result.commandPath)
+  const availableOptions = applySchemaOptionTypes(
+    collectAvailableOptions(meta, result.commandPath),
+    commandMeta
+  )
 
   const positionalArgs: string[] = []
   const optionArgs: Record<string, any> = {}
@@ -201,9 +336,10 @@ export function parseCLIArguments(
       const equalIndex = arg.indexOf('=')
       if (
         negatedKey &&
-        typeof availableOptions[negatedKey]?.default === 'boolean'
+        availableOptions[negatedKey] &&
+        resolveOptionType(availableOptions[negatedKey]) === 'boolean'
       ) {
-        // Requiring a boolean default keeps a literal `--no-something` option
+        // Requiring a boolean type keeps a literal `--no-something` option
         // name parsing as itself rather than as a negation.
         optionArgs[negatedKey] = false
       } else if (equalIndex > 0) {
@@ -215,7 +351,11 @@ export function parseCLIArguments(
         }
 
         const value = arg.slice(equalIndex + 1)
-        optionArgs[key] = parseOptionValue(value, optionDef)
+        if (optionDef) {
+          assignOptionValue(optionArgs, key, readOptionValue(value, optionDef))
+        } else {
+          optionArgs[key] = parseOptionValue(value, optionDef)
+        }
       } else {
         const key = toCamelCase(arg.slice(2))
         const optionDef = availableOptions[key]
@@ -224,24 +364,33 @@ export function parseCLIArguments(
           warnUnknownOption(arg.slice(2), availableOptions, result)
         }
 
-        if (optionDef && optionDef.array) {
-          currentIndex++
-          const values: any[] = []
-          while (
-            currentIndex < args.length &&
-            !args[currentIndex].startsWith('-')
+        if (!optionDef) {
+          // With no spec there is nothing to consult, so the lookahead
+          // heuristic is all that is left.
+          if (
+            currentIndex + 1 < args.length &&
+            !args[currentIndex + 1].startsWith('-')
           ) {
-            values.push(parseOptionValue(args[currentIndex], optionDef))
             currentIndex++
+            optionArgs[key] = parseOptionValue(args[currentIndex], optionDef)
+          } else {
+            optionArgs[key] = true
           }
-          currentIndex-- // Back up one since we'll increment at loop end
-          optionArgs[key] = values
-        } else if (
-          currentIndex + 1 < args.length &&
-          !args[currentIndex + 1].startsWith('-')
-        ) {
+        } else if (resolveOptionType(optionDef) === 'boolean') {
+          const literal = readBooleanLiteral(args[currentIndex + 1])
+          if (literal === undefined) {
+            optionArgs[key] = true
+          } else {
+            currentIndex++
+            optionArgs[key] = literal
+          }
+        } else if (currentIndex + 1 < args.length) {
           currentIndex++
-          optionArgs[key] = parseOptionValue(args[currentIndex], optionDef)
+          assignOptionValue(
+            optionArgs,
+            key,
+            readOptionValue(args[currentIndex], optionDef)
+          )
         } else {
           optionArgs[key] = true
         }
@@ -259,16 +408,27 @@ export function parseCLIArguments(
 
         const longOption = findLongOption(shortFlag, availableOptions)
         if (longOption) {
+          const optionDef = availableOptions[longOption]
           // Only the last flag in a cluster can take a value.
-          if (
-            i === arg.length - 1 &&
-            currentIndex + 1 < args.length &&
-            !args[currentIndex + 1].startsWith('-')
+          const isLast = i === arg.length - 1
+          const literal =
+            isLast && resolveOptionType(optionDef) === 'boolean'
+              ? readBooleanLiteral(args[currentIndex + 1])
+              : undefined
+
+          if (literal !== undefined) {
+            currentIndex++
+            optionArgs[longOption] = literal
+          } else if (
+            isLast &&
+            resolveOptionType(optionDef) !== 'boolean' &&
+            currentIndex + 1 < args.length
           ) {
             currentIndex++
-            optionArgs[longOption] = parseOptionValue(
-              args[currentIndex],
-              availableOptions[longOption]
+            assignOptionValue(
+              optionArgs,
+              longOption,
+              readOptionValue(args[currentIndex], optionDef)
             )
           } else {
             optionArgs[longOption] = true
@@ -362,11 +522,11 @@ function parseOptionValue(value: string, optionDef?: CLIOption): any {
     return value
   }
 
-  const defaultValue = optionDef.default
-  if (typeof defaultValue === 'boolean') {
-    return value === 'true' || value === '1' || value === 'yes'
+  const optionType = resolveOptionType(optionDef)
+  if (optionType === 'boolean') {
+    return readBooleanLiteral(value) ?? false
   }
-  if (typeof defaultValue === 'number') {
+  if (optionType === 'number') {
     return parseFloat(value)
   }
 

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

@@ -9,8 +9,7 @@ import type {
   GatewayInboundMessage,
   GatewayOutboundMessage,
 } from './gateway.types.js'
-import type { CorePikkuMiddleware } from '../../types/core.types.js'
-
+import type { CorePikkuMiddleware } from '../../middleware/middleware.types.js'
 const createMockAdapter = (
   opts: {
     name?: string