@pylonsync/functions 0.3.261 → 0.3.263

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pylonsync/functions",
-  "version": "0.3.261",
+  "version": "0.3.263",
   "description": "TypeScript function runtime for pylon — defines server-side queries, mutations, and actions.",
   "type": "module",
   "main": "src/index.ts",

package/src/runtime-db.test.ts

@@ -0,0 +1,86 @@
+/**
+ * Regression tests for the ctx.db builder surfaces (runtime.ts).
+ *
+ * Guards the contract the types now promise (types.ts made `unsafe`
+ * REQUIRED on the top-level db and absent on the unsafe surface):
+ *
+ *   1. `db.unsafe` always exists, with the full op surface.
+ *   2. `db.unsafe.unsafe` does NOT exist (no chaining — it would be a
+ *      runtime undefined that the old optional type silently allowed).
+ *   3. Plain ops emit `unsafe_op: false`; `unsafe.*` ops emit
+ *      `unsafe_op: true` — the flag the Rust policy gate keys on.
+ *
+ * runtime.ts runs main() on import (it IS the bun runner entrypoint),
+ * so the builders are exercised in a child process: we feed it a
+ * script over a kept-open stdin pipe and read the NDJSON protocol
+ * frames it writes to stdout.
+ */
+import { expect, test } from "bun:test";
+import { mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+const RUNTIME = join(import.meta.dir, "runtime.ts");
+
+const SCRIPT = `
+import { buildDbReader, buildDbWriter } from ${JSON.stringify(RUNTIME)};
+
+const reader = buildDbReader("c_r");
+const writer = buildDbWriter("c_w");
+
+// Structural facts ride stderr (fenceStdout reserves stdout for frames).
+console.error("STRUCT " + JSON.stringify({
+  readerUnsafe: typeof reader.unsafe.get === "function",
+  writerUnsafeWrites: typeof (writer.unsafe as any).update === "function",
+  noReaderChain: (reader.unsafe as any).unsafe === undefined,
+  noWriterChain: (writer.unsafe as any).unsafe === undefined,
+}));
+
+// Fire one op per surface — no host replies, so don't await; the
+// emitted frames on stdout are the assertion target.
+reader.get("Todo", "r1").catch(() => {});
+reader.unsafe.get("Todo", "r2").catch(() => {});
+writer.update("Todo", "w1", { a: 1 }).catch(() => {});
+writer.unsafe.update("Todo", "w2", { a: 2 }).catch(() => {});
+
+setTimeout(() => process.exit(0), 300);
+`;
+
+test("db builders: required unsafe surface, no chaining, unsafe_op flag routing", async () => {
+  const dir = mkdtempSync(join(tmpdir(), "pylon-fn-db-"));
+  const scriptPath = join(dir, "probe.ts");
+  writeFileSync(scriptPath, SCRIPT);
+
+  const proc = Bun.spawn(["bun", scriptPath], {
+    stdin: "pipe", // keep main()'s readerLoop alive until the probe exits itself
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+  const [stdout, stderr] = await Promise.all([
+    new Response(proc.stdout).text(),
+    new Response(proc.stderr).text(),
+    proc.exited,
+  ]);
+
+  // 1+2: structure as reported from inside the child.
+  const structLine = stderr.split("\n").find((l) => l.includes("STRUCT "));
+  expect(structLine).toBeDefined();
+  const struct = JSON.parse(structLine!.slice(structLine!.indexOf("STRUCT ") + 7));
+  expect(struct.readerUnsafe).toBe(true);
+  expect(struct.writerUnsafeWrites).toBe(true);
+  expect(struct.noReaderChain).toBe(true);
+  expect(struct.noWriterChain).toBe(true);
+
+  // 3: every emitted db frame carries the right unsafe_op flag.
+  const frames = stdout
+    .split("\n")
+    .filter((l) => l.trim().startsWith("{"))
+    .map((l) => JSON.parse(l) as Record<string, unknown>)
+    .filter((f) => f.type === "db");
+  const byId = (id: string) => frames.find((f) => f.id === id);
+
+  expect(byId("r1")).toMatchObject({ op: "get", unsafe_op: false });
+  expect(byId("r2")).toMatchObject({ op: "get", unsafe_op: true });
+  expect(byId("w1")).toMatchObject({ op: "update", unsafe_op: false });
+  expect(byId("w2")).toMatchObject({ op: "update", unsafe_op: true });
+});

package/src/runtime.ts

@@ -357,7 +357,11 @@ function rpc(callId: string, msg: Record<string, unknown>): Promise<unknown> {
 // `serverData` read handle that reuses this module's `send` + `pendingRpcs`
 // + reader loop. The render call_id ("r_<n>") correlates DB replies back
 // through the shared pendingRpcs map.
-export function buildDbReader(callId: string, unsafeOp = false): DbReader {
+export function buildDbReader(callId: string): DbReader {
+  return { ...buildReaderOps(callId, false), unsafe: buildReaderOps(callId, true) };
+}
+
+function buildReaderOps(callId: string, unsafeOp: boolean): Omit<DbReader, "unsafe"> {
   // All DB ops use rpcDb so Promise.all over ctx.db reads can run in
   // parallel without colliding on the outer call_id key.
   //
@@ -366,7 +370,7 @@ export function buildDbReader(callId: string, unsafeOp = false): DbReader {
   // caller-aware policy gate (in Phase 2 — see
   // pylon-functions/protocol.rs). Plain ctx.db.* leaves the flag
   // off (the safe default); ctx.db.unsafe.* sets it.
-  const reader: DbReader = {
+  return {
     async get(entity, id) {
       return (await rpcDb(callId, {
         type: "db",
@@ -435,23 +439,26 @@ export function buildDbReader(callId: string, unsafeOp = false): DbReader {
       })) as any;
     },
   };
-  if (!unsafeOp) {
-    (reader as DbReader & { unsafe: DbReader }).unsafe = buildDbReader(
-      callId,
-      true,
-    );
-  }
-  return reader;
 }
 
-export function buildDbWriter(callId: string, unsafeOp = false): DbWriter {
-  // Drop the reader's `unsafe` shortcut before spreading — the
-  // writer needs its own (which we attach below). Without this
-  // strip, `writer.unsafe` would be a DbReader and the type
-  // narrows incorrectly.
-  const { unsafe: _ignored, ...readerOps } = buildDbReader(callId, unsafeOp);
-  const writer: DbWriter = {
-    ...readerOps,
+export function buildDbWriter(callId: string): DbWriter {
+  // Top-level `ctx.db` is the safe path. `ctx.db.unsafe` is the
+  // escape hatch — same surface, every emitted op carries
+  // `unsafe_op: true` so the future caller-aware policy gate
+  // (PYLON_STRICT_FN_POLICIES) skips enforcement. Use sparingly,
+  // with a justifying comment, ideally in code that runs only
+  // from server-internal callers (webhooks, cron sweeps, admin
+  // tools).
+  //
+  // The unsafe surface carries no `.unsafe` of its own — chaining
+  // is a compile error AND a self-reference would loop on JSON
+  // serialization.
+  return { ...buildWriterOps(callId, false), unsafe: buildWriterOps(callId, true) };
+}
+
+function buildWriterOps(callId: string, unsafeOp: boolean): Omit<DbWriter, "unsafe"> {
+  return {
+    ...buildReaderOps(callId, unsafeOp),
     async insert(entity, data) {
       const r = (await rpcDb(callId, {
         type: "db",
@@ -518,23 +525,6 @@ export function buildDbWriter(callId: string, unsafeOp = false): DbWriter {
       });
     },
   };
-  // Top-level `ctx.db` is the safe path. `ctx.db.unsafe` is the
-  // escape hatch — same surface, every emitted op carries
-  // `unsafe_op: true` so the future caller-aware policy gate
-  // (PYLON_STRICT_FN_POLICIES) skips enforcement. Use sparingly,
-  // with a justifying comment, ideally in code that runs only
-  // from server-internal callers (webhooks, cron sweeps, admin
-  // tools).
-  //
-  // Self-reference would create an infinite loop on JSON
-  // serialization; only assign on the writer's `.unsafe` once.
-  if (!unsafeOp) {
-    (writer as DbWriter & { unsafe: DbWriter }).unsafe = buildDbWriter(
-      callId,
-      true,
-    );
-  }
-  return writer;
 }
 
 function buildStream(callId: string): Stream {

package/src/ssr-client-bundler.ts

@@ -38,6 +38,16 @@ type Send = (msg: Record<string, unknown>) => void;
 interface BundleClientMessage {
   type: "bundle_client";
   call_id: string;
+  /**
+   * Project-relative directory holding the route tree
+   * (`<app_dir>/**​/page.tsx`). Defaults to `"app"` when the host
+   * doesn't send it (older hosts, or the default single-`app/`
+   * layout). The full-stack app that namespaces its frontend under a
+   * subdir — e.g. `web/app` via `discoverAppRoutes({appDir:"web/app"})`
+   * — sends the same dir here so the client bundler and the SSR
+   * manifest agree on where the routes live.
+   */
+  app_dir?: string;
 }
 
 interface DiscoveredRoute {
@@ -87,19 +97,22 @@ declare const Bun: {
 };
 
 /**
- * Synchronously walk `app/` under cwd. Returns one entry per
- * discovered page, each carrying its layout chain (root → leaf).
- * Mirrors the discovery logic in @pylonsync/sdk's
- * `discoverAppRoutes` exactly — same sort order, same group-strip,
- * so the in-browser map keys line up with the manifest's component
- * field.
+ * Synchronously walk the route dir (`<appDirRel>` under cwd, e.g.
+ * `app` or `web/app`) and return one entry per discovered page, each
+ * carrying its layout chain (root → leaf). `appDirRel` MUST match the
+ * `appDir` the manifest was built with (`discoverAppRoutes({appDir})`)
+ * so the component paths — `path.relative(cwd, file)` — line up with
+ * the manifest's `component` field byte-for-byte. Mirrors the
+ * discovery logic in @pylonsync/sdk's `discoverAppRoutes` exactly:
+ * same sort order, same group-strip.
  */
 function discoverRoutes(
   fs: any,
   path: any,
   cwd: string,
+  appDirRel: string,
 ): DiscoveredRoute[] {
-  const appDir = path.join(cwd, "app");
+  const appDir = path.join(cwd, appDirRel);
   if (!fs.existsSync(appDir) || !fs.statSync(appDir).isDirectory()) {
     return [];
   }
@@ -290,6 +303,15 @@ function makeNoopResponse() {
 // For a hydrated error boundary (#279), synthesize the reset() the server
 // rendered as a no-op: re-fetch + re-render the current URL (a transient
 // error clears to the page; a deterministic one re-shows the boundary).
+// The current route's dynamic params (e.g. { projectId: "p_1" }). Lives here,
+// not in the DOM __PYLON_DATA__ (which navigate() never rewrites), so useParams()
+// in a deep client child has a reactive source. A fresh object per nav → stable
+// reference between navs (useSyncExternalStore needs that).
+let currentParams = {};
+function setNavParams(data) {
+  currentParams = (data && data.props && data.props.params) || {};
+}
+
 function withClientProps(data) {
   const props = { ...(data.props || {}) };
   props.serverData = makeClientServerData(data.ssrData);
@@ -396,6 +418,7 @@ export function hydrate(component, Page, Layouts) {
       );
       return;
     }
+    setNavParams(data);
     const tree = buildTree(Page, Layouts, withClientProps(data));
     activeRoot = hydrateRoot(document, tree);
     installNavHandlers();
@@ -472,6 +495,7 @@ async function navigate(href, opts) {
   }
   document.title = doc.title || document.title;
   syncHeadMeta(doc);
+  setNavParams(data);
   const tree = buildTree(route.Page, route.Layouts, withClientProps(data));
   activeRoot.render(tree);
   const target = url.pathname + url.search;
@@ -559,7 +583,14 @@ function installNavHandlers() {
 }
 
 // Expose for <Link> component prefetch.
-const pylonGlobal = { prefetch, navigate };
+const pylonGlobal = {
+  prefetch,
+  navigate,
+  // Read by useParams(); a getter so it always reflects the latest nav.
+  get params() {
+    return currentParams;
+  },
+};
 if (typeof window !== "undefined") {
   window.__pylon = pylonGlobal;
 }
@@ -666,11 +697,13 @@ let _inflightBuild: Promise<BuildOutput> | null = null;
  * Used from `handleBundleClient` (protocol RPC path from Rust) AND
  * from `getManifest` (in-process SSR path).
  */
-export async function buildClientBundle(): Promise<BuildOutput> {
+export async function buildClientBundle(
+  appDirRel: string = "app",
+): Promise<BuildOutput> {
   if (_inflightBuild) return _inflightBuild;
   _inflightBuild = (async () => {
     try {
-      return await _doBuild();
+      return await _doBuild(appDirRel);
     } finally {
       _inflightBuild = null;
     }
@@ -678,7 +711,7 @@ export async function buildClientBundle(): Promise<BuildOutput> {
   return _inflightBuild;
 }
 
-async function _doBuild(): Promise<BuildOutput> {
+async function _doBuild(appDirRel: string): Promise<BuildOutput> {
   // node:* are available in Bun, but `globalThis.require` is
   // not defined in ESM. Use dynamic import; Bun fast-paths these.
   const fsMod: any = await import("node:fs");
@@ -686,7 +719,7 @@ async function _doBuild(): Promise<BuildOutput> {
   const fs = fsMod.default ?? fsMod;
   const path = pathMod.default ?? pathMod;
   const cwd = process.cwd();
-  return _doBuildInner(fs, path, cwd);
+  return _doBuildInner(fs, path, cwd, appDirRel);
 }
 
 /**
@@ -701,8 +734,9 @@ async function buildTailwind(
   path: any,
   cwd: string,
   outdir: string,
+  appDirRel: string,
 ): Promise<string | null> {
-  const globalsPath = path.join(cwd, "app", "globals.css");
+  const globalsPath = path.join(cwd, appDirRel, "globals.css");
   if (!fs.existsSync(globalsPath)) return null;
   // Resolve @tailwindcss/cli. The package only exports
   // `./package.json` in its `exports` map (it's a binary, not a
@@ -760,10 +794,17 @@ async function buildTailwind(
   return stylesName;
 }
 
-async function _doBuildInner(fs: any, path: any, cwd: string): Promise<BuildOutput> {
-  const routes = discoverRoutes(fs, path, cwd);
+async function _doBuildInner(
+  fs: any,
+  path: any,
+  cwd: string,
+  appDirRel: string,
+): Promise<BuildOutput> {
+  const routes = discoverRoutes(fs, path, cwd, appDirRel);
     if (routes.length === 0) {
-      throw new Error("no SSR routes discovered under app/ — nothing to bundle");
+      throw new Error(
+        `no SSR routes discovered under ${appDirRel}/ — nothing to bundle`,
+      );
     }
 
     const stageDir = path.join(cwd, ".pylon");
@@ -958,7 +999,7 @@ async function _doBuildInner(fs: any, path: any, cwd: string): Promise<BuildOutp
     // `app/globals.css`. Adds the stylesheet to every route's css
     // array so SSR head injection emits `<link rel="stylesheet">`.
     try {
-      const styles = await buildTailwind(fs, path, cwd, outdir);
+      const styles = await buildTailwind(fs, path, cwd, outdir, appDirRel);
       if (styles) {
         for (const r of Object.values(manifest.routes)) {
           r.css = [styles];
@@ -1036,7 +1077,9 @@ export async function handleBundleClient(
   send: Send,
 ): Promise<void> {
   try {
-    const { manifestPath, outdir } = await buildClientBundle();
+    const appDirRel =
+      msg.app_dir && msg.app_dir.length > 0 ? msg.app_dir : "app";
+    const { manifestPath, outdir } = await buildClientBundle(appDirRel);
     send({
       type: "bundle_client_result",
       call_id: msg.call_id,

package/src/ssr-runtime.test.ts

@@ -11,6 +11,8 @@ import {
   buildHydrationTail,
   errorDigest,
   resolveOrigin,
+  asRouteControl,
+  PylonRouteControl,
 } from "./ssr-runtime";
 
 describe("resolveOrigin — Host-header allowlist (cache-poisoning fence)", () => {
@@ -391,3 +393,41 @@ describe("buildHydrationTail — boundary hydration (#279) + strip (#270)", () =
     expect(errorDigest(new Error("other"))).not.toBe(d1);
   });
 });
+
+describe("asRouteControl — route-control normalization (redirect/notFound)", () => {
+  test("passes the framework's own PylonRouteControl straight through", () => {
+    const redirect = new PylonRouteControl("redirect");
+    redirect.url = "/login";
+    redirect.redirectStatus = 302;
+    expect(asRouteControl(redirect)).toBe(redirect);
+
+    const nf = new PylonRouteControl("notFound");
+    expect(asRouteControl(nf)).toBe(nf);
+  });
+
+  test("recognizes @pylonsync/react's branded notFound() error by digest", () => {
+    // The cross-package contract: `notFound()` from @pylonsync/react throws an
+    // error stamped `digest === "PYLON_NOT_FOUND"`. The runtime duck-types on
+    // that brand (no import of the React class) and turns it into a notFound
+    // control → a real 404 + nearest not-found.tsx. If this regresses, a
+    // server page calling notFound() would 500 instead of 404.
+    const reactNotFound = Object.assign(new Error("PYLON_NOT_FOUND"), {
+      digest: "PYLON_NOT_FOUND",
+    });
+    const ctrl = asRouteControl(reactNotFound);
+    expect(ctrl).not.toBeNull();
+    expect(ctrl?.kind).toBe("notFound");
+  });
+
+  test("does NOT swallow ordinary errors as a 404 (fails open is forbidden)", () => {
+    // The critical safety property: a real render error must fall through to
+    // the error.tsx / 500 path, never be silently masked as a not-found.
+    expect(asRouteControl(new Error("boom"))).toBeNull();
+    expect(asRouteControl(new TypeError("nope"))).toBeNull();
+    expect(asRouteControl({ digest: "SOME_OTHER_DIGEST" })).toBeNull();
+    expect(asRouteControl({ digest: 42 })).toBeNull();
+    expect(asRouteControl(null)).toBeNull();
+    expect(asRouteControl(undefined)).toBeNull();
+    expect(asRouteControl("PYLON_NOT_FOUND")).toBeNull(); // a bare string, not an error
+  });
+});

package/src/ssr-runtime.ts

@@ -99,6 +99,34 @@ export class PylonRouteControl extends Error {
   }
 }
 
+/**
+ * Digest brand that `@pylonsync/react`'s `notFound()` stamps on the error it
+ * throws. We recognize it here by string instead of importing the class so the
+ * runtime stays decoupled from the React package (which doesn't depend on
+ * functions). Keep in sync with `NotFoundError.digest` in
+ * `packages/react/src/useRouter.ts`.
+ */
+const REACT_NOT_FOUND_DIGEST = "PYLON_NOT_FOUND";
+
+/**
+ * Normalize a thrown value into a route-control signal: either the framework's
+ * own `PylonRouteControl` (`response.redirect()` / `response.notFound()`) or a
+ * branded `NotFoundError` thrown by `@pylonsync/react`'s `notFound()` from a
+ * page/layout render. Returns `null` for an ordinary error so the caller falls
+ * through to its real error-handling path.
+ */
+export function asRouteControl(err: unknown): PylonRouteControl | null {
+  if (err instanceof PylonRouteControl) return err;
+  if (
+    err != null &&
+    typeof err === "object" &&
+    (err as { digest?: unknown }).digest === REACT_NOT_FOUND_DIGEST
+  ) {
+    return new PylonRouteControl("notFound");
+  }
+  return null;
+}
+
 export interface SsrCookieOptions {
   path?: string;
   domain?: string;
@@ -1481,7 +1509,8 @@ export async function handleRenderRoute(
           // (partial HTML); the dev overlay (#275) only covers failures BEFORE
           // response_start (host-side err channel). Buffered renders surface
           // their error through the catch/boundary path below.
-          if (err instanceof PylonRouteControl) {
+          const ctrl = asRouteControl(err);
+          if (ctrl) {
             // A redirect()/notFound() thrown from BELOW a <Suspense> boundary:
             // the shell already committed the head, so React swallowed it and
             // it can't change the response. This is a known limitation on BOTH
@@ -1489,9 +1518,10 @@ export async function handleRenderRoute(
             // synchronous shell). Surface it loudly instead of silently losing.
             // eslint-disable-next-line no-console
             console.error(
-              `[ssr] response.${err.kind}() called below a <Suspense> boundary was ignored — ` +
-                `the HTTP head was already sent. Call response.redirect()/notFound() in the ` +
-                `synchronous shell render, before any await/<Suspense>.`,
+              `[ssr] ${ctrl.kind}() called below a <Suspense> boundary was ignored — ` +
+                `the HTTP head was already sent. Call response.redirect()/notFound() (or ` +
+                `notFound() from @pylonsync/react) in the synchronous shell render, before ` +
+                `any await/<Suspense>.`,
             );
             return;
           }
@@ -1736,16 +1766,20 @@ export async function handleRenderRoute(
 
     send({ type: "render_done", call_id: msg.call_id });
   } catch (err: any) {
-    // A page/layout called response.redirect() or response.notFound()
-    // during render → short-circuit to a 3xx + Location or a 404 instead
-    // of a body. Page-set cookies/headers still ride along.
-    if (err instanceof PylonRouteControl) {
-      if (err.kind === "redirect") {
+    // A page/layout called response.redirect()/response.notFound(), or
+    // `notFound()` from @pylonsync/react, during render → short-circuit to a
+    // 3xx + Location or a 404 instead of a body. Page-set cookies/headers
+    // still ride along.
+    const ctrl = asRouteControl(err);
+    if (ctrl) {
+      if (ctrl.kind === "redirect") {
         send({
           type: "response_start",
           call_id: msg.call_id,
-          status: err.redirectStatus ?? 307,
-          headers: finalizeHeaders(responseState, { location: err.url ?? "/" }),
+          status: ctrl.redirectStatus ?? 307,
+          headers: finalizeHeaders(responseState, {
+            location: ctrl.url ?? "/",
+          }),
         });
         send({ type: "render_done", call_id: msg.call_id });
         return;

package/src/types.ts

@@ -99,10 +99,11 @@ export interface DbReader {
    * convention. A future `pylon lint` rule will flag bare
    * `ctx.db.unsafe.*` without a comment immediately above.
    *
-   * Optional on the type because old Pylon runtimes don't ship
-   * it; new code that targets v0.3.161+ can rely on the field.
+   * Required on the type (every runtime since v0.3.161 ships it) —
+   * but absent on the unsafe surface itself, so `ctx.db.unsafe.unsafe`
+   * is a compile error rather than a runtime undefined.
    */
-  unsafe?: DbReader;
+  unsafe: Omit<DbReader, "unsafe">;
 
   /** Get a single row by ID. Returns null if not found. */
   get(entity: string, id: string): Promise<Record<string, unknown> | null>;
@@ -201,7 +202,7 @@ export interface DbWriter extends DbReader {
    * write surface (insert/update/delete/link/unlink/advisoryLock).
    * Overrides the inherited read-only `unsafe` from DbReader.
    */
-  unsafe?: DbWriter;
+  unsafe: Omit<DbWriter, "unsafe">;
 
   /** Insert a new row. Returns the generated ID. */
   insert(entity: string, data: Record<string, unknown>): Promise<string>;