@pikku/core 0.12.72 → 0.12.77

package/dist/dev/reload-meta.js

@@ -24,27 +24,16 @@ const readJson = async (logger, file) => {
     }
 };
 /**
- * Re-reads the codegen output (wiring meta + JSON schemas) into the running
- * process so new and changed functions become callable without a server
- * restart. The generated `*-meta.gen.ts` files are plain
- * `pikkuState(area, key, <json>)` side effects, but they cannot be
- * re-imported after a dev-time codegen — the ESM cache pins both the wrapper
- * and its JSON import — so this reads the JSON sources directly and applies
- * the same state.
- *
- * Meant to be called by a dev-server watcher after each codegen pass. Routes
- * registered by NEW `wireHTTP` files are not picked up (their modules were
- * never imported); those still need a restart.
+ * Re-reads codegen output (wiring meta + JSON schemas) into the running
+ * process, so new and changed functions become callable without a restart.
+ * Called by a dev-server watcher after each codegen pass. Routes registered by
+ * NEW `wireHTTP` files are not picked up — their modules were never imported.
  */
 export async function reloadGeneratedMeta(options) {
     const { pikkuDir, logger, schemaService } = options;
     const dir = resolve(pikkuDir);
     const functionsMeta = await readJson(logger, join(dir, 'function/pikku-functions-meta.gen.json'));
-    // Merge over the existing map, don't replace it: framework internals like
-    // pikkuWorkflowOrchestrator / the per-workflow queue workers are registered
-    // at service-init (pikku-workflow-service.ts), never in the generated JSON —
-    // a wholesale replace drops them and workflow jobs then fail with
-    // "Function meta not found: pikkuWorkflowOrchestrator".
+    // knowledge: decisions/internals/core-hot-reload-merges-generated-meta-never-replaces-it.md
     if (functionsMeta) {
         const existing = pikkuState(null, 'function', 'meta') ?? {};
         pikkuState(null, 'function', 'meta', { ...existing, ...functionsMeta });
@@ -56,9 +45,6 @@ export async function reloadGeneratedMeta(options) {
     if (rpcMeta)
         pikkuState(null, 'rpc', 'meta', rpcMeta);
     const queueMeta = await readJson(logger, join(dir, 'queue/pikku-queue-workers-wirings-meta.gen.json'));
-    // Same reason as function meta: the workflow service adds its orchestrator /
-    // step queues (and wf-orchestrator-* / wf-step-* per-workflow queues) here at
-    // init, absent from the generated JSON — merge so they survive the reload.
     if (queueMeta) {
         const existing = pikkuState(null, 'queue', 'meta') ?? {};
         pikkuState(null, 'queue', 'meta', { ...existing, ...queueMeta });
@@ -67,7 +53,6 @@ export async function reloadGeneratedMeta(options) {
     if (agentMeta?.agentsMeta) {
         pikkuState(null, 'agent', 'agentsMeta', agentMeta.agentsMeta);
     }
-    // Generated JSON schemas: <outDir>/schemas/schemas/<Name>.schema.json.
     // Re-adding replaces the map entry; the schema service recompiles any
     // validator whose stored schema value no longer matches.
     const schemasDir = join(dir, 'schemas', 'schemas');
@@ -98,16 +83,11 @@ export async function reloadGeneratedMeta(options) {
     }
 }
 /**
- * Prunes the live addon registry down to what the current source still declares.
- *
- * Dev hot-reload re-imports only changed/added files, so a deleted `*.addon.ts`
- * leaves its `wireAddon` entry stranded in `pikkuState(null,'addons','packages')`
- * until a full restart — the reason `getInstalledAddons` reports removed addons.
- * The Map holds definitions (namespace → package config), not runtime state, so
- * dropping any namespace the fresh inspection no longer declares is safe.
+ * Prunes the live addon registry to the namespaces the current source still
+ * declares. Hot reload only re-imports files that exist, so a deleted
+ * `*.addon.ts` otherwise leaves its `wireAddon` entry stranded until a restart.
  *
- * `declaredNamespaces` is the set of `wireAddon` names from the just-regenerated
- * inspection (`inspectorState.rpc.wireAddonDeclarations.keys()`).
+ * `declaredNamespaces` is `inspectorState.rpc.wireAddonDeclarations.keys()`.
  */
 export function reconcileAddonRegistry(declaredNamespaces, logger) {
     const declared = new Set(declaredNamespaces);

package/dist/errors/error-handler.d.ts

@@ -1,46 +1,21 @@
-/**
- * Base class for custom errors.
- * @extends {Error}
- */
 export declare class PikkuError extends Error {
-    /**
-     * Creates an instance of PikkuError.
-     * @param message - The error message.
-     */
     constructor(message?: string);
 }
 /**
- * Whether an error is a deliberate, expected failure rather than an uncaught
- * bug. A `PikkuError` always counts; so does any error carrying `expected:
- * true` — used to keep the marker alive when an error is serialized across a
- * workflow step boundary and rehydrated as a plain `Error`. Callers log the
- * message alone for expected errors and the full stack for everything else.
+ * A `PikkuError`, or any error carrying `expected: true` — the marker that
+ * survives serialization across a workflow step boundary and rehydration as a
+ * plain `Error`. Callers log the message alone for these, the full stack for
+ * everything else.
  */
 export declare const isExpectedError: (error: unknown) => boolean;
-/**
- * Interface for error details.
- */
 export interface ErrorDetails {
     status: number;
     message: string;
     mcpCode?: number;
 }
-/**
- * Adds an error to the API errors map.
- * @param error - The error to add.
- * @param details - The details of the error.
- */
+export type PikkuErrorConstructor = new (...args: any[]) => Error;
 export declare const addError: (error: any, { status, message, mcpCode }: ErrorDetails) => void;
-/**
- * Adds multiple errors to the API errors map.
- * @param errors - An array of errors and their details.
- */
 export declare const addErrors: (errors: Array<[error: any, details: ErrorDetails]>) => void;
-/**
- * Retrieves the error response for a given error.
- * @param error - The error to get the response for.
- * @returns An object containing the status and message, or undefined if the error is not found.
- */
 export declare const getErrorResponse: (error: Error) => {
     status: number;
     message: string;

package/dist/errors/error-handler.js

@@ -1,13 +1,5 @@
 import { pikkuState } from '../pikku-state.js';
-/**
- * Base class for custom errors.
- * @extends {Error}
- */
 export class PikkuError extends Error {
-    /**
-     * Creates an instance of PikkuError.
-     * @param message - The error message.
-     */
     constructor(message = 'An error occurred') {
         super(message);
         Object.setPrototypeOf(this, new.target.prototype);
@@ -15,40 +7,32 @@ export class PikkuError extends Error {
     }
 }
 /**
- * Whether an error is a deliberate, expected failure rather than an uncaught
- * bug. A `PikkuError` always counts; so does any error carrying `expected:
- * true` — used to keep the marker alive when an error is serialized across a
- * workflow step boundary and rehydrated as a plain `Error`. Callers log the
- * message alone for expected errors and the full stack for everything else.
+ * A `PikkuError`, or any error carrying `expected: true` — the marker that
+ * survives serialization across a workflow step boundary and rehydration as a
+ * plain `Error`. Callers log the message alone for these, the full stack for
+ * everything else.
  */
 export const isExpectedError = (error) => error instanceof PikkuError || error?.expected === true;
-/**
- * Adds an error to the API errors map.
- * @param error - The error to add.
- * @param details - The details of the error.
- */
 export const addError = (error, { status, message, mcpCode }) => {
     pikkuState(null, 'misc', 'errors').set(error, mcpCode === undefined ? { status, message } : { status, message, mcpCode });
 };
-/**
- * Adds multiple errors to the API errors map.
- * @param errors - An array of errors and their details.
- */
 export const addErrors = (errors) => {
     errors.forEach((error) => {
         addError(error[0], error[1]);
     });
 };
-/**
- * Retrieves the error response for a given error.
- * @param error - The error to get the response for.
- * @returns An object containing the status and message, or undefined if the error is not found.
- */
 export const getErrorResponse = (error) => {
-    const errors = Array.from(pikkuState(null, 'misc', 'errors').entries());
-    const foundError = errors.find(([e]) => e.name === error.constructor.name);
-    if (foundError) {
-        return foundError[1];
+    const errors = pikkuState(null, 'misc', 'errors');
+    let ctor = error?.constructor;
+    while (typeof ctor === 'function' && ctor !== Object) {
+        const details = errors.get(ctor);
+        if (details) {
+            return details;
+        }
+        ctor = Object.getPrototypeOf(ctor);
     }
-    return pikkuState(null, 'misc', 'errors').get(error);
+    const name = error?.constructor?.name;
+    return name
+        ? Array.from(errors.entries()).find(([e]) => e.name === name)?.[1]
+        : undefined;
 };

package/dist/errors/errors.d.ts

@@ -1,6 +1,3 @@
-/**
- * The server cannot or will not process the request due to client error (e.g., malformed request syntax).
- */
 import { PikkuError } from './error-handler.js';
 export declare class InvalidMiddlewareWireError extends PikkuError {
 }
@@ -10,47 +7,18 @@ export declare class MissingServiceError extends PikkuError {
 }
 export declare class LocalEnvironmentOnlyError extends PikkuError {
 }
-/**
- * The server cannot or will not process the request due to client error (e.g., malformed request syntax).
- * @group Error
- */
 export declare class BadRequestError extends PikkuError {
 }
-/**
- * Authentication is required and has failed or has not yet been provided.
- * @group Error
- */
 export declare class UnauthorizedError extends PikkuError {
 }
-/**
- * More specific error to why it's unauthorized.
- * @group Error
- */
 export declare class MissingSessionError extends PikkuError {
 }
-/**
- * More specific error to why it's unauthorized.
- * @group Error
- */
 export declare class InvalidSessionError extends PikkuError {
 }
-/**
- * Reserved for future use, often related to digital payment or subscription services.
- * @group Error
- */
 export declare class PaymentRequiredError extends PikkuError {
 }
-/**
- * The client does not have permission to access the requested resource.
- * @group Error
- */
 export declare class ForbiddenError extends PikkuError {
 }
-/**
- * A required credential is missing. The payload contains metadata
- * about the credential so the client can initiate a connect flow.
- * @group Error
- */
 export declare class MissingCredentialError extends PikkuError {
     payload: {
         error: 'missing_credential';
@@ -60,11 +28,6 @@ export declare class MissingCredentialError extends PikkuError {
     };
     constructor(credentialName: string, credentialType: 'oauth2' | 'apikey', connectUrl?: string);
 }
-/**
- * The session does not hold a scope required by the function. The payload
- * names the missing scope so the client can surface what to request.
- * @group Error
- */
 export declare class MissingScopeError extends PikkuError {
     payload: {
         error: 'missing_scope';
@@ -72,179 +35,97 @@ export declare class MissingScopeError extends PikkuError {
     };
     constructor(scope: string);
 }
-/**
- * The session is readonly and cannot access a non-readonly function.
- * @group Error
- */
 export declare class ReadonlySessionError extends PikkuError {
 }
-/**
- * The request was made from an origin that is not permitted to access this resource.
- * @group Error
- */
 export declare class InvalidOriginError extends PikkuError {
 }
-/**
- * The server cannot find the requested resource.
- * @group Error
- */
 export declare class NotFoundError extends PikkuError {
 }
-/**
- * The request method is known by the server but is not supported by the resource.
- * @group Error
- */
 export declare class MethodNotAllowedError extends PikkuError {
 }
-/**
- * The requested resource cannot produce a response matching the list of acceptable values in the request's headers.
- * @group Error
- */
 export declare class NotAcceptableError extends PikkuError {
 }
-/**
- * The client must authenticate itself to get the requested response.
- * @group Error
- */
 export declare class ProxyAuthenticationRequiredError extends PikkuError {
 }
-/**
- * The server request expired
- * @group Error
- */
 export declare class RequestTimeoutError extends PikkuError {
 }
-/**
- * The request could not be completed due to a conflict with the current state of the target resource.
- * @group Error
- */
 export declare class ConflictError extends PikkuError {
 }
-/**
- * The resource that is being accessed is no longer available and will not be available again.
- * @group Error
- */
 export declare class GoneError extends PikkuError {
 }
-/**
- * The request did not specify the length of its content, which is required by the requested resource.
- * @group Error
- */
 export declare class LengthRequiredError extends PikkuError {
 }
-/**
- * The server does not meet one of the preconditions that the requester put on the request.
- * @group Error
- */
 export declare class PreconditionFailedError extends PikkuError {
 }
-/**
- * The request is larger than the server is willing or able to process.
- * @group Error
- */
 export declare class PayloadTooLargeError extends PikkuError {
 }
-/**
- * The URI requested by the client is longer than the server is willing to interpret.
- * @group Error
- */
 export declare class URITooLongError extends PikkuError {
 }
-/**
- * The server does not support the media format of the requested data.
- * @group Error
- */
 export declare class UnsupportedMediaTypeError extends PikkuError {
 }
-/**
- * The client has asked for a portion of the file, but the server cannot supply that portion.
- * @group Error
- */
 export declare class RangeNotSatisfiableError extends PikkuError {
 }
-/**
- * The server cannot meet the requirements of the Expect request-header field.
- * @group Error
- */
 export declare class ExpectationFailedError extends PikkuError {
 }
-/**
- * Indicates that the server understood the content type of the request content, and the syntax of the request content was correct, but it was unable to process the contained instructions.
- * @group Error
- */
 export declare class UnprocessableContentError extends PikkuError {
 }
-/**
- * Indicates that the server understood the content type of the request content, and the syntax of the request content was correct, but it was unable to process the contained instructions.
- * @group Error
- */
 export declare class LockedError extends PikkuError {
 }
-/**
- * The user has sent too many requests in a given amount of time ("rate limiting").
- * @group Error
- */
 export declare class TooManyRequestsError extends PikkuError {
 }
-/**
- * A generic error message, given when no more specific message is suitable.
- * @group Error
- */
 export declare class InternalServerError extends PikkuError {
 }
-/**
- * The server does not recognize the request method and cannot support it.
- * @group Error
- */
 export declare class NotImplementedError extends PikkuError {
 }
-/**
- * The server was acting as a gateway or proxy and received an invalid response from the upstream server.
- * @group Error
- */
 export declare class BadGatewayError extends PikkuError {
 }
-/**
- * The server is currently unavailable (overloaded or down).
- * @group Error
- */
 export declare class ServiceUnavailableError extends PikkuError {
 }
-/**
- * The server was acting as a gateway or proxy and did not receive a timely response from the upstream server.
- * @group Error
- */
 export declare class GatewayTimeoutError extends PikkuError {
 }
-/**
- * The server does not support the HTTP protocol version used in the request.
- * @group Error
- */
 export declare class HTTPVersionNotSupportedError extends PikkuError {
 }
-/**
- * The server took too long to complete the request, reaching the maximum compute time allowed.
- * @group Error
- */
 export declare class MaxComputeTimeReachedError extends PikkuError {
 }
-/**
- * A required schema was not found during validation.
- * @group Error
- */
 export declare class MissingSchemaError extends PikkuError {
 }
+export declare class WeakKeyMaterialError extends PikkuError {
+    constructor(name: string, minimumLength: number, actualLength: number);
+}
+export declare class AIProviderNotConfiguredError extends PikkuError {
+    constructor();
+}
+export declare class AIProviderAuthError extends PikkuError {
+    constructor(message?: string);
+}
 /**
- * An AI provider has not been configured. Set up an AI provider (e.g. OpenAI, Anthropic) to use agent features.
+ * An administrative operation targeted a role that is declared in code.
+ *
+ * System roles ship with the product: the console may show and grant them, but
+ * renaming, re-scoping or deleting one would let a UI action silently change
+ * what a declared persona means, and what every scenario written against that
+ * role is actually testing.
  * @group Error
  */
-export declare class AIProviderNotConfiguredError extends PikkuError {
-    constructor();
+export declare class SystemRoleImmutableError extends PikkuError {
+    payload: {
+        error: 'system_role_immutable';
+        role: string;
+        operation: string;
+    };
+    constructor(role: string, operation: string);
 }
 /**
- * The AI provider API key is missing or invalid.
+ * A role was created with the name of a role declared in code.
+ *
+ * Shadowing is refused rather than merged: two rows answering to one name make
+ * "does Susan hold `buyer`?" depend on which one the store happened to return.
  * @group Error
  */
-export declare class AIProviderAuthError extends PikkuError {
-    constructor(message?: string);
+export declare class SystemRoleShadowedError extends PikkuError {
+    payload: {
+        error: 'system_role_shadowed';
+        role: string;
+    };
+    constructor(role: string);
 }