@pikku/core 0.12.72 → 0.12.74

package/src/dev/reload-meta.ts

@@ -41,17 +41,10 @@ const readJson = async (
 }
 
 /**
- * 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: ReloadGeneratedMetaOptions
@@ -63,11 +56,7 @@ export async function reloadGeneratedMeta(
     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 })
@@ -89,9 +78,6 @@ export async function reloadGeneratedMeta(
     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 })
@@ -105,7 +91,6 @@ export async function reloadGeneratedMeta(
     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')
@@ -138,16 +123,11 @@ export async function reloadGeneratedMeta(
 }
 
 /**
- * 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: Iterable<string>,

package/src/errors/error-handler.ts

@@ -1,14 +1,6 @@
 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: string = 'An error occurred') {
     super(message)
     Object.setPrototypeOf(this, new.target.prototype)
@@ -17,29 +9,22 @@ 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: unknown): boolean =>
   error instanceof PikkuError || (error as any)?.expected === true
 
-/**
- * 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 const addError = (
   error: any,
   { status, message, mcpCode }: ErrorDetails
@@ -50,10 +35,6 @@ export const addError = (
   )
 }
 
-/**
- * Adds multiple errors to the API errors map.
- * @param errors - An array of errors and their details.
- */
 export const addErrors = (
   errors: Array<[error: any, details: ErrorDetails]>
 ) => {
@@ -62,18 +43,22 @@ export const addErrors = (
   })
 }
 
-/**
- * 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: Error
 ): { status: number; message: string; mcpCode?: number } | undefined => {
-  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: unknown = (error as any)?.constructor
+  while (typeof ctor === 'function' && ctor !== Object) {
+    const details = errors.get(ctor as PikkuErrorConstructor)
+    if (details) {
+      return details
+    }
+    ctor = Object.getPrototypeOf(ctor)
   }
-  return pikkuState(null, 'misc', 'errors').get(error)
+
+  const name = (error as any)?.constructor?.name
+  return name
+    ? Array.from(errors.entries()).find(([e]) => e.name === name)?.[1]
+    : undefined
 }

package/src/errors/error.test.ts

@@ -115,7 +115,6 @@ describe('getErrorResponse', () => {
     const customError = new CustomError()
     const customErrorDetails = { status: 400, message: 'Custom Error' }
 
-    // Add the custom error to the apiErrors map
     addError(CustomError, customErrorDetails)
 
     const response = getErrorResponse(customError)
@@ -195,3 +194,33 @@ describe('all built-in error classes', () => {
     })
   }
 })
+
+describe('getErrorResponse resolution order', () => {
+  test('a subclass of a registered error inherits its registered status', () => {
+    class TenantNotFoundError extends NotFoundError {}
+    const expected = getErrorResponse(new NotFoundError())
+    assert.deepStrictEqual(getErrorResponse(new TenantNotFoundError()), expected)
+  })
+
+  test('an unregistered, non-colliding error class resolves to undefined', () => {
+    class TotallyUnknownError extends Error {}
+    assert.strictEqual(getErrorResponse(new TotallyUnknownError()), undefined)
+  })
+
+  test('name matching is a deliberate fallback for duplicate package copies', () => {
+    const Shadow = class NotFoundError extends Error {}
+    assert.deepStrictEqual(
+      getErrorResponse(new Shadow()),
+      getErrorResponse(new NotFoundError())
+    )
+  })
+
+  test('a registered class is matched by identity, not by scanning names', () => {
+    class DirectlyRegisteredError extends PikkuError {}
+    addError(DirectlyRegisteredError, { status: 418, message: 'teapot' })
+    assert.deepStrictEqual(getErrorResponse(new DirectlyRegisteredError()), {
+      status: 418,
+      message: 'teapot',
+    })
+  })
+})

package/src/errors/errors.ts

@@ -1,6 +1,3 @@
-/**
- * The server cannot or will not process the request due to client error (e.g., malformed request syntax).
- */
 import { addError, PikkuError } from './error-handler.js'
 
 export class InvalidMiddlewareWireError extends PikkuError {}
@@ -27,10 +24,6 @@ addError(LocalEnvironmentOnlyError, {
   message: 'This operation is only available in local development mode',
 })
 
-/**
- * The server cannot or will not process the request due to client error (e.g., malformed request syntax).
- * @group Error
- */
 export class BadRequestError extends PikkuError {}
 addError(BadRequestError, {
   status: 400,
@@ -39,20 +32,8 @@ addError(BadRequestError, {
     'The server cannot or will not process the request due to client error (e.g., malformed request syntax).',
 })
 
-/**
- * Authentication is required and has failed or has not yet been provided.
- * @group Error
- */
 export class UnauthorizedError extends PikkuError {}
-/**
- * More specific error to why it's unauthorized.
- * @group Error
- */
 export class MissingSessionError extends PikkuError {}
-/**
- * More specific error to why it's unauthorized.
- * @group Error
- */
 export class InvalidSessionError extends PikkuError {}
 
 addError(UnauthorizedError, {
@@ -66,10 +47,6 @@ addError(InvalidSessionError, {
   message: 'The session provided is not valid.',
 })
 
-/**
- * Reserved for future use, often related to digital payment or subscription services.
- * @group Error
- */
 export class PaymentRequiredError extends PikkuError {}
 addError(PaymentRequiredError, {
   status: 402,
@@ -77,10 +54,6 @@ addError(PaymentRequiredError, {
     'Reserved for future use, often related to digital payment or subscription services.',
 })
 
-/**
- * The client does not have permission to access the requested resource.
- * @group Error
- */
 export class ForbiddenError extends PikkuError {}
 addError(ForbiddenError, {
   status: 403,
@@ -88,11 +61,6 @@ addError(ForbiddenError, {
     'The client does not have permission to access the requested resource.',
 })
 
-/**
- * A required credential is missing. The payload contains metadata
- * about the credential so the client can initiate a connect flow.
- * @group Error
- */
 export class MissingCredentialError extends PikkuError {
   public payload: {
     error: 'missing_credential'
@@ -120,11 +88,6 @@ addError(MissingCredentialError, {
   message: 'A required credential is not configured.',
 })
 
-/**
- * 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 class MissingScopeError extends PikkuError {
   public payload: {
     error: 'missing_scope'
@@ -144,20 +107,12 @@ addError(MissingScopeError, {
   message: 'The session does not hold a scope required by this function.',
 })
 
-/**
- * The session is readonly and cannot access a non-readonly function.
- * @group Error
- */
 export class ReadonlySessionError extends PikkuError {}
 addError(ReadonlySessionError, {
   status: 403,
   message: 'The session is readonly and cannot access this function.',
 })
 
-/**
- * The request was made from an origin that is not permitted to access this resource.
- * @group Error
- */
 export class InvalidOriginError extends PikkuError {}
 addError(InvalidOriginError, {
   status: 403,
@@ -165,25 +120,13 @@ addError(InvalidOriginError, {
     'The request was made from an origin that is not permitted to access this resource.',
 })
 
-/**
- * The server cannot find the requested resource.
- * @group Error
- */
 export class NotFoundError extends PikkuError {}
-/**
- * The server cannot find the requested route.
- * @group Error
- */
 addError(NotFoundError, {
   status: 404,
   mcpCode: -32601,
   message: 'The server cannot find the requested resource.',
 })
 
-/**
- * The request method is known by the server but is not supported by the resource.
- * @group Error
- */
 export class MethodNotAllowedError extends PikkuError {}
 addError(MethodNotAllowedError, {
   status: 405,
@@ -191,10 +134,6 @@ addError(MethodNotAllowedError, {
     'The request method is known by the server but is not supported by the resource.',
 })
 
-/**
- * The requested resource cannot produce a response matching the list of acceptable values in the request's headers.
- * @group Error
- */
 export class NotAcceptableError extends PikkuError {}
 addError(NotAcceptableError, {
   status: 406,
@@ -202,30 +141,18 @@ addError(NotAcceptableError, {
     "The requested resource cannot produce a response matching the list of acceptable values in the request's headers.",
 })
 
-/**
- * The client must authenticate itself to get the requested response.
- * @group Error
- */
 export class ProxyAuthenticationRequiredError extends PikkuError {}
 addError(ProxyAuthenticationRequiredError, {
   status: 407,
   message: 'The client must authenticate itself to get the requested response.',
 })
 
-/**
- * The server request expired
- * @group Error
- */
 export class RequestTimeoutError extends PikkuError {}
 addError(RequestTimeoutError, {
   status: 408,
   message: 'The request timeout has expired.',
 })
 
-/**
- * The request could not be completed due to a conflict with the current state of the target resource.
- * @group Error
- */
 export class ConflictError extends PikkuError {}
 addError(ConflictError, {
   status: 409,
@@ -233,10 +160,6 @@ addError(ConflictError, {
     'The request could not be completed due to a conflict with the current state of the target resource.',
 })
 
-/**
- * The resource that is being accessed is no longer available and will not be available again.
- * @group Error
- */
 export class GoneError extends PikkuError {}
 addError(GoneError, {
   status: 410,
@@ -244,10 +167,6 @@ addError(GoneError, {
     'The resource that is being accessed is no longer available and will not be available again.',
 })
 
-/**
- * The request did not specify the length of its content, which is required by the requested resource.
- * @group Error
- */
 export class LengthRequiredError extends PikkuError {}
 addError(LengthRequiredError, {
   status: 411,
@@ -255,10 +174,6 @@ addError(LengthRequiredError, {
     'The request did not specify the length of its content, which is required by the requested resource.',
 })
 
-/**
- * The server does not meet one of the preconditions that the requester put on the request.
- * @group Error
- */
 export class PreconditionFailedError extends PikkuError {}
 addError(PreconditionFailedError, {
   status: 412,
@@ -266,10 +181,6 @@ addError(PreconditionFailedError, {
     'The server does not meet one of the preconditions that the requester put on the request.',
 })
 
-/**
- * The request is larger than the server is willing or able to process.
- * @group Error
- */
 export class PayloadTooLargeError extends PikkuError {}
 addError(PayloadTooLargeError, {
   status: 413,
@@ -277,10 +188,6 @@ addError(PayloadTooLargeError, {
     'The request is larger than the server is willing or able to process.',
 })
 
-/**
- * The URI requested by the client is longer than the server is willing to interpret.
- * @group Error
- */
 export class URITooLongError extends PikkuError {}
 addError(URITooLongError, {
   status: 414,
@@ -288,10 +195,6 @@ addError(URITooLongError, {
     'The URI requested by the client is longer than the server is willing to interpret.',
 })
 
-/**
- * The server does not support the media format of the requested data.
- * @group Error
- */
 export class UnsupportedMediaTypeError extends PikkuError {}
 addError(UnsupportedMediaTypeError, {
   status: 415,
@@ -299,10 +202,6 @@ addError(UnsupportedMediaTypeError, {
     'The server does not support the media format of the requested data.',
 })
 
-/**
- * The client has asked for a portion of the file, but the server cannot supply that portion.
- * @group Error
- */
 export class RangeNotSatisfiableError extends PikkuError {}
 addError(RangeNotSatisfiableError, {
   status: 416,
@@ -310,10 +209,6 @@ addError(RangeNotSatisfiableError, {
     'The client has asked for a portion of the file, but the server cannot supply that portion.',
 })
 
-/**
- * The server cannot meet the requirements of the Expect request-header field.
- * @group Error
- */
 export class ExpectationFailedError extends PikkuError {}
 addError(ExpectationFailedError, {
   status: 417,
@@ -321,10 +216,6 @@ addError(ExpectationFailedError, {
     'The server cannot meet the requirements of the Expect request-header field.',
 })
 
-/**
- * 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 class UnprocessableContentError extends PikkuError {}
 addError(UnprocessableContentError, {
   status: 422,
@@ -332,10 +223,6 @@ addError(UnprocessableContentError, {
     '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..',
 })
 
-/**
- * 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 class LockedError extends PikkuError {}
 addError(LockedError, {
   status: 423,
@@ -343,10 +230,6 @@ addError(LockedError, {
     "The resource is locked, meaning it can't be accessed. Its response body should contain information in WebDAV's XML format.",
 })
 
-/**
- * The user has sent too many requests in a given amount of time ("rate limiting").
- * @group Error
- */
 export class TooManyRequestsError extends PikkuError {}
 addError(TooManyRequestsError, {
   status: 429,
@@ -354,10 +237,6 @@ addError(TooManyRequestsError, {
     'The user has sent too many requests in a given amount of time ("rate limiting").',
 })
 
-/**
- * A generic error message, given when no more specific message is suitable.
- * @group Error
- */
 export class InternalServerError extends PikkuError {}
 addError(InternalServerError, {
   status: 500,
@@ -365,10 +244,6 @@ addError(InternalServerError, {
     'A generic error message, given when no more specific message is suitable.',
 })
 
-/**
- * The server does not recognize the request method and cannot support it.
- * @group Error
- */
 export class NotImplementedError extends PikkuError {}
 addError(NotImplementedError, {
   status: 501,
@@ -376,10 +251,6 @@ addError(NotImplementedError, {
     'The server does not recognize the request method and cannot support it.',
 })
 
-/**
- * The server was acting as a gateway or proxy and received an invalid response from the upstream server.
- * @group Error
- */
 export class BadGatewayError extends PikkuError {}
 addError(BadGatewayError, {
   status: 502,
@@ -387,20 +258,12 @@ addError(BadGatewayError, {
     'The server was acting as a gateway or proxy and received an invalid response from the upstream server.',
 })
 
-/**
- * The server is currently unavailable (overloaded or down).
- * @group Error
- */
 export class ServiceUnavailableError extends PikkuError {}
 addError(ServiceUnavailableError, {
   status: 503,
   message: 'The server is currently unavailable (overloaded or down).',
 })
 
-/**
- * The server was acting as a gateway or proxy and did not receive a timely response from the upstream server.
- * @group Error
- */
 export class GatewayTimeoutError extends PikkuError {}
 addError(GatewayTimeoutError, {
   status: 504,
@@ -408,10 +271,6 @@ addError(GatewayTimeoutError, {
     'The server was acting as a gateway or proxy and did not receive a timely response from the upstream server.',
 })
 
-/**
- * The server does not support the HTTP protocol version used in the request.
- * @group Error
- */
 export class HTTPVersionNotSupportedError extends PikkuError {}
 addError(HTTPVersionNotSupportedError, {
   status: 505,
@@ -419,10 +278,6 @@ addError(HTTPVersionNotSupportedError, {
     'The server does not support the HTTP protocol version used in the request.',
 })
 
-/**
- * The server took too long to complete the request, reaching the maximum compute time allowed.
- * @group Error
- */
 export class MaxComputeTimeReachedError extends PikkuError {}
 addError(MaxComputeTimeReachedError, {
   status: 524,
@@ -430,10 +285,6 @@ addError(MaxComputeTimeReachedError, {
     'The server took too long to complete the request, reaching the maximum compute time allowed.',
 })
 
-/**
- * A required schema was not found during validation.
- * @group Error
- */
 export class MissingSchemaError extends PikkuError {}
 addError(MissingSchemaError, {
   status: 500,
@@ -441,10 +292,18 @@ addError(MissingSchemaError, {
     'A required schema was not found. Ensure schema generation has been run.',
 })
 
-/**
- * An AI provider has not been configured. Set up an AI provider (e.g. OpenAI, Anthropic) to use agent features.
- * @group Error
- */
+export class WeakKeyMaterialError extends PikkuError {
+  constructor(name: string, minimumLength: number, actualLength: number) {
+    super(
+      `${name} must be at least ${minimumLength} characters of high-entropy key material, got ${actualLength}. Generate one with \`openssl rand -base64 32\` and redeploy every service that shares it.`
+    )
+  }
+}
+addError(WeakKeyMaterialError, {
+  status: 500,
+  message: 'A configured secret does not carry enough entropy to be used.',
+})
+
 export class AIProviderNotConfiguredError extends PikkuError {
   constructor() {
     super(
@@ -458,10 +317,6 @@ addError(AIProviderNotConfiguredError, {
     'No AI provider configured. Please set up an AI provider (e.g. OpenAI, Anthropic) and provide a valid API key to use this agent.',
 })
 
-/**
- * The AI provider API key is missing or invalid.
- * @group Error
- */
 export class AIProviderAuthError extends PikkuError {
   constructor(message?: string) {
     super(
@@ -475,3 +330,64 @@ addError(AIProviderAuthError, {
   message:
     'AI provider API key is missing or invalid. Please check your API key configuration.',
 })
+
+/**
+ * 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 class SystemRoleImmutableError extends PikkuError {
+  public payload: {
+    error: 'system_role_immutable'
+    role: string
+    operation: string
+  }
+
+  constructor(role: string, operation: string) {
+    super(
+      `Cannot ${operation} '${role}': it is a system role, declared in code with defineSystemRole. ` +
+        `Edit the declaration, or create a separate role in the console.`
+    )
+    this.payload = {
+      error: 'system_role_immutable',
+      role,
+      operation,
+    }
+  }
+}
+addError(SystemRoleImmutableError, {
+  status: 409,
+  message: 'This role is declared in code and cannot be changed here.',
+})
+
+/**
+ * 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 class SystemRoleShadowedError extends PikkuError {
+  public payload: {
+    error: 'system_role_shadowed'
+    role: string
+  }
+
+  constructor(role: string) {
+    super(
+      `Cannot create role '${role}': a system role of that name is declared in code.`
+    )
+    this.payload = {
+      error: 'system_role_shadowed',
+      role,
+    }
+  }
+}
+addError(SystemRoleShadowedError, {
+  status: 409,
+  message: 'A system role of that name is already declared in code.',
+})