@pikku/core 0.12.111 → 0.12.112

package/CHANGELOG.md

@@ -1,3 +1,16 @@
+## 0.12.112
+
+### Patch Changes
+
+- 02eeffb: fix: hot reload reads the changed source instead of a leftover compiled copy
+
+  `pikku dev` announced `Hot-reloaded: <fn>` and kept serving the previous
+  implementation whenever a `.js` from an earlier `tsc`, `pikku dist` or bundler
+  run sat beside the edited `.ts` — the reloader preferred that file, and dev
+  never rebuilds it. The changed source is now what runs, and the module runner
+  resolves and compiles the project's own TypeScript dependencies so a helper
+  edited alongside its caller reloads with it.
+
 ## 0.12.111
 
 ### Patch Changes

package/dist/dev/hot-reload.d.ts

@@ -3,7 +3,6 @@ export { reloadGeneratedMeta, reconcileAddonRegistry } from './reload-meta.js';
 interface PikkuDevReloaderOptions {
     srcDirectories: string[];
     logger: Logger;
-    pikkuDir?: string;
 }
 export interface PikkuDevReloaderHandle {
     close: () => void;

package/dist/dev/hot-reload.js

@@ -1,5 +1,4 @@
 import { watch } from 'node:fs';
-import { stat } from 'node:fs/promises';
 import { basename, join, resolve, relative } from 'node:path';
 import { pikkuState } from '../pikku-state.js';
 import { clearMiddlewareCache } from '../middleware-runner.js';
@@ -14,24 +13,6 @@ const isFunctionConfig = (value) => {
         'func' in value &&
         typeof value.func === 'function');
 };
-const findCompiledFile = async (tsFile, srcDir, pikkuDir) => {
-    const rel = relative(srcDir, tsFile).replace(/\.ts$/, '.js');
-    const candidates = [
-        join(pikkuDir, 'dist', rel),
-        join(srcDir, rel),
-        tsFile.replace(/\.ts$/, '.js'),
-    ];
-    for (const candidate of candidates) {
-        try {
-            await stat(candidate);
-            return candidate;
-        }
-        catch {
-            // not found, try next
-        }
-    }
-    return null;
-};
 const isWatchedTsFile = (filename) => {
     return (filename.endsWith('.ts') &&
         !filename.endsWith('.test.ts') &&
@@ -55,9 +36,8 @@ const reloadFailureReason = (error) => {
     return `  ${error.stack ?? error.message}`;
 };
 export async function pikkuDevReloader(options) {
-    const { srcDirectories, logger, pikkuDir = '.pikku' } = options;
+    const { srcDirectories, logger } = options;
     const absSrcDirs = srcDirectories.map((d) => resolve(d));
-    const absPikkuDir = resolve(pikkuDir);
     const watchers = [];
     const functionsMap = pikkuState(null, 'function', 'functions');
     const moduleRunner = createModuleRunner();
@@ -68,15 +48,14 @@ export async function pikkuDevReloader(options) {
         const srcDir = absSrcDirs.find((d) => changedTsFile.startsWith(d));
         if (!srcDir)
             return;
-        const compiledFile = await findCompiledFile(changedTsFile, srcDir, absPikkuDir);
-        const importPath = compiledFile ?? changedTsFile;
-        const result = await moduleRunner.run(importPath);
+        // knowledge: decisions/internals/hot-reload-reads-the-changed-source-never-a-compiled-copy.md
+        const result = await moduleRunner.run(changedTsFile);
         if (!result.ok) {
             // Keeping the old code leaves the process disagreeing with the file on
             // disk, and the only symptom is stale output from a function that looks
             // correct in the editor — so the reason has to be printed here, where it
             // is still known, rather than left for the developer to reconstruct.
-            logger.error(`Failed to import: ${relative(process.cwd(), importPath)} (keeping old code)\n` +
+            logger.error(`Failed to import: ${relative(process.cwd(), changedTsFile)} (keeping old code)\n` +
                 reloadFailureReason(result.error));
             return;
         }

package/dist/dev/module-runner.js

@@ -1,6 +1,6 @@
-import { readFile } from 'node:fs/promises';
+import { readFileSync, statSync } from 'node:fs';
 import { createRequire } from 'node:module';
-import { dirname, resolve } from 'node:path';
+import { dirname, isAbsolute, join, resolve, sep } from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { compileFunction } from 'node:vm';
 let transformSync;
@@ -18,7 +18,78 @@ const loadTransform = async () => {
  *  is correct, and no amount of re-reading it will reveal that the reloader —
  *  not the file — is what cannot cope. */
 export const isTopLevelAwaitLimitation = (error) => /top-level await/i.test(error.message);
+const TYPESCRIPT_FILE = /\.(m|c)?tsx?$/;
+const isFile = (path) => {
+    try {
+        return statSync(path).isFile();
+    }
+    catch {
+        return false;
+    }
+};
+/** Where a relative specifier's TypeScript source lives, for the specifiers a
+ *  plain `require` cannot resolve. A TS project writes `./sibling.js` for a file
+ *  that only exists as `./sibling.ts`, and a reloaded module is the source, so
+ *  every one of its relative imports arrives in that unresolvable form. */
+const findTypeScriptSource = (specifier, importerDir) => {
+    if (!specifier.startsWith('.') && !isAbsolute(specifier))
+        return undefined;
+    const base = resolve(importerDir, specifier);
+    const withoutJs = base.replace(/\.(m|c)?js$/, '');
+    const candidates = [
+        `${withoutJs}.ts`,
+        `${withoutJs}.tsx`,
+        `${withoutJs}.mts`,
+        `${withoutJs}.cts`,
+        join(base, 'index.ts'),
+        join(base, 'index.tsx'),
+    ];
+    return candidates.find(isFile);
+};
+const isProjectTypeScript = (path) => TYPESCRIPT_FILE.test(path) && !path.includes(`${sep}node_modules${sep}`);
+/** JSX is a syntax esbuild only parses when asked, so a `.tsx` helper handed to
+ *  the `ts` loader fails to compile and the file importing it keeps its old
+ *  code. */
+const loaderFor = (path) => {
+    if (path.endsWith('.tsx'))
+        return 'tsx';
+    if (TYPESCRIPT_FILE.test(path))
+        return 'ts';
+    if (path.endsWith('.jsx'))
+        return 'jsx';
+    return 'js';
+};
+const evaluateModule = (absPath, cache) => {
+    const cached = cache.get(absPath);
+    if (cached)
+        return cached;
+    const source = readFileSync(absPath, 'utf-8');
+    const { code } = transformSync(source, {
+        loader: loaderFor(absPath),
+        format: 'cjs',
+        sourcefile: absPath,
+    });
+    const fn = compileFunction(code, ['require', 'exports', 'module', '__filename', '__dirname'], { filename: absPath });
+    const moduleObj = { exports: {} };
+    // Seeded before evaluation so an import cycle terminates the way CJS's own
+    // cache makes it terminate, and overwritten after because esbuild's `cjs`
+    // emit assigns a fresh `module.exports` on the way out.
+    cache.set(absPath, moduleObj.exports);
+    fn(createRequireForFile(absPath, cache), moduleObj.exports, moduleObj, absPath, dirname(absPath));
+    cache.set(absPath, moduleObj.exports);
+    return moduleObj.exports;
+};
 /** The `require` a reloaded module is run with.
+ *
+ *  Resolution goes through the host first, so every package binds to the
+ *  instance the rest of the process holds and a user file's `wire*` side
+ *  effect mutates live state rather than a private copy.
+ *
+ *  A resolved TypeScript file outside `node_modules` is the project's own
+ *  source, and is compiled here instead of handed back to the host: both hosts
+ *  cache what they load, so a helper edited alongside the function importing it
+ *  would otherwise keep answering with the version loaded at startup — the same
+ *  stale-code-under-a-successful-reload the reloader exists to avoid.
  *
  *  On Bun, `createRequire`'s referrer stops being honoured somewhere in a
  *  long-running process: the same relative specifier that resolves in a fresh
@@ -27,47 +98,55 @@ export const isTopLevelAwaitLimitation = (error) => /top-level await/i.test(erro
  *  is left serving the previous code from an edit that looked applied. Bun's
  *  own resolver still answers correctly when handed the importer's directory
  *  outright, so the specifier is resolved to an absolute path first and the
- *  referrer never has to survive the trip. Anything Bun's resolver declines —
- *  builtins among them — falls through to `require` unchanged.
+ *  referrer never has to survive the trip.
+ *
+ *  What neither host resolves is a relative `./sibling.js` whose only file on
+ *  disk is `./sibling.ts` — node's `require` has no `.js → .ts` rewrite, and
+ *  the reloader hands it source. Those, and only those, are compiled here.
  */
-const createRequireForFile = (absPath) => {
+const createRequireForFile = (absPath, cache) => {
     const base = createRequire(pathToFileURL(absPath));
     const bun = globalThis.Bun;
-    if (!bun)
-        return base;
     const importerDir = dirname(absPath);
-    const resolveThroughBun = (specifier) => {
+    const resolveThroughHost = (specifier) => {
+        if (bun) {
+            try {
+                return bun.resolveSync(specifier, importerDir);
+            }
+            catch {
+                return undefined;
+            }
+        }
         try {
-            return bun.resolveSync(specifier, importerDir);
+            return base.resolve(specifier);
         }
         catch {
-            return specifier;
+            return undefined;
         }
     };
     // Only resolution is delegated; the require itself stays outside the guard so
     // a module that throws while evaluating reports its own error rather than
     // being retried under a second specifier.
-    const bunRequire = ((specifier) => base(resolveThroughBun(specifier)));
-    return Object.assign(bunRequire, base);
+    const loadingRequire = ((specifier) => {
+        const resolved = resolveThroughHost(specifier) ??
+            findTypeScriptSource(specifier, importerDir);
+        if (!resolved)
+            return base(specifier);
+        if (isProjectTypeScript(resolved))
+            return evaluateModule(resolved, cache);
+        return base(resolved);
+    });
+    return Object.assign(loadingRequire, base);
 };
 export const createModuleRunner = () => {
     const registry = new Map();
     const run = async (filePath) => {
         const absPath = resolve(filePath);
         try {
-            const transform = await loadTransform();
-            const source = await readFile(absPath, 'utf-8');
-            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 = createRequireForFile(absPath);
-            const moduleObj = { exports: {} };
-            fn(require, moduleObj.exports, moduleObj, absPath, dirname(absPath));
-            registry.set(absPath, moduleObj.exports);
-            return { ok: true, exports: moduleObj.exports };
+            await loadTransform();
+            const exports = evaluateModule(absPath, new Map());
+            registry.set(absPath, exports);
+            return { ok: true, exports };
         }
         catch (thrown) {
             // A bad edit, or the one known limitation: a file using top-level

package/knowledge/decisions/internals/a-reset-suite-makes-the-dev-seed-the-fixture.md

@@ -0,0 +1,50 @@
+---
+type: decision
+title: With scenarios.reset on, the dev seed is the fixture every assertion is written against
+description: The rollback restores the database as the suite found it, so seed rows are the shared baseline — which makes an absolute date in the seed a test that expires
+tags: cli, scenarios
+---
+
+# A reset suite makes the dev seed the fixture
+
+`scenarios.reset` takes a copy of every table when the suite starts and restores
+that copy between scenarios. It is a snapshot-and-restore, not a
+truncate-and-reseed: nothing replays the seed file, and nothing regenerates its
+rows.
+
+Two things follow, and both are easy to get wrong.
+
+**The seed is the fixture.** Before a reset was available, a project usually had
+a hand-rolled reset RPC that wiped and re-created the handful of rows its
+scenarios touched. That RPC was the fixture and the seed was scenery. With the
+rollback on, the whole seed is in scope — every booking, invoice and event a
+developer put there for their own convenience is now a row some scenario can
+count. Assertions written as counts against the old narrow fixture go wrong the
+moment the baseline widens.
+
+**A date literal in the seed expires.** A seed is applied once, and from then on
+the restore keeps handing back the same rows. Write `'2026-03-14'` and the
+fixture is correct on the day it was written and quietly wrong a month later —
+the booking that was supposed to be upcoming is in the past, and the scenario
+that asserts on it fails for a reason that has nothing to do with the code. Seed
+dates belong relative to the moment the seed is applied:
+
+```sql
+INSERT INTO booking (id, starts_at, ends_at) VALUES
+  ('b_upcoming', date('now', '+200 days'), date('now', '+207 days')),
+  ('b_ended',    date('now', '-8 days'),   date('now', '-1 days'));
+```
+
+`date('now', ...)` in sqlite, `now() + interval '200 days'` in postgres. Pick the
+offsets so each row sits unambiguously on the side of whatever boundary the
+scenarios test, rather than a day away from it.
+
+There is a third limit worth stating plainly: the baseline is the database _as
+the suite starts_, so it is not a pristine seed. Run N+1 inherits whatever run N
+left behind. A value that must be unique in the database — an invoice number, a
+reference code — has to be scoped to the run, not hard-coded, or the second run
+collides with the first.
+
+**What this rules out:** treating the reset as "the suite starts from the seed
+every time". It starts from wherever the database was, and keeps returning
+there.

package/knowledge/decisions/internals/hot-reload-reads-the-changed-source-never-a-compiled-copy.md

@@ -0,0 +1,38 @@
+---
+type: decision
+title: Hot reload reads the changed source, never a compiled copy of it
+description: A leftover .js beside a .ts made the reloader announce a reload while re-registering the previous implementation; project TypeScript is now compiled by the reloader itself
+tags: core, dev
+---
+
+# Hot reload reads the changed source, never a compiled copy of it
+
+The reloader watches `.ts` files and runs the file that changed. It used to
+look for a compiled `.js` first — `<outDir>/dist/<rel>.js`, then the sibling
+`<file>.js` — and import the source only when neither existed.
+
+`pikku dev` compiles nothing. Every one of those `.js` files is a leftover from
+an earlier `tsc`, `pikku dist` or bundler run, so reading one re-registered the
+implementation the developer had just replaced and logged `Hot-reloaded: <fn>`
+over the top of it. The log line reads as confirmation, so the change looks
+applied and wrong rather than unapplied — which is the expensive way round
+(#1721).
+
+The lookup was a leftover of the first implementation, which imported raw file
+content through a `data:` URL and genuinely could not handle TypeScript. The
+module runner has transpiled with esbuild since, so the source was loadable all
+along and the compiled candidates could only ever supply stale code.
+
+Loading the source means the reloader also owns resolution. `require('./x.js')`
+where only `x.ts` exists is what every relative import in a TypeScript project
+looks like, and node's `require` has no `.js → .ts` rewrite. Resolution goes
+through the host first — so packages bind to the instance the rest of the
+process holds and `wire*` side effects mutate live state — and a resolved
+TypeScript file outside `node_modules` is then compiled by the reloader rather
+than handed back, because both node and Bun cache what they load and a helper
+edited alongside its caller would otherwise keep answering with the copy loaded
+at startup. That cache is scoped to a single reload for the same reason.
+
+**What this rules out:** reintroducing a compiled-output lookup as a
+"performance" shortcut, and letting the host load project `.ts` dependencies so
+reloads inherit its module cache.

package/knowledge/decisions/internals/index.md

@@ -12,6 +12,7 @@ caller is entitled to assume.
 <!-- pikku:knowledge-index -->
 
 - [A non-streaming agent run registers with aiRunState on the same terms as a streaming one](a-non-streaming-agent-run-registers-with-airunstate-too.md) — Otherwise interruptAIAgent finds the run, passes the ownership check, then cannot stop it — and reports that as if the run were on another host
+- [With scenarios.reset on, the dev seed is the fixture every assertion is written against](a-reset-suite-makes-the-dev-seed-the-fixture.md) — The rollback restores the database as the suite found it, so seed rows are the shared baseline — which makes an absolute date in the seed a test that expires
 - [A resumed turn is as interruptible as the first one](a-resumed-agent-turn-is-as-interruptible-as-the-first.md) — It is the same person listening to the same voice, and after an approval it is where most of the reply actually gets spoken
 - [A scenario step's prose template is offered to a virtual user unfilled](a-scenario-step-template-is-offered-unfilled.md) — A reporter fills placeholders from a run that happened; there is no run yet, and the filled form would answer the question the user is there to answer
 - [A secret that fails to decrypt fails the whole read](a-secret-that-fails-to-decrypt-fails-the-whole-read.md) — getSecrets throws naming the key and its key_version rather than omitting the row, because a silent omission surfaces as an unrelated failure much later
@@ -73,6 +74,7 @@ caller is entitled to assume.
 - [Gateway webhook challenges echo bytes not JSON](gateway-webhook-challenges-echo-bytes-not-json.md) — String verification challenges are returned raw with returnsJSON false, because platforms byte-compare the echo and JSON quoting fails the handshake
 - [Gateway wiring is a meta-wiring over HTTP and channels](gateway-wiring-is-a-meta-wiring-over-http-and-channels.md) — wireGateway writes handler implementations into the HTTP and channel state directly while the inspector compiles the corresponding meta, so runtime registration deliberately writes no meta
 - [Generated src paths in pikku meta are absolute](generated-src-paths-in-pikku-meta-are-absolute.md) — emailsMeta.src is resolved by the CLI at generation time, so reading through the project-relative helpers produces a wrong compound path
+- [Hot reload reads the changed source, never a compiled copy of it](hot-reload-reads-the-changed-source-never-a-compiled-copy.md) — A leftover .js beside a .ts made the reloader announce a reload while re-registering the previous implementation; project TypeScript is now compiled by the reloader itself
 - [Hot reload writes into the function map captured at startup, not pikkuState's current one](hot-reload-writes-into-the-function-map-captured-at-startup.md) — A dev-server watcher may have swapped in a codegen-scoped map whose writes are discarded on restore, and schemas are deliberately left alone
 - [HTTP request bodies are read once and shared between consumers](http-request-bodies-are-read-once-and-shared.md) — The fetch request wrapper memoises the single-use body and builds web Requests lazily, at the cost of holding the whole body in memory
 - [HTTP route groups cascade config in a fixed, per-field order](http-route-groups-cascade-config-in-a-fixed-order.md) — basePath concatenates, tags and middleware merge outward-in, auth is overridden by the innermost group

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/core",
-  "version": "0.12.111",
+  "version": "0.12.112",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/pikkujs/pikku.git",