@pikku/core 0.9.12-next.0 → 0.10.0

package/src/pikku-state.ts

@@ -32,7 +32,7 @@ import {
   MCPToolMeta,
   MCPPromptMeta,
 } from './wirings/mcp/mcp.types.js'
-import { CLIProgramMeta, CLIProgramState } from './wirings/cli/cli.types.js'
+import { CLIMeta, CLIProgramState } from './wirings/cli/cli.types.js'
 
 interface PikkuState {
   function: {
@@ -76,7 +76,7 @@ interface PikkuState {
     promptsMeta: MCPPromptMeta
   }
   cli: {
-    meta: Record<string, CLIProgramMeta>
+    meta: CLIMeta | Record<string, any> // Backward compatible with old published CLI format
     programs: Record<string, CLIProgramState>
   }
   middleware: {
@@ -105,6 +105,32 @@ interface PikkuState {
       }
     >
   }
+  permissions: {
+    tagGroup: Record<string, CorePermissionGroup | CorePikkuPermission[]>
+    httpGroup: Record<string, CorePermissionGroup | CorePikkuPermission[]>
+    tagGroupMeta: Record<
+      string,
+      {
+        exportName: string | null
+        sourceFile: string
+        position: number
+        services: FunctionServicesMeta
+        permissionCount: number
+        isFactory: boolean
+      }
+    >
+    httpGroupMeta: Record<
+      string,
+      {
+        exportName: string | null
+        sourceFile: string
+        position: number
+        services: FunctionServicesMeta
+        permissionCount: number
+        isFactory: boolean
+      }
+    >
+  }
   misc: {
     errors: Map<PikkuError, ErrorDetails>
     schemas: Map<string, any>
@@ -149,7 +175,7 @@ export const resetPikkuState = () => {
       promptsMeta: {} as MCPPromptMeta,
     },
     cli: {
-      meta: {},
+      meta: { programs: {}, renderers: {} },
       programs: {},
     },
     middleware: {
@@ -158,6 +184,12 @@ export const resetPikkuState = () => {
       tagGroupMeta: {},
       httpGroupMeta: {},
     },
+    permissions: {
+      tagGroup: {},
+      httpGroup: {},
+      tagGroupMeta: {},
+      httpGroupMeta: {},
+    },
     misc: {
       errors: globalThis.pikkuState?.misc?.errors || new Map(),
       schemas: new Map(),

package/src/types/core.types.ts

@@ -1,6 +1,7 @@
 import type { Logger, LogLevel } from '../services/logger.js'
 import { VariablesService } from '../services/variables-service.js'
 import { SchemaService } from '../services/schema-service.js'
+import { JWTService } from '../services/jwt-service.js'
 import { PikkuHTTP } from '../wirings/http/http.types.js'
 import { UserSessionService } from '../services/user-session-service.js'
 import { PikkuChannel } from '../wirings/channel/channel.types.js'
@@ -46,6 +47,27 @@ export type MiddlewareMetadata =
       inline?: boolean // true if inline middleware
     }
 
+/**
+ * Metadata for permissions at any level
+ * - type: 'http' = HTTP route permission group (references httpGroup in pikkuState)
+ * - type: 'tag' = Tag-based permission group (references tagGroup in pikkuState)
+ * - type: 'wire' = Wire-level individual permission
+ */
+export type PermissionMetadata =
+  | {
+      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 permission
+    }
+
 export type FunctionRuntimeMeta = {
   pikkuFuncName: string
   inputSchemaName: string | null
@@ -62,7 +84,8 @@ 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)
+    middleware: MiddlewareMetadata[] // Function-level middleware
+    permissions: PermissionMetadata[] // Function-level permissions
   }>
 
 export type FunctionsRuntimeMeta = Record<string, FunctionRuntimeMeta>
@@ -127,6 +150,8 @@ export interface CoreUserSession {}
 export interface CoreSingletonServices<Config extends CoreConfig = CoreConfig> {
   /** The schema library used to validate data */
   schema?: SchemaService
+  /** The JWT service used to encode and decode tokens */
+  jwt?: JWTService
   /** The core configuration for the application. */
   config: Config
   /** The logger used by the application. */
@@ -162,6 +187,24 @@ export type CorePikkuMiddleware<
   next: () => Promise<void>
 ) => Promise<void>
 
+/**
+ * Configuration object for creating middleware with metadata
+ *
+ * @template SingletonServices - The singleton services type
+ * @template UserSession - The user session type
+ */
+export type CorePikkuMiddlewareConfig<
+  SingletonServices extends CoreSingletonServices = CoreSingletonServices,
+  UserSession extends CoreUserSession = CoreUserSession,
+> = {
+  /** The middleware function */
+  func: CorePikkuMiddleware<SingletonServices, UserSession>
+  /** Optional human-readable name for the middleware */
+  name?: string
+  /** Optional description of what the middleware does */
+  description?: string
+}
+
 /**
  * A factory function that takes input and returns middleware
  * Used when middleware needs configuration/input parameters
@@ -186,14 +229,38 @@ export type CorePikkuMiddlewareGroup<
 
 /**
  * Factory function for creating middleware with tree-shaking support
+ * Supports both direct function and configuration object syntax
+ *
+ * @example
+ * ```typescript
+ * // Direct function syntax
+ * export const logMiddleware = pikkuMiddleware(
+ *   async ({ logger }, _interaction, next) => {
+ *     logger.info('Request started')
+ *     await next()
+ *   }
+ * )
+ *
+ * // Configuration object syntax with metadata
+ * export const logMiddleware = pikkuMiddleware({
+ *   name: 'Request Logger',
+ *   description: 'Logs request information',
+ *   func: async ({ logger }, _interaction, next) => {
+ *     logger.info('Request started')
+ *     await next()
+ *   }
+ * })
+ * ```
  */
 export const pikkuMiddleware = <
   SingletonServices extends CoreSingletonServices = CoreSingletonServices,
   UserSession extends CoreUserSession = CoreUserSession,
 >(
-  middleware: CorePikkuMiddleware<SingletonServices, UserSession>
+  middleware:
+    | CorePikkuMiddleware<SingletonServices, UserSession>
+    | CorePikkuMiddlewareConfig<SingletonServices, UserSession>
 ): CorePikkuMiddleware<SingletonServices, UserSession> => {
-  return middleware
+  return typeof middleware === 'function' ? middleware : middleware.func
 }
 
 /**

package/src/utils.ts

@@ -41,7 +41,7 @@ export const isSerializable = (data: any): boolean => {
 
 const EMPTY_ARRAY = Object.freeze([])
 
-export const freezeDedupe = <T extends Function>(
+export const freezeDedupe = <T>(
   arr?: readonly T[] | T[] | undefined
 ): readonly T[] => {
   if (!arr || arr.length === 0) return EMPTY_ARRAY

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

@@ -85,16 +85,16 @@ export const processMessageHandlers = (
       return
     }
 
-    const { pikkuFuncName, middleware: inheritedMiddleware } = getRouteMeta(
-      channelConfig.name,
-      routingProperty,
-      routerValue
-    )
+    const {
+      pikkuFuncName,
+      middleware: inheritedMiddleware,
+      permissions: inheritedPermissions,
+    } = getRouteMeta(channelConfig.name, routingProperty, routerValue)
 
-    const permissions =
-      typeof onMessage === 'function' ? {} : onMessage.permissions
+    const wirePermissions =
+      typeof onMessage === 'function' ? undefined : onMessage.permissions
 
-    const middleware =
+    const wireMiddleware =
       typeof onMessage === 'function' ? [] : onMessage.middleware
 
     return await runPikkuFunc(
@@ -109,9 +109,10 @@ export const processMessageHandlers = (
         }),
         data: () => data,
         userSession: services.userSession,
-        permissions,
         inheritedMiddleware,
-        wireMiddleware: middleware,
+        wireMiddleware,
+        inheritedPermissions,
+        wirePermissions,
         tags: channelConfig.tags,
         interaction: { channel: channelHandler.getChannel() },
       }

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

@@ -1,8 +1,10 @@
 import { NotFoundError } from '../../errors/errors.js'
 import { addFunction } from '../../function/function-runner.js'
+import { CorePikkuPermission } from '../../function/functions.types.js'
 import { pikkuState } from '../../pikku-state.js'
 import { coerceTopLevelDataFromSchema, validateSchema } from '../../schema.js'
 import { UserSessionService } from '../../services/user-session-service.js'
+import { CorePikkuMiddleware } from '../../types/core.types.js'
 import { httpRouter } from '../http/routers/http-router.js'
 import {
   ChannelMeta,
@@ -18,11 +20,17 @@ import {
 export const wireChannel = <
   In,
   Channel extends string,
+  PikkuPermission extends CorePikkuPermission<In>,
+  PikkuMiddleware extends CorePikkuMiddleware,
   ChannelFunction,
-  ChannelFunctionSessionless,
-  PikkuPermission,
 >(
-  channel: CoreChannel<In, Channel, ChannelFunction, PikkuPermission>
+  channel: CoreChannel<
+    In,
+    Channel,
+    PikkuPermission,
+    PikkuMiddleware,
+    ChannelFunction
+  >
 ) => {
   // Get the channel metadata
   const channelsMeta = pikkuState('channel', 'meta')
@@ -35,27 +43,20 @@ export const wireChannel = <
 
   // Register onConnect function if provided
   if (channel.onConnect && channelMeta.connect) {
-    addFunction(channelMeta.connect.pikkuFuncName, {
-      func: channel.onConnect as any,
-    })
+    addFunction(channelMeta.connect.pikkuFuncName, channel.onConnect as any)
   }
 
   // Register onDisconnect function if provided
   if (channel.onDisconnect && channelMeta.disconnect) {
-    addFunction(channelMeta.disconnect.pikkuFuncName, {
-      func: channel.onDisconnect,
-    })
+    addFunction(
+      channelMeta.disconnect.pikkuFuncName,
+      channel.onDisconnect as any
+    )
   }
 
   // Register onMessage function if provided
   if (channel.onMessage && channelMeta.message?.pikkuFuncName) {
-    const messageFunc =
-      typeof channel.onMessage === 'function'
-        ? channel.onMessage
-        : channel.onMessage.func
-    addFunction(channelMeta.message.pikkuFuncName, {
-      func: messageFunc,
-    })
+    addFunction(channelMeta.message.pikkuFuncName, channel.onMessage as any)
   }
 
   // Register functions in onMessageWiring
@@ -70,18 +71,8 @@ export const wireChannel = <
         const wiringMeta = channelWirings[wiringKey]
         if (!wiringMeta) return
 
-        // Extract the function from the handler
-        const wiringFunc =
-          typeof handler === 'function'
-            ? { func: handler }
-            : {
-                func: handler.func,
-                auth: handler.auth,
-                permissions: handler.permissions,
-              }
-
         // Register the function using the pikku name from metadata
-        addFunction(wiringMeta.pikkuFuncName, wiringFunc)
+        addFunction(wiringMeta.pikkuFuncName, handler as any)
       })
     })
   }

package/src/wirings/channel/channel.types.ts

@@ -10,9 +10,12 @@ import {
   CreateSessionServices,
   CorePikkuMiddleware,
   MiddlewareMetadata,
+  PermissionMetadata,
 } from '../../types/core.types.js'
 import {
+  CorePermissionGroup,
   CorePikkuFunction,
+  CorePikkuFunctionConfig,
   CorePikkuFunctionSessionless,
   CorePikkuPermission,
 } from '../../function/functions.types.js'
@@ -37,6 +40,7 @@ export interface ChannelMessageMeta {
   pikkuFuncName: string
   docs?: PikkuDocs
   middleware?: MiddlewareMetadata[]
+  permissions?: PermissionMetadata[]
 }
 
 export interface ChannelMeta {
@@ -53,6 +57,7 @@ export interface ChannelMeta {
   docs?: PikkuDocs
   tags?: string[]
   middleware?: MiddlewareMetadata[] // Pre-resolved middleware chain (tag + explicit)
+  permissions?: PermissionMetadata[] // Pre-resolved permission chain (tag + explicit)
 }
 
 export type ChannelsMeta = Record<string, ChannelMeta>
@@ -60,15 +65,24 @@ export type ChannelsMeta = Record<string, ChannelMeta>
 export type CoreChannel<
   ChannelData,
   Channel extends string,
-  ChannelConnect =
+  ChannelConnect = CorePikkuFunctionConfig<
     | CorePikkuFunction<void, unknown, ChannelData>
     | CorePikkuFunctionSessionless<void, unknown, ChannelData>,
-  ChannelDisconnect =
+    CorePikkuPermission<void>,
+    CorePikkuMiddleware
+  >,
+  ChannelDisconnect = CorePikkuFunctionConfig<
     | CorePikkuFunction<void, void, ChannelData>
     | CorePikkuFunctionSessionless<void, void, ChannelData>,
-  ChannelFunctionMessage =
+    CorePikkuPermission<void>,
+    CorePikkuMiddleware
+  >,
+  ChannelFunctionMessage = CorePikkuFunctionConfig<
     | CorePikkuFunction<unknown, unknown, ChannelData>
     | CorePikkuFunctionSessionless<unknown, unknown, ChannelData>,
+    CorePikkuPermission<unknown>,
+    CorePikkuMiddleware
+  >,
   PikkuPermission = CorePikkuPermission<ChannelData>,
   PikkuMiddleware = CorePikkuMiddleware,
 > = {
@@ -76,13 +90,7 @@ export type CoreChannel<
   route: Channel
   onConnect?: ChannelConnect
   onDisconnect?: ChannelDisconnect
-  onMessage?:
-    | {
-        func: ChannelFunctionMessage
-        permissions?: Record<string, PikkuPermission[] | PikkuPermission>
-        auth?: boolean
-      }
-    | ChannelFunctionMessage
+  onMessage?: ChannelFunctionMessage
   onMessageWiring?: Record<
     string,
     Record<
@@ -90,13 +98,14 @@ export type CoreChannel<
       | ChannelFunctionMessage
       | {
           func: ChannelFunctionMessage
-          permissions?: Record<string, PikkuPermission[] | PikkuPermission>
+          permissions?: CorePermissionGroup<PikkuPermission>
           auth?: boolean
+          middleware?: PikkuMiddleware[]
         }
     >
   >
   middleware?: PikkuMiddleware[]
-  permissions?: Record<string, PikkuPermission[] | PikkuPermission>
+  permissions?: CorePermissionGroup<PikkuPermission>
   auth?: boolean
   docs?: Partial<{
     description: string
@@ -107,16 +116,16 @@ export type CoreChannel<
   tags?: string[]
 }
 
-export interface PikkuChannel<OpeningData, Out> {
+export interface PikkuChannel<OpeningData, out Out> {
   // The channel identifier
   channelId: string
   // The data the channel was created with. This could be query parameters
   // or parameters in the url.
   openingData: OpeningData
   // The data to send. This will fail is the stream has been closed.
-  send: (data: Out, isBinary?: boolean) => Promise<void> | void
+  send(data: Out, isBinary?: boolean): Promise<void> | void
   // This will close the channel.
-  close: () => Promise<void> | void
+  close(): Promise<void> | void
   // The current state of the channel
   state: 'initial' | 'open' | 'closed'
 }

package/src/wirings/cli/channel/cli-channel-runner.ts

@@ -1,5 +1,5 @@
 import { pikkuState } from '../../../pikku-state.js'
-import { CorePikkuCLIRender } from '../cli.types.js'
+import { CorePikkuCLIRender, CLIMeta } from '../cli.types.js'
 import { generateCommandHelp, parseCLIArguments } from '../command-parser.js'
 
 /**
@@ -27,8 +27,13 @@ export async function executeCLIViaChannel({
   defaultRenderer?: CorePikkuCLIRender<any>
 }): Promise<void> {
   // Get CLI metadata from state
-  const allCLIMeta = pikkuState('cli', 'meta') || {}
-  const programMeta = allCLIMeta[programName]
+  const allCLIMeta = pikkuState('cli', 'meta') as unknown as CLIMeta | undefined
+  if (!allCLIMeta) {
+    throw new Error(
+      '[PKU342] CLI metadata not found. No CLI wirings were registered. See https://pikku.dev/errors/pku342 for more information.'
+    )
+  }
+  const programMeta = allCLIMeta.programs[programName]
 
   if (!programMeta) {
     console.error(`Error: CLI program "${programName}" not found`)

package/src/wirings/cli/cli-runner.test.ts

@@ -30,7 +30,7 @@ describe('CLI Runner', () => {
 
   describe('runCLICommand', () => {
     test('should throw NotFoundError when program not found', async () => {
-      pikkuState('cli', 'meta', {})
+      pikkuState('cli', 'meta', { programs: {}, renderers: {} })
 
       await assert.rejects(
         async () =>
@@ -46,11 +46,14 @@ describe('CLI Runner', () => {
 
     test('should throw NotFoundError when command not found', async () => {
       pikkuState('cli', 'meta', {
-        'test-cli': {
-          program: 'test-cli',
-          commands: {},
-          options: {},
+        programs: {
+          'test-cli': {
+            program: 'test-cli',
+            commands: {},
+            options: {},
+          },
         },
+        renderers: {},
       })
 
       pikkuState('cli', 'programs', {
@@ -82,18 +85,21 @@ describe('CLI Runner', () => {
 
       // Setup metadata
       pikkuState('cli', 'meta', {
-        'test-cli': {
-          program: 'test-cli',
-          commands: {
-            greet: {
-              command: 'greet <name>',
-              pikkuFuncName: 'greetFunc',
-              positionals: [{ name: 'name', required: true }],
-              options: {},
+        programs: {
+          'test-cli': {
+            program: 'test-cli',
+            commands: {
+              greet: {
+                command: 'greet <name>',
+                pikkuFuncName: 'greetFunc',
+                positionals: [{ name: 'name', required: true }],
+                options: {},
+              },
             },
+            options: {},
           },
-          options: {},
         },
+        renderers: {},
       })
 
       pikkuState('cli', 'programs', {
@@ -143,18 +149,21 @@ describe('CLI Runner', () => {
       }
 
       pikkuState('cli', 'meta', {
-        'test-cli': {
-          program: 'test-cli',
-          commands: {
-            test: {
-              command: 'test',
-              pikkuFuncName: 'testFunc',
-              positionals: [],
-              options: {},
+        programs: {
+          'test-cli': {
+            program: 'test-cli',
+            commands: {
+              test: {
+                command: 'test',
+                pikkuFuncName: 'testFunc',
+                positionals: [],
+                options: {},
+              },
             },
+            options: {},
           },
-          options: {},
         },
+        renderers: {},
       })
 
       pikkuState('cli', 'programs', {
@@ -200,18 +209,21 @@ describe('CLI Runner', () => {
       const testFunc = async () => ({ success: true })
 
       pikkuState('cli', 'meta', {
-        'test-cli': {
-          program: 'test-cli',
-          commands: {
-            greet: {
-              command: 'greet <name>',
-              pikkuFuncName: 'greetFunc',
-              positionals: [{ name: 'name', required: true }],
-              options: {},
+        programs: {
+          'test-cli': {
+            program: 'test-cli',
+            commands: {
+              greet: {
+                command: 'greet <name>',
+                pikkuFuncName: 'greetFunc',
+                positionals: [{ name: 'name', required: true }],
+                options: {},
+              },
             },
+            options: {},
           },
-          options: {},
         },
+        renderers: {},
       })
 
       pikkuState('cli', 'programs', {
@@ -249,18 +261,21 @@ describe('CLI Runner', () => {
       const testFunc = async () => ({ success: true })
 
       pikkuState('cli', 'meta', {
-        'test-cli': {
-          program: 'test-cli',
-          commands: {
-            secure: {
-              command: 'secure',
-              pikkuFuncName: 'secureFunc',
-              positionals: [],
-              options: {},
+        programs: {
+          'test-cli': {
+            program: 'test-cli',
+            commands: {
+              secure: {
+                command: 'secure',
+                pikkuFuncName: 'secureFunc',
+                positionals: [],
+                options: {},
+              },
             },
+            options: {},
           },
-          options: {},
         },
+        renderers: {},
       })
 
       pikkuState('function', 'meta', {
@@ -292,24 +307,27 @@ describe('CLI Runner', () => {
       const greetFunc = async () => 'Hello'
 
       pikkuState('cli', 'meta', {
-        'my-cli': {
-          program: 'my-cli',
-          commands: {
-            greet: {
-              command: 'greet <name>',
-              pikkuFuncName: 'greetFunc',
-              positionals: [{ name: 'name', required: true }],
-              options: {
-                loud: {
-                  description: 'Use loud greeting',
-                  short: 'l',
-                  default: false,
+        programs: {
+          'my-cli': {
+            program: 'my-cli',
+            commands: {
+              greet: {
+                command: 'greet <name>',
+                pikkuFuncName: 'greetFunc',
+                positionals: [{ name: 'name', required: true }],
+                options: {
+                  loud: {
+                    description: 'Use loud greeting',
+                    short: 'l',
+                    default: false,
+                  },
                 },
               },
             },
+            options: {},
           },
-          options: {},
         },
+        renderers: {},
       })
 
       wireCLI({
@@ -330,11 +348,14 @@ describe('CLI Runner', () => {
       }
 
       pikkuState('cli', 'meta', {
-        'my-cli': {
-          program: 'my-cli',
-          commands: {},
-          options: {},
+        programs: {
+          'my-cli': {
+            program: 'my-cli',
+            commands: {},
+            options: {},
+          },
         },
+        renderers: {},
       })
 
       wireCLI({
@@ -349,7 +370,7 @@ describe('CLI Runner', () => {
     })
 
     test('should throw error when CLI metadata not found', () => {
-      pikkuState('cli', 'meta', {})
+      pikkuState('cli', 'meta', { programs: {}, renderers: {} })
 
       assert.throws(() => {
         wireCLI({