@pikku/core 0.12.71 → 0.12.74

package/src/middleware/telemetry.ts

@@ -1,21 +1,6 @@
 import { pikkuMiddleware, pikkuMiddlewareFactory } from '../types/core.types.js'
 
-/**
- * Outer telemetry middleware that captures total request duration and outcome.
- * Runs at `highest` priority (outermost in the middleware chain).
- *
- * Emits a structured JSON log entry with `__pikku_telemetry: 'end'` containing:
- * - Total duration (including all middleware)
- * - Outcome (ok/error)
- * - Wire metadata (wireType, wireId, traceId)
- * - HTTP details (method, path, status) if applicable
- *
- * @example
- * ```typescript
- * import { telemetryOuter } from '@pikku/core/middleware'
- * addTagMiddleware('myTag', [telemetryOuter()])
- * ```
- */
+/** Outermost telemetry: total duration, including every middleware. */
 export const telemetryOuter = pikkuMiddlewareFactory<{
   environmentId?: string
   orgId?: string
@@ -58,21 +43,7 @@ export const telemetryOuter = pikkuMiddlewareFactory<{
   })
 })
 
-/**
- * Inner telemetry middleware that captures function execution duration and user context.
- * Runs at `lowest` priority (innermost, closest to the function).
- *
- * Emits a structured JSON log entry with `__pikku_telemetry: 'end'` containing:
- * - Function-only duration (excluding outer middleware like auth)
- * - User identity (pikkuUserId) if authenticated
- * - Wire metadata (wireType, wireId, traceId)
- *
- * @example
- * ```typescript
- * import { telemetryInner } from '@pikku/core/middleware'
- * addTagMiddleware('myTag', [telemetryInner()])
- * ```
- */
+/** Innermost telemetry: function-only duration, excluding outer middleware. */
 export const telemetryInner = pikkuMiddlewareFactory<{
   environmentId?: string
   orgId?: string

package/src/middleware-runner.test.ts

@@ -114,7 +114,6 @@ describe('combineMiddleware', () => {
   })
 
   test('should execute middleware in correct order: wireInheritedMiddleware (tags) → wireMiddleware → funcInheritedMiddleware (tags) → funcMiddleware', () => {
-    // Setup tagged middleware
     const wiringTagMiddleware: CorePikkuMiddleware = async (
       services,
       wire,
@@ -441,7 +440,6 @@ describe('runMiddleware', () => {
       }
     )
 
-    // Should only execute each middleware once
     assert.deepEqual(executionOrder, ['middleware1', 'middleware2', 'main'])
   })
 

package/src/middleware-runner.ts

@@ -31,23 +31,6 @@ const sortByPriority = (
   )
 }
 
-/**
- * Runs a chain of middleware functions in sequence before executing the main function.
- *
- * @param services - An object containing services (e.g., singletonServices, userSession, etc.)
- * @param wire - The wire context, e.g., { http }.
- * @param middlewares - An array of middleware functions to run.
- * @param main - The main function to execute after all middleware have run.
- * @returns A promise resolving to the result of the main function.
- *
- * @example
- * runMiddleware(
- *   { ...services, userSession },
- *   { http },
- *   [middleware1, middleware2, middleware3],
- *   async () => { return await runMain(); }
- * );
- */
 export const runMiddleware = async <
   Middleware extends CorePikkuMiddleware<any, any>,
 >(
@@ -56,7 +39,6 @@ export const runMiddleware = async <
   middlewares: readonly Middleware[],
   main?: () => Promise<unknown>
 ): Promise<unknown> => {
-  // Sort by priority if not already sorted (cached middleware is pre-sorted)
   const sorted = isSortedByPriority(middlewares)
     ? middlewares
     : ([...middlewares].sort(
@@ -91,14 +73,8 @@ const isSortedByPriority = (
 }
 
 /**
- * Registers tag-scoped middleware. Applies to any wiring (HTTP, Channel,
- * Queue, Scheduler, MCP, CLI, Workflow, Agent) that carries the matching tag.
- *
- * For tree-shaking, wrap in a factory:
- * `export const x = () => addTagMiddleware('tag', [...])`
- *
- * @example
- * export const adminMiddleware = () => addTagMiddleware('admin', [authMiddleware])
+ * Registers tag-scoped middleware for any wiring carrying the tag. Wrap in a
+ * factory (`export const x = () => addTagMiddleware(...)`) for tree-shaking.
  */
 export const addTagMiddleware = <PikkuMiddleware extends CorePikkuMiddleware>(
   tag: string,
@@ -114,14 +90,8 @@ export const addTagMiddleware = <PikkuMiddleware extends CorePikkuMiddleware>(
 }
 
 /**
- * Registers wire-agnostic global middleware. Runs at the top of every
- * wiring's middleware chain — before wire-, tag-, and function-level
- * entries — across HTTP, Channel, Queue, Scheduler, MCP, CLI, Workflow, Agent.
- *
- * Resolution order: global → wire → tag → function.
- *
- * @example
- * addGlobalMiddleware([telemetryMiddleware])
+ * Registers wire-agnostic global middleware, which runs at the top of every
+ * wiring's chain — before wire-, tag- and function-level entries.
  */
 export const addGlobalMiddleware = <
   PikkuMiddleware extends CorePikkuMiddleware,
@@ -140,17 +110,6 @@ export const addGlobalMiddleware = <
   return middleware
 }
 
-/**
- * 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 (pikkuFuncId) of the middleware function.
- * @returns {CorePikkuMiddleware | undefined} The middleware function, or undefined if not found.
- *
- * @internal
- */
 const getMiddlewareByName = (name: string): CorePikkuMiddleware | undefined => {
   const middlewareStore = pikkuState(null, 'misc', 'middleware')
   const middleware = middlewareStore[name]
@@ -180,28 +139,6 @@ export const clearMiddlewareCache = () => {
   }
 }
 
-/**
- * Combines wiring-specific middleware with function-level middleware.
- *
- * 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 {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(wireType, wireId, {
- *   inheritedMiddleware: meta.middleware,
- *   wireMiddleware: [inlineMiddleware],
- *   funcMiddleware: funcMeta.middleware
- * })
- * ```
- */
 export const combineMiddleware = (
   wireType: PikkuWiringTypes,
   uid: string,
@@ -237,7 +174,6 @@ export const combineMiddleware = (
   if (wireInheritedMiddleware) {
     for (const meta of wireInheritedMiddleware) {
       if (meta.type === 'http') {
-        // Look up HTTP middleware group from pikkuState
         const group = pikkuState(packageName, 'middleware', 'httpGroup')[
           meta.route
         ]
@@ -254,7 +190,6 @@ export const combineMiddleware = (
           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)
@@ -263,12 +198,11 @@ export const combineMiddleware = (
     }
   }
 
-  // 2. Add inline wire middleware
   if (wireMiddleware) {
     resolved.push(...wireMiddleware)
   }
 
-  // 3. Resolve function inherited middleware (only tags, wire middleware already handled)
+  // Only tags here; wire middleware is resolved via wireInheritedMiddleware.
   if (funcInheritedMiddleware) {
     for (const meta of funcInheritedMiddleware) {
       if (meta.type === 'tag') {
@@ -280,16 +214,13 @@ export const combineMiddleware = (
           resolved.push(...(group as CorePikkuMiddleware[]))
         }
       }
-      // Note: wire middleware is already handled in wireInheritedMiddleware
     }
   }
 
-  // 4. Add inline function middleware
   if (funcMiddleware) {
     resolved.push(...funcMiddleware)
   }
 
-  // Sort by priority, deduplicate, and freeze
   sortByPriority(resolved)
   middlewareCache[wireType][uid] = freezeDedupe(
     resolved

package/src/permissions.test.ts

@@ -164,6 +164,36 @@ describe('runPermissions — package isolation', () => {
       message: 'Permission denied',
     })
   })
+
+  test('a root global applies inside a package too', async () => {
+    // The generated `addGlobalPermission` wrapper takes no package argument, so
+    // an application's rules always land in the root bucket. If those stopped
+    // at the addon boundary, "every request needs a signed-in user" would
+    // silently exempt every function an addon contributed.
+    addGlobalPermission([async () => false])
+    await assert.rejects(run({ packageName: 'pkg-a' }), {
+      message: 'Permission denied',
+    })
+  })
+
+  test('root and package globals both have to pass', async () => {
+    addGlobalPermission([async () => true])
+    addGlobalPermission([async () => false], 'pkg-a')
+    await assert.rejects(run({ packageName: 'pkg-a' }), {
+      message: 'Permission denied',
+    })
+  })
+
+  test('passes when the root and package globals both pass', async () => {
+    addGlobalPermission([async () => true])
+    addGlobalPermission([async () => true], 'pkg-a')
+    await run({ packageName: 'pkg-a' })
+  })
+
+  test('a package global does not leak back out to the root', async () => {
+    addGlobalPermission([async () => false], 'pkg-a')
+    await run({})
+  })
 })
 
 describe('checkAuthPermissions', () => {

package/src/permissions.ts

@@ -10,23 +10,6 @@ import type {
 import { pikkuState } from './pikku-state.js'
 import { ForbiddenError } from './errors/errors.js'
 
-/**
- * Evaluates a single permission group. A group ORs its branches together and
- * ANDs the entries within a branch: the group passes if at least one branch
- * (an array of permission functions, all of which must return true — or a lone
- * function) is satisfied.
- *
- * This is the only place OR lives in authorization. Everything cross-cutting —
- * global permissions, scopes, and auth — ANDs together; a function's own
- * `permissions` group is the sole place where "owner OR admin"-style
- * alternatives are expressed.
- *
- * @param permissions - The permission group to evaluate.
- * @param services - The core services required for permission validation.
- * @param data - The request data passed to each permission function.
- * @param wire - The wire object containing request/response context and session.
- * @returns A promise resolving to true if the group is satisfied.
- */
 const verifyPermissions = async (
   permissions: CorePermissionGroup,
   services: CoreServices,
@@ -71,20 +54,6 @@ export const clearPermissionsCache = () => {
   }
 }
 
-/**
- * Registers wire-agnostic global permissions. Global permissions are an AND
- * gate: every registered requirement must pass on every function invocation,
- * regardless of transport. A requirement may be a single permission function
- * or a permission group (in which case that group ORs internally, but the
- * group as a whole must still pass).
- *
- * Global permissions never satisfy a function's own `permissions` — the two
- * are independent gates that both have to pass, so a broad global can only
- * ever narrow access.
- *
- * @example
- * addGlobalPermission([signedInUser])
- */
 export const addGlobalPermission = (
   permissions: CorePermissionGroup | CorePikkuPermission[],
   packageName: string | null = null
@@ -120,11 +89,27 @@ export const addTagPermission = (
   )
 }
 
+const bucket = (
+  packageName: string | null
+): (CorePermissionGroup | CorePikkuPermission)[] =>
+  (pikkuState(packageName, 'permissions', 'global') as unknown as (
+    | CorePermissionGroup
+    | CorePikkuPermission
+  )[]) ?? []
+
 /**
- * Resolves the registered global permission requirements for a package,
- * caching the resolved array per package. The cache is keyed by package name
- * (an empty string for the root package) so packages never collide, and it is
- * cleared whenever globals are registered or on hot reload.
+ * Global permissions in effect for a function, root ones first.
+ *
+ * A function that belongs to a package reads *both* buckets, not just its own.
+ * The generated `addGlobalPermission` wrapper always registers under the root
+ * (`null`) package — it takes no package argument — so resolving the package
+ * bucket alone meant an application's "every request needs a signed-in user"
+ * rule silently stopped at the addon boundary, and the bucket the addon's
+ * functions did read was one no host could write to. Both directions of that
+ * are wrong, and the safe union is to apply everything: globals are an AND
+ * gate, so adding the root ones can only ever tighten.
+ *
+ * knowledge: decisions/security/global-permissions-and-function-permissions-are-independent-gates.md
  */
 const resolveGlobalPermissions = (
   packageName: string | null
@@ -134,12 +119,9 @@ const resolveGlobalPermissions = (
   if (cached) {
     return cached
   }
-  const globals = pikkuState(
-    packageName,
-    'permissions',
-    'global'
-  ) as unknown as (CorePermissionGroup | CorePikkuPermission)[]
-  const resolved = globals && globals.length > 0 ? [...globals] : []
+  const resolved = packageName
+    ? [...bucket(null), ...bucket(packageName)]
+    : [...bucket(null)]
   globalPermissionsCache[key] = resolved
   return resolved
 }
@@ -149,17 +131,6 @@ const asGroup = (
 ): CorePermissionGroup =>
   typeof entry === 'function' ? { permission: entry } : entry
 
-/**
- * Runs authorization for a function invocation. Two independent gates, both of
- * which must pass:
- *
- * 1. Global permissions — AND. Every registered global requirement must pass.
- * 2. Function permissions — OR. The function's own `permissions` group must be
- *    satisfied (see {@link verifyPermissions}).
- *
- * A passing global requirement never contributes to the function gate, so a
- * broad global like `signedIn` can't satisfy an admin-only function.
- */
 export const runPermissions = async ({
   funcPermissions,
   services,
@@ -197,25 +168,8 @@ export const runPermissions = async ({
   }
 }
 
-/**
- * Checks whether a session passes the auth checks (pikkuAuth only) for a
- * given function/agent. Skips pikkuPermission checks since those require
- * request data which isn't available at filter time. Global auth requirements
- * are included so a filtered list honours app-wide auth.
- *
- * `funcPermissions` is the live {@link CorePermissionGroup} from the function or
- * agent config, not the metadata form: the `pikkuAuth` brand only survives on
- * the actual predicate objects, and the by-name registry those metadata entries
- * would resolve against is never populated. Passing metadata here would silently
- * collect nothing and let every gated tool through.
- *
- * @param funcPermissions - The live permission group from the func/agent config
- * @param session - The user's session
- * @param services - Singleton services
- * @param packageName - Optional package namespace
- * @returns true if the session passes the auth checks (or no auth checks exist)
- */
 export const checkAuthPermissions = async (
+  /** Must be the live permission group from the func/agent config, never metadata. */
   funcPermissions: CorePermissionGroup | undefined,
   session: CoreUserSession,
   services: CoreServices,
@@ -230,9 +184,6 @@ export const checkAuthPermissions = async (
     never
   >
 
-  // Collect auth-only (pikkuAuth) predicates from globals and the function's
-  // referenced permissions. Data-dependent permissions are ignored — they
-  // can't be evaluated without request data at filter time.
   const authPerms: CorePikkuPermission<any, any, any>[] = []
 
   const collect = (perm: CorePermissionGroup | CorePikkuPermission) => {
@@ -260,7 +211,6 @@ export const checkAuthPermissions = async (
     collect(funcPermissions)
   }
 
-  // No auth permissions = allowed (only data-dependent permissions exist)
   if (authPerms.length === 0) return true
 
   for (const perm of authPerms) {

package/src/pikku-request.ts

@@ -1,6 +1,4 @@
 /**
- * Simplest class to represent a pikku request.
- * @template In - The type of the request body.
  * @group RequestResponse
  */
 export abstract class PikkuRequest<In = any> {
@@ -10,10 +8,6 @@ export abstract class PikkuRequest<In = any> {
     this.#data = data
   }
 
-  /**
-   * Retrieves the data
-   * @returns A promise that resolves to an object containing the combined data.
-   */
   public async data(): Promise<In> {
     if (this.#data === undefined) {
       throw new Error('Data not found')

package/src/pikku-state.ts

@@ -14,7 +14,7 @@ import type { GatewaysMeta } from './wirings/gateway/gateway.types.js'
 import type { ScheduledTasksMeta } from './wirings/scheduler/scheduler.types.js'
 import type { TriggerMeta } from './wirings/trigger/trigger.types.js'
 
-const PIKKU_STATE_KEY = Symbol('@pikku/core/state')
+const PIKKU_STATE_KEY = Symbol.for('@pikku/core/state')
 
 export const getAllPackageStates = (): Map<string, PikkuPackageState> => {
   if (!(globalThis as any)[PIKKU_STATE_KEY]) {
@@ -23,22 +23,6 @@ export const getAllPackageStates = (): Map<string, PikkuPackageState> => {
   return (globalThis as any)[PIKKU_STATE_KEY] as Map<string, PikkuPackageState>
 }
 
-/**
- * Get or set package-scoped pikku state
- *
- * @param packageName - Package name (null for main package, '@scope/package' for addon packages)
- * @param type - State category (function, rpc, http, etc.)
- * @param content - Content key within the category
- * @param value - Optional value to set
- * @returns The current value of the state
- *
- * @example
- * // Main package
- * pikkuState(null, 'function', 'functions').get(funcName)
- *
- * // Addon package
- * pikkuState('@acme/stripe-functions', 'rpc', 'meta')
- */
 export const pikkuState = <
   Type extends keyof PikkuPackageState,
   Content extends keyof PikkuPackageState[Type],
@@ -50,7 +34,6 @@ export const pikkuState = <
 ): PikkuPackageState[Type][Content] => {
   const resolvedPackageName = packageName ?? '__main__'
 
-  // Initialize package state if it doesn't exist
   if (!getAllPackageStates().has(resolvedPackageName)) {
     initializePikkuState(resolvedPackageName)
   }
@@ -160,9 +143,6 @@ const createEmptyPackageState = (): PikkuPackageState => ({
   },
 })
 
-/**
- * Initialize state for a new package
- */
 export const initializePikkuState = (packageName: string): void => {
   if (!getAllPackageStates().has(packageName)) {
     getAllPackageStates().set(packageName, createEmptyPackageState())
@@ -170,13 +150,12 @@ export const initializePikkuState = (packageName: string): void => {
 }
 
 export const resetPikkuState = () => {
-  // Preserve the errors map before resetting
+  // Error definitions come from module-import side effects that never re-run.
   const existingErrors = getAllPackageStates().get('__main__')?.misc.errors
 
   ;(globalThis as any)[PIKKU_STATE_KEY] = new Map<string, PikkuPackageState>()
   initializePikkuState('__main__')
 
-  // Restore the errors map if it existed
   if (existingErrors) {
     const mainState = getAllPackageStates().get('__main__')!
     mainState.misc.errors = existingErrors
@@ -201,13 +180,6 @@ export const getCreateWireServices = (): CreateWireServices | undefined => {
   return pikkuState(null, 'package', 'factories')?.createWireServices
 }
 
-/**
- * Register service factories for an addon package.
- * These factories are used to create services when the package's functions are invoked.
- *
- * @param packageName - The package name (e.g., '@pikku/templates-function-addon')
- * @param factories - The service factory functions
- */
 export const addPackageServiceFactories = (
   packageName: string,
   factories: NonNullable<PikkuPackageState['package']['factories']>

package/src/production-barrels-stay-lean.test.ts

@@ -0,0 +1,110 @@
+import { describe, test } from 'node:test'
+import assert from 'node:assert/strict'
+import { existsSync, readFileSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import { join, dirname, resolve, relative } from 'node:path'
+
+const srcRoot = dirname(fileURLToPath(import.meta.url))
+
+/**
+ * Statements that only move types. TypeScript erases them, so they cost a
+ * production bundle nothing and are deliberately not followed.
+ */
+const TYPE_ONLY = /^\s*(?:import|export)\s+type\b/
+
+/**
+ * The modules a production server must never load by importing a barrel.
+ *
+ * Each is scenario or virtual-user runtime: `http-personas` signs personas in
+ * and reaches the actor-flow conversation runner, which reaches the agent
+ * runner. None of it runs in production, and an unbundled Node or Lambda deploy
+ * does no tree-shaking — it loads whatever the graph names.
+ */
+const FORBIDDEN = [
+  'services/http-personas.ts',
+  'wirings/actor-flow/run-conversation.ts',
+  'wirings/workflow/pikku-scenario-service.ts',
+]
+
+const resolveSpecifier = (fromFile: string, specifier: string) => {
+  const base = resolve(dirname(fromFile), specifier.replace(/\.js$/, ''))
+  for (const candidate of [`${base}.ts`, join(base, 'index.ts')]) {
+    if (existsSync(candidate)) return candidate
+  }
+  return undefined
+}
+
+/**
+ * Every module loaded as a side effect of importing `entry`, following value
+ * imports only.
+ *
+ * A dynamic `await import(...)` is not followed: it does not run at module
+ * init, which is the whole reason `pikku-scenario-service` reaches
+ * `http-personas` that way.
+ */
+const runtimeGraph = (entry: string): Set<string> => {
+  const seen = new Set<string>()
+  const queue = [entry]
+
+  while (queue.length) {
+    const file = queue.pop()!
+    if (seen.has(file)) continue
+    seen.add(file)
+
+    for (const line of readFileSync(file, 'utf-8').split('\n')) {
+      if (TYPE_ONLY.test(line)) continue
+      const specifier = line.match(/\bfrom\s+'(\.[^']+)'/)?.[1]
+      if (!specifier) continue
+      const target = resolveSpecifier(file, specifier)
+      if (target) queue.push(target)
+    }
+  }
+
+  return seen
+}
+
+describe('production barrels stay lean', () => {
+  for (const barrel of ['services/index.ts', 'wirings/workflow/index.ts']) {
+    test(`@pikku/core ${barrel} does not load scenario runtime`, () => {
+      const reached = runtimeGraph(join(srcRoot, barrel))
+      const offenders = FORBIDDEN.filter((module) =>
+        reached.has(join(srcRoot, module))
+      )
+
+      assert.deepEqual(
+        offenders,
+        [],
+        `${barrel} pulls scenario runtime into every app that imports it:\n` +
+          `${offenders.join('\n')}\n` +
+          `Export the value from '@pikku/core/persona' instead — types may stay here.`
+      )
+    })
+  }
+
+  test('the persona entry point still exports the runtime that moved', async () => {
+    const persona = await import('./wirings/persona/index.js')
+
+    for (const name of [
+      'createHttpPersonas',
+      'HttpPersona',
+      'postScenarioJson',
+      'readScenarioHttpResponse',
+    ]) {
+      assert.ok(
+        name in persona,
+        `@pikku/core/persona no longer exports ${name}; it has to live somewhere`
+      )
+    }
+  })
+
+  test('the graph walker actually reaches things', () => {
+    // Guards the test above: a walker that silently resolved nothing would pass
+    // no matter what the barrels imported.
+    const reached = runtimeGraph(join(srcRoot, 'wirings/persona/index.ts'))
+    assert.ok(
+      reached.has(join(srcRoot, 'services/http-personas.ts')),
+      `walker failed to reach a known value import; reached ${reached.size} files:\n` +
+        [...reached].map((f) => relative(srcRoot, f)).join('\n')
+    )
+  })
+})