@pikku/core 0.12.2 → 0.12.4

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

@@ -1,519 +0,0 @@
-import { NotFoundError, PikkuMissingMetaError } from '../../errors/errors.js'
-import { addFunction, runPikkuFunc } from '../../function/function-runner.js'
-import { pikkuState } from '../../pikku-state.js'
-import type {
-  CorePikkuMiddleware,
-  CoreUserSession,
-} from '../../types/core.types.js'
-import type {
-  CoreCLI,
-  CLICommandMeta,
-  CLIOption,
-  CLIProgramState,
-  CorePikkuCLIRender,
-  CoreCLICommandConfig,
-  CLIMeta,
-} from './cli.types.js'
-import type {
-  CoreSingletonServices,
-  CoreServices,
-  CreateWireServices,
-  PikkuWire,
-  CreateConfig,
-  CreateSingletonServices,
-} from '../../types/core.types.js'
-import type { PikkuChannel } from '../channel/channel.types.js'
-import {
-  PikkuSessionService,
-  createMiddlewareSessionWireProps,
-} 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
- */
-const defaultJSONRenderer: CorePikkuCLIRender<any> = (_services, data) => {
-  console.log(JSON.stringify(data, null, 2))
-}
-
-/**
- * Registers a CLI command tree and all its functions
- */
-export const wireCLI = <
-  Commands extends Record<string, CoreCLICommandConfig<any, any, any>>,
-  GlobalOptions,
-  PikkuMiddleware extends CorePikkuMiddleware,
-  GlobalOutput,
->(
-  cli: CoreCLI<Commands, GlobalOptions, PikkuMiddleware, GlobalOutput>
-) => {
-  // Get the existing metadata that was generated during inspection
-  const cliMeta = pikkuState(null, 'cli', 'meta') || {}
-
-  if (!cliMeta.programs?.[cli.program]) {
-    throw new PikkuMissingMetaError(
-      `CLI metadata not found for program '${cli.program}'`
-    )
-  }
-
-  // Get existing programs state and add this program
-  const programs: Record<string, CLIProgramState> =
-    pikkuState(null, 'cli', 'programs') || {}
-  programs[cli.program] = {
-    defaultRenderer: (cli.render ||
-      defaultJSONRenderer) as CorePikkuCLIRender<any>,
-    middleware: cli.middleware || [],
-    renderers: {},
-    tags: cli.tags,
-  }
-  pikkuState(null, 'cli', 'programs', programs)
-
-  // Register all command functions recursively
-  registerCLICommands(
-    cli.commands as Record<string, any>,
-    [],
-    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: any): {
-  func: Function
-  middleware?: any[]
-  auth?: boolean
-  permissions?: any
-  tags?: string[]
-} {
-  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: Record<string, any>,
-  path: string[] = [],
-  inheritedOptions: Record<string, CLIOption> = {},
-  program: string
-) {
-  // Get the CLI metadata to find actual function names
-  const cliMeta = pikkuState(null, 'cli', 'meta').programs[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: CLICommandMeta | undefined = cliMeta?.commands[fullPath[0]]
-    for (let i = 1; i < fullPath.length; i++) {
-      currentMeta = currentMeta?.subcommands?.[fullPath[i]]
-    }
-    const funcName = currentMeta?.pikkuFuncId
-
-    // 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: Record<string, CLIProgramState> = pikkuState(
-      null,
-      '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: Record<string, any>,
-  funcName: string,
-  availableOptions: Record<string, CLIOption>
-): Record<string, any> {
-  const funcMeta = pikkuState(null, 'function', 'meta')[funcName]
-  const schemaName = funcMeta?.inputSchemaName
-  const schema = schemaName
-    ? pikkuState(null, 'misc', 'schemas').get(schemaName)
-    : null
-
-  if (schema && schema.properties) {
-    // If we have a schema, only include fields that are in the schema
-    const result: Record<string, any> = {}
-    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,
-  createWireServices,
-}: {
-  program: string
-  commandPath: string[]
-  data: Record<string, any>
-  singletonServices: CoreSingletonServices
-  createWireServices?: CreateWireServices
-}): Promise<any> {
-  // Get the command metadata to find the function name
-  const cliMeta = pikkuState(null, 'cli', 'meta')
-  const programMeta = cliMeta.programs?.[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.pikkuFuncId
-
-  // Get program-specific data
-  const programs: Record<string, CLIProgramState> =
-    pikkuState(null, 'cli', 'programs') || {}
-  const programData = programs[program]
-
-  // Combine program middleware + command middleware from the hierarchy
-  const allWireMiddleware: CorePikkuMiddleware[] = [
-    ...(programData?.middleware || []),
-  ]
-
-  // Walk through the command path and collect middleware from the runtime config
-  const commandParts: string[] = []
-  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: PikkuChannel<unknown, unknown> = {
-    channelId: `cli:${program}:${commandId}`,
-    openingData: pluckedData,
-    send: async (data: any) => {
-      if (renderer) {
-        await Promise.resolve(renderer(singletonServices, data, undefined))
-      }
-    },
-    sendBinary: () => {
-      throw new Error('Binary data is not supported on CLI channels')
-    },
-    close: () => {
-      if (channel) {
-        channel.state = 'closed'
-      }
-    },
-    state: 'open',
-  }
-
-  const userSession = new PikkuSessionService<CoreUserSession>()
-
-  const wire: PikkuWire = {
-    cli: {
-      program,
-      command: commandPath,
-      data: pluckedData,
-      channel,
-    },
-    ...createMiddlewareSessionWireProps(userSession),
-  }
-
-  try {
-    const result = await runPikkuFunc('cli', commandId, funcName, {
-      singletonServices,
-      createWireServices,
-      data: pluckedData,
-      auth: false,
-      inheritedMiddleware: currentCommand.middleware,
-      wireMiddleware: allWireMiddleware,
-      inheritedPermissions: currentCommand.permissions,
-      wirePermissions: undefined,
-      tags: programData?.tags,
-      wire,
-      sessionService: userSession,
-    })
-
-    // 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
-        )
-      )
-    }
-
-    return result
-  } finally {
-    // Close the channel
-    channel.close()
-  }
-}
-
-/**
- * Factory function for CLI-specific renderers
- */
-export const pikkuCLIRender = <
-  Data,
-  Services extends CoreSingletonServices = CoreServices,
-  Session extends CoreUserSession = CoreUserSession,
->(
-  renderer: (
-    services: Services,
-    data: Data,
-    session?: Session
-  ) => void | Promise<void>
-): CorePikkuCLIRender<Data, Services, Session> => {
-  return renderer
-}
-
-/**
- * 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,
-  createConfig,
-  createSingletonServices,
-  createWireServices,
-}: {
-  programName: string
-  args?: string[]
-  createConfig?: CreateConfig<any, any>
-  createSingletonServices: CreateSingletonServices<any, any>
-  createWireServices?: CreateWireServices<any, 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(null, '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/docs/pikku-cli/errors/pku342 for more information.'
-      )
-    }
-    const programMeta = allCLIMeta.programs[programName]
-
-    if (!programMeta) {
-      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)
-    // 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,
-        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)
-        throw new CLIError('Unknown command', 1)
-      } else {
-        // Show errors for other types of errors
-        console.error('Errors:')
-        parsed.errors.forEach((error) => console.error(`  ${error}`))
-        throw new CLIError(parsed.errors.join('\n'), 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 = createConfig
-      ? await createConfig(new LocalVariablesService(), data)
-      : ({} as any)
-
-    // Create services with config
-    const singletonServices = await createSingletonServices(config)
-
-    // Execute the command
-    await runCLICommand({
-      program: programName,
-      commandPath: parsed.commandPath,
-      data,
-      singletonServices,
-      createWireServices,
-    })
-  } 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
-    if (args.includes('--verbose') || args.includes('-v')) {
-      console.error('Stack trace:', error.stack)
-    }
-
-    throw new CLIError(error.message || String(error), 1)
-  }
-}