@pikku/core 0.9.11 → 0.9.12-next.0

package/src/middleware-runner.ts

@@ -3,7 +3,9 @@ import {
   CoreSingletonServices,
   PikkuInteraction,
   CorePikkuMiddleware,
+  CorePikkuMiddlewareGroup,
   PikkuWiringTypes,
+  MiddlewareMetadata,
 } from './types/core.types.js'
 import { pikkuState } from './pikku-state.js'
 import { freezeDedupe } from './utils.js'
@@ -49,79 +51,89 @@ export const runMiddleware = async <Middleware extends CorePikkuMiddleware>(
 }
 
 /**
- * Adds global middleware for a specific tag.
+ * Registers 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.
+ * This function registers middleware at runtime that will be applied to
+ * any wiring (HTTP, Channel, Queue, Scheduler, MCP, CLI) that includes the matching tag.
+ *
+ * For tree-shaking benefits, wrap in a factory function:
+ * `export const x = () => addMiddleware('tag', [...])`
+ *
+ * Accepts an array that can contain:
+ * - Direct middleware functions (CorePikkuMiddleware)
+ * - Factory middleware functions (CorePikkuMiddlewareFactory)
  *
  * @template PikkuMiddleware The middleware type.
  * @param {string} tag - The tag that the middleware should apply to.
- * @param {PikkuMiddleware[]} middleware - The middleware array to apply for the specified tag.
+ * @param {CorePikkuMiddlewareGroup} middleware - Array of middleware for this tag.
  *
- * @throws {Error} If middleware for the tag already exists.
+ * @returns {CorePikkuMiddlewareGroup} The middleware array (for chaining/wrapping).
  *
  * @example
  * ```typescript
- * // Add admin middleware for admin endpoints
- * addMiddleware('admin', [adminMiddleware])
+ * // Recommended: tree-shakeable
+ * export const adminMiddleware = () => addMiddleware('admin', [
+ *   authMiddleware,
+ *   loggingMiddleware({ level: 'info' })
+ * ])
  *
- * // Add authentication middleware for auth endpoints
- * addMiddleware('auth', [authMiddleware])
- *
- * // Add logging middleware for all API endpoints
- * addMiddleware('api', [loggingMiddleware])
+ * // Also works: no tree-shaking
+ * export const apiMiddleware = addMiddleware('api', [
+ *   rateLimitMiddleware
+ * ])
  * ```
  */
 export const addMiddleware = <PikkuMiddleware extends CorePikkuMiddleware>(
   tag: string,
-  middleware: PikkuMiddleware[]
-) => {
-  const middlewareStore = pikkuState('misc', 'middleware')
-
-  // Check if tag already exists
-  if (middlewareStore[tag]) {
-    throw new Error(
-      `Middleware for tag '${tag}' already exists. Use a different tag or remove the existing middleware first.`
-    )
-  }
-
-  middlewareStore[tag] = middleware as CorePikkuMiddleware[]
+  middleware: CorePikkuMiddlewareGroup
+): CorePikkuMiddlewareGroup => {
+  const tagGroups = pikkuState('middleware', 'tagGroup')
+  tagGroups[tag] = middleware
+  return middleware
 }
 
 /**
- * Retrieves middleware for a given set of tags.
+ * Registers a single middleware function by name in the global middleware store.
  *
- * This function looks up all middleware registered for any of the provided tags
- * and returns them as a flattened array.
+ * This function is used by CLI-generated code to register middleware functions
+ * that can be referenced by name in metadata. It stores middleware in a special
+ * namespace to avoid conflicts with tag-based middleware.
  *
- * @param {string[]} tags - Array of tags to look up middleware for.
- * @returns {CorePikkuMiddleware[]} Array of middleware functions that apply to the given tags.
+ * @param {string} name - The unique name (pikkuFuncName) of the middleware function.
+ * @param {CorePikkuMiddleware} middleware - The middleware function to register.
  *
  * @example
  * ```typescript
- * // Get all middleware for tags 'api' and 'auth'
- * const middleware = getMiddlewareForTags(['api', 'auth'])
+ * // Called by CLI-generated pikku-middleware.gen.ts
+ * registerMiddleware('authMiddleware_src_middleware_ts_10_5', authMiddleware)
+ * registerMiddleware('loggingMiddleware_src_middleware_ts_20_10', loggingMiddleware)
  * ```
  */
-export const getMiddlewareForTags = (
-  tags?: string[]
-): CorePikkuMiddleware[] => {
-  if (!tags || tags.length === 0) {
-    return []
-  }
-
+export const registerMiddleware = (
+  name: string,
+  middleware: CorePikkuMiddleware
+) => {
   const middlewareStore = pikkuState('misc', 'middleware')
-  const applicableMiddleware: CorePikkuMiddleware[] = []
-
-  // Collect middleware for all matching tags
-  for (const tag of tags) {
-    const tagMiddleware = middlewareStore[tag]
-    if (tagMiddleware) {
-      applicableMiddleware.push(...tagMiddleware)
-    }
-  }
+  middlewareStore[name] = [middleware]
+}
 
-  return applicableMiddleware
+/**
+ * Retrieves a registered middleware function by its name.
+ *
+ * This function looks up middleware that was registered with registerMiddleware.
+ * It's used internally by the framework to resolve middleware references in metadata.
+ *
+ * @param {string} name - The unique name (pikkuFuncName) of the middleware function.
+ * @returns {CorePikkuMiddleware | undefined} The middleware function, or undefined if not found.
+ *
+ * @internal
+ */
+export const getMiddlewareByName = (
+  name: string
+): CorePikkuMiddleware | undefined => {
+  const middlewareStore = pikkuState('misc', 'middleware')
+  const middleware = middlewareStore[name]
+  return middleware?.[0]
 }
 
 const middlewareCache: Record<
@@ -134,28 +146,28 @@ const middlewareCache: Record<
   [PikkuWiringTypes.queue]: {},
   [PikkuWiringTypes.scheduler]: {},
   [PikkuWiringTypes.mcp]: {},
+  [PikkuWiringTypes.cli]: {},
 }
 
 /**
- * Combines tag-based middleware with wiring-specific middleware and function-level middleware.
+ * Combines wiring-specific middleware with function-level middleware.
  *
- * This helper function gets middleware for tags and combines it with any
- * wiring-specific middleware and function-level middleware, avoiding the need for manual spreading.
+ * This function resolves middleware metadata into actual middleware functions and combines them.
+ * It filters out wire middleware without tags from inheritedMiddleware to avoid duplication
+ * (those are passed separately as wireMiddleware).
  *
  * @param {object} options - Configuration object for combining middleware.
- * @param {CorePikkuMiddleware[] | undefined} options.wiringMiddleware - Wiring-specific middleware.
- * @param {string[] | undefined} options.wiringTags - Array of wiring-level tags to look up middleware for.
- * @param {CorePikkuMiddleware[] | undefined} options.funcMiddleware - Function-level middleware.
- * @param {string[] | undefined} options.funcTags - Array of function-level tags to look up middleware for.
- * @returns {CorePikkuMiddleware[]} Combined array of tag-based and wiring-specific middleware.
+ * @param {MiddlewareMetadata[] | undefined} options.inheritedMiddleware - Metadata from wiring (HTTP + tags + wire with tags).
+ * @param {CorePikkuMiddleware[] | undefined} options.wireMiddleware - Inline wire middleware.
+ * @param {MiddlewareMetadata[] | undefined} options.funcMiddleware - Function middleware metadata.
+ * @returns {CorePikkuMiddleware[]} Combined array of resolved middleware.
  *
  * @example
  * ```typescript
- * const combined = combineMiddleware({
- *   wiringMiddleware: httpRoute.middleware,
- *   wiringTags: httpRoute.tags,
- *   funcMiddleware: funcConfig.middleware,
- *   funcTags: funcConfig.tags
+ * const combined = combineMiddleware(wireType, wireId, {
+ *   inheritedMiddleware: meta.middleware,
+ *   wireMiddleware: [inlineMiddleware],
+ *   funcMiddleware: funcMeta.middleware
  * })
  * ```
  */
@@ -163,38 +175,79 @@ export const combineMiddleware = (
   wireType: PikkuWiringTypes,
   uid: string,
   {
-    httpMiddleware,
-    wiringMiddleware,
-    wiringTags,
+    wireInheritedMiddleware,
+    wireMiddleware,
+    funcInheritedMiddleware,
     funcMiddleware,
-    funcTags,
   }: {
-    httpMiddleware?: CorePikkuMiddleware[]
-    wiringMiddleware?: CorePikkuMiddleware[]
-    wiringTags?: string[]
+    wireInheritedMiddleware?: MiddlewareMetadata[]
+    wireMiddleware?: CorePikkuMiddleware[]
+    funcInheritedMiddleware?: MiddlewareMetadata[]
     funcMiddleware?: CorePikkuMiddleware[]
-    funcTags?: string[]
   } = {}
 ): readonly CorePikkuMiddleware[] => {
   if (middlewareCache[wireType][uid]) {
     return middlewareCache[wireType][uid]
   }
 
-  // Run middleware in specific order:
-  // 1) wiringTags middleware
-  // 2) wiringMiddleware
-  // 3) funcMiddleware
-  // 4) funcTags middleware
-  const wiringTaggedMiddleware = getMiddlewareForTags(wiringTags)
-  const funcTaggedMiddleware = getMiddlewareForTags(funcTags)
+  const resolved: CorePikkuMiddleware[] = []
+
+  // 1. Resolve wire inherited middleware (HTTP + tag groups + individual wire middleware)
+  if (wireInheritedMiddleware) {
+    for (const meta of wireInheritedMiddleware) {
+      if (meta.type === 'http') {
+        // Look up HTTP middleware group from pikkuState
+        const group = pikkuState('middleware', 'httpGroup')[meta.route]
+        if (group) {
+          // At runtime, all factories should be resolved to middleware
+          resolved.push(...(group as CorePikkuMiddleware[]))
+        }
+      } else if (meta.type === 'tag') {
+        // Look up tag middleware group from pikkuState
+        const group = pikkuState('middleware', 'tagGroup')[meta.tag]
+        if (group) {
+          // At runtime, all factories should be resolved to middleware
+          resolved.push(...(group as CorePikkuMiddleware[]))
+        }
+      } else if (meta.type === 'wire') {
+        // Individual wire middleware (exported, not inline)
+        const middleware = getMiddlewareByName(meta.name)
+        if (middleware) {
+          resolved.push(middleware)
+        }
+      }
+    }
+  }
+
+  // 2. Add inline wire middleware
+  if (wireMiddleware) {
+    resolved.push(...wireMiddleware)
+  }
+
+  // 3. Resolve function inherited middleware (only tags, wire middleware already handled)
+  if (funcInheritedMiddleware) {
+    for (const meta of funcInheritedMiddleware) {
+      if (meta.type === 'tag') {
+        // Look up tag middleware group from pikkuState
+        const group = pikkuState('middleware', 'tagGroup')[meta.tag]
+        if (group) {
+          // At runtime, all factories should be resolved to middleware
+          resolved.push(...(group as CorePikkuMiddleware[]))
+        }
+      }
+      // Note: wire middleware is already handled in wireInheritedMiddleware
+    }
+  }
+
+  // 4. Add inline function middleware
+  if (funcMiddleware) {
+    resolved.push(...funcMiddleware)
+  }
 
-  middlewareCache[wireType][uid] = freezeDedupe([
-    ...(httpMiddleware || []),
-    ...wiringTaggedMiddleware,
-    ...(wiringMiddleware || []),
-    ...(funcMiddleware || []),
-    ...funcTaggedMiddleware,
-  ]) as readonly CorePikkuMiddleware[]
+  // Deduplicate and freeze
+  middlewareCache[wireType][uid] = freezeDedupe(
+    resolved
+  ) as readonly CorePikkuMiddleware[]
 
   return middlewareCache[wireType][uid]
 }

package/src/permissions.ts

@@ -152,6 +152,7 @@ const permissionCache: Record<
   [PikkuWiringTypes.queue]: {},
   [PikkuWiringTypes.scheduler]: {},
   [PikkuWiringTypes.mcp]: {},
+  [PikkuWiringTypes.cli]: {},
 }
 
 /**

package/src/pikku-state.ts

@@ -4,7 +4,12 @@ import {
   HTTPMethod,
   HTTPWiringsMeta,
 } from './wirings/http/http.types.js'
-import { FunctionsMeta, CorePikkuMiddleware } from './types/core.types.js'
+import {
+  FunctionsMeta,
+  CorePikkuMiddleware,
+  CorePikkuMiddlewareGroup,
+  FunctionServicesMeta,
+} from './types/core.types.js'
 import {
   CoreScheduledTask,
   ScheduledTasksMeta,
@@ -27,6 +32,7 @@ import {
   MCPToolMeta,
   MCPPromptMeta,
 } from './wirings/mcp/mcp.types.js'
+import { CLIProgramMeta, CLIProgramState } from './wirings/cli/cli.types.js'
 
 interface PikkuState {
   function: {
@@ -69,6 +75,36 @@ interface PikkuState {
     prompts: Map<string, CoreMCPPrompt>
     promptsMeta: MCPPromptMeta
   }
+  cli: {
+    meta: Record<string, CLIProgramMeta>
+    programs: Record<string, CLIProgramState>
+  }
+  middleware: {
+    tagGroup: Record<string, CorePikkuMiddlewareGroup>
+    httpGroup: Record<string, CorePikkuMiddlewareGroup>
+    tagGroupMeta: Record<
+      string,
+      {
+        exportName: string | null
+        sourceFile: string
+        position: number
+        services: FunctionServicesMeta
+        middlewareCount: number
+        isFactory: boolean
+      }
+    >
+    httpGroupMeta: Record<
+      string,
+      {
+        exportName: string | null
+        sourceFile: string
+        position: number
+        services: FunctionServicesMeta
+        middlewareCount: number
+        isFactory: boolean
+      }
+    >
+  }
   misc: {
     errors: Map<PikkuError, ErrorDetails>
     schemas: Map<string, any>
@@ -89,7 +125,6 @@ export const resetPikkuState = () => {
     },
     http: {
       permissions: new Map(),
-      middleware: new Map(),
       routes: new Map(),
       meta: {},
     },
@@ -113,6 +148,16 @@ export const resetPikkuState = () => {
       prompts: new Map(),
       promptsMeta: {} as MCPPromptMeta,
     },
+    cli: {
+      meta: {},
+      programs: {},
+    },
+    middleware: {
+      tagGroup: {},
+      httpGroup: {},
+      tagGroupMeta: {},
+      httpGroupMeta: {},
+    },
     misc: {
       errors: globalThis.pikkuState?.misc?.errors || new Map(),
       schemas: new Map(),

package/src/services/content-service.ts

@@ -1,5 +1,3 @@
-import { ReadStream } from 'fs'
-
 export interface ContentService {
   /**
    * Signs a content key to generate a secure, time-limited access URL.
@@ -49,7 +47,10 @@ export interface ContentService {
    * @param stream - A readable stream of the file contents.
    * @returns A boolean indicating success.
    */
-  writeFile(assetKey: string, stream: ReadStream): Promise<boolean>
+  writeFile(
+    assetKey: string,
+    stream: ReadableStream | NodeJS.ReadableStream
+  ): Promise<boolean>
 
   /**
    * Copies a file from a local absolute path into storage under a new asset key.
@@ -64,5 +65,5 @@ export interface ContentService {
    * @param assetKey - The key of the file to read.
    * @returns A readable file stream.
    */
-  readFile(assetKey: string): Promise<ReadStream>
+  readFile(assetKey: string): Promise<ReadableStream | NodeJS.ReadableStream>
 }

package/src/services/index.ts

@@ -15,4 +15,3 @@ export * from './user-session-service.js'
 export * from './local-secrets.js'
 export * from './local-variables.js'
 export * from './logger-console.js'
-export * from './local-content.js'

package/src/services/local-content.ts

@@ -1,4 +1,4 @@
-import { createReadStream, createWriteStream, promises, ReadStream } from 'fs'
+import { createReadStream, createWriteStream, promises } from 'fs'
 import { mkdir } from 'fs/promises'
 import { ContentService, Logger } from '@pikku/core/services'
 import { pipeline } from 'stream/promises'
@@ -38,7 +38,10 @@ export class LocalContent implements ContentService {
     }
   }
 
-  public async writeFile(assetKey: string, stream: Readable): Promise<boolean> {
+  public async writeFile(
+    assetKey: string,
+    stream: ReadableStream | NodeJS.ReadableStream
+  ): Promise<boolean> {
     this.logger.debug(`Writing file: ${assetKey}`)
 
     const path = `${this.config.localFileUploadPath}/${assetKey}`
@@ -47,7 +50,7 @@ export class LocalContent implements ContentService {
       await this.createDirectoryForFile(path)
       const fileStream = createWriteStream(path)
       // Use pipeline to properly manage stream piping and errors
-      await pipeline(stream, fileStream)
+      await pipeline(stream as Readable, fileStream)
       return true
     } catch (e) {
       console.error(e)
@@ -72,7 +75,9 @@ export class LocalContent implements ContentService {
     return false
   }
 
-  public async readFile(assetKey: string): Promise<ReadStream> {
+  public async readFile(
+    assetKey: string
+  ): Promise<ReadableStream | NodeJS.ReadableStream> {
     this.logger.debug(`Getting key: ${assetKey}`)
 
     const filePath = `${this.config.localFileUploadPath}/${assetKey}`

package/src/types/core.types.ts

@@ -8,6 +8,7 @@ import { PikkuRPC } from '../wirings/rpc/rpc-types.js'
 import { PikkuMCP } from '../wirings/mcp/mcp.types.js'
 import { PikkuScheduledTask } from '../wirings/scheduler/scheduler.types.js'
 import { PikkuQueue } from '../wirings/queue/queue.types.js'
+import { PikkuCLI } from '../wirings/cli/cli.types.js'
 
 export enum PikkuWiringTypes {
   http = 'http',
@@ -16,6 +17,7 @@ export enum PikkuWiringTypes {
   rpc = 'rpc',
   queue = 'queue',
   mcp = 'mcp',
+  cli = 'cli',
 }
 
 export interface FunctionServicesMeta {
@@ -23,6 +25,27 @@ export interface FunctionServicesMeta {
   services: string[]
 }
 
+/**
+ * Metadata for middleware at any level
+ * - type: 'http' = HTTP route middleware group (references httpGroup in pikkuState)
+ * - type: 'tag' = Tag-based middleware group (references tagGroup in pikkuState)
+ * - type: 'wire' = Wire-level individual middleware
+ */
+export type MiddlewareMetadata =
+  | {
+      type: 'http'
+      route: string // Route pattern (e.g., '*' for all, '/api/*' for specific)
+    }
+  | {
+      type: 'tag'
+      tag: string // Tag name
+    }
+  | {
+      type: 'wire'
+      name: string
+      inline?: boolean // true if inline middleware
+    }
+
 export type FunctionRuntimeMeta = {
   pikkuFuncName: string
   inputSchemaName: string | null
@@ -39,6 +62,7 @@ export type FunctionMeta = FunctionRuntimeMeta &
     tags: string[]
     docs: PikkuDocs
     isDirectFunction: boolean // true if it's pikkuFunc(fn), false if it's pikkuFunc({ func: fn })
+    middleware: MiddlewareMetadata[] // Function-level middleware (type will be undefined)
   }>
 
 export type FunctionsRuntimeMeta = Record<string, FunctionRuntimeMeta>
@@ -121,6 +145,7 @@ export type PikkuInteraction<In = unknown, Out = unknown> = Partial<{
   channel: PikkuChannel<unknown, Out>
   scheduledTask: PikkuScheduledTask
   queue: PikkuQueue
+  cli: PikkuCLI
 }>
 
 /**
@@ -137,6 +162,28 @@ export type CorePikkuMiddleware<
   next: () => Promise<void>
 ) => Promise<void>
 
+/**
+ * A factory function that takes input and returns middleware
+ * Used when middleware needs configuration/input parameters
+ */
+export type CorePikkuMiddlewareFactory<
+  In = any,
+  SingletonServices extends CoreSingletonServices = CoreSingletonServices,
+  UserSession extends CoreUserSession = CoreUserSession,
+> = (input: In) => CorePikkuMiddleware<SingletonServices, UserSession>
+
+/**
+ * A group of middleware (combination of regular middleware and factories)
+ * Used with addMiddleware() and addHTTPMiddleware() to group related middleware together
+ */
+export type CorePikkuMiddlewareGroup<
+  SingletonServices extends CoreSingletonServices = CoreSingletonServices,
+  UserSession extends CoreUserSession = CoreUserSession,
+> = Array<
+  | CorePikkuMiddleware<SingletonServices, UserSession>
+  | CorePikkuMiddlewareFactory<any, SingletonServices, UserSession>
+>
+
 /**
  * Factory function for creating middleware with tree-shaking support
  */
@@ -149,6 +196,29 @@ export const pikkuMiddleware = <
   return middleware
 }
 
+/**
+ * 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: CorePikkuMiddlewareFactory<In>
+): CorePikkuMiddlewareFactory<In> => {
+  return factory
+}
+
 /**
  * Represents the core services used by Pikku, including singleton services and the request/response interaction.
  */
@@ -193,9 +263,10 @@ export type CreateSessionServices<
 /**
  * Defines a function type for creating config.
  */
-export type CreateConfig<Config extends CoreConfig> = (
-  variables?: VariablesService
-) => Promise<Config>
+export type CreateConfig<
+  Config extends CoreConfig,
+  RemainingArgs extends any[] = unknown[],
+> = (variables?: VariablesService, ...args: RemainingArgs) => Promise<Config>
 
 /**
  * Represents the documentation for a route, including summary, description, tags, and errors.

package/src/wirings/channel/channel-handler.ts

@@ -61,7 +61,6 @@ const validateAuth = (
 
 export const processMessageHandlers = (
   services: CoreServices,
-  session: CoreUserSession | undefined,
   channelConfig: CoreChannel<any, any>,
   channelHandler: PikkuChannelHandler
 ) => {
@@ -71,7 +70,6 @@ export const processMessageHandlers = (
   const processMessage = async (
     data: JSONValue,
     onMessage: any,
-    session: CoreUserSession | undefined,
     routingProperty?: string,
     routerValue?: string
   ): Promise<unknown> => {
@@ -87,7 +85,7 @@ export const processMessageHandlers = (
       return
     }
 
-    const { pikkuFuncName } = getRouteMeta(
+    const { pikkuFuncName, middleware: inheritedMiddleware } = getRouteMeta(
       channelConfig.name,
       routingProperty,
       routerValue
@@ -104,15 +102,18 @@ export const processMessageHandlers = (
       channelConfig.name,
       pikkuFuncName,
       {
+        singletonServices: services,
         getAllServices: () => ({
           ...services,
           channel: channelHandler.getChannel(),
         }),
-        data,
-        session,
+        data: () => data,
+        userSession: services.userSession,
         permissions,
-        middleware,
+        inheritedMiddleware,
+        wireMiddleware: middleware,
         tags: channelConfig.tags,
+        interaction: { channel: channelHandler.getChannel() },
       }
     )
   }
@@ -133,7 +134,6 @@ export const processMessageHandlers = (
             result = await processMessage(
               messageData,
               routes[routerValue],
-              session,
               routingProperty,
               routerValue
             )
@@ -144,11 +144,7 @@ export const processMessageHandlers = (
         // Default handler if no routes matched but json data was parsed
         if (!processed && channelConfig.onMessage) {
           processed = true
-          result = await processMessage(
-            messageData,
-            channelConfig.onMessage,
-            session
-          )
+          result = await processMessage(messageData, channelConfig.onMessage)
         }
       } catch (error) {
         // Most likely a json error.. ignore
@@ -158,7 +154,7 @@ export const processMessageHandlers = (
     // Default handler if no routes matched and json data wasn't parsed
     if (!processed && channelConfig.onMessage) {
       processed = true
-      result = await processMessage(rawData, channelConfig.onMessage, session)
+      result = await processMessage(rawData, channelConfig.onMessage)
     }
 
     if (!processed) {