@pikku/core 0.12.63 → 0.12.64

package/src/dev/module-runner.ts

@@ -0,0 +1,103 @@
+import { readFile } from 'node:fs/promises'
+import { createRequire } from 'node:module'
+import { dirname, resolve } from 'node:path'
+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).
+  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: (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
+}
+
+export const createModuleRunner = (): PikkuModuleRunner => {
+  const registry = new Map<string, Record<string, unknown>>()
+
+  const run = async (
+    filePath: string
+  ): Promise<Record<string, unknown> | null> => {
+    const absPath = resolve(filePath)
+    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',
+        sourcefile: absPath,
+      })
+
+      const fn = compileFunction(
+        code,
+        ['require', 'exports', 'module', '__filename', '__dirname'],
+        { filename: absPath }
+      )
+
+      const require = createRequire(pathToFileURL(absPath))
+      const moduleObj: { exports: Record<string, unknown> } = { exports: {} }
+      fn(require, moduleObj.exports, moduleObj, absPath, dirname(absPath))
+
+      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.
+      return null
+    }
+  }
+
+  return {
+    run,
+    evict: (filePath: string) => {
+      registry.delete(resolve(filePath))
+    },
+    clear: () => {
+      registry.clear()
+    },
+    get size() {
+      return registry.size
+    },
+  }
+}

package/src/dev/reload-meta.test.ts

@@ -6,7 +6,8 @@ import { tmpdir } from 'node:os'
 
 import { pikkuState, resetPikkuState } from '../pikku-state.js'
 import { getSchema } from '../schema.js'
-import { reloadGeneratedMeta } from './reload-meta.js'
+import { wireAddon } from '../wirings/rpc/wire-addon.js'
+import { reloadGeneratedMeta, reconcileAddonRegistry } from './reload-meta.js'
 
 const createMockLogger = () => {
   const logs: Array<{ level: string; message: string }> = []
@@ -96,7 +97,9 @@ describe('reloadGeneratedMeta', { concurrency: false }, () => {
     )
     await writeFile(
       join(tmpDir, 'queue/pikku-queue-workers-wirings-meta.gen.json'),
-      JSON.stringify({ userQueue: { pikkuFuncId: 'userFunc', name: 'userQueue' } })
+      JSON.stringify({
+        userQueue: { pikkuFuncId: 'userFunc', name: 'userQueue' },
+      })
     )
 
     await reloadGeneratedMeta({
@@ -152,3 +155,29 @@ describe('reloadGeneratedMeta', { concurrency: false }, () => {
     assert.deepEqual(errors, [])
   })
 })
+
+describe('reconcileAddonRegistry', { concurrency: false }, () => {
+  beforeEach(() => resetPikkuState())
+
+  test('drops addons the fresh generation no longer declares', () => {
+    wireAddon({ name: 'gmail', package: '@pikku/addon-gmail' })
+    wireAddon({ name: 'mandrill-e2e', package: '@pikku/addon-mandrill' })
+
+    // gmail is still wired in source; mandrill-e2e's *.addon.ts was deleted.
+    reconcileAddonRegistry(['gmail'])
+
+    const addons = pikkuState(null, 'addons', 'packages')
+    assert.ok(addons.has('gmail'), 'still-declared addon is kept')
+    assert.ok(!addons.has('mandrill-e2e'), 'deleted addon is pruned')
+  })
+
+  test('keeps every addon when all are still declared', () => {
+    wireAddon({ name: 'gmail', package: '@pikku/addon-gmail' })
+    wireAddon({ name: 'mailgun', package: '@pikku/addon-mailgun' })
+
+    reconcileAddonRegistry(['gmail', 'mailgun'])
+
+    const addons = pikkuState(null, 'addons', 'packages')
+    assert.equal(addons.size, 2)
+  })
+})

package/src/dev/reload-meta.ts

@@ -136,3 +136,29 @@ 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.
+ *
+ * `declaredNamespaces` is the set of `wireAddon` names from the just-regenerated
+ * inspection (`inspectorState.rpc.wireAddonDeclarations.keys()`).
+ */
+export function reconcileAddonRegistry(
+  declaredNamespaces: Iterable<string>,
+  logger?: Logger
+): void {
+  const declared = new Set(declaredNamespaces)
+  const addons = pikkuState(null, 'addons', 'packages')
+  for (const namespace of [...addons.keys()]) {
+    if (!declared.has(namespace)) {
+      addons.delete(namespace)
+      logger?.info(`• Removed unwired addon "${namespace}"`)
+    }
+  }
+}

package/src/errors/errors.ts

@@ -120,6 +120,30 @@ 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'
+    scope: string
+  }
+
+  constructor(scope: string) {
+    super(`Missing required scope: ${scope}`)
+    this.payload = {
+      error: 'missing_scope',
+      scope,
+    }
+  }
+}
+addError(MissingScopeError, {
+  status: 403,
+  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