@pikku/cli 0.9.15 → 0.10.0

package/src/functions/wirings/cli/pikku-command-cli-entry.ts

@@ -0,0 +1,216 @@
+import { pikkuSessionlessFunc } from '../../../../.pikku/pikku-types.gen.js'
+import { writeFileInDir } from '../../../utils/file-writer.js'
+import { checkRequiredTypes } from '../../../utils/check-required-types.js'
+import { logCommandInfoAndTime } from '../../../middleware/log-command-info-and-time.js'
+import { join } from 'node:path'
+import { serializeLocalCLIBootstrap } from './serialize-local-cli-bootstrap.js'
+import { serializeChannelCLI } from './serialize-channel-cli.js'
+import {
+  serializeChannelCLIClient,
+  collectRendererNames,
+} from './serialize-channel-cli-client.js'
+import { existsSync } from 'fs'
+import { rm } from 'fs/promises'
+import { ErrorCode } from '@pikku/inspector'
+
+export const pikkuCLIEntry: any = pikkuSessionlessFunc<void, void>({
+  func: async ({ logger, config, getInspectorState }) => {
+    const visitState = await getInspectorState()
+
+    // Check if CLI entrypoints are configured
+    if (
+      !config.cli?.entrypoints ||
+      Object.keys(config.cli.entrypoints).length === 0
+    ) {
+      logger.info({
+        message:
+          'No CLI entrypoints configured in config.cli.entrypoints, skipping CLI bootstrap generation',
+        type: 'skip',
+      })
+      return
+    }
+
+    // Generate bootstrap files for each configured entrypoint
+    for (const [programName, entrypointConfigs] of Object.entries(
+      config.cli.entrypoints
+    )) {
+      const programMeta = visitState.cli.meta.programs[programName]
+
+      if (!programMeta) {
+        logger.warn(
+          `CLI program '${programName}' not found in metadata, skipping`
+        )
+        continue
+      }
+
+      // Normalize to array
+      const configs = Array.isArray(entrypointConfigs)
+        ? entrypointConfigs
+        : [entrypointConfigs]
+
+      for (const entrypointConfig of configs) {
+        // Normalize entrypoint config to get type
+        const entrypointType =
+          typeof entrypointConfig === 'string'
+            ? 'cli'
+            : entrypointConfig.type || 'cli'
+
+        // Handle channel type entrypoint
+        if (entrypointType === 'channel') {
+          if (
+            typeof entrypointConfig === 'string' ||
+            entrypointConfig.type !== 'channel'
+          ) {
+            throw new Error('Channel entrypoint must be a channel type object')
+          }
+
+          const channelWirePath = entrypointConfig.wirePath
+          const channelClientPath = entrypointConfig.path
+          const channelName = entrypointConfig.name
+          const channelRoute = entrypointConfig.route
+
+          const channelWireFile = join(config.rootDir, channelWirePath)
+
+          const channelCode = serializeChannelCLI(
+            programName,
+            programMeta,
+            channelWireFile,
+            visitState.functions.files,
+            config.packageMappings,
+            config.channelsTypesFile,
+            config.functionTypesFile,
+            channelName,
+            channelRoute
+          )
+
+          await writeFileInDir(logger, channelWireFile, channelCode)
+          logger.debug(
+            `Serialized CLI channel for ${programName}: ${channelWireFile}`
+          )
+
+          // Generate client code if clientPath is provided
+          if (channelClientPath) {
+            const channelClientFile = join(config.rootDir, channelClientPath)
+
+            // Validate that renderers don't depend on services (client-side renderers can't access server services)
+            const rendererNames = collectRendererNames(programMeta)
+            const problematicRenderers: Array<{
+              name: string
+              services: string[]
+            }> = []
+
+            for (const rendererName of rendererNames) {
+              const rendererMeta = visitState.cli.meta.renderers[rendererName]
+              if (rendererMeta?.services?.services?.length > 0) {
+                problematicRenderers.push({
+                  name: rendererName,
+                  services: rendererMeta.services.services,
+                })
+              }
+            }
+
+            // If any renderers depend on services, abort client generation
+            if (problematicRenderers.length > 0) {
+              const details = problematicRenderers
+                .map(
+                  (r) => `  - ${r.name} depends on: ${r.services.join(', ')}`
+                )
+                .join('\n')
+
+              logger.critical(
+                ErrorCode.CLI_CLIENTSIDE_RENDERER_HAS_SERVICES,
+                `Cannot generate CLI channel client for '${programName}': renderers cannot depend on services (client-side execution)\n${details}\n\nRenderers used in CLI-over-channel must be service-free since they execute on the client.`
+              )
+
+              // Delete existing client file if it exists
+              if (existsSync(channelClientFile)) {
+                await rm(channelClientFile)
+                logger.debug(
+                  `Deleted existing CLI channel client: ${channelClientFile}`
+                )
+              }
+
+              continue
+            }
+
+            const clientCode = serializeChannelCLIClient(
+              programName,
+              programMeta,
+              channelClientFile,
+              config,
+              config.bootstrapFile,
+              channelRoute,
+              visitState.cli.meta.renderers
+            )
+
+            await writeFileInDir(logger, channelClientFile, clientCode)
+            logger.debug(
+              `Serialized CLI channel client for ${programName}: ${channelClientFile}`
+            )
+          }
+
+          continue
+        }
+
+        // Handle CLI type entrypoint (default)
+        const entrypointPath =
+          typeof entrypointConfig === 'string'
+            ? entrypointConfig
+            : entrypointConfig.type === 'cli'
+              ? entrypointConfig.path
+              : undefined
+
+        if (!entrypointPath) {
+          throw new Error(
+            `CLI entrypoint must have a path: ${JSON.stringify(entrypointConfig)}`
+          )
+        }
+
+        const bootstrapFile = join(config.rootDir, entrypointPath)
+
+        // Get service factories for local mode
+        // Check for required types
+        checkRequiredTypes(visitState.filesAndMethodsErrors, {
+          config: true,
+          singletonServicesFactory: true,
+          sessionServicesFactory: true,
+        })
+
+        const {
+          pikkuConfigFactory,
+          singletonServicesFactory,
+          sessionServicesFactory,
+        } = visitState.filesAndMethods
+
+        if (
+          !pikkuConfigFactory ||
+          !singletonServicesFactory ||
+          !sessionServicesFactory
+        ) {
+          throw new Error('Required types not found')
+        }
+
+        const bootstrapCode = serializeLocalCLIBootstrap(
+          programName,
+          programMeta,
+          bootstrapFile,
+          config,
+          pikkuConfigFactory,
+          singletonServicesFactory,
+          sessionServicesFactory
+        )
+
+        await writeFileInDir(logger, bootstrapFile, bootstrapCode)
+        logger.debug(
+          `Serialized CLI bootstrap for ${programName}: ${bootstrapFile}`
+        )
+      }
+    }
+  },
+  middleware: [
+    logCommandInfoAndTime({
+      commandStart: 'Serializing CLI',
+      commandEnd: 'Serialized CLI',
+    }),
+  ],
+})

package/src/functions/wirings/cli/pikku-command-cli-types.ts

@@ -0,0 +1,48 @@
+import { pikkuSessionlessFunc } from '../../../../.pikku/pikku-types.gen.js'
+import { writeFileInDir } from '../../../utils/file-writer.js'
+import { getFileImportRelativePath } from '../../../utils/file-import-path.js'
+import { logCommandInfoAndTime } from '../../../middleware/log-command-info-and-time.js'
+import { serializeCLITypes } from './serialize-cli-types.js'
+import { checkRequiredTypes } from '../../../utils/check-required-types.js'
+
+export const pikkuCLITypes: any = pikkuSessionlessFunc<void, void>({
+  func: async ({ logger, config, getInspectorState }) => {
+    const { cliTypesFile, functionTypesFile, packageMappings } = config
+    const visitState = await getInspectorState()
+
+    const functionTypesImportPath = getFileImportRelativePath(
+      cliTypesFile,
+      functionTypesFile,
+      packageMappings
+    )
+
+    // Check for required types
+    checkRequiredTypes(visitState.filesAndMethodsErrors, {
+      userSessionType: true,
+      sessionServiceType: true,
+      singletonServicesType: true,
+    })
+
+    const { userSessionType, singletonServicesType } =
+      visitState.filesAndMethods
+
+    if (!userSessionType || !singletonServicesType) {
+      throw new Error('Required types not found')
+    }
+
+    const content = serializeCLITypes(
+      functionTypesImportPath,
+      `import type { ${userSessionType.type} } from '${getFileImportRelativePath(cliTypesFile, userSessionType.typePath, packageMappings)}'`,
+      userSessionType.type,
+      `import type { ${singletonServicesType.type} } from '${getFileImportRelativePath(cliTypesFile, singletonServicesType.typePath, packageMappings)}'`,
+      singletonServicesType.type
+    )
+    await writeFileInDir(logger, cliTypesFile, content)
+  },
+  middleware: [
+    logCommandInfoAndTime({
+      commandStart: 'Creating CLI types',
+      commandEnd: 'Created CLI types',
+    }),
+  ],
+})

package/src/functions/wirings/cli/pikku-command-cli.ts

@@ -0,0 +1,39 @@
+import { pikkuSessionlessFunc } from '../../../../.pikku/pikku-types.gen.js'
+import { serializeFileImports } from '../../../utils/file-imports-serializer.js'
+import { writeFileInDir } from '../../../utils/file-writer.js'
+import { logCommandInfoAndTime } from '../../../middleware/log-command-info-and-time.js'
+
+export const pikkuCLI: any = pikkuSessionlessFunc<void, boolean | undefined>({
+  func: async ({ logger, config, getInspectorState }) => {
+    const visitState = await getInspectorState()
+    const { cliWiringsFile, cliWiringMetaFile, packageMappings } = config
+    const { cli } = visitState
+
+    // Generate CLI wirings file
+    await writeFileInDir(
+      logger,
+      cliWiringsFile,
+      serializeFileImports(
+        'wireCLI',
+        cliWiringsFile,
+        cli.files,
+        packageMappings
+      )
+    )
+
+    // Generate CLI metadata file
+    await writeFileInDir(
+      logger,
+      cliWiringMetaFile,
+      `import { pikkuState } from '@pikku/core'\npikkuState('cli', 'meta', ${JSON.stringify(cli.meta, null, 2)})`
+    )
+
+    return true
+  },
+  middleware: [
+    logCommandInfoAndTime({
+      commandStart: 'Finding CLI commands',
+      commandEnd: 'Found CLI commands',
+    }),
+  ],
+})

package/src/functions/wirings/cli/serialize-channel-cli-client.ts

@@ -0,0 +1,171 @@
+import { CLIProgramMeta, CLICommandMeta } from '@pikku/core/cli'
+import { getFileImportRelativePath } from '../../../utils/file-import-path.js'
+import { Config } from '../../../../types/application-types.js'
+
+/**
+ * Collect all unique renderer names from CLI metadata (populated by inspector)
+ */
+export function collectRendererNames(programMeta: CLIProgramMeta): Set<string> {
+  const rendererNames = new Set<string>()
+
+  // Add program-level default renderer
+  if (programMeta.defaultRenderName) {
+    rendererNames.add(programMeta.defaultRenderName)
+  }
+
+  // Recursively collect renderer names from commands
+  function collectFromCommand(command: CLICommandMeta): void {
+    if (command.renderName) {
+      rendererNames.add(command.renderName)
+    }
+
+    // Recursively process subcommands
+    if (command.subcommands) {
+      for (const subCommand of Object.values(command.subcommands)) {
+        collectFromCommand(subCommand)
+      }
+    }
+  }
+
+  // Process all commands
+  for (const command of Object.values(programMeta.commands)) {
+    collectFromCommand(command)
+  }
+
+  return rendererNames
+}
+
+/**
+ * Build a renderers map for CLI commands
+ */
+function buildRenderersMap(programMeta: CLIProgramMeta): string {
+  const entries: string[] = []
+
+  // Build map entries for each command that has a renderer
+  function addCommandRenderer(command: CLICommandMeta, path: string[]): void {
+    const commandId = path.join('.')
+    if (command.renderName) {
+      entries.push(`    '${commandId}': ${command.renderName}`)
+    }
+
+    // Recursively process subcommands
+    if (command.subcommands) {
+      for (const [subName, subCommand] of Object.entries(command.subcommands)) {
+        addCommandRenderer(subCommand, [...path, subName])
+      }
+    }
+  }
+
+  // Process all commands
+  for (const [commandName, command] of Object.entries(programMeta.commands)) {
+    addCommandRenderer(command, [commandName])
+  }
+
+  if (entries.length === 0) {
+    return '{}'
+  }
+
+  return `{\n${entries.join(',\n')}\n  }`
+}
+
+/**
+ * Serializes a CLI-over-Channel client bootstrap file
+ * Similar to local CLI bootstrap but uses WebSocket connection
+ */
+export function serializeChannelCLIClient(
+  programName: string,
+  programMeta: CLIProgramMeta,
+  clientFile: string,
+  config: Config,
+  cliBootstrapPath: string,
+  channelRoute?: string,
+  renderersMeta?: Record<string, any>
+): string {
+  const capitalizedName =
+    programName.charAt(0).toUpperCase() + programName.slice(1).replace(/-/g, '')
+  const finalChannelRoute = channelRoute || `/cli/${programName}`
+
+  // Get relative import path to CLI bootstrap (for metadata)
+  const bootstrapImportPath = getFileImportRelativePath(
+    clientFile,
+    cliBootstrapPath,
+    config.packageMappings
+  )
+
+  // Collect all unique renderer names from CLI metadata (populated by inspector)
+  const rendererNames = collectRendererNames(programMeta)
+
+  // Generate renderer imports from their source files
+  let rendererImports = ''
+  if (rendererNames.size > 0 && renderersMeta) {
+    const importsByFile = new Map<string, string[]>()
+
+    for (const rendererName of rendererNames) {
+      const meta = renderersMeta[rendererName]
+      if (meta?.exportedName && meta?.filePath) {
+        const relativePath = getFileImportRelativePath(
+          clientFile,
+          meta.filePath,
+          config.packageMappings
+        )
+        if (!importsByFile.has(relativePath)) {
+          importsByFile.set(relativePath, [])
+        }
+        importsByFile.get(relativePath)!.push(meta.exportedName)
+      }
+    }
+
+    // Generate import statements
+    for (const [path, names] of importsByFile) {
+      rendererImports += `import { ${names.join(', ')} } from '${path}'\n`
+    }
+  }
+
+  // Build renderers map
+  const renderersMap = buildRenderersMap(programMeta)
+
+  // Determine default renderer
+  const defaultRendererCode = programMeta.defaultRenderName
+    ? `,\n    defaultRenderer: ${programMeta.defaultRenderName}`
+    : ''
+
+  return `
+import { executeCLIViaChannel } from '@pikku/core/cli/channel'
+import { CorePikkuWebsocket } from '@pikku/websocket'
+import '${bootstrapImportPath}'
+${rendererImports}
+/**
+ * ${capitalizedName} CLI Client (via WebSocket Channel)
+ * Executes CLI commands over a WebSocket connection
+ */
+export async function ${capitalizedName}CLIClient(
+  url: string,
+  args?: string[]
+): Promise<void> {
+  // Create WebSocket connection
+  const pikkuWS = new CorePikkuWebsocket(url)
+
+  // Register renderers for CLI commands
+  const renderers = ${renderersMap}
+
+  await executeCLIViaChannel({
+    programName: '${programName}',
+    pikkuWS,
+    args,
+    renderers${defaultRendererCode},
+  })
+}
+
+// Export as default for easy importing
+export default ${capitalizedName}CLIClient
+
+// For direct execution (if this file is run directly)
+if (import.meta.url === \`file://\${process.argv[1]}\`) {
+  const url = process.env.PIKKU_WS_URL || 'ws://localhost:3000${finalChannelRoute}'
+  ${capitalizedName}CLIClient(url, process.argv.slice(2)).catch(error => {
+    console.error('Fatal error:', error.message)
+    process.exit(1)
+  })
+}
+`
+}

package/src/functions/wirings/cli/serialize-channel-cli.ts

@@ -0,0 +1,102 @@
+import { CLIProgramMeta } from '@pikku/core/cli'
+import { getFileImportRelativePath } from '../../../utils/file-import-path.js'
+
+/**
+ * Serializes a wireChannel call from CLI metadata
+ * This creates a WebSocket backend for all CLI commands
+ */
+export function serializeChannelCLI(
+  programName: string,
+  programMeta: CLIProgramMeta,
+  channelFile: string,
+  functionFiles: Map<string, { path: string; exportedName: string }>,
+  packageMappings: Record<string, string>,
+  channelTypesFile: string,
+  functionTypesFile: string,
+  channelName?: string,
+  channelRoute?: string
+): string {
+  const finalChannelName = channelName || `${programName}-cli`
+  const finalChannelRoute = channelRoute || `/cli/${programName}`
+  // Flatten all commands into a single routing map
+  const commandMap: Record<
+    string,
+    { pikkuFuncName: string; importPath?: string }
+  > = {}
+
+  const collectCommands = (
+    commands: Record<string, any>,
+    path: string[] = []
+  ) => {
+    for (const [name, cmd] of Object.entries(commands)) {
+      const fullPath = [...path, name]
+      const commandKey = fullPath.join('.')
+
+      if (cmd.pikkuFuncName) {
+        commandMap[commandKey] = {
+          pikkuFuncName: cmd.pikkuFuncName,
+        }
+      }
+
+      // Recursively process subcommands
+      if (cmd.subcommands) {
+        collectCommands(cmd.subcommands, fullPath)
+      }
+    }
+  }
+
+  collectCommands(programMeta.commands)
+
+  // Generate the wireChannel call
+  const commandEntries = Object.entries(commandMap)
+    .map(([commandKey, { pikkuFuncName }]) => {
+      return `      '${commandKey}': ${pikkuFuncName}`
+    })
+    .join(',\n')
+
+  // Generate imports from function file locations
+  const funcNames = [
+    ...new Set(Object.values(commandMap).map((v) => v.pikkuFuncName)),
+  ]
+  const imports = funcNames
+    .map((pikkuFuncName) => {
+      const fileInfo = functionFiles.get(pikkuFuncName)
+      if (!fileInfo) {
+        throw new Error(`Function not found in files map: ${pikkuFuncName}`)
+      }
+
+      const importPath = getFileImportRelativePath(
+        channelFile,
+        fileInfo.path,
+        packageMappings
+      )
+      return `import { ${fileInfo.exportedName} } from '${importPath}'`
+    })
+    .join('\n')
+
+  // Get relative path to channel types file
+  const channelTypesPath = getFileImportRelativePath(
+    channelFile,
+    channelTypesFile,
+    packageMappings
+  )
+
+  return `/**
+ * WebSocket channel backend for '${programName}' CLI commands
+ */
+import { wireChannel } from '${channelTypesPath}'
+${imports}
+
+wireChannel({
+  name: '${finalChannelName}',
+  route: '${finalChannelRoute}',
+  auth: false,
+  onMessageWiring: {
+    command: {
+${commandEntries}
+    }
+  },
+  tags: ['cli', '${programName}']
+})
+`
+}

package/src/functions/wirings/cli/serialize-cli-types.ts

@@ -0,0 +1,79 @@
+/**
+ * Generates type definitions for CLI wirings
+ */
+export const serializeCLITypes = (
+  functionTypesImportPath: string,
+  userSessionTypeImport: string,
+  userSessionTypeName: string,
+  singletonServicesTypeImport: string,
+  singletonServicesTypeName: string
+) => {
+  return `/**
+
+ * CLI-specific type definitions for tree-shaking optimization
+ */
+
+import { CoreCLI, wireCLI as wireCLICore, CorePikkuCLIRender, CoreCLICommandConfig } from '@pikku/core/cli'
+import type { PikkuFunctionConfig, PikkuMiddleware } from '${functionTypesImportPath}'
+${userSessionTypeImport}
+${singletonServicesTypeImport}
+
+${singletonServicesTypeName !== 'SingletonServices' ? `type SingletonServices = ${singletonServicesTypeName}` : ''}
+${userSessionTypeName !== 'Session' ? `type Session = ${userSessionTypeName}` : ''}
+
+/**
+ * Type-safe CLI renderer definition that can access your application's services.
+ * Use this to define custom renderers for CLI command output.
+ *
+ * @template Data - The output data type from the CLI command
+ * @template RequiredServices - The services required for this renderer
+ */
+type PikkuCLIRender<Data, RequiredServices extends SingletonServices = SingletonServices> = CorePikkuCLIRender<Data, RequiredServices, Session>
+
+/**
+ * CLI command configuration with project-specific types.
+ * Uses CoreCLICommandConfig from @pikku/core with local middleware and render types.
+ */
+type CLICommandConfig<Func extends PikkuFunctionConfig<In, Out>, In = any, Out = any, Params extends string = string> = CoreCLICommandConfig<Func, PikkuMiddleware, PikkuCLIRender<any>, Params>
+
+/**
+ * Type definition for CLI applications with commands and global options.
+ *
+ * @template Commands - Type describing the command structure
+ * @template GlobalOptions - Type for global CLI options
+ */
+type CLIWiring<Commands extends Record<string, CoreCLICommandConfig<any, PikkuMiddleware, PikkuCLIRender<any>, any>>, GlobalOptions> = CoreCLI<Commands, GlobalOptions, PikkuMiddleware, PikkuCLIRender<any>>
+
+/**
+ * Registers a CLI application with the Pikku framework.
+ * Creates command-line interfaces with type-safe commands and options.
+ *
+ * @template Commands - Type describing the command structure
+ * @template GlobalOptions - Type for global CLI options
+ * @param cli - CLI definition with program name, commands, and global options
+ */
+export const wireCLI = <Commands extends Record<string, CoreCLICommandConfig<any, PikkuMiddleware, PikkuCLIRender<any>, any>>, GlobalOptions>(
+  cli: CLIWiring<Commands, GlobalOptions>
+) => {
+  wireCLICore(cli as any)
+}
+
+/**
+ * Creates a CLI command definition with automatic option inference from the function's input type.
+ * This allows TypeScript to automatically derive CLI options from the function signature.
+ *
+ * @template FuncConfig - The Pikku function config type
+ * @template Params - The parameters string literal type
+ * @param config - CLI command configuration
+ * @returns CLI command configuration with inferred types
+ */
+export const pikkuCLICommand = <
+  FuncConfig extends PikkuFunctionConfig<any, any>,
+  Params extends string
+>(
+  config: CLICommandConfig<FuncConfig, any, any, Params>
+): CoreCLICommandConfig<FuncConfig, PikkuMiddleware, PikkuCLIRender<any>, string> => {
+  return config as any
+}
+`
+}