@pikku/core 0.12.72 → 0.12.74

package/dist/function/function-runner.js

@@ -1,6 +1,8 @@
+import { beginChanges } from './abort-scope.js';
 import { runMiddleware, combineMiddleware } from '../middleware-runner.js';
 import { combineChannelMiddleware, wrapChannelWithMiddleware, } from '../wirings/channel/channel-middleware-runner.js';
 import { runPermissions } from '../permissions.js';
+import { withoutSecrets } from '../services/secretless.js';
 import { pikkuState } from '../pikku-state.js';
 import { applyDefaultsFromSchema, coerceTopLevelDataFromSchema, validateSchema, } from '../schema.js';
 import { parseVersionedId } from '../version.js';
@@ -12,6 +14,7 @@ import { defaultPikkuUserIdResolver } from '../services/pikku-user-id.js';
 import { createInvocationAudit, resolveAuditConfig, } from '../services/audit-service.js';
 import { rpcService } from '../wirings/rpc/rpc-runner.js';
 import { getOrCreatePackageSingletonServices } from '../wirings/rpc/addon-runner.js';
+import { resolveAddonAuth, resolveAddonScopes, resolveAddonTagMiddleware, } from '../wirings/rpc/wire-addon.js';
 import { closeWireServices } from '../utils.js';
 async function resolveSession(wire, singletonServices, sessionService) {
     const pikkuUserId = defaultPikkuUserIdResolver(wire);
@@ -81,11 +84,10 @@ export const runPikkuFunc = async (wireType, wireId, funcName, { singletonServic
         throw new Error(`Function meta not found: ${funcName}`);
     }
     const resolvedFunctionId = funcMeta.pikkuFuncId ?? funcName;
-    // For addon packages, get or create their singleton services
+    const keepsSecrets = funcMeta.secretBroker === true;
     const resolvedSingletonServices = packageName
         ? await getOrCreatePackageSingletonServices(packageName, singletonServices, addonInstance)
         : singletonServices;
-    // Get the package's createWireServices if available
     let resolvedCreateWireServices = createWireServices;
     if (packageName) {
         const factories = pikkuState(packageName, 'package', 'factories');
@@ -101,11 +103,9 @@ export const runPikkuFunc = async (wireType, wireId, funcName, { singletonServic
     const resolvedWire = allChannelMiddleware.length > 0 && wire.channel
         ? wrapChannelWithMiddleware(wire, resolvedSingletonServices, allChannelMiddleware)
         : wire;
-    // Set up credential wire service early so middleware can use setCredential.
-    // An addon instance with credentialOverrides always gets a fresh alias-aware
-    // service so its logical credential names resolve to instance-specific ones,
-    // even when a parent credential service is already present on the wire.
-    // Otherwise skip if already set up (e.g. addon functions reuse the parent wire).
+    // Set up early so middleware can use setCredential. An addon instance with
+    // credentialOverrides always gets a fresh alias-aware service, even when a
+    // parent credential service is already present on the wire.
     if (addonInstance?.credentialOverrides) {
         // Credentials belong to the consuming project, so resolve them via the
         // project's credentialService (the addon's own singletons may not carry it).
@@ -131,7 +131,6 @@ export const runPikkuFunc = async (wireType, wireId, funcName, { singletonServic
     if (addonInstance) {
         invocationWire.addonNamespace = addonInstance.namespace;
     }
-    // Helper function to run permissions and execute the function
     const executeFunction = async () => {
         await resolveSession(invocationWire, resolvedSingletonServices, sessionService);
         if (sessionService) {
@@ -143,7 +142,9 @@ export const runPikkuFunc = async (wireType, wireId, funcName, { singletonServic
         }
         const session = invocationWire.session;
         if (funcMeta.sessionless) {
-            if (wiringAuth === true || funcConfig.auth === true) {
+            if (wiringAuth === true ||
+                funcConfig.auth === true ||
+                resolveAddonAuth(packageName, addonInstance?.namespace)) {
                 if (!session) {
                     throw new ForbiddenError('Authentication required');
                 }
@@ -160,31 +161,32 @@ export const runPikkuFunc = async (wireType, wireId, funcName, { singletonServic
         if (session?.readonly && !funcMeta.readonly) {
             throw new ReadonlySessionError();
         }
-        // Scopes gate before the data is evaluated: they depend only on the
-        // session, so a denied request never pays to parse or validate its body.
-        // Scopes are an AND gate and stay separate from runPermissions, which
-        // evaluates the function's own OR-groups against request data.
-        verifyScopes(funcConfig.scopes ?? funcMeta.scopes, session);
-        // Evaluate the data from the lazy function
+        // Only mutating functions get a checkpoint. A read has nothing to declare,
+        // and offering it there would invite the contradiction of a `readonly`
+        // function announcing where its changes begin.
+        if (!funcMeta.readonly) {
+            invocationWire.beginChanges = beginChanges;
+        }
+        // knowledge: decisions/security/addon-scopes-are-resolved-where-the-function-runs.md
+        const addonScopes = resolveAddonScopes(packageName, addonInstance?.namespace);
+        const functionScopes = funcConfig.scopes ?? funcMeta.scopes;
+        verifyScopes(addonScopes.length > 0
+            ? [...addonScopes, ...(functionScopes ?? [])]
+            : functionScopes, session);
         let actualData = await data();
-        // Validate and coerce data if schema is defined
         const inputSchemaName = funcMeta.inputSchemaName;
         if (inputSchemaName) {
-            // Fill in schema defaults before anything reads the data. Unconditional:
-            // a default belongs to the schema, not to the transport the call arrived
-            // on. Runs before coercion so a defaulted value and a supplied one are
-            // treated identically from here on.
             actualData = applyDefaultsFromSchema(inputSchemaName, actualData, packageName);
-            // Coerce (top level) data types before validation (e.g. string→array, string→date)
             if (coerceDataFromSchema) {
                 coerceTopLevelDataFromSchema(inputSchemaName, actualData, packageName);
             }
-            // Validate request data against the defined schema, if any
             await validateSchema(resolvedSingletonServices.logger, resolvedSingletonServices.schema, inputSchemaName, actualData, packageName);
         }
         await runPermissions({
             funcPermissions: funcConfig.permissions,
-            services: resolvedSingletonServices,
+            services: keepsSecrets
+                ? resolvedSingletonServices
+                : withoutSecrets(resolvedSingletonServices, 'a permission'),
             wire: invocationWire,
             data: actualData,
             packageName,
@@ -196,13 +198,7 @@ export const runPikkuFunc = async (wireType, wireId, funcName, { singletonServic
             let services = wireServices && Object.keys(wireServices).length > 0
                 ? { ...resolvedSingletonServices, ...wireServices }
                 : resolvedSingletonServices;
-            // The audit gate is per-function, but the auditLog wire service is
-            // created per-transport-invocation — a nested/exposed-RPC call would
-            // otherwise inherit an auditLog constructed while the OUTER wire's
-            // audit was unset (e.g. the generated rpcCaller has no audit config),
-            // silently dropping every write. Re-gate here: if this function
-            // declares audit and the inherited auditLog wasn't built for this
-            // invocation (config identity check), bind a fresh one to this wire.
+            // knowledge: decisions/internals/core-function-runner-restores-the-wire-fields-it-overwrites.md
             if (resolvedAuditConfig &&
                 resolvedSingletonServices.audit &&
                 services.auditLog?.config !== resolvedAuditConfig) {
@@ -223,7 +219,7 @@ export const runPikkuFunc = async (wireType, wireId, funcName, { singletonServic
                 configurable: true,
                 enumerable: true,
             });
-            return await funcConfig.func(services, actualData, invocationWire);
+            return await funcConfig.func(keepsSecrets ? services : withoutSecrets(services, 'a pikku function'), actualData, invocationWire);
         }
         finally {
             // Flush the runner-installed audit buffer before wire services close.
@@ -233,9 +229,12 @@ export const runPikkuFunc = async (wireType, wireId, funcName, { singletonServic
             }
         }
     };
+    const addonTagMiddleware = resolveAddonTagMiddleware(packageName, addonInstance?.namespace);
     const allMiddleware = combineMiddleware(wireType, wireId, {
         wireInheritedMiddleware: inheritedMiddleware,
-        wireMiddleware,
+        wireMiddleware: addonTagMiddleware.length > 0
+            ? [...addonTagMiddleware, ...(wireMiddleware ?? [])]
+            : wireMiddleware,
         funcInheritedMiddleware: funcMeta.middleware,
         funcMiddleware: funcConfig.middleware,
         packageName,
@@ -287,5 +286,11 @@ export const runPikkuFunc = async (wireType, wireId, funcName, { singletonServic
         else {
             invocationWire.audit = previousAudit;
         }
+        if (previousAddonNamespace === undefined) {
+            delete invocationWire.addonNamespace;
+        }
+        else {
+            invocationWire.addonNamespace = previousAddonNamespace;
+        }
     }
 };

package/dist/function/functions.types.d.ts

@@ -1,156 +1,64 @@
-import type { CoreServices, CoreSingletonServices, CoreUserSession, CorePikkuMiddleware, PikkuWire, PickRequired } from '../types/core.types.js';
+import type { CoreServices, CoreSecretlessSingletonServices, CoreUserSession, CorePikkuMiddleware, PikkuWire, PickRequired, SecretlessServices } from '../types/core.types.js';
 import type { PikkuRPC } from '../wirings/rpc/rpc-types.js';
 import type { StandardSchemaV1 } from '@standard-schema/spec';
 import type { PikkuError } from '../errors/error-handler.js';
 import type { CoreNodeConfig } from '../wirings/node/node.types.js';
+import type { ScenarioSurface } from '../wirings/workflow/scenario-step.types.js';
 /**
  * @deprecated Use StandardSchemaV1 from @standard-schema/spec instead.
  * This alias exists only for backward compatibility with generated code.
  */
 export type ZodLike<T = any> = StandardSchemaV1<T, T>;
-/**
- * Represents a core API function that performs an operation using core services and a user session.
- *
- * @template In - The input type.
- * @template Out - The output type.
- * @template Services - The services type, defaults to `CoreServices`.
- * @template Wire - The wire type, defaults to `PikkuWire<In, Out>`.
- */
-export type CorePikkuFunction<In, Out, Services extends CoreSingletonServices = CoreServices, Session extends CoreUserSession = CoreUserSession, Wire extends PikkuWire<In, Out, true, Session, PikkuRPC, null, string> = PikkuWire<In, Out, true, Session>> = (services: Services, data: In, wire: Wire) => Wire['channel'] extends null ? Promise<Out> : Promise<Out> | Promise<void>;
-/**
- * Represents a core API function that can be used without a session.
- *
- * @template In - The input type.
- * @template Out - The output type.
- * @template Services - The services type, defaults to `CoreServices`.
- * @template Wire - The wire type, defaults to `PikkuWire<In, Out>`.
- */
-export type CorePikkuFunctionSessionless<In, Out, Services extends CoreSingletonServices = CoreServices, Session extends CoreUserSession = CoreUserSession, Wire extends PikkuWire<In, Out, false, Session, PikkuRPC, null, string> = PikkuWire<In, Out, false, Session>> = (services: Services, data: In, wire: Wire) => Wire['channel'] extends null ? Promise<Out> : Promise<Out> | Promise<void>;
-/**
- * Represents a function that checks permissions for a given operation.
- *
- * @template In - The input type.
- * @template Services - The services type, defaults to `CoreServices`.
- * @template Session - The session type, defaults to `CoreUserSession`.
- */
-export type CorePikkuPermission<In = any, Services extends CoreSingletonServices = CoreServices, Wire extends PikkuWire<In, never, false, any, PikkuRPC, never, never> = PikkuWire<In, never, false, any, PikkuRPC, never, never>> = (services: Services, data: In, wire: Wire) => Promise<boolean>;
-/**
- * Configuration object for creating a permission with metadata
- *
- * @template In - The input type.
- * @template Services - The services type, defaults to `CoreServices`.
- * @template Session - The session type, defaults to `CoreUserSession`.
- */
-export type CorePikkuPermissionConfig<In = any, Services extends CoreSingletonServices = CoreServices, Wire extends PikkuWire<In, never, false, any, PikkuRPC, never, never> = PikkuWire<In, never, false, any, PikkuRPC, never, never>> = {
-    /** The permission function */
+export type CorePikkuFunction<In, Out, Services extends CoreSecretlessSingletonServices = SecretlessServices<CoreServices>, Session extends CoreUserSession = CoreUserSession, Wire extends PikkuWire<In, Out, true, Session, PikkuRPC, null, string> = PikkuWire<In, Out, true, Session>> = (services: Services, data: In, wire: Wire) => Wire['channel'] extends null ? Promise<Out> : Promise<Out> | Promise<void>;
+export type CorePikkuFunctionSessionless<In, Out, Services extends CoreSecretlessSingletonServices = SecretlessServices<CoreServices>, Session extends CoreUserSession = CoreUserSession, Wire extends PikkuWire<In, Out, false, Session, PikkuRPC, null, string> = PikkuWire<In, Out, false, Session>> = (services: Services, data: In, wire: Wire) => Wire['channel'] extends null ? Promise<Out> : Promise<Out> | Promise<void>;
+export type CorePikkuPermission<In = any, Services extends CoreSecretlessSingletonServices = SecretlessServices<CoreServices>, Wire extends PikkuWire<In, never, false, any, PikkuRPC, never, never> = PikkuWire<In, never, false, any, PikkuRPC, never, never>> = (services: Services, data: In, wire: Wire) => Promise<boolean>;
+export type CorePikkuPermissionConfig<In = any, Services extends CoreSecretlessSingletonServices = SecretlessServices<CoreServices>, Wire extends PikkuWire<In, never, false, any, PikkuRPC, never, never> = PikkuWire<In, never, false, any, PikkuRPC, never, never>> = {
     func: CorePikkuPermission<In, Services, Wire>;
-    /** Optional human-readable name for the permission */
     name?: string;
-    /** Optional description of what the permission checks */
     description?: string;
 };
-/**
- * Factory function for creating permissions with tree-shaking support
- * Supports both direct function and configuration object syntax
- *
- * @example
- * ```typescript
- * // Direct function syntax
- * export const adminPermission = pikkuPermission(
- *   async ({ logger }, _data, { getSession }) => {
- *     const currentSession = await getSession()
- *     return currentSession?.role === 'admin'
- *   }
- * )
- *
- * // Configuration object syntax with metadata
- * export const adminPermission = pikkuPermission({
- *   name: 'Admin Permission',
- *   description: 'Checks if user has admin role',
- *   func: async ({ logger }, _data, { getSession }) => {
- *     const currentSession = await getSession()
- *     return currentSession?.role === 'admin'
- *   }
- * })
- * ```
- */
-export declare const pikkuPermission: <In = any, Services extends CoreSingletonServices = CoreServices, Wire extends PickRequired<PikkuWire<In, never, false, any, PikkuRPC, never, never>, "session"> = PickRequired<PikkuWire<In, never, false, any, PikkuRPC, never, never>, "session">>(permission: CorePikkuPermission<In, Services, Wire> | CorePikkuPermissionConfig<In, Services, Wire>) => CorePikkuPermission<In, Services, Wire>;
-/**
- * A factory function that takes input and returns a permission
- * Used when permissions need configuration/input parameters
- *
- * @template In - The input type for the factory.
- * @template Services - The services type, defaults to `CoreServices`.
- * @template Session - The session type, defaults to `CoreUserSession`.
- */
-export type CorePikkuPermissionFactory<In = any, Services extends CoreSingletonServices = CoreServices, Wire extends PikkuWire<In, never, false, any, PikkuRPC, never, never> = PikkuWire<In, never, false, any, PikkuRPC, never, never>> = (input: In) => CorePikkuPermission<any, Services, Wire>;
-/**
- * Factory function for creating permission factories
- * Use this when your permission needs configuration/input parameters
- *
- * @example
- * ```typescript
- * export const requireRole = pikkuPermissionFactory<{ role: string }>(({
- *   role
- * }) => {
- *   return pikkuPermission(async ({ logger }, data, { getSession }) => {
- *      const currentSession = await getSession()
- *     if (!currentSession || currentSession.role !== role) {
- *       logger.warn(`Permission denied: required role '${role}'`)
- *       return false
- *     }
- *     return true
- *   })
- * })
- * ```
- */
+export declare const pikkuPermission: <In = any, Services extends CoreSecretlessSingletonServices = SecretlessServices<CoreServices>, Wire extends PickRequired<PikkuWire<In, never, false, any, PikkuRPC, never, never>, "session"> = PickRequired<PikkuWire<In, never, false, any, PikkuRPC, never, never>, "session">>(permission: CorePikkuPermission<In, Services, Wire> | CorePikkuPermissionConfig<In, Services, Wire>) => CorePikkuPermission<In, Services, Wire>;
+export type CorePikkuPermissionFactory<In = any, Services extends CoreSecretlessSingletonServices = SecretlessServices<CoreServices>, Wire extends PikkuWire<In, never, false, any, PikkuRPC, never, never> = PikkuWire<In, never, false, any, PikkuRPC, never, never>> = (input: In) => CorePikkuPermission<any, Services, Wire>;
 export declare const pikkuPermissionFactory: <In = any>(factory: CorePikkuPermissionFactory<In>) => CorePikkuPermissionFactory<In>;
 /**
- * A function that generates a human-readable description of a pending approval action.
- * Used by AI agents to show meaningful approval prompts instead of raw tool arguments.
- *
- * @template In - The input type (same as the function it describes).
- * @template Services - The services type, defaults to `CoreSingletonServices`.
+ * Renders a human-readable approval prompt for an AI agent, in place of the
+ * raw tool arguments.
  */
-export type CorePikkuApprovalDescription<In = any, Services extends CoreSingletonServices = CoreSingletonServices> = (services: Services, data: In) => Promise<string>;
-/**
- * Factory function for creating approval description functions with tree-shaking support.
- *
- * @example
- * ```typescript
- * export const deleteTodoApproval = pikkuApprovalDescription(
- *   async ({ todoStore }, { id }) => {
- *     const todo = await todoStore.get(id)
- *     return `Delete todo: "${todo.title}"`
- *   }
- * )
- * ```
- */
-export declare const pikkuApprovalDescription: <In = any, Services extends CoreSingletonServices = CoreSingletonServices>(fn: CorePikkuApprovalDescription<In, Services>) => CorePikkuApprovalDescription<In, Services>;
-export type CorePikkuAuth<Services extends CoreSingletonServices = CoreServices, Session extends CoreUserSession = CoreUserSession> = (services: Services, session: Session) => Promise<boolean> | boolean;
-export type CorePikkuAuthConfig<Services extends CoreSingletonServices = CoreServices, Session extends CoreUserSession = CoreUserSession> = {
+export type CorePikkuApprovalDescription<In = any, Services extends CoreSecretlessSingletonServices = CoreSecretlessSingletonServices> = (services: Services, data: In) => Promise<string>;
+export declare const pikkuApprovalDescription: <In = any, Services extends CoreSecretlessSingletonServices = CoreSecretlessSingletonServices>(fn: CorePikkuApprovalDescription<In, Services>) => CorePikkuApprovalDescription<In, Services>;
+export type CorePikkuAuth<Services extends CoreSecretlessSingletonServices = SecretlessServices<CoreServices>, Session extends CoreUserSession = CoreUserSession> = (services: Services, session: Session) => Promise<boolean> | boolean;
+export type CorePikkuAuthConfig<Services extends CoreSecretlessSingletonServices = SecretlessServices<CoreServices>, Session extends CoreUserSession = CoreUserSession> = {
     func: CorePikkuAuth<Services, Session>;
     name?: string;
     description?: string;
 };
-export declare const pikkuAuth: <Services extends CoreSingletonServices = CoreServices, Session extends CoreUserSession = CoreUserSession>(auth: CorePikkuAuth<Services, Session> | CorePikkuAuthConfig<Services, Session>) => CorePikkuPermission<any, Services, any>;
+export declare const pikkuAuth: <Services extends CoreSecretlessSingletonServices = SecretlessServices<CoreServices>, Session extends CoreUserSession = CoreUserSession>(auth: CorePikkuAuth<Services, Session> | CorePikkuAuthConfig<Services, Session>) => CorePikkuPermission<any, Services, any>;
 export type CorePermissionGroup<PikkuPermission = CorePikkuPermission<any>> = Record<string, PikkuPermission | PikkuPermission[]> | undefined;
 /**
- * A lifecycle hook: the same call signature as the function it hangs off, but
- * its return value is discarded. A hook is setup/teardown, not a step — it has
- * no id, no meta and no schema, so it is never recorded and never replayed.
+ * A lifecycle hook: same call signature as the function it hangs off, return
+ * value discarded. Setup/teardown, not a step — no id, no meta, no schema, so
+ * it is never recorded and never replayed.
  */
 export type CorePikkuFunctionHook<Services = any, Data = any, Wire = any> = (services: Services, data: Data, wire: Wire) => Promise<void> | void;
 export type CorePikkuFunctionConfig<PikkuFunction extends CorePikkuFunction<any, any, any, any, any> | CorePikkuFunctionSessionless<any, any, any, any, any>, PikkuPermission extends CorePikkuPermission<any, any, any> = CorePikkuPermission<any>, PikkuMiddleware extends CorePikkuMiddleware<any, any> = CorePikkuMiddleware<any, any>, InputSchema extends StandardSchemaV1 | undefined = undefined, OutputSchema extends StandardSchemaV1 | undefined = undefined, Scope extends string = string> = {
-    /** Short human-readable name (e.g. "Create Todo") */
     title?: string;
-    /** Longer-form description of what the function does */
     description?: string;
     /** Explicit logical name override; lets multiple exports share a versioned base */
     override?: string;
     version?: number;
     tags?: string[];
     expose?: boolean;
+    /**
+     * The function performs its own authorization in its body — verifying a
+     * signed token, checking a webhook signature, matching an invite code — so
+     * it is not open despite carrying no session, scope or permission.
+     *
+     * Purely declarative: nothing at runtime reads it, and it grants nothing. It
+     * exists so the claim is written down where an audit can find it, and so
+     * codegen stops warning about a gate it has no way to see. Asserting it
+     * falsely disables the one check that would have caught the mistake.
+     */
+    selfAuthenticated?: boolean;
     remote?: boolean;
     mcp?: boolean;
     readonly?: boolean;
@@ -162,8 +70,12 @@ export type CorePikkuFunctionConfig<PikkuFunction extends CorePikkuFunction<any,
     workflowRetries?: number;
     /** Timeout for this function when used as a workflow step (e.g. '30s', '5m'). */
     workflowTimeout?: string;
-    /** Scenario steps only: this step drives a browser, so the runner must provision one before calling it. */
-    browser?: boolean;
+    /**
+     * Scenario steps only: which surfaces this step declares a binding for. The
+     * runner uses it to pick a binding, decide whether to provision a browser,
+     * and report how much of the flow each surface actually covers.
+     */
+    surfaces?: ScenarioSurface[];
     audit?: boolean | {
         durability?: 'best-effort' | 'transactional';
     };
@@ -176,26 +88,22 @@ export type CorePikkuFunctionConfig<PikkuFunction extends CorePikkuFunction<any,
      */
     before?: CorePikkuFunctionHook;
     /**
-     * Scenarios only: always runs after the scenario body, in a `finally`.
-     * Throwing fails a run that would otherwise have passed; on an
-     * already-failed run it attaches as the `cause` and never replaces the
-     * original error.
+     * Scenarios only: always runs after the body, in a `finally`. Throwing fails
+     * an otherwise-passing run; on an already-failed run it attaches as `cause`
+     * and never replaces the original error.
      */
     after?: CorePikkuFunctionHook;
     /**
-     * Scenarios only: why this scenario is held out of a default run. It is
-     * reported as skipped rather than quietly omitted, and naming it directly
-     * with `--flows` runs it anyway.
+     * Scenarios only: why this scenario is held out of a default run. Reported
+     * as skipped rather than quietly omitted; naming it in `--flows` runs it.
      */
     skip?: string;
     auth?: boolean;
     /**
-     * Scopes the session must hold to run this function. All of them are
-     * required (AND), and they are checked before `permissions` — unlike
-     * permissions, which OR together, a scope can only narrow access.
-     *
-     * Narrowed to the generated `ScopeId` union in a project's own
-     * `pikku-types.gen.ts`, so an undeclared scope is a compile error.
+     * Scopes the session must hold; all are required (AND) and checked before
+     * `permissions`, which OR together — a scope can only narrow access.
+     * Narrowed to the generated `ScopeId` union, so an undeclared scope is a
+     * compile error.
      */
     scopes?: Scope[];
     permissions?: CorePermissionGroup<PikkuPermission>;

package/dist/function/functions.types.js

@@ -1,67 +1,9 @@
-/**
- * Factory function for creating permissions with tree-shaking support
- * Supports both direct function and configuration object syntax
- *
- * @example
- * ```typescript
- * // Direct function syntax
- * export const adminPermission = pikkuPermission(
- *   async ({ logger }, _data, { getSession }) => {
- *     const currentSession = await getSession()
- *     return currentSession?.role === 'admin'
- *   }
- * )
- *
- * // Configuration object syntax with metadata
- * export const adminPermission = pikkuPermission({
- *   name: 'Admin Permission',
- *   description: 'Checks if user has admin role',
- *   func: async ({ logger }, _data, { getSession }) => {
- *     const currentSession = await getSession()
- *     return currentSession?.role === 'admin'
- *   }
- * })
- * ```
- */
 export const pikkuPermission = (permission) => {
     return typeof permission === 'function' ? permission : permission.func;
 };
-/**
- * Factory function for creating permission factories
- * Use this when your permission needs configuration/input parameters
- *
- * @example
- * ```typescript
- * export const requireRole = pikkuPermissionFactory<{ role: string }>(({
- *   role
- * }) => {
- *   return pikkuPermission(async ({ logger }, data, { getSession }) => {
- *      const currentSession = await getSession()
- *     if (!currentSession || currentSession.role !== role) {
- *       logger.warn(`Permission denied: required role '${role}'`)
- *       return false
- *     }
- *     return true
- *   })
- * })
- * ```
- */
 export const pikkuPermissionFactory = (factory) => {
     return factory;
 };
-/**
- * Factory function for creating approval description functions with tree-shaking support.
- *
- * @example
- * ```typescript
- * export const deleteTodoApproval = pikkuApprovalDescription(
- *   async ({ todoStore }, { id }) => {
- *     const todo = await todoStore.get(id)
- *     return `Delete todo: "${todo.title}"`
- *   }
- * )
- * ```
- */
 export const pikkuApprovalDescription = (fn) => {
     return fn;
 };

package/dist/function/list.types.d.ts

@@ -1,35 +1,8 @@
 /**
- * List-function primitives.
- *
- * A "list function" is any Pikku function that returns a paginated
- * collection. Adopting this shape unlocks a shared vocabulary across
- * MCP tools, AI agents, typed RPC clients, and widget libraries — they
- * all reason about cursor, filter, sort, and search uniformly.
- *
- * Under the hood, a list function is still a normal `pikkuFunc`. These
- * types are purely structural constraints; no runtime behaviour change.
- *
- * @example
- * ```ts
- * import { pikkuFunc } from '#pikku'
- * import type { ListInput, ListOutput } from '@pikku/core'
- *
- * export const listSessions = pikkuFunc<
- *   ListInput<{ status?: SessionStatus[] }, 'user' | 'status' | 'uploaded_at'>,
- *   ListOutput<Session>
- * >({
- *   func: async ({ kysely }, input) => {
- *     // input.sort / input.filter / input.cursor / input.search are typed
- *     return { rows, nextCursor, totalCount }
- *   },
- * })
- * ```
- */
-/**
- * Shape every list function accepts as input.
- *
- * @template F - User-defined filter shape. Each key is a filterable field.
- * @template S - String union of sortable column names.
+ * A list function is an ordinary `pikkuFunc` whose input and output adopt
+ * these shapes. They are purely structural — no runtime behaviour attaches to
+ * them — and exist so MCP tools, agents, RPC clients and widget libraries all
+ * reason about cursor, filter, sort and search the same way.
  */
 export interface ListInput<F extends Record<string, unknown> = Record<string, never>, S extends string = never> {
     /** Opaque cursor from the previous page's `nextCursor`. */
@@ -41,14 +14,10 @@ export interface ListInput<F extends Record<string, unknown> = Record<string, ne
         column: S;
         direction: 'asc' | 'desc';
     }>;
-    /** Structured filter tree. See {@link Filter}. */
     filter?: Filter<F>;
     /** Unstructured text search across server-configured fields. */
     search?: string;
 }
-/**
- * Shape every list function returns.
- */
 export interface ListOutput<Row> {
     rows: Row[];
     /** Null when no more pages. */
@@ -57,12 +26,9 @@ export interface ListOutput<Row> {
     totalCount?: number;
 }
 /**
- * Leaf predicate value on a single field.
- *
- * Operator keywords (`equals`, `not`, `in`, `notIn`, `gt`, `gte`, `lt`,
- * `lte`, `contains`, `startsWith`, `endsWith`, `mode`) mirror Prisma's
- * vocabulary for dev familiarity. These keys are reserved and cannot be
- * used as user field names in a Filter's `F` type.
+ * Leaf predicate on a single field. The operator keywords mirror Prisma's
+ * vocabulary; they are reserved and cannot be used as user field names in a
+ * Filter's `F` type.
  */
 export type LeafValue<T> = T | null | T[] | {
     equals?: T | null;
@@ -79,9 +45,8 @@ export type LeafValue<T> = T | null | T[] | {
     mode?: 'sensitive' | 'insensitive';
 };
 /**
- * A single-key object keyed by a field name from F, value is a leaf
- * predicate. Single-key so the runtime discriminator is unambiguous:
- * multi-key objects are OR groups.
+ * A single-key object keyed by a field of F. Single-key so the runtime
+ * discriminator is unambiguous — multi-key objects are OR groups.
  */
 export type LeafFilter<F extends Record<string, unknown>> = {
     [K in keyof F]: {
@@ -89,24 +54,9 @@ export type LeafFilter<F extends Record<string, unknown>> = {
     };
 }[keyof F];
 /**
- * Recursive filter tree.
- *
- * - `Array<Filter<F>>` — AND of children.
- * - `{ [label: string]: Filter<F> }` — OR of children. Keys are arbitrary
- *   labels (unique strings), ignored at evaluation time.
- * - `LeafFilter<F>` — single-key predicate on a declared field.
- *
- * @example "status = pending AND (therapist = kim OR therapist = park) AND uploaded_at > 2026-04-10"
- * ```ts
- * const filter: Filter<{ status: string; therapistId: string; uploadedAt: string }> = [
- *   { status: 'pending' },
- *   {
- *     kim:  { therapistId: 'kim' },
- *     park: { therapistId: 'park' },
- *   },
- *   { uploadedAt: { gt: '2026-04-10' } },
- * ]
- * ```
+ * Recursive filter tree: an array is an AND of its children; an object is an
+ * OR of its children, keyed by arbitrary unique labels that are ignored at
+ * evaluation time; a single-key object is a leaf predicate.
  */
 export type Filter<F extends Record<string, unknown>> = LeafFilter<F> | Filter<F>[] | {
     [label: string]: Filter<F>;

package/dist/function/list.types.js

@@ -1,28 +1,7 @@
 /**
- * List-function primitives.
- *
- * A "list function" is any Pikku function that returns a paginated
- * collection. Adopting this shape unlocks a shared vocabulary across
- * MCP tools, AI agents, typed RPC clients, and widget libraries — they
- * all reason about cursor, filter, sort, and search uniformly.
- *
- * Under the hood, a list function is still a normal `pikkuFunc`. These
- * types are purely structural constraints; no runtime behaviour change.
- *
- * @example
- * ```ts
- * import { pikkuFunc } from '#pikku'
- * import type { ListInput, ListOutput } from '@pikku/core'
- *
- * export const listSessions = pikkuFunc<
- *   ListInput<{ status?: SessionStatus[] }, 'user' | 'status' | 'uploaded_at'>,
- *   ListOutput<Session>
- * >({
- *   func: async ({ kysely }, input) => {
- *     // input.sort / input.filter / input.cursor / input.search are typed
- *     return { rows, nextCursor, totalCount }
- *   },
- * })
- * ```
+ * A list function is an ordinary `pikkuFunc` whose input and output adopt
+ * these shapes. They are purely structural — no runtime behaviour attaches to
+ * them — and exist so MCP tools, agents, RPC clients and widget libraries all
+ * reason about cursor, filter, sort and search the same way.
  */
 export {};

package/dist/handle-error.d.ts

@@ -1,16 +1,3 @@
 import type { Logger } from './services/logger.js';
 import type { PikkuHTTP } from './wirings/http/http.types.js';
-/**
- * Handle errors that occur during route processing
- *
- * @param {any} e - The error that occurred
- * @param {PikkuHTTP | undefined} http - HTTP wire object
- * @param {string} traceId - Unique ID for tracking this error
- * @param {Logger} logger - Logger service
- * @param {number[]} logWarningsForStatusCodes - HTTP status codes to log as warnings
- * @param {boolean} respondWith404 - Whether to respond with 404 for NotFoundError
- * @param {boolean} bubbleError - Whether to throw the error after handling
- * @param {boolean} exposeErrors - Whether to include internal error details (message, stack and
- * payload of 5xx errors) in the response body. Ignored in production.
- */
 export declare const handleHTTPError: (e: any, http: PikkuHTTP | undefined, traceId: string | undefined, logger: Logger, logWarningsForStatusCodes: number[], respondWith404: boolean, bubbleError: boolean, exposeErrors?: boolean) => void;