@pikku/cli 0.9.14 → 0.9.16-next.0

package/.pikku/channel/pikku-channel-types.gen.ts

@@ -0,0 +1,92 @@
+/**
+ * This file was generated by the @pikku/cli
+ */
+/**
+ * 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 '../function/pikku-function-types.gen.js'
+
+/**
+ * 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/.pikku/cli/pikku-cli-types.gen.ts

@@ -0,0 +1,71 @@
+/**
+ * This file was generated by the @pikku/cli
+ */
+/**
+ * This file was generated by the @pikku/cli
+ * CLI-specific type definitions for tree-shaking optimization
+ */
+
+import { CoreCLI, wireCLI as wireCLICore, CorePikkuCLIRender, CoreCLICommandConfig } from '@pikku/core'
+import type { PikkuFunctionConfig, PikkuMiddleware } from '../function/pikku-function-types.gen.js'
+import type { UserSession } from '../../types/application-types.d.js'
+import type { SingletonServices } from '../../types/application-types.d.js'
+
+
+type Session = UserSession
+
+/**
+ * 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<any, any>> = CoreCLICommandConfig<Func, PikkuMiddleware, PikkuCLIRender<any>>
+
+/**
+ * Result type for CLI command configuration
+ */
+type CLICommandResult<Func extends PikkuFunctionConfig<any, any>> = CLICommandConfig<Func>
+
+/**
+ * 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>>>, 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>>>, 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 Func - The Pikku function config type to create a CLI command for
+ * @param config - CLI command configuration
+ * @returns CLI command configuration with inferred types
+ */
+export const pikkuCLICommand = <Func extends PikkuFunctionConfig<any, any>>(
+  config: CLICommandConfig<Func>
+): CLICommandResult<Func> => {
+  return config as any
+}

package/.pikku/cli/pikku-cli-wirings-meta.gen.ts

@@ -0,0 +1,5 @@
+/**
+ * This file was generated by the @pikku/cli
+ */
+import { pikkuState } from '@pikku/core'
+pikkuState('cli', 'meta', {})

package/.pikku/cli/pikku-cli-wirings.gen.ts

@@ -0,0 +1,4 @@
+/**
+ * This file was generated by the @pikku/cli
+ */
+/* The files with an wireCLI function call */

package/.pikku/function/pikku-function-types.gen.ts

@@ -0,0 +1,292 @@
+/**
+ * This file was generated by the @pikku/cli
+ */
+/**
+ * This file was generated by the @pikku/cli
+ * Core function, middleware, and permission types for all wirings
+ */
+
+import { CorePikkuFunctionConfig, CorePikkuPermission, CorePikkuMiddleware, addMiddleware as addMiddlewareCore, addPermission as addPermissionCore } from '@pikku/core'
+import { CorePikkuFunction, CorePikkuFunctionSessionless } from '@pikku/core/function'
+import { PikkuChannel, PikkuMCP } from '@pikku/core'
+
+import type { UserSession } from '../../types/application-types.d.js'
+import type { SingletonServices } from '../../types/application-types.d.js'
+import type { Services } from '../../types/application-types.d.js'
+import type { TypedPikkuRPC } from '../rpc/pikku-rpc-wirings-map.internal.gen.d.js'
+
+
+
+type Session = UserSession
+
+/**
+ * Type-safe API permission definition that integrates with your application's session type.
+ * Use this to define authorization logic for your API endpoints.
+ *
+ * @template In - The input type that the permission check will receive
+ * @template RequiredServices - The services required for this permission check
+ */
+export type PikkuPermission<In = unknown, RequiredServices extends Services = Services> = CorePikkuPermission<In, RequiredServices, Session>
+
+/**
+ * Type-safe middleware definition that can access your application's services and session.
+ * Use this to define reusable middleware that can be applied to multiple wirings.
+ *
+ * @template RequiredServices - The services required for this middleware
+ */
+export type PikkuMiddleware<RequiredServices extends SingletonServices = SingletonServices> = CorePikkuMiddleware<RequiredServices, Session>
+
+/**
+ * Factory function for creating permissions with tree-shaking support.
+ * This enables the bundler to detect which services your permission actually uses.
+ *
+ * @example
+ * ```typescript
+ * const permission = pikkuPermission(({ logger }, data, session) => {
+ *   return session?.isAdmin || false
+ * })
+ * ```
+ */
+export const pikkuPermission = <In>(func: PikkuPermission<In>) => {
+  return func
+}
+
+/**
+ * Factory function for creating middleware with tree-shaking support.
+ * This enables the bundler to detect which services your middleware actually uses.
+ *
+ * @example
+ * ```typescript
+ * const middleware = pikkuMiddleware(({ logger }, interactions, next) => {
+ *   logger.info('Middleware executed')
+ *   await next()
+ * })
+ * ```
+ */
+export const pikkuMiddleware = (func: PikkuMiddleware) => {
+  return func
+}
+
+/**
+ * Factory function for creating middleware factories
+ * Use this when your middleware needs configuration/input parameters
+ *
+ * @example
+ * ```typescript
+ * export const logMiddleware = pikkuMiddlewareFactory<LogOptions>(({
+ *   message,
+ *   level = 'info'
+ * }) => {
+ *   return pikkuMiddleware(async ({ logger }, _interaction, next) => {
+ *     logger[level](message)
+ *     await next()
+ *   })
+ * })
+ * ```
+ */
+export const pikkuMiddlewareFactory = <In = any>(
+  factory: (input: In) => PikkuMiddleware
+): ((input: In) => PikkuMiddleware) => {
+  return factory
+}
+
+/**
+ * A sessionless API function that doesn't require user authentication.
+ * Use this for public endpoints, health checks, or operations that don't need user context.
+ *
+ * @template In - The input type
+ * @template Out - The output type that the function returns
+ * @template ChannelData - Channel data type (null = optional channel)
+ * @template MCPData - MCP data type (null = optional MCP)
+ * @template RequiredServices - Services required by this function
+ */
+export type PikkuFunctionSessionless<
+  In = unknown,
+  Out = never,
+  ChannelData = null,  // null means optional channel
+  MCPData = null, // null means optional MCP
+  RequiredServices extends Services = Services &
+    { rpc: TypedPikkuRPC } & (
+    [ChannelData] extends [null]
+      ? { channel?: PikkuChannel<unknown, Out> }  // Optional channel
+      : { channel: PikkuChannel<ChannelData, Out> }  // Required channel with any data type
+  ) & ([MCPData] extends [null]
+    ? { mcp?: PikkuMCP }  // Optional MCP
+    : { mcp: PikkuMCP }  // Required MCP
+  )
+> = CorePikkuFunctionSessionless<In, Out, ChannelData, RequiredServices, Session>
+
+/**
+ * A session-aware API function that requires user authentication.
+ * Use this for protected endpoints that need access to user session data.
+ *
+ * @template In - The input type
+ * @template Out - The output type that the function returns
+ * @template ChannelData - Channel data type (null = optional channel)
+ * @template MCPData - MCP data type (null = optional MCP)
+ * @template RequiredServices - Services required by this function
+ */
+export type PikkuFunction<
+  In = unknown,
+  Out = never,
+  ChannelData = null,  // null means optional channel
+  MCPData = null, // null means optional MCP
+  RequiredServices extends Services = Omit<Services, 'rpc'> &
+    { rpc: TypedPikkuRPC } & (
+    [ChannelData] extends [null]
+      ? { channel?: PikkuChannel<unknown, Out> }  // Optional channel
+      : { channel: PikkuChannel<ChannelData, Out> }  // Required channel with any data type
+  ) & ([MCPData] extends [null]
+    ? { mcp?: PikkuMCP }  // Optional MCP
+    : { mcp: PikkuMCP }  // Required MCP
+  )
+> = CorePikkuFunction<In, Out, ChannelData, RequiredServices, Session>
+
+/**
+ * Configuration object for Pikku functions with optional middleware, permissions, tags, and documentation.
+ * This type wraps CorePikkuFunctionConfig with the user's custom types.
+ *
+ * @template In - The input type
+ * @template Out - The output type
+ * @template PikkuFunc - The function type (can be narrowed to PikkuFunction or PikkuFunctionSessionless)
+ */
+export type PikkuFunctionConfig<
+  In = unknown,
+  Out = unknown,
+  PikkuFunc extends PikkuFunction<In, Out> | PikkuFunctionSessionless<In, Out> = PikkuFunction<In, Out> | PikkuFunctionSessionless<In, Out>
+> = CorePikkuFunctionConfig<PikkuFunc, PikkuPermission<In>, PikkuMiddleware>
+
+/**
+ * Creates a Pikku function that can be either session-aware or sessionless.
+ * This is the main function wrapper for creating API endpoints.
+ *
+ * @template In - Input type for the function
+ * @template Out - Output type for the function
+ * @param func - Function definition, either direct function or configuration object
+ * @returns The normalized configuration object
+ *
+ * @example
+ * \`\`\`typescript
+ * const createUser = pikkuFunc<{name: string, email: string}, {id: number, message: string}>({
+ *   func: async ({db, logger}, input) => {
+ *     logger.info('Creating user', input.name)
+ *     const user = await db.users.create(input)
+ *     return {id: user.id, message: \`User \${input.name} created successfully\`}
+ *   },
+ *   auth: true
+ * })
+ * \`\`\`
+ */
+export const pikkuFunc = <In, Out = unknown>(
+  func:
+    | PikkuFunction<In, Out>
+    | CorePikkuFunctionConfig<PikkuFunction<In, Out>, PikkuPermission<In>>
+) => {
+  return typeof func === 'function' ? { func } : func
+}
+
+/**
+ * Creates a sessionless Pikku function that doesn't require user authentication.
+ * Use this for public endpoints, webhooks, or background tasks.
+ *
+ * @template In - Input type for the function
+ * @template Out - Output type for the function
+ * @param func - Function definition, either direct function or configuration object
+ * @returns The normalized configuration object
+ *
+ * @example
+ * \`\`\`typescript
+ * const healthCheck = pikkuSessionlessFunc<void, {status: string, timestamp: string}>({
+ *   func: async ({logger}) => {
+ *     logger.info('Health check requested')
+ *     return {status: 'healthy', timestamp: new Date().toISOString()}
+ *   },
+ *   name: 'healthCheck'
+ * })
+ * \`\`\`
+ */
+export const pikkuSessionlessFunc = <In, Out = unknown>(
+  func:
+    | PikkuFunctionSessionless<In, Out>
+    | CorePikkuFunctionConfig<PikkuFunctionSessionless<In, Out>, PikkuPermission<In>, PikkuMiddleware>
+) => {
+  return typeof func === 'function' ? { func } : func
+}
+
+/**
+ * Creates a function that takes no input and returns no output.
+ * Useful for health checks, triggers, or cleanup operations.
+ *
+ * @param func - Function definition, either direct function or configuration object
+ * @returns The normalized configuration object
+ *
+ * @example
+ * \`\`\`typescript
+ * const cleanupTempFiles = pikkuVoidFunc(async ({fileSystem, logger}) => {
+ *     logger.info('Starting cleanup of temporary files')
+ *     await fileSystem.deleteDirectory('/tmp/uploads')
+ *     logger.info('Cleanup completed')
+ * })
+ * \`\`\`
+ */
+export const pikkuVoidFunc = (
+  func:
+    | PikkuFunctionSessionless<void, void>
+    | CorePikkuFunctionConfig<PikkuFunctionSessionless<void, void>, PikkuPermission<void>>
+) => {
+  return typeof func === 'function' ? { func } : func
+}
+
+/**
+ * Adds global middleware for a specific tag.
+ *
+ * This function allows you to register middleware that will be applied to
+ * any wiring (HTTP, Channel, Queue, Scheduler, MCP) that includes the matching tag.
+ *
+ * @param tag - The tag that the middleware should apply to.
+ * @param middleware - The middleware array to apply for the specified tag.
+ *
+ * @throws Error if middleware for the tag already exists.
+ *
+ * @example
+ * ```typescript
+ * // Add admin middleware for admin endpoints
+ * addMiddleware('admin', [adminMiddleware])
+ *
+ * // Add authentication middleware for auth endpoints
+ * addMiddleware('auth', [authMiddleware])
+ *
+ * // Add logging middleware for all API endpoints
+ * addMiddleware('api', [loggingMiddleware])
+ * ```
+ */
+export const addMiddleware = (tag: string, middleware: PikkuMiddleware[]) => {
+  addMiddlewareCore(tag, middleware as any)
+}
+
+/**
+ * Adds global permissions for a specific tag.
+ *
+ * This function allows you to register permissions that will be applied to
+ * any wiring (HTTP, Channel, Queue, Scheduler, MCP) that includes the matching tag.
+ *
+ * @param tag - The tag that the permissions should apply to.
+ * @param permissions - The permissions array to apply for the specified tag.
+ *
+ * @throws Error if permissions for the tag already exist.
+ *
+ * @example
+ * ```typescript
+ * // Add admin permissions for admin endpoints
+ * addPermission('admin', [adminPermission])
+ *
+ * // Add authentication permissions for auth endpoints
+ * addPermission('auth', [authPermission])
+ *
+ * // Add read permissions for all API endpoints
+ * addPermission('api', [readPermission])
+ * ```
+ */
+export const addPermission = <In = unknown>(tag: string, permissions: PikkuPermission<In>[]) => {
+  addPermissionCore(tag, permissions as any)
+}