@pikku/cli 0.9.14 → 0.9.16-next.0

package/src/functions/wirings/channels/pikku-command-channels-map.ts

@@ -0,0 +1,31 @@
+import { pikkuSessionlessFunc } from '../../../../.pikku/pikku-types.gen.js'
+import { writeFileInDir } from '../../../utils/file-writer.js'
+import { logCommandInfoAndTime } from '../../../middleware/log-command-info-and-time.js'
+import { serializeTypedChannelsMap } from './serialize-typed-channel-map.js'
+
+export const pikkuChannelsMap: any = pikkuSessionlessFunc<void, void>({
+  func: async ({ logger, config, getInspectorState }) => {
+    const state = await getInspectorState()
+    const { channelsMapDeclarationFile, packageMappings } = config
+
+    const content = serializeTypedChannelsMap(
+      channelsMapDeclarationFile,
+      packageMappings,
+      state.functions.typesMap,
+      state.functions.meta,
+      state.channels.meta
+    )
+    await writeFileInDir(logger, channelsMapDeclarationFile, content)
+  },
+  middleware: [
+    logCommandInfoAndTime({
+      commandStart: 'Creating channels map',
+      commandEnd: 'Created channels map',
+      skipCondition: async ({ getInspectorState }) => {
+        const state = await getInspectorState()
+        return state.channels.files.size === 0
+      },
+      skipMessage: 'none found',
+    }),
+  ],
+})

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

@@ -0,0 +1,45 @@
+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 pikkuChannels: any = pikkuSessionlessFunc<
+  void,
+  boolean | undefined
+>({
+  func: async ({ logger, config, getInspectorState }) => {
+    const visitState = await getInspectorState()
+    const { channelsWiringFile, channelsWiringMetaFile, packageMappings } =
+      config
+    const { channels } = visitState
+
+    await writeFileInDir(
+      logger,
+      channelsWiringFile,
+      serializeFileImports(
+        'addChannel',
+        channelsWiringFile,
+        channels.files,
+        packageMappings
+      )
+    )
+    await writeFileInDir(
+      logger,
+      channelsWiringMetaFile,
+      `import { pikkuState } from '@pikku/core'\npikkuState('channel', 'meta', ${JSON.stringify(channels.meta, null, 2)})`
+    )
+
+    return true
+  },
+  middleware: [
+    logCommandInfoAndTime({
+      commandStart: 'Finding Channels',
+      commandEnd: 'Found channels',
+      skipCondition: async ({ getInspectorState }) => {
+        const visitState = await getInspectorState()
+        return visitState.channels.files.size === 0
+      },
+      skipMessage: 'none found',
+    }),
+  ],
+})

package/src/functions/wirings/channels/pikku-command-websocket-typed.ts

@@ -0,0 +1,33 @@
+import { pikkuSessionlessFunc } from '../../../../.pikku/pikku-types.gen.js'
+import { getFileImportRelativePath } from '../../../utils/file-import-path.js'
+import { writeFileInDir } from '../../../utils/file-writer.js'
+import { logCommandInfoAndTime } from '../../../middleware/log-command-info-and-time.js'
+import { serializeWebsocketWrapper } from './serialize-websocket-wrapper.js'
+
+export const pikkuWebSocketTyped: any = pikkuSessionlessFunc<void, void>({
+  func: async ({ logger, config }) => {
+    const { websocketFile, channelsMapDeclarationFile, packageMappings } =
+      config
+
+    if (!websocketFile) {
+      throw new Error("fetchFile is isn't set in the pikku config")
+    }
+
+    const channelsMapDeclarationPath = getFileImportRelativePath(
+      websocketFile,
+      channelsMapDeclarationFile,
+      packageMappings
+    )
+
+    const content = [serializeWebsocketWrapper(channelsMapDeclarationPath)]
+    await writeFileInDir(logger, websocketFile, content.join('\n'))
+  },
+  middleware: [
+    logCommandInfoAndTime({
+      commandStart: 'Generating websocket wrapper',
+      commandEnd: 'Generated websocket wrapper',
+      skipCondition: ({ config }) => config.websocketFile === undefined,
+      skipMessage: "websocketFile isn't set in the pikku config",
+    }),
+  ],
+})

package/src/functions/wirings/channels/serialize-channel-types.ts

@@ -0,0 +1,95 @@
+/**
+ * Generates type definitions for WebSocket channel wirings
+ */
+export const serializeChannelTypes = (functionTypesImportPath: string) => {
+  return `/**
+ * This file was generated by the @pikku/cli
+ * Channel-specific type definitions for tree-shaking optimization
+ */
+
+import { CoreChannel, wireChannel as wireChannelCore } from '@pikku/core/channel'
+import { CorePikkuFunctionConfig } from '@pikku/core'
+import { AssertHTTPWiringParams } from '@pikku/core/http'
+import type { PikkuFunction, PikkuFunctionSessionless, PikkuPermission, PikkuMiddleware } from '${functionTypesImportPath}'
+
+/**
+ * Type definition for WebSocket channels with typed data exchange.
+ * Supports connection, disconnection, and message handling.
+ *
+ * @template ChannelData - Type of data exchanged through the channel
+ * @template Channel - String literal type for the channel name
+ */
+type ChannelWiringFunction<I, O, C = {}> = PikkuFunctionSessionless<I, O, C> | PikkuFunction<I, O, C>
+type ChannelWiring<ChannelData, Channel extends string> = CoreChannel<ChannelData, Channel, ChannelWiringFunction<void, unknown> | ChannelWiringFunction<void, unknown, ChannelData>, ChannelWiringFunction<void, void> | ChannelWiringFunction<void, void, ChannelData>, ChannelWiringFunction<any, any> | ChannelWiringFunction<any, any, ChannelData>, PikkuPermission, PikkuMiddleware>
+
+/**
+ * Creates a function that handles WebSocket channel connections.
+ * Called when a client connects to a channel.
+ *
+ * @template Out - Output type for connection response
+ * @template ChannelData - Type of data associated with the channel
+ * @param func - Function definition, either direct function or configuration object
+ * @returns The unwrapped function for internal use
+ */
+export const pikkuChannelConnectionFunc = <Out = unknown, ChannelData = unknown>(
+  func:
+    | PikkuFunctionSessionless<void, Out, ChannelData>
+    | {
+        func: PikkuFunctionSessionless<void, Out, ChannelData>
+        name?: string
+      }
+) => {
+  return typeof func === 'function' ? func : func.func
+}
+
+/**
+ * Creates a function that handles WebSocket channel disconnections.
+ * Called when a client disconnects from a channel.
+ *
+ * @template ChannelData - Type of data associated with the channel
+ * @param func - Function definition, either direct function or configuration object
+ * @returns The unwrapped function for internal use
+ */
+export const pikkuChannelDisconnectionFunc = <ChannelData = unknown>(
+  func:
+    | PikkuFunctionSessionless<void, void, ChannelData>
+    | {
+        func: PikkuFunction<void, void, ChannelData>
+        name?: string
+      }
+) => {
+  return typeof func === 'function' ? func : func.func
+}
+
+/**
+ * Creates a function that handles WebSocket channel messages.
+ * Called when a message is received on a channel.
+ *
+ * @template In - Input type for channel messages
+ * @template Out - Output type for channel responses
+ * @template ChannelData - Type of data associated with the channel
+ * @param func - Function definition, either direct function or configuration object
+ * @returns The unwrapped function for internal use
+ */
+export const pikkuChannelFunc = <In = unknown, Out = unknown, ChannelData = unknown>(
+  func:
+    | PikkuFunctionSessionless<In, Out, ChannelData>
+    | CorePikkuFunctionConfig<PikkuFunction<In, Out, ChannelData>, PikkuPermission<In>>
+) => {
+  return typeof func === 'function' ? func : func.func
+}
+
+/**
+ * Registers a WebSocket channel with the Pikku framework.
+ *
+ * @template ChannelData - Type of data associated with the channel
+ * @template Channel - String literal type for the channel name
+ * @param channel - Channel definition with connection, disconnection, and message handlers
+ */
+export const wireChannel = <ChannelData, Channel extends string>(
+  channel: ChannelWiring<ChannelData, Channel> & AssertHTTPWiringParams<ChannelData, Channel>
+) => {
+  wireChannelCore(channel as any) // TODO
+}
+`
+}

package/src/{wirings → functions/wirings}/channels/serialize-typed-channel-map.ts

@@ -1,7 +1,7 @@
 import { ChannelsMeta } from '@pikku/core/channel'
-import { serializeImportMap } from '../../serialize-import-map.js'
+import { serializeImportMap } from '../../../utils/serialize-import-map.js'
 import { TypesMap } from '@pikku/inspector'
-import { generateCustomTypes } from '../../utils.js'
+import { generateCustomTypes } from '../../../utils/custom-types-generator.js'
 import { FunctionsMeta } from '@pikku/core'
 
 export const serializeTypedChannelsMap = (

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

@@ -0,0 +1,173 @@
+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 } from './serialize-channel-cli-client.js'
+
+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[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)
+
+            const clientCode = serializeChannelCLIClient(
+              programName,
+              programMeta,
+              channelClientFile,
+              config,
+              config.bootstrapFiles.cli,
+              channelRoute
+            )
+
+            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',
+      skipCondition: async ({ getInspectorState }) => {
+        const visitState = await getInspectorState()
+        return visitState.cli.files.size === 0
+      },
+      skipMessage: 'none found',
+    }),
+  ],
+})

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

@@ -0,0 +1,50 @@
+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',
+      skipCondition: false,
+      skipMessage: '',
+    }),
+  ],
+})

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

@@ -0,0 +1,41 @@
+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',
+      skipCondition: false,
+      skipMessage: 'none found',
+    }),
+  ],
+})

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

@@ -0,0 +1,72 @@
+import { CLIProgramMeta } from '@pikku/core'
+import { getFileImportRelativePath } from '../../../utils/file-import-path.js'
+import { Config } from '../../../../types/application-types.js'
+
+/**
+ * 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
+): 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
+  )
+
+  // TODO: Collect renderer imports and create renderers map
+  // For now, renderers are not implemented
+
+  return `/**
+ * This file was generated by the @pikku/cli
+ */
+import { executeCLIViaChannel } from '@pikku/core/cli/channel'
+import { CorePikkuWebsocket } from '@pikku/websocket'
+import '${bootstrapImportPath}'
+
+/**
+ * ${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)
+
+  // TODO: Import and register renderers when renderer tracking is implemented
+  const renderers = {}
+
+  await executeCLIViaChannel({
+    programName: '${programName}',
+    pikkuWS,
+    args,
+    renderers,
+  })
+}
+
+// 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).catch(error => {
+    console.error('Fatal error:', error.message)
+    process.exit(1)
+  })
+}
+`
+}

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

@@ -0,0 +1,123 @@
+import { CLIProgramMeta } from '@pikku/core'
+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 paths to type files
+  const channelTypesPath = getFileImportRelativePath(
+    channelFile,
+    channelTypesFile,
+    packageMappings
+  )
+  const functionTypesPath = getFileImportRelativePath(
+    channelFile,
+    functionTypesFile,
+    packageMappings
+  )
+
+  return `/**
+ * This file was generated by the @pikku/cli
+ * WebSocket channel backend for '${programName}' CLI commands
+ */
+import { wireChannel } from '${channelTypesPath}'
+import { PikkuMiddleware } from '${functionTypesPath}'
+${imports}
+
+// Middleware to close channel after command execution
+const closeAfterExecution: PikkuMiddleware = async (_services, interaction, next) => {
+  try {
+    const result = await next()
+    return result
+  } finally {
+    // Close the channel after function completes
+    if (interaction.channel) {
+      await interaction.channel.close()
+    }
+  }
+}
+
+wireChannel({
+  name: '${finalChannelName}',
+  route: '${finalChannelRoute}',
+  auth: false,
+  middleware: [closeAfterExecution],
+  onMessageWiring: {
+    command: {
+${commandEntries}
+    }
+  },
+  tags: ['cli', '${programName}']
+})
+`
+}