@pikku/core 0.12.15 → 0.12.16

package/src/middleware-runner.ts

@@ -5,10 +5,34 @@ import type {
   CorePikkuMiddlewareGroup,
   PikkuWiringTypes,
   MiddlewareMetadata,
+  MiddlewarePriority,
 } from './types/core.types.js'
 import { pikkuState } from './pikku-state.js'
 import { freezeDedupe, getTagGroups } from './utils.js'
 
+const PRIORITY_ORDER: Record<MiddlewarePriority, number> = {
+  highest: 0,
+  high: 1,
+  medium: 2,
+  low: 3,
+  lowest: 4,
+}
+
+const getMiddlewarePriority = (fn: CorePikkuMiddleware): number => {
+  const priority = (
+    fn as CorePikkuMiddleware & { __priority?: MiddlewarePriority }
+  ).__priority
+  return PRIORITY_ORDER[priority ?? 'medium']
+}
+
+const sortByPriority = (
+  middlewares: CorePikkuMiddleware[]
+): CorePikkuMiddleware[] => {
+  return middlewares.sort(
+    (a, b) => getMiddlewarePriority(a) - getMiddlewarePriority(b)
+  )
+}
+
 /**
  * Runs a chain of middleware functions in sequence before executing the main function.
  *
@@ -32,11 +56,16 @@ export const runMiddleware = async <Middleware extends CorePikkuMiddleware>(
   middlewares: readonly Middleware[],
   main?: () => Promise<unknown>
 ): Promise<unknown> => {
-  // Deduplicate middleware using Set to avoid running the same middleware multiple times
+  // Sort by priority if not already sorted (cached middleware is pre-sorted)
+  const sorted = isSortedByPriority(middlewares)
+    ? middlewares
+    : ([...middlewares].sort(
+        (a, b) => getMiddlewarePriority(a) - getMiddlewarePriority(b)
+      ) as readonly Middleware[])
   let result: any
   const dispatch = async (index: number): Promise<any> => {
-    if (middlewares && index < middlewares.length) {
-      return await middlewares[index]!(services as any, wire, () =>
+    if (sorted && index < sorted.length) {
+      return await sorted[index]!(services as any, wire, () =>
         dispatch(index + 1)
       )
     } else if (main) {
@@ -47,6 +76,20 @@ export const runMiddleware = async <Middleware extends CorePikkuMiddleware>(
   return result
 }
 
+const isSortedByPriority = (
+  middlewares: readonly CorePikkuMiddleware[]
+): boolean => {
+  for (let i = 1; i < middlewares.length; i++) {
+    if (
+      getMiddlewarePriority(middlewares[i]) <
+      getMiddlewarePriority(middlewares[i - 1])
+    ) {
+      return false
+    }
+  }
+  return true
+}
+
 /**
  * Registers global middleware for a specific tag.
  *
@@ -231,7 +274,8 @@ export const combineMiddleware = (
     resolved.push(...funcMiddleware)
   }
 
-  // Deduplicate and freeze
+  // Sort by priority, deduplicate, and freeze
+  sortByPriority(resolved)
   middlewareCache[wireType][uid] = freezeDedupe(
     resolved
   ) as readonly CorePikkuMiddleware[]

package/src/types/core.types.ts

@@ -305,6 +305,23 @@ export type CorePikkuMiddleware<
   next: () => Promise<void>
 ) => Promise<void>
 
+/**
+ * Priority levels for middleware execution order.
+ * Lower priority runs first (outermost in the onion model).
+ *
+ * - `highest` — Runs first (outermost). Use for telemetry, request tracing.
+ * - `high` — Runs early. Use for CORS, rate limiting.
+ * - `medium` — Default. Use for auth, most user middleware.
+ * - `low` — Runs late. Use for post-auth processing.
+ * - `lowest` — Runs last (innermost, closest to function). Use for inner telemetry.
+ */
+export type MiddlewarePriority =
+  | 'highest'
+  | 'high'
+  | 'medium'
+  | 'low'
+  | 'lowest'
+
 /**
  * Configuration object for creating middleware with metadata
  *
@@ -321,6 +338,8 @@ export type CorePikkuMiddlewareConfig<
   name?: string
   /** Optional description of what the middleware does */
   description?: string
+  /** Execution priority. Lower runs first (outermost). Defaults to 'medium'. */
+  priority?: MiddlewarePriority
 }
 
 /**
@@ -378,7 +397,15 @@ export const pikkuMiddleware = <
     | CorePikkuMiddleware<SingletonServices, UserSession>
     | CorePikkuMiddlewareConfig<SingletonServices, UserSession>
 ): CorePikkuMiddleware<SingletonServices, UserSession> => {
-  return typeof middleware === 'function' ? middleware : middleware.func
+  if (typeof middleware === 'function') return middleware
+  const func = middleware.func as CorePikkuMiddleware<
+    SingletonServices,
+    UserSession
+  > & { __priority?: MiddlewarePriority }
+  if (middleware.priority) {
+    func.__priority = middleware.priority
+  }
+  return func
 }
 
 /**

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

@@ -70,7 +70,11 @@ export class PikkuMockRequest implements PikkuHTTPRequest {
 }
 
 export class PikkuMockResponse implements PikkuHTTPResponse {
-  public _status: number | undefined
+  public _status: number = 200
+
+  public get statusCode(): number {
+    return this._status
+  }
 
   status(code: number): this {
     this._status = code

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

@@ -500,8 +500,9 @@ export async function executeCLI({
       ? await createConfig(new LocalVariablesService(), data)
       : ({} as any)
 
-    // Create services with config
+    // Create services with config and register in global state
     const singletonServices = await createSingletonServices(config)
+    pikkuState(null, 'package', 'singletonServices', singletonServices)
 
     // Execute the command
     await runCLICommand({

package/src/wirings/http/http.types.ts

@@ -271,6 +271,7 @@ export interface PikkuHTTPRequest<In = unknown> {
 }
 
 export interface PikkuHTTPResponse<Out = unknown> {
+  readonly statusCode: number
   status(code: number): this
   cookie(name: string, value: string | null, options: SerializeOptions): this
   header(name: string, value: string | string[]): this

package/src/wirings/http/pikku-fetch-http-response.ts

@@ -19,6 +19,10 @@ export class PikkuFetchHTTPResponse implements PikkuHTTPResponse {
     }
   }
 
+  public get statusCode(): number {
+    return this.#statusCode
+  }
+
   public status(code: number): this {
     this.#statusCode = code
     return this

package/src/wirings/mcp/mcp.types.ts

@@ -127,7 +127,7 @@ export type CoreMCPTool<
 > = {
   name: string
   title?: string
-  description: string
+  description?: string
   summary?: string
   errors?: string[]
   func: PikkuFunctionConfig