@pylonsync/functions 0.3.311 → 0.3.312

package/dist/server-only.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Marker import that pins a module to the SERVER. Put it at the top of any
+ * module that must never reach the browser — one holding secrets, server
+ * config, or node-only APIs:
+ *
+ *   import "@pylonsync/functions/server-only";
+ *
+ *   export const stripeKey = process.env.STRIPE_SECRET_KEY!;
+ *
+ * Page (`page.tsx`) and layout (`layout.tsx`) modules — and everything they
+ * transitively import — are bundled for client hydration, so a plain literal or
+ * server config in that graph would ship to the browser. If a module marked
+ * with this import is pulled into a client-reachable page, the SSR client
+ * bundler REFUSES to build and names the offending importer (see the
+ * `pylon-server-only` plugin in `ssr-client-bundler.ts`).
+ *
+ * On the server this is an inert no-op. There is nothing to call — importing it
+ * is the whole contract.
+ */
+export {};

package/dist/ssr-client-bundler.d.ts

@@ -14,6 +14,16 @@ interface BundleClientMessage {
      */
     app_dir?: string;
 }
+/**
+ * Fail the CLIENT bundle when a `server-only` module is resolved — meaning it
+ * was pulled into a page/layout's client graph. Page/layout modules (and their
+ * transitive imports) are bundled for hydration, so a literal secret or server
+ * config in that graph would ship to the browser (the `process.env.*` `define`
+ * only neutralizes env reads). Authors mark such modules with
+ * `import "@pylonsync/functions/server-only"`; this turns an accidental client
+ * import into a loud build failure that names the offending importer.
+ */
+export declare function assertNotServerOnly(specifier: string, importer: string): void;
 /**
  * Manifest schema. One entry per route, indexed by the same
  * project-relative component path the SSR side passes through.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pylonsync/functions",
-  "version": "0.3.311",
+  "version": "0.3.312",
   "description": "TypeScript function runtime for pylon — defines server-side queries, mutations, and actions.",
   "type": "module",
   "main": "src/index.ts",
@@ -14,6 +14,10 @@
       "types": "./dist/runtime.d.ts",
       "default": "./src/runtime.ts"
     },
+    "./server-only": {
+      "types": "./dist/server-only.d.ts",
+      "default": "./src/server-only.ts"
+    },
     "./client-bundler": {
       "types": "./dist/ssr-client-bundler.d.ts",
       "default": "./src/ssr-client-bundler.ts"

package/src/server-only.ts

@@ -0,0 +1,20 @@
+/**
+ * Marker import that pins a module to the SERVER. Put it at the top of any
+ * module that must never reach the browser — one holding secrets, server
+ * config, or node-only APIs:
+ *
+ *   import "@pylonsync/functions/server-only";
+ *
+ *   export const stripeKey = process.env.STRIPE_SECRET_KEY!;
+ *
+ * Page (`page.tsx`) and layout (`layout.tsx`) modules — and everything they
+ * transitively import — are bundled for client hydration, so a plain literal or
+ * server config in that graph would ship to the browser. If a module marked
+ * with this import is pulled into a client-reachable page, the SSR client
+ * bundler REFUSES to build and names the offending importer (see the
+ * `pylon-server-only` plugin in `ssr-client-bundler.ts`).
+ *
+ * On the server this is an inert no-op. There is nothing to call — importing it
+ * is the whole contract.
+ */
+export {};

package/src/ssr-client-bundler.test.ts

@@ -24,6 +24,7 @@ import * as os from "node:os";
 import {
   buildClientBundle,
   buildTailwind,
+  assertNotServerOnly,
   type PylonBundleManifest,
 } from "./ssr-client-bundler";
 import { nearestBoundaryComponent } from "./ssr-client-boundary";
@@ -430,3 +431,60 @@ describe("Tailwind compile is concurrency-safe", () => {
     expect(stranded).toEqual([]);
   }, 20_000);
 });
+
+describe("server-only guard (secrets can't leak into the client bundle)", () => {
+  test("assertNotServerOnly throws for server-only specifiers, passes others", () => {
+    expect(() =>
+      assertNotServerOnly("@pylonsync/functions/server-only", "app/page.tsx"),
+    ).toThrow(/server-only/i);
+    expect(() => assertNotServerOnly("server-only", "app/x/layout.tsx")).toThrow(
+      /server-only/i,
+    );
+    // The importer is named so the author can find the offending module.
+    expect(() => assertNotServerOnly("server-only", "app/secrets.ts")).toThrow(
+      /app\/secrets\.ts/,
+    );
+    // Ordinary imports pass untouched.
+    expect(() => assertNotServerOnly("react", "app/page.tsx")).not.toThrow();
+    expect(() => assertNotServerOnly("@/lib/utils", "app/page.tsx")).not.toThrow();
+  });
+
+  test("a real client build importing a server-only module FAILS via the guard", async () => {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), "pylon-server-only-"));
+    const entry = path.join(dir, "entry.ts");
+    fs.writeFileSync(entry, `import "server-only";\nexport const x = 1;\n`);
+    // Same plugin the bundler installs. `guardFired` proves the guard's
+    // onResolve ran for the marker (Bun runs plugin resolution BEFORE default
+    // resolution) — distinguishing a real guard rejection from an unrelated
+    // "module not found". Bun surfaces the plugin throw as a failed build.
+    let guardFired = false;
+    let failed = false;
+    try {
+      const result = await Bun.build({
+        entrypoints: [entry],
+        outdir: path.join(dir, "out"),
+        target: "browser",
+        plugins: [
+          {
+            name: "pylon-server-only",
+            setup(build: any) {
+              build.onResolve(
+                { filter: /^(@pylonsync\/functions\/server-only|server-only)$/ },
+                (args: any) => {
+                  guardFired = true;
+                  assertNotServerOnly(args.path, args.importer);
+                },
+              );
+            },
+          },
+        ],
+      } as any);
+      failed = !result.success;
+    } catch {
+      failed = true;
+    }
+    expect(guardFired).toBe(true);
+    expect(failed).toBe(true);
+    fs.rmSync(dir, { recursive: true, force: true });
+  });
+});

package/src/ssr-client-bundler.ts

@@ -101,10 +101,46 @@ declare const Bun: {
         };
     publicPath?: string;
     root?: string;
+    plugins?: Array<{
+      name: string;
+      setup(build: {
+        onResolve(
+          opts: { filter: RegExp; namespace?: string },
+          callback: (args: { path: string; importer: string }) => void,
+        ): void;
+      }): void;
+    }>;
   }): Promise<BunBuildOutput>;
   file(path: string): { exists(): Promise<boolean> };
 };
 
+/**
+ * Specifiers marking a module as SERVER-ONLY: `@pylonsync/functions/server-only`
+ * (in-ecosystem) or the bare `server-only` (Next.js compat). A module that
+ * imports one must never reach the browser.
+ */
+const SERVER_ONLY_RE = /^(@pylonsync\/functions\/server-only|server-only)$/;
+
+/**
+ * Fail the CLIENT bundle when a `server-only` module is resolved — meaning it
+ * was pulled into a page/layout's client graph. Page/layout modules (and their
+ * transitive imports) are bundled for hydration, so a literal secret or server
+ * config in that graph would ship to the browser (the `process.env.*` `define`
+ * only neutralizes env reads). Authors mark such modules with
+ * `import "@pylonsync/functions/server-only"`; this turns an accidental client
+ * import into a loud build failure that names the offending importer.
+ */
+export function assertNotServerOnly(specifier: string, importer: string): void {
+  if (SERVER_ONLY_RE.test(specifier)) {
+    throw new Error(
+      `pylon: "${specifier}" is server-only but was imported into the client bundle by ` +
+        `${importer || "a page/layout module"}. Page/layout modules (and everything they import) ship to ` +
+        `the browser — move server-only code (secrets, server config, node-only APIs) into a server function ` +
+        `(functions/) or a route.ts handler and pass only the rendered values as props.`,
+    );
+  }
+}
+
 /**
  * Synchronously walk the route dir (`<appDirRel>` under cwd, e.g.
  * `app` or `web/app`) and return one entry per discovered page, each
@@ -1240,6 +1276,19 @@ async function _doBuildInner(
         chunk: "chunks/[name]-[hash].js",
         asset: "assets/[name]-[hash][ext]",
       },
+      // Refuse to bundle a server-only module into a client-reachable page —
+      // secrets / server config in a page's import graph would otherwise ship
+      // to the browser.
+      plugins: [
+        {
+          name: "pylon-server-only",
+          setup(build) {
+            build.onResolve({ filter: SERVER_ONLY_RE }, (args) => {
+              assertNotServerOnly(args.path, args.importer);
+            });
+          },
+        },
+      ],
     });
 
     if (!result.success) {
@@ -1281,6 +1330,52 @@ async function _doBuildInner(
       }
     }
 
+    // loro-crdt's web build locates its WASM sibling at RUNTIME via
+    // `new URL("loro_wasm_bg.wasm", import.meta.url)` — the file never
+    // appears in the static import graph, so Bun doesn't emit it and every
+    // CRDT-using page 404s on /_pylon/build/loro_wasm_bg.wasm during
+    // hydration. When any built output references the wasm by name, copy
+    // the binary next to the entries AND into chunks/ so the runtime URL
+    // resolves from either an entry or a split chunk.
+    try {
+      const referencesLoroWasm = result.outputs.some((o) => {
+        if (!o.path.endsWith(".js")) return false;
+        try {
+          return fs.readFileSync(o.path, "utf8").includes("loro_wasm_bg.wasm");
+        } catch {
+          return false;
+        }
+      });
+      if (referencesLoroWasm) {
+        const loroPkg = (Bun as any).resolveSync(
+          "loro-crdt/package.json",
+          cwd,
+        ) as string;
+        // The wasm must come from the SAME build variant whose JS glue got
+        // bundled — the wasm-bindgen import namespaces differ between
+        // variants (mixing them fails instantiation with `Import #0 "wbg"`).
+        // `target: "browser"` resolves the package's "browser" condition, so
+        // prefer browser/; web/ is the fallback for older package layouts.
+        const loroDir = path.dirname(loroPkg);
+        const wasmSrc = ["browser", "web"]
+          .map((v) => path.join(loroDir, v, "loro_wasm_bg.wasm"))
+          .find((p) => fs.existsSync(p));
+        if (wasmSrc) {
+          fs.copyFileSync(wasmSrc, path.join(outdir, "loro_wasm_bg.wasm"));
+          const chunksDir = path.join(outdir, "chunks");
+          if (fs.existsSync(chunksDir)) {
+            fs.copyFileSync(
+              wasmSrc,
+              path.join(chunksDir, "loro_wasm_bg.wasm"),
+            );
+          }
+        }
+      }
+    } catch {
+      // Best-effort: failing to copy just reproduces the 404 this guards
+      // against; the build itself is fine.
+    }
+
     // Scan a built JS file for static `import` literals pointing
     // at `./chunks/<file>.js` and return them resolved to outdir-
     // relative paths. Bun's minified output uses simple double