@pikku/cli 0.11.2 → 0.12.0

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

@@ -1,94 +0,0 @@
-/**
- * Generates type definitions for WebSocket channel wirings
- */
-export const serializeChannelTypes = (functionTypesImportPath: string) => {
-  return `/**
-
- * Channel-specific type definitions for tree-shaking optimization
- */
-
-import { CoreChannel, wireChannel as wireChannelCore } from '@pikku/core/channel'
-import { AssertHTTPWiringParams } from '@pikku/core/http'
-import type { PikkuFunctionConfig, PikkuFunctionSessionless, PikkuPermission, PikkuMiddleware } from '${functionTypesImportPath}'
-
-/**
- * Type definition for WebSocket channels with typed data exchange.
- * Supports connection, disconnection, and message handling.
- * Accepts both session-based (PikkuFunction) and sessionless (PikkuFunctionSessionless) functions.
- *
- * @template ChannelData - Type of data exchanged through the channel
- * @template Channel - String literal type for the channel name
- */
-type ChannelWiring<ChannelData, Channel extends string> = CoreChannel<
-  ChannelData,
-  Channel,
-  PikkuFunctionConfig<void, any, 'channel' | 'session' | 'rpc'>,
-  PikkuFunctionConfig<void, void, 'channel' | 'session' | 'rpc'>,
-  PikkuFunctionConfig<any, any, 'channel' | 'session' | 'rpc'>,
-  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
- * @param func - Function definition, either direct function or configuration object
- * @returns The normalized configuration object
- */
-export const pikkuChannelConnectionFunc = <Out = unknown>(
-  func:
-    | PikkuFunctionSessionless<void, Out, 'channel' | 'session' | 'rpc'>
-    | PikkuFunctionConfig<void, Out, 'channel' | 'session' | 'rpc'>
-) => {
-  return typeof func === 'function' ? { func } : func
-}
-
-/**
- * Creates a function that handles WebSocket channel disconnections.
- * Called when a client disconnects from a channel.
- *
- * @param func - Function definition, either direct function or configuration object
- * @returns The normalized configuration object
- */
-export const pikkuChannelDisconnectionFunc = (
-  func:
-    | PikkuFunctionSessionless<void, void, 'channel'>
-    | PikkuFunctionConfig<void, void, 'channel' | 'session' | 'rpc'>
-) => {
-  return typeof func === 'function' ? { func } : func
-}
-
-/**
- * Creates a function that handles WebSocket channel messages.
- * Called when a message is received on a channel.
- * This is the same as pikkuSessionlessFunc but with ChannelData = unknown by default.
- *
- * @template In - Input type for channel messages
- * @template Out - Output type for channel responses
- * @param func - Function definition, either direct function or configuration object
- * @returns The normalized configuration object
- */
-export const pikkuChannelFunc = <In, Out = unknown>(
-  func:
-    | PikkuFunctionSessionless<In, Out, 'channel' | 'session' | 'rpc'>
-    | PikkuFunctionConfig<In, Out, 'channel' | 'session' | 'rpc'>
-) => {
-  return typeof func === 'function' ? { 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/functions/wirings/channels/serialize-typed-channel-map.ts

@@ -1,172 +0,0 @@
-import { ChannelsMeta } from '@pikku/core/channel'
-import { serializeImportMap } from '../../../utils/serialize-import-map.js'
-import { TypesMap } from '@pikku/inspector'
-import { generateCustomTypes } from '../../../utils/custom-types-generator.js'
-import { FunctionsMeta } from '@pikku/core'
-
-export const serializeTypedChannelsMap = (
-  relativeToPath: string,
-  packageMappings: Record<string, string>,
-  typesMap: TypesMap,
-  functionsMeta: FunctionsMeta,
-  channelsMeta: ChannelsMeta
-): string => {
-  const { channels, requiredTypes } = generateChannels(
-    functionsMeta,
-    channelsMeta
-  )
-  typesMap.customTypes.forEach(({ references }) => {
-    for (const reference of references) {
-      // Skip __object types (placeholder types for invalid/broken functions)
-      if (reference !== '__object' && !reference.startsWith('__object_')) {
-        requiredTypes.add(reference)
-      }
-    }
-  })
-  const imports = serializeImportMap(
-    relativeToPath,
-    packageMappings,
-    typesMap,
-    requiredTypes
-  )
-  const serializedCustomTypes = generateCustomTypes(typesMap, requiredTypes)
-  return `/**
- * This provides the structure needed for TypeScript to be aware of channels
- */
-    
-${imports}
-${serializedCustomTypes}
-
-interface ChannelHandler<I, O> {
-    input: I;
-    output: O;
-}
-
-${channels}
-
-export type ChannelDefaultHandlerOf<Channel extends keyof ChannelsMap> =
-    ChannelsMap[Channel]['defaultMessage'] extends { input: infer I; output: infer O }
-        ? ChannelHandler<I, O>
-        : never;
-
-export type ChannelWiringHandlerOf<
-    Channel extends keyof ChannelsMap, 
-    Route extends keyof ChannelsMap[Channel]['routes'], 
-    Method extends keyof ChannelsMap[Channel]['routes'][Route],
-> =
-    ChannelsMap[Channel]['routes'][Route][Method] extends { input: infer I; output: infer O }
-        ? ChannelHandler<I, O>
-        : never;
-`
-}
-
-function generateChannels(
-  functionsMeta: FunctionsMeta,
-  channelsMeta: ChannelsMeta
-) {
-  const requiredTypes = new Set<string>()
-  const channelsObject: Record<
-    string,
-    {
-      message: { inputs: string[] | null; outputs: string[] | null } | null
-      routes: Record<
-        string,
-        Record<
-          string,
-          {
-            inputTypes: string[] | null
-            outputTypes: string[] | null
-          }
-        >
-      >
-    }
-  > = {}
-
-  for (const meta of Object.values(channelsMeta)) {
-    const { name, messageWirings, message } = meta
-
-    if (!channelsObject[name]) {
-      channelsObject[name] = { message: null, routes: {} }
-    }
-
-    if (message) {
-      const func = functionsMeta[message.pikkuFuncName]
-      if (!func) {
-        throw new Error(
-          `Function ${message.pikkuFuncName} not found in functionsMeta for channel ${name}`
-        )
-      }
-      const inputTypes = func.inputs || null
-      const outputTypes = func.outputs || null
-      channelsObject[name].message = {
-        inputs: inputTypes,
-        outputs: outputTypes,
-      }
-      inputTypes?.forEach((type) => requiredTypes.add(type))
-      outputTypes?.forEach((type) => requiredTypes.add(type))
-    }
-
-    for (const [key, route] of Object.entries(messageWirings)) {
-      if (!channelsObject[name].routes[key]) {
-        channelsObject[name].routes[key] = {}
-      }
-      for (const [method, { pikkuFuncName }] of Object.entries(route)) {
-        const func = functionsMeta[pikkuFuncName]
-        if (!func) {
-          throw new Error(
-            `Function ${pikkuFuncName} not found in functionsMeta for channel ${name}, route ${key}, method ${method}`
-          )
-        }
-        const inputTypes = func.inputs || null
-        const outputTypes = func.outputs || null
-        channelsObject[name].routes[key][method] = {
-          inputTypes,
-          outputTypes,
-        }
-        inputTypes?.forEach((type) => requiredTypes.add(type))
-        outputTypes?.forEach((type) => requiredTypes.add(type))
-      }
-    }
-  }
-
-  let routesStr = 'export type ChannelsMap = {\n'
-
-  for (const [channelPath, { routes, message }] of Object.entries(
-    channelsObject
-  )) {
-    routesStr += `  readonly '${channelPath}': {\n`
-
-    // Add `routes` object
-    routesStr += `    readonly routes: {\n`
-    for (const [key, methods] of Object.entries(routes)) {
-      routesStr += `      readonly ${key}: {\n`
-      for (const [method, handler] of Object.entries(methods)) {
-        routesStr += `        readonly ${method}: ChannelHandler<${
-          formatTypeArray(handler.inputTypes) || 'void'
-        }, ${formatTypeArray(handler.outputTypes) || 'never'}>,\n`
-      }
-      routesStr += '      },\n'
-    }
-    routesStr += '    },\n'
-
-    // Add `defaultMessage` outside `routes`
-    if (message) {
-      routesStr += `    readonly defaultMessage: ChannelHandler<${formatTypeArray(
-        message.inputs
-      )}, ${formatTypeArray(message.outputs)}>,\n`
-    } else {
-      routesStr += `    readonly defaultMessage: never,\n`
-    }
-
-    routesStr += '  },\n'
-  }
-
-  routesStr += '};'
-
-  return { channels: routesStr, requiredTypes }
-}
-
-// Utility to format type arrays
-function formatTypeArray(types: string[] | null): string {
-  return types ? types.join(' | ') : 'null'
-}

package/src/functions/wirings/channels/serialize-websocket-wrapper.ts

@@ -1,89 +0,0 @@
-export const serializeWebsocketWrapper = (channelsMapPath: string) => {
-  return `import { CorePikkuWebsocket, CorePikkuRouteHandler } from '@pikku/websocket'
-import { ChannelDefaultHandlerOf, ChannelWiringHandlerOf, ChannelsMap } from '${channelsMapPath}';
-
-class PikkuWebSocketRoute<Channel extends keyof ChannelsMap, Route extends keyof ChannelsMap[Channel]['routes']> extends CorePikkuRouteHandler {
-    public subscribe<
-        Method extends keyof ChannelsMap[Channel]['routes'][Route],
-        Data extends ChannelWiringHandlerOf<Channel, Route, Method>['output']
-    >(method: Method, callback: (data: Data) => void
-    ) {
-        super.subscribe(method.toString(), callback)
-    }
-
-    public unsubscribe<
-        Method extends keyof ChannelsMap[Channel]['routes'][Route],
-        Data extends ChannelWiringHandlerOf<Channel, Route, Method>['output']
-    >(method: Method, callback?: (data: Data) => void) {
-        super.unsubscribe(method.toString(), callback)
-    }
-
-    public send<
-        Method extends keyof ChannelsMap[Channel]['routes'][Route],
-        Data extends ChannelWiringHandlerOf<Channel, Route, Method>['input']
-    >(method: Method, data: Data) {
-        super.send(method.toString(), data)
-    }
-}
-
-/**
- * Type-safe WebSocket wrapper for Pikku channels.
- *
- * @example
- * // Browser usage
- * const ws = new WebSocket('ws://localhost:3000')
- * const pikkuWS = new PikkuWebSocket<'events'>(ws)
- *
- * @example
- * // Node.js usage
- * import WebSocket from 'ws'
- * const ws = new WebSocket('ws://localhost:3000')
- * const pikkuWS = new PikkuWebSocket<'events'>(ws)
- */
-export class PikkuWebSocket<Channel extends keyof ChannelsMap, EventHubTopics extends Record<string, any> = {}> extends CorePikkuWebsocket {
-    /**
-     * Send a message to a specific route and method.
-     * Validates the input data type.
-     */
-    public getRoute<Route extends keyof ChannelsMap[Channel]['routes']>(route: Route): PikkuWebSocketRoute<Channel, Route> {
-        return super.getRoute(route)
-    }
-
-    /**
-     * Subscribe to a specific route and method.
-     */
-    public subscribe<Data extends ChannelDefaultHandlerOf<Channel>['output']>(
-        callback: (data: Data) => void
-    ) {
-        super.subscribe(callback)
-    }
-
-    /**
-     * Subscribe to a specific route and method.
-     */
-    public unsubscribe<Data extends ChannelDefaultHandlerOf<Channel>['output']>(
-        callback?: (data: Data) => void
-    ) {
-        super.unsubscribe(callback)
-    }
-
-    public send(data: ChannelDefaultHandlerOf<Channel>['input']) {
-        super.send(data)
-    }
-
-    /**
-     * Subscribe to a topic from the EventHub system with strong typing.
-     */
-    public subscribeToEventHub<Topic extends keyof EventHubTopics>(
-        topic: Topic,
-        callback: (data: EventHubTopics[Topic]) => void
-    ) {
-        super.subscribe((data) => {
-            if (data.topic === topic) {
-                callback(data as EventHubTopics[Topic])
-            }
-        })
-    }
-}
-  `
-}

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

@@ -1,216 +0,0 @@
-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'
-            ? 'local'
-            : entrypointConfig.type || 'local'
-
-        // 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 local CLI type entrypoint (default)
-        const entrypointPath =
-          typeof entrypointConfig === 'string'
-            ? entrypointConfig
-            : entrypointConfig.type === 'local'
-              ? 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,
-          wireServicesFactory: true,
-        })
-
-        const {
-          pikkuConfigFactory,
-          singletonServicesFactory,
-          wireServicesFactory,
-        } = visitState.filesAndMethods
-
-        if (
-          !pikkuConfigFactory ||
-          !singletonServicesFactory ||
-          !wireServicesFactory
-        ) {
-          throw new Error('Required types not found')
-        }
-
-        const bootstrapCode = serializeLocalCLIBootstrap(
-          programName,
-          programMeta,
-          bootstrapFile,
-          config,
-          pikkuConfigFactory,
-          singletonServicesFactory,
-          wireServicesFactory
-        )
-
-        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

@@ -1,48 +0,0 @@
-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,
-      wireServiceType: 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

@@ -1,62 +0,0 @@
-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'
-import { getFileImportRelativePath } from '../../../utils/file-import-path.js'
-
-export const pikkuCLI: any = pikkuSessionlessFunc<void, boolean | undefined>({
-  func: async ({ logger, config, getInspectorState }) => {
-    const visitState = await getInspectorState()
-    const {
-      cliWiringsFile,
-      cliWiringMetaFile,
-      cliWiringMetaJsonFile,
-      packageMappings,
-      schema,
-    } = config
-    const { cli } = visitState
-
-    // Generate CLI wirings file
-    await writeFileInDir(
-      logger,
-      cliWiringsFile,
-      serializeFileImports(
-        'wireCLI',
-        cliWiringsFile,
-        cli.files,
-        packageMappings
-      )
-    )
-
-    await writeFileInDir(
-      logger,
-      cliWiringMetaJsonFile,
-      JSON.stringify(cli.meta, null, 2)
-    )
-
-    const jsonImportPath = getFileImportRelativePath(
-      cliWiringMetaFile,
-      cliWiringMetaJsonFile,
-      packageMappings
-    )
-
-    const supportsImportAttributes = schema?.supportsImportAttributes ?? false
-    const importStatement = supportsImportAttributes
-      ? `import metaData from '${jsonImportPath}' with { type: 'json' }`
-      : `import metaData from '${jsonImportPath}'`
-
-    await writeFileInDir(
-      logger,
-      cliWiringMetaFile,
-      `import { pikkuState } from '@pikku/core'\nimport { CLIMeta } from '@pikku/core/cli'\n${importStatement}\npikkuState('cli', 'meta', metaData as CLIMeta)`
-    )
-
-    return true
-  },
-  middleware: [
-    logCommandInfoAndTime({
-      commandStart: 'Finding CLI commands',
-      commandEnd: 'Found CLI commands',
-    }),
-  ],
-})