@pikku/core 0.12.72 → 0.12.77

package/src/dev/module-runner.ts

@@ -5,46 +5,26 @@ import { pathToFileURL } from 'node:url'
 import { compileFunction } from 'node:vm'
 import type { transformSync as EsbuildTransformSync } from 'esbuild'
 
-// Evictable module runner for hot-reload.
-//
-// Re-importing a changed user file through the native ESM loader (a fresh
-// `data:` URL on Node, a fresh temp-file path on Bun) is unbounded: the loader
-// keeps a `Map<url, moduleRecord>` for the realm lifetime with no eviction API,
-// so every reload permanently leaks a module record and the dev server
-// eventually OOMs (worse on Bun). Instead we own the registry: transpile the
-// source to CJS (esbuild), run it as a plain function via `vm.compileFunction`
-// — which produces a garbage-collectable function rather than a permanent
-// loader entry — and store the resulting exports under a STABLE path key. A
-// reload overwrites that one slot, so the previous module becomes unreachable
-// and is collected. `import`s inside the user file are delegated to
-// `createRequire`, whose resolution matches the native loader AND returns the
-// same live singletons (Node/Bun share the require/import module cache), so
-// top-level side effects (wireHTTP et al) mutate the same running services.
 type EsbuildTransform = typeof EsbuildTransformSync
 
 let transformSync: EsbuildTransform | undefined
 
 const loadTransform = async (): Promise<EsbuildTransform> => {
   if (transformSync) return transformSync
-  // esbuild is a dev-only dependency, hoisted from @pikku/cli at runtime — the
-  // same lazy pattern the reloader previously used for tsx. It is never loaded
-  // in production runtimes (the `./dev` export is dev-only).
+  // esbuild is a dev-only dependency hoisted from @pikku/cli at runtime; the
+  // `./dev` export is dev-only so it is never loaded in production runtimes.
   const esbuild = await import('esbuild')
   transformSync = esbuild.transformSync
   return transformSync
 }
 
 export interface PikkuModuleRunner {
-  /** Run a user module by absolute path, returning its exports. Repeated runs
-   *  of the same path overwrite a single registry slot (the previous module is
-   *  collected). Returns `null` if transpile/compile/evaluation fails, so the
-   *  caller can keep the previously-loaded code. */
+  /** Run a user module by absolute path. Repeated runs of one path overwrite a
+   *  single registry slot. Returns `null` on failure so the caller can keep the
+   *  previously-loaded code. */
   run: (absPath: string) => Promise<Record<string, unknown> | null>
-  /** Drop a single module from the registry. */
   evict: (absPath: string) => void
-  /** Drop every module from the registry. */
   clear: () => void
-  /** Number of modules currently held. */
   readonly size: number
 }
 
@@ -58,10 +38,6 @@ export const createModuleRunner = (): PikkuModuleRunner => {
     try {
       const transform = await loadTransform()
       const source = await readFile(absPath, 'utf-8')
-      // No sourcemap: an inline sourcemap embeds a base64 copy of the source
-      // that the engine retains per compile, reintroducing linear growth on
-      // Node — the exact leak this runner exists to remove. `filename` still
-      // anchors stack traces to the user file.
       const { code } = transform(source, {
         loader: absPath.endsWith('.ts') ? 'ts' : 'js',
         format: 'cjs',
@@ -81,9 +57,8 @@ export const createModuleRunner = (): PikkuModuleRunner => {
       registry.set(absPath, moduleObj.exports)
       return moduleObj.exports
     } catch {
-      // Transpile/compile/evaluate failure (a bad edit, or the one known
-      // limitation — a file using top-level `await`, which can't be emitted in
-      // `cjs` form). Return null so the caller keeps the previously-loaded code.
+      // A bad edit, or the one known limitation: a file using top-level
+      // `await`, which cannot be emitted in `cjs` form.
       return null
     }
   }

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',
+    })
+  })
+})