@pikku/core 0.9.11 → 0.10.0

package/src/permissions.ts

@@ -2,6 +2,7 @@ import {
   CoreServices,
   CoreUserSession,
   PikkuWiringTypes,
+  PermissionMetadata,
 } from './types/core.types.js'
 import {
   CorePermissionGroup,
@@ -9,6 +10,7 @@ import {
 } from './function/functions.types.js'
 import { pikkuState } from './pikku-state.js'
 import { ForbiddenError } from './errors/errors.js'
+import { freezeDedupe } from './utils.js'
 
 /**
  * This function validates permissions by iterating over permission groups and executing the corresponding permission functions. If all functions in at least one group return true, the permission is considered valid.
@@ -51,43 +53,93 @@ export const verifyPermissions = async (
   return false
 }
 
+/**
+ * Registers a single permission function by name in the global permission store.
+ *
+ * This function is used by CLI-generated code to register permission functions
+ * that can be referenced by name in metadata. It stores permissions in a special
+ * namespace to avoid conflicts with tag-based permissions.
+ *
+ * @param {string} name - The unique name (pikkuFuncName) of the permission function.
+ * @param {CorePikkuPermission} permission - The permission function to register.
+ *
+ * @example
+ * ```typescript
+ * // Called by CLI-generated pikku-permissions.gen.ts
+ * registerPermission('adminPermission_src_permissions_ts_10_5', adminPermission)
+ * registerPermission('readPermission_src_permissions_ts_20_10', readPermission)
+ * ```
+ */
+export const registerPermission = (
+  name: string,
+  permission: CorePikkuPermission<any>
+) => {
+  const permissionStore = pikkuState('misc', 'permissions')
+  permissionStore[name] = [permission]
+}
+
+/**
+ * Retrieves a registered permission function by its name.
+ *
+ * This function looks up permissions that was registered with registerPermission.
+ * It's used internally by the framework to resolve permission references in metadata.
+ *
+ * @param {string} name - The unique name (pikkuFuncName) of the permission function.
+ * @returns {CorePikkuPermission | undefined} The permission function, or undefined if not found.
+ *
+ * @internal
+ */
+export const getPermissionByName = (
+  name: string
+): CorePikkuPermission | undefined => {
+  const permissionStore = pikkuState('misc', 'permissions')
+  const permission = permissionStore[name]
+  if (Array.isArray(permission) && permission.length === 1) {
+    return permission[0]
+  }
+  return undefined
+}
+
 /**
  * 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.
  *
+ * For tree-shaking benefits, wrap in a factory function:
+ * `export const x = () => addPermission('tag', [...])`
+ *
  * @param {string} tag - The tag that the permissions should apply to.
  * @param {any[]} permissions - The permissions array to apply for the specified tag.
  *
- * @throws {Error} If permissions for the tag already exist.
+ * @returns {CorePermissionGroup | CorePikkuPermission[]} The permissions (for chaining/wrapping).
  *
  * @example
  * ```typescript
- * // Add admin permissions for admin endpoints
- * addPermission('admin', [adminPermission])
- *
- * // Add authentication permissions for auth endpoints
- * addPermission('auth', [authPermission])
+ * // Recommended: tree-shakeable
+ * export const adminPermissions = () => addPermission('admin', [
+ *   adminPermission,
+ *   rolePermission({ role: 'admin' })
+ * ])
  *
- * // Add read permissions for all API endpoints
- * addPermission('api', [readPermission])
+ * // Also works: no tree-shaking
+ * export const apiPermissions = addPermission('api', [
+ *   readPermission
+ * ])
  * ```
  */
 export const addPermission = (
   tag: string,
   permissions: CorePermissionGroup | CorePikkuPermission[]
-) => {
-  const permissionsStore = pikkuState('misc', 'permissions')
-
-  // Check if tag already exists
-  if (permissionsStore[tag]) {
+): CorePermissionGroup | CorePikkuPermission[] => {
+  const tagGroups = pikkuState('permissions', 'tagGroup')
+  if (tagGroups[tag]) {
     throw new Error(
       `Permissions for tag '${tag}' already exist. Use a different tag or remove the existing permissions first.`
     )
   }
-
-  permissionsStore[tag] = permissions
+  tagGroups[tag] = permissions
+  return permissions
 }
 
 const EMPTY: readonly (CorePermissionGroup | CorePikkuPermission)[] = []
@@ -114,7 +166,7 @@ export const getPermissionsForTags = (
     return EMPTY
   }
 
-  const permissionsStore = pikkuState('misc', 'permissions')
+  const permissionsStore = pikkuState('permissions', 'tagGroup')
   const applicablePermissions: Array<
     CorePermissionGroup | CorePikkuPermission
   > = []
@@ -134,17 +186,9 @@ export const getPermissionsForTags = (
   return applicablePermissions
 }
 
-const permissionCache: Record<
+const combinedPermissionsCache: Record<
   PikkuWiringTypes,
-  Partial<
-    Record<
-      string,
-      {
-        wiringTags: readonly (CorePermissionGroup | CorePikkuPermission)[]
-        funcTags: readonly (CorePermissionGroup | CorePikkuPermission)[]
-      }
-    >
-  >
+  Record<string, readonly (CorePermissionGroup | CorePikkuPermission)[]>
 > = {
   [PikkuWiringTypes.http]: {},
   [PikkuWiringTypes.rpc]: {},
@@ -152,114 +196,182 @@ const permissionCache: Record<
   [PikkuWiringTypes.queue]: {},
   [PikkuWiringTypes.scheduler]: {},
   [PikkuWiringTypes.mcp]: {},
+  [PikkuWiringTypes.cli]: {},
 }
 
 /**
- * Runs permission checks in the specified order:
- * 1) wiring tag permissions - at least one must pass if any exist
- * 2) wiring permissions - must pass if defined
- * 3) function tag permissions - at least one must pass if any exist
- * 4) function permissions - must pass if defined
+ * Combines wiring-specific permissions with function-level permissions.
+ *
+ * This function resolves permission metadata into actual permission functions and combines them.
+ * It filters out wire permissions without tags from inheritedPermissions to avoid duplication
+ * (those are passed separately as wirePermissions).
+ *
+ * @param {object} options - Configuration object for combining permissions.
+ * @param {PermissionMetadata[] | undefined} options.wireInheritedPermissions - Metadata from wiring (HTTP + tags + wire with tags).
+ * @param {CorePermissionGroup | CorePikkuPermission[] | undefined} options.wirePermissions - Inline wire permissions.
+ * @param {PermissionMetadata[] | undefined} options.funcInheritedPermissions - Function permissions metadata (only tags).
+ * @param {CorePermissionGroup | CorePikkuPermission[] | undefined} options.funcPermissions - Inline function permissions.
+ * @returns {(CorePermissionGroup | CorePikkuPermission)[]} Combined array of resolved permissions.
+ *
+ * @example
+ * ```typescript
+ * const combined = combinePermissions(wireType, wireId, {
+ *   wireInheritedPermissions: meta.permissions,
+ *   wirePermissions: inlinePermissions,
+ *   funcInheritedPermissions: funcMeta.permissions,
+ *   funcPermissions: funcConfig.permissions
+ * })
+ * ```
  */
-export const runPermissions = async (
+export const combinePermissions = (
   wireType: PikkuWiringTypes,
   uid: string,
   {
-    wiringTags,
-    wiringPermissions,
-    funcTags,
+    wireInheritedPermissions,
+    wirePermissions,
+    funcInheritedPermissions,
     funcPermissions,
-    allServices,
-    data,
-    session,
   }: {
-    wiringTags?: string[]
-    wiringPermissions?: CorePermissionGroup
-    funcTags?: string[]
-    funcPermissions?: CorePermissionGroup
-    allServices: CoreServices
-    data: any
-    session?: CoreUserSession
+    wireInheritedPermissions?: PermissionMetadata[]
+    wirePermissions?: CorePermissionGroup | CorePikkuPermission[]
+    funcInheritedPermissions?: PermissionMetadata[]
+    funcPermissions?: CorePermissionGroup | CorePikkuPermission[]
+  } = {}
+): readonly (CorePermissionGroup | CorePikkuPermission)[] => {
+  if (combinedPermissionsCache[wireType][uid]) {
+    return combinedPermissionsCache[wireType][uid]
   }
-) => {
-  let cachedPermission = permissionCache[wireType][uid]
-  if (!cachedPermission) {
-    cachedPermission = {
-      wiringTags: getPermissionsForTags(wiringTags),
-      funcTags: getPermissionsForTags(funcTags),
+
+  const resolved: (CorePermissionGroup | CorePikkuPermission)[] = []
+
+  // 1. Resolve wire inherited permissions (HTTP + tag groups + individual wire permissions)
+  if (wireInheritedPermissions) {
+    for (const meta of wireInheritedPermissions) {
+      if (meta.type === 'http') {
+        // Look up HTTP permission group from pikkuState
+        const group = pikkuState('permissions', 'httpGroup')[meta.route]
+        if (group) {
+          if (Array.isArray(group)) {
+            resolved.push(...group)
+          } else {
+            resolved.push(group)
+          }
+        }
+      } else if (meta.type === 'tag') {
+        // Look up tag permission group from pikkuState
+        const group = pikkuState('permissions', 'tagGroup')[meta.tag]
+        if (group) {
+          if (Array.isArray(group)) {
+            resolved.push(...group)
+          } else {
+            resolved.push(group)
+          }
+        }
+      } else if (meta.type === 'wire') {
+        // Individual wire permission (exported, not inline)
+        const permission = getPermissionByName(meta.name)
+        if (permission) {
+          resolved.push(permission)
+        }
+      }
     }
-    permissionCache[wireType][uid] = cachedPermission
   }
-  let permissioned = true
 
-  // 1. Wiring tag permissions - at least one must pass if any exist
-  const wiringTaggedPermissions = cachedPermission.wiringTags
-  if (wiringTaggedPermissions.length > 0) {
-    permissioned = false // Start false, need at least one to pass
-    for (const permissions of wiringTaggedPermissions) {
-      const result = await verifyPermissions(
-        typeof permissions === 'function' ? { permissions } : permissions,
-        allServices,
-        data,
-        session
-      )
-      if (result) {
-        permissioned = true
-        break // At least one passed, we're good at this level
-      }
+  // 2. Add inline wire permissions
+  if (wirePermissions) {
+    if (Array.isArray(wirePermissions)) {
+      resolved.push(...wirePermissions)
+    } else {
+      resolved.push(wirePermissions)
     }
-    if (!permissioned) {
-      allServices.logger.debug('Permission denied - wiring tag permissions')
-      throw new ForbiddenError('Permission denied')
+  }
+
+  // 3. Resolve function inherited permissions (only tags, wire permissions already handled)
+  if (funcInheritedPermissions) {
+    for (const meta of funcInheritedPermissions) {
+      if (meta.type === 'tag') {
+        // Look up tag permission group from pikkuState
+        const group = pikkuState('permissions', 'tagGroup')[meta.tag]
+        if (group) {
+          if (Array.isArray(group)) {
+            resolved.push(...group)
+          } else {
+            resolved.push(group)
+          }
+        }
+      }
+      // Note: wire permissions are already handled in wireInheritedPermissions
     }
   }
 
-  // 2. Wiring permissions - must pass if defined
-  if (wiringPermissions) {
-    permissioned = await verifyPermissions(
-      wiringPermissions,
-      allServices,
-      data,
-      session
-    )
-    if (!permissioned) {
-      allServices.logger.debug('Permission denied - wiring permissions')
-      throw new ForbiddenError('Permission denied')
+  // 4. Add inline function permissions
+  if (funcPermissions) {
+    if (Array.isArray(funcPermissions)) {
+      resolved.push(...funcPermissions)
+    } else {
+      resolved.push(funcPermissions)
     }
   }
 
-  // 3. Function tag permissions - at least one must pass if any exist
-  const funcTaggedPermissions = cachedPermission.funcTags
-  if (funcTaggedPermissions.length > 0) {
-    permissioned = false // Start false, need at least one to pass
-    for (const permissions of funcTaggedPermissions) {
+  // Deduplicate and freeze
+  combinedPermissionsCache[wireType][uid] = freezeDedupe(resolved) as readonly (
+    | CorePermissionGroup
+    | CorePikkuPermission
+  )[]
+
+  return combinedPermissionsCache[wireType][uid]
+}
+
+/**
+ * Runs permission checks using combined permissions from all sources.
+ * Combines permissions from wire and function levels, then validates them.
+ */
+export const runPermissions = async (
+  wireType: PikkuWiringTypes,
+  uid: string,
+  {
+    wireInheritedPermissions,
+    wirePermissions,
+    funcInheritedPermissions,
+    funcPermissions,
+    allServices,
+    data,
+    session,
+  }: {
+    wireInheritedPermissions?: PermissionMetadata[]
+    wirePermissions?: CorePermissionGroup | CorePikkuPermission[]
+    funcInheritedPermissions?: PermissionMetadata[]
+    funcPermissions?: CorePermissionGroup | CorePikkuPermission[]
+    allServices: CoreServices
+    data: any
+    session?: CoreUserSession
+  }
+) => {
+  // Combine all permissions: wireInheritedPermissions → wirePermissions → funcInheritedPermissions → funcPermissions
+  const allPermissions = combinePermissions(wireType, uid, {
+    wireInheritedPermissions,
+    wirePermissions,
+    funcInheritedPermissions,
+    funcPermissions,
+  })
+
+  // Check all combined permissions - at least one must pass if any exist
+  if (allPermissions.length > 0) {
+    let permissioned = false
+    for (const permission of allPermissions) {
       const result = await verifyPermissions(
-        typeof permissions === 'function' ? { permissions } : permissions,
+        typeof permission === 'function' ? { permission } : permission,
         allServices,
         data,
         session
       )
       if (result) {
         permissioned = true
-        break // At least one passed, we're good at this level
+        // Continue executing all permissions (don't break early)
       }
     }
     if (!permissioned) {
-      allServices.logger.debug('Permission denied - function tag permissions')
-      throw new ForbiddenError('Permission denied')
-    }
-  }
-
-  // 4. Function permissions - must pass if defined
-  if (funcPermissions) {
-    permissioned = await verifyPermissions(
-      funcPermissions,
-      allServices,
-      data,
-      session
-    )
-    if (!permissioned) {
-      allServices.logger.debug('Permission denied - function permissions')
+      allServices.logger.debug('Permission denied - combined permissions')
       throw new ForbiddenError('Permission denied')
     }
   }

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 { CLIMeta, CLIProgramState } from './wirings/cli/cli.types.js'
 
 interface PikkuState {
   function: {
@@ -69,6 +75,62 @@ interface PikkuState {
     prompts: Map<string, CoreMCPPrompt>
     promptsMeta: MCPPromptMeta
   }
+  cli: {
+    meta: CLIMeta | Record<string, any> // Backward compatible with old published CLI format
+    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
+      }
+    >
+  }
+  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>
@@ -89,7 +151,6 @@ export const resetPikkuState = () => {
     },
     http: {
       permissions: new Map(),
-      middleware: new Map(),
       routes: new Map(),
       meta: {},
     },
@@ -113,6 +174,22 @@ export const resetPikkuState = () => {
       prompts: new Map(),
       promptsMeta: {} as MCPPromptMeta,
     },
+    cli: {
+      meta: { programs: {}, renderers: {} },
+      programs: {},
+    },
+    middleware: {
+      tagGroup: {},
+      httpGroup: {},
+      tagGroupMeta: {},
+      httpGroupMeta: {},
+    },
+    permissions: {
+      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}`