@pikku/cli 0.10.0 → 0.10.2

package/src/cli.wiring.ts

@@ -1,102 +1,107 @@
-import { pikkuSchemas } from './functions/wirings/functions/schemas.js'
-import { pikkuFetch } from './functions/wirings/fetch/index.js'
-import { pikkuWebSocketTyped } from './functions/wirings/channels/pikku-command-websocket-typed.js'
-import { pikkuRPCClient } from './functions/wirings/rpc/pikku-command-rpc-client.js'
-import { pikkuQueueService } from './functions/wirings/queue/pikku-command-queue-service.js'
-import { pikkuOpenAPI } from './functions/wirings/http/pikku-command-openapi.js'
-import { pikkuNext } from './functions/runtimes/nextjs/pikku-command-nextjs.js'
-import { pikkuCLICommand, wireCLI } from '../.pikku/cli/pikku-cli-types.gen.js'
-import { all } from './functions/commands/all.js'
-import { clientCLIRenderer } from './services.js'
+// import { pikkuSchemas } from './functions/wirings/functions/schemas.js'
+// import { pikkuFetch } from './functions/wirings/fetch/index.js'
+// import { pikkuWebSocketTyped } from './functions/wirings/channels/pikku-command-websocket-typed.js'
+// import { pikkuRPCClient } from './functions/wirings/rpc/pikku-command-rpc-client.js'
+// import { pikkuQueueService } from './functions/wirings/queue/pikku-command-queue-service.js'
+// import { pikkuOpenAPI } from './functions/wirings/http/pikku-command-openapi.js'
+// import { pikkuNext } from './functions/runtimes/nextjs/pikku-command-nextjs.js'
+// import { pikkuCLICommand, wireCLI } from '../.pikku/cli/pikku-cli-types.gen.js'
+// import { all } from './functions/commands/all.js'
+// import { bootstrap } from './functions/commands/bootstrap.js'
+// import { clientCLIRenderer } from './services.js'
 
-wireCLI({
-  program: 'pikku',
-  description:
-    'Pikku CLI - Code generation tool for type-safe backend development',
-  render: clientCLIRenderer,
-  options: {
-    config: {
-      description: 'Path to pikku.config.json file',
-      short: 'c',
-    },
-    logLevel: {
-      description: 'Set log level',
-      default: 'info' as const,
-      short: 'l',
-    },
-    userSessionType: {
-      description:
-        'Specify which UserSession type to use (when multiple exist)',
-    },
-    singletonServicesFactoryType: {
-      description: 'Specify which singleton services factory to use',
-    },
-    sessionServicesFactoryType: {
-      description: 'Specify which session services factory to use',
-    },
-    stateOutput: {
-      description: 'Save inspector state to JSON file for reuse',
-    },
-    stateInput: {
-      description: 'Load inspector state from JSON file (skips inspection)',
-    },
-  },
-  commands: {
-    all: pikkuCLICommand({
-      func: all,
-      description: 'Generate all Pikku files (types, schemas, wirings, etc.)',
-      isDefault: true,
-      options: {
-        tags: {
-          description: 'Filter functions by tags (comma-separated)',
-          short: 't',
-        },
-        types: {
-          description: 'Filter functions by types (comma-separated)',
-        },
-        directories: {
-          description: 'Filter functions by directories (comma-separated)',
-          short: 'd',
-        },
-        httpMethods: {
-          description: 'Filter HTTP routes by methods (comma-separated)',
-        },
-        httpRoutes: {
-          description: 'Filter HTTP routes by route patterns (comma-separated)',
-        },
-        names: {
-          description: 'Filter functions by name patterns (supports wildcards)',
-          short: 'n',
-        },
-      },
-    }),
-    schemas: pikkuCLICommand({
-      func: pikkuSchemas,
-      description: 'Generate JSON schemas for function input/output types',
-    }),
-    fetch: pikkuCLICommand({
-      func: pikkuFetch,
-      description: 'Generate type-safe HTTP fetch client',
-    }),
-    websocket: pikkuCLICommand({
-      func: pikkuWebSocketTyped,
-      description: 'Generate type-safe WebSocket client',
-    }),
-    rpc: pikkuCLICommand({
-      func: pikkuRPCClient,
-      description: 'Generate RPC client wrappers',
-    }),
-    'queue-service': pikkuCLICommand({
-      func: pikkuQueueService,
-      description: 'Generate queue service wrapper',
-    }),
-    openapi: pikkuCLICommand({
-      func: pikkuOpenAPI,
-      description: 'Generate OpenAPI specification from HTTP routes',
-    }),
-    nextjs: pikkuCLICommand({
-      func: pikkuNext,
-      description: 'Generate Next.js backend and HTTP wrappers',
-    }),
-  },
-})
+// wireCLI({
+//   program: 'pikku',
+//   description:
+//     'Pikku CLI - Code generation tool for type-safe backend development',
+//   render: clientCLIRenderer,
+//   options: {
+//     config: {
+//       description: 'Path to pikku.config.json file',
+//       short: 'c',
+//     },
+//     logLevel: {
+//       description: 'Set log level',
+//       default: 'info' as const,
+//       short: 'l',
+//     },
+//     userSessionType: {
+//       description:
+//         'Specify which UserSession type to use (when multiple exist)',
+//     },
+//     singletonServicesFactoryType: {
+//       description: 'Specify which singleton services factory to use',
+//     },
+//     sessionServicesFactoryType: {
+//       description: 'Specify which session services factory to use',
+//     },
+//     stateOutput: {
+//       description: 'Save inspector state to JSON file for reuse',
+//     },
+//     stateInput: {
+//       description: 'Load inspector state from JSON file (skips inspection)',
+//     },
+//   },
+//   commands: {
+//     all: pikkuCLICommand({
+//       func: all,
+//       description: 'Generate all Pikku files (types, schemas, wirings, etc.)',
+//       isDefault: true,
+//       options: {
+//         tags: {
+//           description: 'Filter functions by tags (comma-separated)',
+//           short: 't',
+//         },
+//         types: {
+//           description: 'Filter functions by types (comma-separated)',
+//         },
+//         directories: {
+//           description: 'Filter functions by directories (comma-separated)',
+//           short: 'd',
+//         },
+//         httpMethods: {
+//           description: 'Filter HTTP routes by methods (comma-separated)',
+//         },
+//         httpRoutes: {
+//           description: 'Filter HTTP routes by route patterns (comma-separated)',
+//         },
+//         names: {
+//           description: 'Filter functions by name patterns (supports wildcards)',
+//           short: 'n',
+//         },
+//       },
+//     }),
+//     bootstrap: pikkuCLICommand({
+//       func: bootstrap,
+//       description: 'Generate only type files (setup phase only)',
+//     }),
+//     schemas: pikkuCLICommand({
+//       func: pikkuSchemas,
+//       description: 'Generate JSON schemas for function input/output types',
+//     }),
+//     fetch: pikkuCLICommand({
+//       func: pikkuFetch,
+//       description: 'Generate type-safe HTTP fetch client',
+//     }),
+//     websocket: pikkuCLICommand({
+//       func: pikkuWebSocketTyped,
+//       description: 'Generate type-safe WebSocket client',
+//     }),
+//     rpc: pikkuCLICommand({
+//       func: pikkuRPCClient,
+//       description: 'Generate RPC client wrappers',
+//     }),
+//     'queue-service': pikkuCLICommand({
+//       func: pikkuQueueService,
+//       description: 'Generate queue service wrapper',
+//     }),
+//     openapi: pikkuCLICommand({
+//       func: pikkuOpenAPI,
+//       description: 'Generate OpenAPI specification from HTTP routes',
+//     }),
+//     nextjs: pikkuCLICommand({
+//       func: pikkuNext,
+//       description: 'Generate Next.js backend and HTTP wrappers',
+//     }),
+//   },
+// })

package/src/functions/commands/all.ts

@@ -2,9 +2,11 @@ import { existsSync } from 'fs'
 import { pikkuVoidFunc } from '../../../.pikku/pikku-types.gen.js'
 import { getFileImportRelativePath } from '../../utils/file-import-path.js'
 import { writeFileInDir } from '../../utils/file-writer.js'
+import { CommandSummary } from '../../utils/command-summary.js'
 
 export const all: any = pikkuVoidFunc({
   func: async ({ logger, config, rpc, getInspectorState }) => {
+    const summary = new CommandSummary('all')
     const allImports: string[] = []
     let typesDeclarationFileExists = true
 
@@ -16,7 +18,7 @@ export const all: any = pikkuVoidFunc({
 
     // This is needed since the wireHTTP function will add the routes to the visitState
     if (!typesDeclarationFileExists) {
-      logger.info(`• Type file first created, inspecting again...\x1b[0m`)
+      logger.debug(`• Type file first created, inspecting again...`)
       await getInspectorState(true)
     }
 
@@ -125,7 +127,7 @@ export const all: any = pikkuVoidFunc({
     }
 
     if (config.openAPI) {
-      logger.info(
+      logger.debug(
         `• OpenAPI requires a reinspection to pickup new generated types..`
       )
       await getInspectorState(true)
@@ -145,6 +147,40 @@ export const all: any = pikkuVoidFunc({
         .join('\n')
     )
 
+    // Get final inspector state and collect stats for summary
+    const state = await getInspectorState()
+    if (state.http?.meta)
+      summary.set('httpRoutes', Object.keys(state.http.meta).length)
+    if (state.channels?.meta)
+      summary.set('channels', Object.keys(state.channels.meta).length)
+    if (state.scheduledTasks?.meta)
+      summary.set(
+        'scheduledTasks',
+        Object.keys(state.scheduledTasks.meta).length
+      )
+    if (state.queueWorkers?.meta)
+      summary.set('queueWorkers', Object.keys(state.queueWorkers.meta).length)
+    if (state.mcpEndpoints) {
+      const mcpTotal =
+        Object.keys(state.mcpEndpoints.toolsMeta || {}).length +
+        Object.keys(state.mcpEndpoints.resourcesMeta || {}).length +
+        Object.keys(state.mcpEndpoints.promptsMeta || {}).length
+      if (mcpTotal > 0) summary.set('mcpEndpoints', mcpTotal)
+    }
+    if (state.cli?.meta) {
+      // Count total CLI commands across all programs
+      const totalCommands = Object.values(state.cli.meta).reduce(
+        (sum, program) => sum + (program.commands?.length || 0),
+        0
+      )
+      if (totalCommands > 0) summary.set('cliCommands', totalCommands)
+    }
+
+    // Display summary (unless in silent mode)
+    if (!logger.isSilent()) {
+      console.log(summary.format())
+    }
+
     // Check for critical errors and exit if any were logged
     if (logger.hasCriticalErrors()) {
       process.exit(1)

package/src/functions/commands/bootstrap.ts

@@ -0,0 +1,27 @@
+import { pikkuVoidFunc } from '../../../.pikku/pikku-types.gen.js'
+
+export const bootstrap: any = pikkuVoidFunc({
+  func: async ({ logger, config, rpc, getInspectorState }) => {
+    // Initialize inspector state in bootstrap mode with core types only
+    // This allows bootstrap to run immediately without inspecting the codebase
+    // All subsequent RPC commands will use this cached state
+    await getInspectorState(false, false, true)
+
+    await rpc.invoke('pikkuFunctionTypes', null)
+
+    // Generate wiring-specific type files for tree-shaking
+    // These use the bootstrap mode state with core types
+    await rpc.invoke('pikkuFunctionTypesSplit', null)
+    await rpc.invoke('pikkuHTTPTypes', null)
+    await rpc.invoke('pikkuChannelTypes', null)
+    await rpc.invoke('pikkuSchedulerTypes', null)
+    await rpc.invoke('pikkuQueueTypes', null)
+    await rpc.invoke('pikkuMCPTypes', null)
+    await rpc.invoke('pikkuCLITypes', null)
+
+    // Check for critical errors and exit if any were logged
+    if (logger.hasCriticalErrors()) {
+      process.exit(1)
+    }
+  },
+})

package/src/functions/runtimes/nextjs/serialize-nextjs-backend-wrapper.ts

@@ -6,14 +6,17 @@ export const serializeNextJsBackendWrapper = (
   sessionServicesImport: string
 ) => {
   return `'server-only'
-  
+
 /**
  * This file provides a wrapper around the PikkuNextJS class to allow for methods to be type checked against your routes.
  * It ensures type safety for route handling methods when integrating with the @pikku/core framework.
  */
 import { PikkuNextJS } from '@pikku/next'
+import { NextRequest } from 'next/server.js'
 import type { HTTPWiringsMap, HTTPWiringHandlerOf, HTTPWiringsWithMethod } from '${routesMapPath}'
 
+type RouteContext = { params: Promise<Record<string, string | string[]>> }
+
 ${configImport}
 ${singleServicesFactoryImport}
 ${sessionServicesImport}
@@ -21,6 +24,11 @@ ${sessionServicesImport}
 import '${bootstrapPath}'
 
 let _pikku: PikkuNextJS | undefined
+let _removeAPIPrefix = true
+
+export const removeAPIPrefix = (enable: boolean) => {
+  _removeAPIPrefix = enable
+}
 
 /**
  * Initializes and returns an instance of PikkuNextJS with helper methods for handling route requests.
@@ -178,8 +186,44 @@ export const pikku = (_options?: any) => {
     patch: dynamicPatch,
     del: dynamicDel,
     staticGet,
-    staticPost
+    staticPost,
+  }
+}
+
+/**
+ * Pre-bound API request handler for Next.js App Router route handlers.
+ * Use this to directly export route handlers without losing context.
+ *
+ * @param req - The Next.js request object.
+ * @param context - Next.js route context (unused by Pikku, but required by Next.js signature).
+ * @returns A promise that resolves to a Next.js Response object.
+ *
+ * @example
+ * export const GET = pikkuAPIRequest
+ * export const POST = pikkuAPIRequest
+ */
+export const pikkuAPIRequest = (
+  req: NextRequest,
+  context: RouteContext
+): Promise<Response> => {
+  if (!_pikku) {
+    _pikku = new PikkuNextJS(
+      createConfig as any,
+      createSingletonServices as any,
+      createSessionServices
+    )
+  }
+  if (_removeAPIPrefix) {
+    const url = new URL(req.url)
+    url.pathname = url.pathname.replace(/^\\/api/, '') || '/'
+    req = new NextRequest(url.toString(), {
+      method: req.method,
+      headers: req.headers,
+      body: req.body,
+      duplex: 'half',
+    } as any)
   }
+  return _pikku.apiRequest(req)
 }
 `
 }

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

@@ -10,11 +10,12 @@ export const serializeChannelTypes = (functionTypesImportPath: string) => {
 import { CoreChannel, wireChannel as wireChannelCore } from '@pikku/core/channel'
 import { CorePikkuFunctionConfig } from '@pikku/core'
 import { AssertHTTPWiringParams } from '@pikku/core/http'
-import type { PikkuFunctionSessionless, PikkuPermission, PikkuMiddleware } from '${functionTypesImportPath}'
+import type { PikkuFunction, 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
@@ -24,7 +25,7 @@ type ChannelWiring<ChannelData, Channel extends string> = CoreChannel<
   Channel,
   CorePikkuFunctionConfig<PikkuFunctionSessionless<void, any, ChannelData>, PikkuPermission<void>, PikkuMiddleware>,
   CorePikkuFunctionConfig<PikkuFunctionSessionless<void, void, ChannelData>, PikkuPermission<void>, PikkuMiddleware>,
-  CorePikkuFunctionConfig<PikkuFunctionSessionless<any, any, ChannelData>, PikkuPermission<any>, PikkuMiddleware>,
+  CorePikkuFunctionConfig<PikkuFunctionSessionless<any, any, ChannelData> | PikkuFunction<any, any, ChannelData>, PikkuPermission<any>, PikkuMiddleware>,
   PikkuPermission,
   PikkuMiddleware
 >

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

@@ -26,6 +26,20 @@ class PikkuWebSocketRoute<Channel extends keyof ChannelsMap, Route extends keyof
     }
 }
 
+/**
+ * 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.

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

@@ -52,8 +52,8 @@ export const pikkuCLIEntry: any = pikkuSessionlessFunc<void, void>({
         // Normalize entrypoint config to get type
         const entrypointType =
           typeof entrypointConfig === 'string'
-            ? 'cli'
-            : entrypointConfig.type || 'cli'
+            ? 'local'
+            : entrypointConfig.type || 'local'
 
         // Handle channel type entrypoint
         if (entrypointType === 'channel') {
@@ -152,11 +152,11 @@ export const pikkuCLIEntry: any = pikkuSessionlessFunc<void, void>({
           continue
         }
 
-        // Handle CLI type entrypoint (default)
+        // Handle local CLI type entrypoint (default)
         const entrypointPath =
           typeof entrypointConfig === 'string'
             ? entrypointConfig
-            : entrypointConfig.type === 'cli'
+            : entrypointConfig.type === 'local'
               ? entrypointConfig.path
               : undefined
 

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

@@ -142,8 +142,27 @@ export async function ${capitalizedName}CLIClient(
   url: string,
   args?: string[]
 ): Promise<void> {
+  // Get WebSocket implementation (browser or Node.js)
+  let WebSocketImpl: any
+  if (typeof WebSocket !== 'undefined') {
+    WebSocketImpl = WebSocket
+  } else {
+    // Node.js environment - dynamically import 'ws'
+    try {
+      const wsModule = await import('ws')
+      WebSocketImpl = wsModule.default
+    } catch (e) {
+      throw new Error(
+        'No WebSocket implementation found. In Node.js environments, you need to:\\n' +
+        '1. Install the "ws" package: npm install ws\\n' +
+        'Learn more: https://www.npmjs.com/package/ws'
+      )
+    }
+  }
+
   // Create WebSocket connection
-  const pikkuWS = new CorePikkuWebsocket(url)
+  const ws = new WebSocketImpl(url) as WebSocket
+  const pikkuWS = new CorePikkuWebsocket(ws)
 
   // Register renderers for CLI commands
   const renderers = ${renderersMap}
@@ -161,10 +180,11 @@ 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}'
+  const url = process.env.PIKKU_WS_URL || 'ws://localhost:4002${finalChannelRoute}'
   ${capitalizedName}CLIClient(url, process.argv.slice(2)).catch(error => {
-    console.error('Fatal error:', error.message)
-    process.exit(1)
+    console.error('Fatal channel CLI error:', error)
+    // TODO: We get an error code even when it exists cleanly, investigate
+    // process.exit(1)
   })
 }
 `

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

@@ -47,13 +47,6 @@ export function serializeChannelCLI(
 
   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)),
@@ -81,19 +74,58 @@ export function serializeChannelCLI(
     packageMappings
   )
 
+  // Get relative path to function types file
+  const functionTypesPath = getFileImportRelativePath(
+    channelFile,
+    functionTypesFile,
+    packageMappings
+  )
+
   return `/**
  * WebSocket channel backend for '${programName}' CLI commands
  */
 import { wireChannel } from '${channelTypesPath}'
+import { pikkuMiddleware } from '${functionTypesPath}'
 ${imports}
 
+// Middleware to close the channel after CLI command completes
+const cliCloseOnComplete = pikkuMiddleware(async (services, { channel }, next) => {
+  const closeChannel = () => {
+    setTimeout(async () => {
+      try {
+        // This gives time for the response to be sent before closing
+        await channel?.close()
+      } catch (err) {
+        // Ignore errors on close
+      }
+    }, 200)
+  }
+  
+  try {
+    const result = await next()
+    closeChannel()
+    return result
+  } catch (error) {
+    closeChannel()
+    throw error
+  }
+})
+
 wireChannel({
   name: '${finalChannelName}',
   route: '${finalChannelRoute}',
   auth: false,
   onMessageWiring: {
     command: {
-${commandEntries}
+${Object.entries(commandMap)
+  .map(
+    ([commandKey, { pikkuFuncName }]) =>
+      `      '${commandKey}': {
+        func: ${pikkuFuncName},
+        middleware: [cliCloseOnComplete],
+      }`
+  )
+  .join(',\n')}
     }
   },
   tags: ['cli', '${programName}']

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

@@ -30,6 +30,28 @@ ${userSessionTypeName !== 'Session' ? `type Session = ${userSessionTypeName}` :
  */
 type PikkuCLIRender<Data, RequiredServices extends SingletonServices = SingletonServices> = CorePikkuCLIRender<Data, RequiredServices, Session>
 
+/**
+ * Creates a type-safe CLI renderer with access to your application's singleton services.
+ * The renderer receives the full singleton services and output data to format and display results.
+ *
+ * @template Data - The output data type from the CLI command
+ * @template RequiredServices - The minimum services required for type checking (defaults to SingletonServices)
+ * @param render - Function that receives singleton services and data to render output
+ * @returns A CLI renderer configuration
+ *
+ * @example
+ * \`\`\`typescript
+ * const myRenderer = pikkuCLIRender<MyData>(({ logger }, data) => {
+ *   logger.info(data.message)
+ * })
+ * \`\`\`
+ */
+export const pikkuCLIRender = <Data, RequiredServices extends SingletonServices = SingletonServices>(
+  render: (services: SingletonServices, data: Data) => void | Promise<void>
+): PikkuCLIRender<Data, RequiredServices> => {
+  return render as any
+}
+
 /**
  * CLI command configuration with project-specific types.
  * Uses CoreCLICommandConfig from @pikku/core with local middleware and render types.