@pikku/core 0.12.71 → 0.12.74

package/dist/wirings/http/pikku-fetch-http-request.js

@@ -1,9 +1,8 @@
 import { parse as parseQuery } from 'picoquery';
 import { parse as parseCookie } from 'cookie';
-import { UnprocessableContentError } from '../../errors/errors.js';
+import { PayloadTooLargeError, UnprocessableContentError, } from '../../errors/errors.js';
+export const DEFAULT_MAX_BODY_SIZE = 10 * 1024 * 1024;
 /**
- * Abstract class representing a pikku request.
- * @template In - The type of the request body.
  * @group RequestResponse
  */
 export class PikkuFetchHTTPRequest {
@@ -14,9 +13,11 @@ export class PikkuFetchHTTPRequest {
     #rawBodyText;
     #rawBodyBuffer;
     #rawBufferPromise;
-    constructor(request) {
+    #maxBodySize;
+    constructor(request, { maxBodySize = DEFAULT_MAX_BODY_SIZE } = {}) {
         this.request = request;
         this.#url = new URL(request.url);
+        this.#maxBodySize = maxBodySize;
     }
     method() {
         return this.request.method.toLowerCase();
@@ -24,33 +25,13 @@ export class PikkuFetchHTTPRequest {
     path() {
         return this.#url.pathname;
     }
-    /**
-     * Retrieves the request body.
-     * @returns A promise that resolves to the request body.
-     */
     async json() {
         const text = await this.#readRawText();
         return JSON.parse(text);
     }
-    /**
-     * Retrieves the raw request body as a Buffer.
-     * @returns A promise that resolves to the raw request body.
-     */
     async arrayBuffer() {
         return this.#readRawBuffer();
     }
-    /**
-     * Reads the underlying single-use request body exactly once and memoises both
-     * the in-flight promise and the result. `json()`, `arrayBuffer()`, `body()`
-     * and `toWebRequest()` all funnel through here, so a request whose body is
-     * consumed in more than one place can no longer race on the underlying stream
-     * and fail with "Body has already been used".
-     *
-     * If a second consumer asks for the body while the first read is still in
-     * flight, that is the concurrent double-read that used to crash — now safe,
-     * but warned about so the redundant consumer is found and removed at the
-     * source rather than silently leaning on this cache.
-     */
     async #readRawBuffer() {
         if (this.#rawBodyBuffer !== undefined) {
             return this.#rawBodyBuffer;
@@ -68,12 +49,59 @@ export class PikkuFetchHTTPRequest {
                 `toWebRequest just for headers) should be removed.`);
             return this.#rawBufferPromise;
         }
-        this.#rawBufferPromise = this.request.arrayBuffer().then((buf) => {
+        this.#rawBufferPromise = this.#readBoundedBuffer().then((buf) => {
             this.#rawBodyBuffer = buf;
             return buf;
         });
         return this.#rawBufferPromise;
     }
+    async #readBoundedBuffer() {
+        const contentLength = this.request.headers.get('content-length');
+        if (contentLength !== null) {
+            const declaredSize = Number(contentLength);
+            if (Number.isFinite(declaredSize) && declaredSize > this.#maxBodySize) {
+                throw this.#payloadTooLarge();
+            }
+        }
+        const stream = this.request.body;
+        if (stream === null) {
+            const buffer = await this.request.arrayBuffer();
+            if (buffer.byteLength > this.#maxBodySize) {
+                throw this.#payloadTooLarge();
+            }
+            return buffer;
+        }
+        const reader = stream.getReader();
+        const chunks = [];
+        let size = 0;
+        try {
+            while (true) {
+                const { done, value } = await reader.read();
+                if (done) {
+                    break;
+                }
+                size += value.byteLength;
+                if (size > this.#maxBodySize) {
+                    await reader.cancel();
+                    throw this.#payloadTooLarge();
+                }
+                chunks.push(value);
+            }
+        }
+        finally {
+            reader.releaseLock();
+        }
+        const body = new Uint8Array(size);
+        let offset = 0;
+        for (const chunk of chunks) {
+            body.set(chunk, offset);
+            offset += chunk.byteLength;
+        }
+        return body.buffer;
+    }
+    #payloadTooLarge() {
+        return new PayloadTooLargeError(`Request body exceeds the maximum size of ${this.#maxBodySize} bytes`);
+    }
     async #readRawText() {
         if (this.#rawBodyText !== undefined) {
             return this.#rawBodyText;
@@ -85,18 +113,9 @@ export class PikkuFetchHTTPRequest {
     headers() {
         return Object.fromEntries(this.request.headers.entries());
     }
-    /**
-     * Retrieves the value of a specific header.
-     * @param headerName - The name of the header to retrieve.
-     * @returns The value of the header, or undefined if the header is not found.
-     */
     header(headerName) {
         return this.request.headers.get(headerName.toLowerCase());
     }
-    /**
-     * Retrieves the cookies from the request.
-     * @returns An object containing the cookies.
-     */
     cookie(cookieName) {
         if (this.#cookies?.[cookieName]) {
             return this.#cookies[cookieName];
@@ -105,31 +124,15 @@ export class PikkuFetchHTTPRequest {
         this.#cookies = cookieHeader ? parseCookie(cookieHeader) : {};
         return this.#cookies[cookieName] || null;
     }
-    /**
-     * Retrieves the request parameters.
-     * @returns An object containing the request parameters.
-     */
     params() {
         return this.#params;
     }
-    /**
-     * Sets the request parameters.
-     * @param params - An object containing the request parameters to set.
-     */
     setParams(params) {
         this.#params = params;
     }
-    /**
-     * Retrieves the query parameters from the request.
-     * @returns An object containing the query parameters.
-     */
     query() {
         return parseQuery(this.#url.searchParams.toString());
     }
-    /**
-     * Retrieves the combined data from the request, including parameters, query, and body.
-     * @returns A promise that resolves to an object containing the combined data.
-     */
     async data() {
         const body = await this.body();
         const parts = [this.params(), this.query(), body];
@@ -191,6 +194,9 @@ export class PikkuFetchHTTPRequest {
             }
         }
         catch (e) {
+            if (e instanceof PayloadTooLargeError) {
+                throw e;
+            }
             throw new UnprocessableContentError(`Error parsing body: ${e}`);
         }
         return body;

package/dist/wirings/http/pikku-fetch-http-response.js

@@ -96,8 +96,6 @@ export class PikkuFetchHTTPResponse {
     }
     toResponse(args) {
         const cookieHeader = Array.from(this.#cookies.entries()).map(([name, { value, flags }]) => serializeCookie(name, value, flags));
-        // Multiple Set-Cookie headers must be appended separately, not joined with commas
-        // per HTTP specification (RFC 6265)
         cookieHeader.forEach((cookie) => this.#headers.append('Set-Cookie', cookie));
         return new Response(this.#body, {
             ...args,
@@ -117,7 +115,6 @@ export class PikkuFetchHTTPResponse {
                 };
                 this.#send = send;
                 this.#close = close;
-                // Force initial flush
                 controller.enqueue(encoder.encode(':\n\n'));
             },
         });

package/dist/wirings/http/routers/path-to-regex.js

@@ -12,42 +12,35 @@ export class PathToRegexRouter {
     initialize() {
         const routes = pikkuState(null, 'http', 'routes');
         const channelRoutes = pikkuState(null, 'channel', 'channels');
-        // Helper function to compile routes for a given method
         const compileRoutesForMethod = (method, routeEntries) => {
             const methodCompiledRoutes = this.compiledRoutes.get(method) || new Map();
             const methodStaticRoutes = this.staticRoutes.get(method) || new Map();
             for (const [routePath] of routeEntries) {
-                // Normalize route path - ensure it starts with /
                 const normalizedRoutePath = routePath.startsWith('/')
                     ? routePath
                     : `/${routePath}`;
-                // Check if route is static (no parameters or wildcards)
                 const isStaticRoute = !/\*|:/.test(normalizedRoutePath);
                 if (isStaticRoute) {
-                    // Store static routes for O(1) lookup
                     methodStaticRoutes.set(normalizedRoutePath, {
-                        route: routePath, // Keep the original route path for lookup in pikkuState
+                        route: routePath,
                     });
                 }
                 else {
-                    // Compile dynamic routes with path-to-regexp
                     const matcher = match(normalizedRoutePath, {
                         decode: decodeURIComponent,
                     });
                     methodCompiledRoutes.set(normalizedRoutePath, {
                         matcher,
-                        route: routePath, // Keep the original route path for lookup in pikkuState
+                        route: routePath,
                     });
                 }
             }
             this.compiledRoutes.set(method, methodCompiledRoutes);
             this.staticRoutes.set(method, methodStaticRoutes);
         };
-        // Precompile all HTTP route matchers
         for (const [method, routeMap] of routes.entries()) {
             compileRoutesForMethod(method, routeMap.entries());
         }
-        // Precompile all channel route matchers (treating them as GET routes for WebSocket upgrades)
         const channelRoutesArray = Array.from(channelRoutes.entries()).map(([, channel]) => [channel.route, channel]);
         compileRoutesForMethod('get', channelRoutesArray);
         this.isInitialized = true;
@@ -56,9 +49,7 @@ export class PathToRegexRouter {
         if (!this.isInitialized) {
             this.initialize();
         }
-        // Normalize path - ensure it starts with /
         const normalizedPath = path.startsWith('/') ? path : `/${path}`;
-        // First, try static routes for O(1) lookup
         const methodStaticRoutes = this.staticRoutes.get(method);
         if (methodStaticRoutes) {
             const staticRoute = methodStaticRoutes.get(normalizedPath);
@@ -69,12 +60,10 @@ export class PathToRegexRouter {
                 };
             }
         }
-        // If no static route matched, try dynamic routes
         const methodRoutes = this.compiledRoutes.get(method);
         if (!methodRoutes) {
             return null;
         }
-        // Try each compiled route for this method
         for (const [, compiledRoute] of methodRoutes.entries()) {
             const result = compiledRoute.matcher(normalizedPath);
             if (result) {

package/dist/wirings/http/web-request.d.ts

@@ -1,12 +1,4 @@
 import type { PikkuHTTPRequest } from './http.types.js';
 import type { PikkuHTTPResponse } from './http.types.js';
-/**
- * Converts a PikkuHTTPRequest into a Web API Request.
- * Useful for bridging Pikku routes to libraries that expect standard Web Request objects.
- */
 export declare function toWebRequest(req: PikkuHTTPRequest, baseUrl?: string): Request;
-/**
- * Applies a Web API Response to a PikkuHTTPResponse.
- * Copies status, headers (including Set-Cookie), redirects, and body.
- */
 export declare function applyWebResponse(res: PikkuHTTPResponse, webResponse: Response): Promise<void>;

package/dist/wirings/http/web-request.js

@@ -1,7 +1,3 @@
-/**
- * Converts a PikkuHTTPRequest into a Web API Request.
- * Useful for bridging Pikku routes to libraries that expect standard Web Request objects.
- */
 export function toWebRequest(req, baseUrl) {
     const proto = req.header('x-forwarded-proto') ?? 'http';
     const host = req.header('x-forwarded-host') ?? req.header('host') ?? 'localhost';
@@ -21,11 +17,6 @@ export function toWebRequest(req, baseUrl) {
     return new Request(url, {
         method,
         headers,
-        // `pull` (lazy) rather than `start` (eager): the body is only read from the
-        // underlying request when this stream is actually consumed. A consumer that
-        // builds a web Request just to read its headers (e.g. a session middleware
-        // calling getSession({ headers })) never touches the body, so it does zero
-        // body I/O and cannot race the route handler's read of the same request.
         body: new ReadableStream({
             async pull(controller) {
                 try {
@@ -34,7 +25,6 @@ export function toWebRequest(req, baseUrl) {
                         controller.enqueue(new Uint8Array(buffer));
                     }
                     else {
-                        // arrayBuffer may be empty if body was pre-parsed (e.g., Express middleware)
                         const contentType = (headers.get('content-type') || '').toLowerCase();
                         const parsed = await req.json();
                         if (parsed &&
@@ -51,9 +41,7 @@ export function toWebRequest(req, baseUrl) {
                         }
                     }
                 }
-                catch {
-                    // Empty body
-                }
+                catch { }
                 controller.close();
             },
         }),
@@ -88,9 +76,29 @@ function collectSetCookieHeaders(webResponse) {
     return values;
 }
 /**
- * Applies a Web API Response to a PikkuHTTPResponse.
- * Copies status, headers (including Set-Cookie), redirects, and body.
+ * Content types whose bodies are text. Everything else is bytes.
+ *
+ * The distinction matters because reading a body as text is lossy for anything
+ * that is not valid UTF-8: every byte that does not decode becomes U+FFFD, and
+ * re-encoding turns each of those into three bytes. A WASM module or an ONNX
+ * model served that way arrives larger than it left and no longer parses, with
+ * a 200 and no error anywhere to say why.
  */
+const TEXTUAL_CONTENT_TYPE = /^(text\/|application\/(json|javascript|ecmascript|xml|x-www-form-urlencoded)|[^;]*\+(json|xml)\b)/i;
+/**
+ * Read a response body as text where that is meaningful, and as bytes
+ * otherwise. An absent content type is treated as text, which is what a body
+ * built from a string gets by default and so preserves existing behaviour.
+ */
+async function readBody(webResponse) {
+    const contentType = webResponse.headers.get('content-type');
+    if (contentType === null || TEXTUAL_CONTENT_TYPE.test(contentType)) {
+        const text = await webResponse.text();
+        return text === '' ? null : text;
+    }
+    const bytes = new Uint8Array(await webResponse.arrayBuffer());
+    return bytes.byteLength === 0 ? null : bytes;
+}
 export async function applyWebResponse(res, webResponse) {
     res.status(webResponse.status);
     const setCookieValues = collectSetCookieHeaders(webResponse);
@@ -112,8 +120,8 @@ export async function applyWebResponse(res, webResponse) {
     if (setCookieValues.length > 0) {
         res.header('Set-Cookie', setCookieValues);
     }
-    const body = await webResponse.text();
-    if (body) {
+    const body = await readBody(webResponse);
+    if (body !== null) {
         if (res.send) {
             res.send(body);
         }

package/dist/wirings/mcp/mcp-runner.d.ts

@@ -6,6 +6,8 @@ export declare class MCPError extends Error {
 }
 export type RunMCPEndpointParams<Tools extends string = any> = {
     mcp?: PikkuMCP<Tools>;
+    /** Defaults to enabled outside production. */
+    exposeErrors?: boolean;
 };
 export type JsonRpcError = {
     code: number;

package/dist/wirings/mcp/mcp-runner.js

@@ -1,5 +1,5 @@
 import { getErrorResponse } from '../../errors/error-handler.js';
-import { closeWireServices } from '../../utils.js';
+import { isProduction } from '../../env.js';
 import { pikkuState, getSingletonServices, getCreateWireServices, } from '../../pikku-state.js';
 import { addFunction, runPikkuFunc } from '../../function/function-runner.js';
 import { resolveNamespace } from '../rpc/rpc-runner.js';
@@ -54,16 +54,13 @@ export async function runMCPResource(request, params, uri) {
     }
     else {
         for (const [uriTemplate, value] of endpoints.entries()) {
-            // Extract parameter names from the template
             const paramNames = Array.from(uriTemplate.matchAll(/\{([^}]+)\}/g), (m) => m[1]);
-            // Create regex pattern to match and capture parameter values
             const regexPattern = uriTemplate.replace(/\{[^}]+\}/g, '([^/]+)');
             const regex = new RegExp(`^${regexPattern}$`);
             const match = uri.match(regex);
             if (match) {
                 endpoint = value;
                 pikkuFuncId = metas[uriTemplate]?.pikkuFuncId;
-                // Extract parameter values and create params object
                 for (let i = 0; i < paramNames.length; i++) {
                     extractedParams[paramNames[i]] = match[i + 1]; // match[0] is the full match
                 }
@@ -85,13 +82,9 @@ export async function runMCPPrompt(request, params, name) {
     const meta = pikkuState(null, 'mcp', 'promptsMeta')[name];
     return await runMCPPikkuFunc(request, 'prompt', name, endpoint, meta?.pikkuFuncId, params);
 }
-/**
- * JSON-RPC 2.0 compatible MCP endpoint runner
- */
-async function runMCPPikkuFunc(request, type, name, mcp, pikkuFuncId, { mcp: mcpWire }) {
+async function runMCPPikkuFunc(request, type, name, mcp, pikkuFuncId, { mcp: mcpWire, exposeErrors = !isProduction() }) {
     const singletonServices = getSingletonServices();
     const createWireServices = getCreateWireServices();
-    let wireServices;
     try {
         if (request.jsonrpc !== '2.0') {
             throw new BadRequestError('Invalid JSON-RPC version, only supoorted version is 2.0');
@@ -118,7 +111,6 @@ async function runMCPPikkuFunc(request, type, name, mcp, pikkuFuncId, { mcp: mcp
         else if (type === 'prompt') {
             meta = pikkuState(null, 'mcp', 'promptsMeta')[name];
         }
-        // Resolve namespaced function IDs (e.g., 'swaggerPetstore:findPetsByStatus')
         let resolvedFuncName = pikkuFuncId;
         let resolvedPackageName = meta?.packageName ?? null;
         if (pikkuFuncId.includes(':')) {
@@ -165,15 +157,13 @@ async function runMCPPikkuFunc(request, type, name, mcp, pikkuFuncId, { mcp: mcp
                 id: request.id,
                 code: -32603,
                 message: 'Internal error',
-                data: { message: e.message, stack: e.stack },
+                // knowledge: decisions/security/mcp-internal-error-details-are-double-gated-on-production.md
+                data: exposeErrors && !isProduction() && e instanceof Error
+                    ? { message: e.message, stack: e.stack }
+                    : undefined,
             });
         }
     }
-    finally {
-        if (wireServices) {
-            await closeWireServices(singletonServices.logger, wireServices);
-        }
-    }
 }
 export const getMCPResources = () => {
     return pikkuState(null, 'mcp', 'resources');

package/dist/wirings/mcp/mcp.types.d.ts

@@ -1,14 +1,8 @@
 import type { CorePikkuFunctionConfig, CorePikkuFunctionSessionless, CorePikkuPermission } from '../../function/functions.types.js';
 import type { CorePikkuMiddleware, MiddlewareMetadata } from '../../types/core.types.js';
-/**
- * Extract URI parameters from MCP resource URI template.
- * E.g., "user/{userId}/post/{postId}" => "userId" | "postId"
- */
+/** "user/{userId}/post/{postId}" => "userId" | "postId" */
 type ExtractMCPURIParams<S extends string> = S extends `${string}{${infer Param}}/${infer Rest}` ? Param | ExtractMCPURIParams<Rest> : S extends `${string}{${infer Param}}` ? Param : never;
-/**
- * Type-level assertion that MCP resource URI parameters are present in the input type.
- * This ensures compile-time safety for URI parameter validation.
- */
+/** Resolves to a tuple of error strings, not `never`, so the mismatch surfaces in the type error. */
 export type AssertMCPResourceURIParams<In, URI extends string> = ExtractMCPURIParams<URI> extends keyof In ? unknown : [
     'Error: MCP Resource URI parameters',
     ExtractMCPURIParams<URI>,
@@ -22,27 +16,18 @@ export type PikkuMCP<Tools extends string = any> = {
     enablePrompts: (prompts: Record<string, boolean>) => Promise<boolean>;
     enableTools: (tools: Record<Tools, boolean>) => Promise<boolean>;
 };
-/**
- * Represents metadata for MCP resources, including name, description, and documentation.
- */
 export type MCPResourceMeta = Record<string, Omit<CoreMCPResource, 'func' | 'middleware'> & {
     pikkuFuncId: string;
     inputSchema: string | null;
     outputSchema: string | null;
     middleware?: MiddlewareMetadata[];
 }>;
-/**
- * Represents metadata for MCP tools, including name, description, and documentation.
- */
 export type MCPToolMeta = Record<string, Omit<CoreMCPTool, 'func' | 'middleware'> & {
     pikkuFuncId: string;
     inputSchema: string | null;
     outputSchema: string | null;
     middleware?: MiddlewareMetadata[];
 }>;
-/**
- * Represents metadata for MCP prompts, including name, description, and arguments.
- */
 export type MCPPromptMeta = Record<string, Omit<CoreMCPPrompt, 'func' | 'middleware'> & {
     pikkuFuncId: string;
     inputSchema: string | null;
@@ -54,9 +39,6 @@ export type MCPPromptMeta = Record<string, Omit<CoreMCPPrompt, 'func' | 'middlew
     }>;
     middleware?: MiddlewareMetadata[];
 }>;
-/**
- * Represents an MCP resource with specific properties.
- */
 export type CoreMCPResource<PikkuFunctionConfig = CorePikkuFunctionConfig<CorePikkuFunctionSessionless<any, any>>, PikkuPermission = CorePikkuPermission<any, any>, PikkuMiddleware = CorePikkuMiddleware<any>> = {
     uri: string;
     title: string;
@@ -70,9 +52,6 @@ export type CoreMCPResource<PikkuFunctionConfig = CorePikkuFunctionConfig<CorePi
     tags?: string[];
     middleware?: PikkuMiddleware[];
 };
-/**
- * Represents an MCP tool with specific properties.
- */
 export type CoreMCPTool<PikkuFunctionConfig = CorePikkuFunctionConfig<CorePikkuFunctionSessionless<any, any>>, PikkuPermission = CorePikkuPermission<any, any>, PikkuMiddleware = CorePikkuMiddleware<any>> = {
     name: string;
     title?: string;
@@ -84,9 +63,6 @@ export type CoreMCPTool<PikkuFunctionConfig = CorePikkuFunctionConfig<CorePikkuF
     streaming?: boolean;
     middleware?: PikkuMiddleware[];
 };
-/**
- * Represents an MCP prompt with specific properties.
- */
 export type CoreMCPPrompt<PikkuFunctionConfig = CorePikkuFunctionConfig<CorePikkuFunctionSessionless<any, MCPPromptResponse>>, PikkuPermission = CorePikkuPermission<any, any>, PikkuMiddleware = CorePikkuMiddleware<any>> = {
     name: string;
     description: string;
@@ -111,9 +87,6 @@ export type JsonRpcErrorResponse = {
     message: string;
     data?: any;
 };
-/**
- * Represents a message in an MCP prompt response
- */
 export type MCPPromptMessage = {
     role: 'user' | 'assistant' | 'system';
     content: {
@@ -122,18 +95,12 @@ export type MCPPromptMessage = {
         data?: string;
     };
 };
-/**
- * Standard response type for MCP prompts - array of messages
- */
 export type MCPPromptResponse = MCPPromptMessage[];
 export type MCPResourceMessage = {
     uri: string;
     text: string;
 };
 export type MCPResourceResponse = MCPResourceMessage[];
-/**
- * Standard response type for MCP prompts - array of messages
- */
 export type MCPToolMessage = {
     type: 'text';
     text: string;

package/dist/wirings/oauth2/oauth2.types.d.ts

@@ -1,17 +1,7 @@
-/**
- * OAuth2 credential and token types.
- */
-/**
- * App credentials for OAuth2 (client ID and secret).
- * These are typically set once and stored in the secret service.
- */
 export type OAuth2AppCredential = {
     clientId: string;
     clientSecret?: string;
 };
-/**
- * OAuth2 token data returned from token endpoint.
- */
 export type OAuth2Token = {
     accessToken: string;
     refreshToken?: string;
@@ -19,21 +9,3 @@ export type OAuth2Token = {
     tokenType: string;
     scope?: string;
 };
-/**
- * OAuth2-specific configuration that extends a credential.
- * This is stored in SecretDefinitionMeta.oauth2 field.
- */
-export type OAuth2Config = {
-    /** Where access/refresh tokens are stored */
-    tokenSecretId: string;
-    /** OAuth2 authorization URL */
-    authorizationUrl: string;
-    /** OAuth2 token exchange URL */
-    tokenUrl: string;
-    /** Required scopes */
-    scopes: string[];
-    /** Use PKCE flow */
-    pkce?: boolean;
-    /** Additional query parameters for authorization URL */
-    additionalParams?: Record<string, string>;
-};

package/dist/wirings/oauth2/oauth2.types.js

@@ -1,4 +1 @@
-/**
- * OAuth2 credential and token types.
- */
 export {};

package/dist/wirings/persona/define-personas.d.ts

@@ -0,0 +1,28 @@
+import type { CorePersonas } from './persona.types.js';
+/**
+ * No-op function for declaring personas.
+ * This exists purely for TypeScript type checking and will be tree-shaken.
+ * The CLI extracts metadata via AST parsing and generates a `PersonaId` union
+ * and a `personas.gen.json` the console and `pikku persona run` read off disk —
+ * describing, listing or running one never has to load the app.
+ *
+ * `definePersonas` rather than `defineVirtualUsers` because declaring is not
+ * running: a persona that exists only to be acted upon (the account an admin
+ * bans, the colleague a document is shared with) is seeded and never run.
+ *
+ * @example
+ * ```typescript
+ * definePersonas({
+ *   susan: {
+ *     name: 'Susan',
+ *     jobTitle: 'Buys for a small café',
+ *     roles: ['buyer'],
+ *     personality: 'Hunts cheap deals. Tries three coupon codes before giving up.',
+ *     goals: ['Get the weekly order in under five minutes'],
+ *     disposition: 'careless',
+ *     account: {},
+ *   },
+ * })
+ * ```
+ */
+export declare const definePersonas: (_config: CorePersonas) => void;

package/dist/wirings/persona/define-personas.js

@@ -0,0 +1,27 @@
+/**
+ * No-op function for declaring personas.
+ * This exists purely for TypeScript type checking and will be tree-shaken.
+ * The CLI extracts metadata via AST parsing and generates a `PersonaId` union
+ * and a `personas.gen.json` the console and `pikku persona run` read off disk —
+ * describing, listing or running one never has to load the app.
+ *
+ * `definePersonas` rather than `defineVirtualUsers` because declaring is not
+ * running: a persona that exists only to be acted upon (the account an admin
+ * bans, the colleague a document is shared with) is seeded and never run.
+ *
+ * @example
+ * ```typescript
+ * definePersonas({
+ *   susan: {
+ *     name: 'Susan',
+ *     jobTitle: 'Buys for a small café',
+ *     roles: ['buyer'],
+ *     personality: 'Hunts cheap deals. Tries three coupon codes before giving up.',
+ *     goals: ['Get the weekly order in under five minutes'],
+ *     disposition: 'careless',
+ *     account: {},
+ *   },
+ * })
+ * ```
+ */
+export const definePersonas = (_config) => { };

package/dist/wirings/persona/index.d.ts

@@ -0,0 +1,21 @@
+export { definePersonas } from './define-personas.js';
+export { isRunnablePersona, roleMismatchMessage, runnablePersonas, validateAndBuildPersonasMeta, verifyPersonaRoles, } from './validate-personas.js';
+export type { RoleVerification } from './validate-personas.js';
+export { personaEnvironmentErrors, personaEnvironmentRefusal, resolvePersonaEnvironments, } from './persona-environments.js';
+export type { PersonaEnvironment, PersonaEnvironmentSubject, } from './persona-environments.js';
+export { personaEmail, personaEmailLabel, personaEmails, } from './persona-email.js';
+export { allowedLinks, applyMailboxAllowlist, isAllowedSender, } from './persona-mailbox.js';
+export type { MailboxAllowlist, PersonaMailbox, ReceivedEmail, } from './persona-mailbox.js';
+export type { CorePersona, CorePersonaAccount, CorePersonas, PersonaAccountMeta, PersonaDefinitions, PersonaMeta, PersonasMeta, } from './persona.types.js';
+/**
+ * Signing in as a persona and talking to a stage over HTTP.
+ *
+ * Deliberately reached through this entry point rather than `@pikku/core/services`.
+ * `HttpPersona` pulls in the actor-flow conversation runner and, through it, the
+ * agent runner — none of which a production server has any use for. Exporting it
+ * from the services barrel put that chain in the module graph of every app that
+ * imports services, which only a bundler could remove and an unbundled Node or
+ * Lambda deploy would load outright.
+ */
+export { HttpPersona, createHttpPersonas, type HttpPersonasConfig, } from '../../services/http-personas.js';
+export { postScenarioJson, readScenarioHttpResponse, } from '../../services/personas-service.js';