@pylonsync/functions 0.3.263 → 0.3.265

package/package.json

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

package/src/index.ts

@@ -25,7 +25,15 @@ export { slugifyName, availableSlug } from "./slugify";
 // SSR page response controller — pages/layouts receive `response` in
 // props (response.setStatus / redirect / notFound / setHeader / setCookie).
 // Type-only; the runtime instance is injected per-render by the SSR adapter.
-export type { SsrResponse, SsrCookieOptions, SsrMetadata } from "./ssr-runtime";
+export type {
+  SsrResponse,
+  SsrCookieOptions,
+  SsrMetadata,
+  Sitemap,
+  SitemapEntry,
+  Robots,
+  RobotsRule,
+} from "./ssr-runtime";
 export type {
   QueryCtx,
   MutationCtx,

package/src/ssr-client-bundler.ts

@@ -81,6 +81,7 @@ declare const Bun: {
     format?: "esm" | "iife";
     minify?: boolean;
     sourcemap?: "none" | "inline" | "external";
+    define?: Record<string, string>;
     external?: string[];
     splitting?: boolean;
     naming?:
@@ -871,6 +872,20 @@ async function _doBuildInner(
       minify: true,
       sourcemap: "none",
       splitting: true,
+      // The browser has no `process`. React, next-themes, sonner, and most
+      // npm UI deps reference `process.env.NODE_ENV` (and migrated Next code
+      // may reference other `process.env.*`), so without this the very first
+      // such reference throws `ReferenceError: process is not defined` during
+      // hydration — React then unmounts the tree and the page renders blank.
+      // Statically replace `process.env.NODE_ENV` with the build mode and
+      // collapse any other `process.env.*` to an empty object (→ undefined),
+      // so no `process` reference survives into the browser bundle.
+      define: {
+        "process.env.NODE_ENV": JSON.stringify(
+          process.env.NODE_ENV === "development" ? "development" : "production",
+        ),
+        "process.env": "({})",
+      },
       naming: {
         entry: "[name]-[hash].js",
         chunk: "chunks/[name]-[hash].js",

package/src/ssr-runtime.ts

@@ -1303,10 +1303,180 @@ export function diffCommittedResponse(
   return null;
 }
 
+// ===========================================================================
+// Data-route file conventions: app/sitemap.ts → /sitemap.xml,
+// app/robots.ts → /robots.txt (Next.js-style). @pylonsync/sdk discovers these
+// (routes with kind "sitemap"/"robots") so the host routes /sitemap.xml +
+// /robots.txt through the SSR RPC; here we detect them by the module basename,
+// call the default export (awaiting if async — so it can hit the DB / enumerate
+// dynamic pages), serialize the return to XML / plain text, and stream it with
+// the right content-type. No React render.
+// ===========================================================================
+
+/** One URL entry in a sitemap (mirrors Next's `MetadataRoute.Sitemap[number]`). */
+export interface SitemapEntry {
+  url: string;
+  lastModified?: string | Date;
+  changeFrequency?:
+    | "always"
+    | "hourly"
+    | "daily"
+    | "weekly"
+    | "monthly"
+    | "yearly"
+    | "never";
+  priority?: number;
+  /** hreflang alternates, e.g. `{ languages: { "en-US": "https://…/en" } }`. */
+  alternates?: { languages?: Record<string, string> };
+}
+
+/** Return type of a default export in `app/sitemap.ts`. */
+export type Sitemap = SitemapEntry[];
+
+export interface RobotsRule {
+  userAgent?: string | string[];
+  allow?: string | string[];
+  disallow?: string | string[];
+  crawlDelay?: number;
+}
+
+/** Return type of a default export in `app/robots.ts`. */
+export interface Robots {
+  rules: RobotsRule | RobotsRule[];
+  sitemap?: string | string[];
+  host?: string;
+}
+
+/** Serialize sitemap entries to a sitemaps.org 0.9 XML document. */
+export function serializeSitemap(entries: Sitemap | undefined): string {
+  const list = Array.isArray(entries) ? entries : [];
+  const esc = (s: unknown): string =>
+    String(s)
+      .replace(/&/g, "&amp;")
+      .replace(/</g, "&lt;")
+      .replace(/>/g, "&gt;")
+      .replace(/"/g, "&quot;")
+      .replace(/'/g, "&apos;");
+  const iso = (d: string | Date): string =>
+    d instanceof Date ? d.toISOString() : String(d);
+  const needsXhtml = list.some(
+    (e) =>
+      e?.alternates?.languages &&
+      Object.keys(e.alternates.languages).length > 0,
+  );
+  const ns =
+    'xmlns="http://www.sitemaps.org/schemas/sitemap/0.9"' +
+    (needsXhtml ? ' xmlns:xhtml="http://www.w3.org/1999/xhtml"' : "");
+  const body = list
+    .filter((e) => e && typeof e.url === "string")
+    .map((e) => {
+      let u = `<url><loc>${esc(e.url)}</loc>`;
+      if (e.lastModified != null)
+        u += `<lastmod>${esc(iso(e.lastModified))}</lastmod>`;
+      if (e.changeFrequency) u += `<changefreq>${esc(e.changeFrequency)}</changefreq>`;
+      if (e.priority != null) u += `<priority>${esc(e.priority)}</priority>`;
+      const langs = e.alternates?.languages;
+      if (langs) {
+        for (const [lang, href] of Object.entries(langs)) {
+          u += `<xhtml:link rel="alternate" hreflang="${esc(lang)}" href="${esc(href)}"/>`;
+        }
+      }
+      return `${u}</url>`;
+    })
+    .join("");
+  return `<?xml version="1.0" encoding="UTF-8"?>\n<urlset ${ns}>${body}</urlset>\n`;
+}
+
+/** Serialize a robots config to robots.txt text. */
+export function serializeRobots(robots: Robots | undefined): string {
+  const arr = (v: string | string[] | undefined): string[] =>
+    v == null ? [] : Array.isArray(v) ? v : [v];
+  const lines: string[] = [];
+  const rules = robots
+    ? Array.isArray(robots.rules)
+      ? robots.rules
+      : [robots.rules]
+    : [];
+  for (const rule of rules) {
+    if (!rule) continue;
+    const uas = arr(rule.userAgent);
+    for (const ua of uas.length ? uas : ["*"]) lines.push(`User-agent: ${ua}`);
+    for (const a of arr(rule.allow)) lines.push(`Allow: ${a}`);
+    for (const d of arr(rule.disallow)) lines.push(`Disallow: ${d}`);
+    if (rule.crawlDelay != null) lines.push(`Crawl-delay: ${rule.crawlDelay}`);
+    lines.push("");
+  }
+  for (const sm of arr(robots?.sitemap)) lines.push(`Sitemap: ${sm}`);
+  if (robots?.host) lines.push(`Host: ${robots.host}`);
+  return `${lines.join("\n").replace(/\n*$/, "")}\n`;
+}
+
+/**
+ * Import app/sitemap or app/robots, run its default export, serialize the
+ * result, and stream it back with the right content-type. Errors surface as a
+ * 500 with a short plain-text message (so a broken sitemap doesn't wedge the
+ * runner). 1-hour cache — sitemaps/robots change rarely; tune via a CDN.
+ */
+export async function handleDataRoute(
+  msg: RenderRouteMessage,
+  kind: "sitemap" | "robots",
+  send: Send,
+): Promise<void> {
+  const emit = (status: number, contentType: string, body: string): void => {
+    send({
+      type: "response_start",
+      call_id: msg.call_id,
+      status,
+      headers:
+        status === 200
+          ? { "content-type": contentType, "cache-control": "public, max-age=3600" }
+          : { "content-type": contentType },
+    });
+    send({
+      type: "render_chunk",
+      call_id: msg.call_id,
+      data: Buffer.from(body, "utf8").toString("base64"),
+    });
+    send({ type: "render_done", call_id: msg.call_id });
+  };
+  try {
+    const cwd = process.cwd();
+    const mod = await importModule(cwd, msg.component);
+    const exp = mod.default ?? mod[kind];
+    const data = typeof exp === "function" ? await exp() : exp;
+    if (kind === "sitemap") {
+      emit(200, "application/xml; charset=utf-8", serializeSitemap(data as Sitemap));
+    } else {
+      emit(200, "text/plain; charset=utf-8", serializeRobots(data as Robots));
+    }
+  } catch (e: any) {
+    emit(
+      500,
+      "text/plain; charset=utf-8",
+      `pylon: failed to generate ${kind} (${msg.component}): ${e?.message ?? String(e)}\n`,
+    );
+  }
+}
+
 export async function handleRenderRoute(
   msg: RenderRouteMessage,
   send: Send,
 ): Promise<void> {
+  // Data-route conventions short-circuit the React render path: app/sitemap →
+  // /sitemap.xml (XML), app/robots → /robots.txt (text). Detected by the module
+  // basename — the SDK only registers these routes for app/sitemap.* /
+  // app/robots.*, so the basename is exactly "sitemap"/"robots" (a real page
+  // component always ends in "/page"). Mirrors the not-found/error basename
+  // check used for boundaries.
+  const dataKind: "sitemap" | "robots" | null = /(^|[\\/])sitemap$/.test(
+    msg.component,
+  )
+    ? "sitemap"
+    : /(^|[\\/])robots$/.test(msg.component)
+      ? "robots"
+      : null;
+  if (dataKind) return handleDataRoute(msg, dataKind, send);
+
   // Declared OUTSIDE the try so the catch can read page-set status/
   // cookies when turning a redirect()/notFound() throw into a response.
   const responseState: ResponseState = {

package/src/ssr-sitemap.test.ts

@@ -0,0 +1,219 @@
+// Tests for the app/sitemap.ts → /sitemap.xml and app/robots.ts → /robots.txt
+// data-route conventions: the pure serializers (where escaping / shape bugs
+// live) plus handleDataRoute end-to-end (import a temp module, serialize, emit
+// the response_start/chunk/done protocol with the right content-type).
+
+import { afterEach, describe, expect, test } from "bun:test";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import {
+  handleDataRoute,
+  serializeRobots,
+  serializeSitemap,
+  type RenderRouteMessage,
+} from "./ssr-runtime";
+
+describe("serializeSitemap", () => {
+  test("empty / undefined → valid empty urlset", () => {
+    for (const v of [[], undefined as any]) {
+      const xml = serializeSitemap(v);
+      expect(xml).toContain('<?xml version="1.0" encoding="UTF-8"?>');
+      expect(xml).toContain(
+        '<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">',
+      );
+      expect(xml).toContain("</urlset>");
+    }
+  });
+
+  test("emits loc + optional fields in order", () => {
+    const xml = serializeSitemap([
+      {
+        url: "https://x.com/blog",
+        lastModified: "2026-01-02",
+        changeFrequency: "weekly",
+        priority: 0.8,
+      },
+    ]);
+    expect(xml).toContain(
+      "<url><loc>https://x.com/blog</loc><lastmod>2026-01-02</lastmod><changefreq>weekly</changefreq><priority>0.8</priority></url>",
+    );
+  });
+
+  test("Date lastModified is ISO-serialized", () => {
+    const d = new Date("2026-06-12T10:00:00.000Z");
+    const xml = serializeSitemap([{ url: "https://x.com/", lastModified: d }]);
+    expect(xml).toContain("<lastmod>2026-06-12T10:00:00.000Z</lastmod>");
+  });
+
+  test("XML-escapes loc and values", () => {
+    const xml = serializeSitemap([
+      { url: "https://x.com/s?a=1&b=2<c>'\"" },
+    ]);
+    expect(xml).toContain(
+      "<loc>https://x.com/s?a=1&amp;b=2&lt;c&gt;&apos;&quot;</loc>",
+    );
+    // raw unescaped specials must not leak into the document body
+    expect(xml.includes("a=1&b=2")).toBe(false);
+  });
+
+  test("hreflang alternates add the xhtml namespace + link tags", () => {
+    const xml = serializeSitemap([
+      {
+        url: "https://x.com/en",
+        alternates: {
+          languages: { "en-US": "https://x.com/en", "es-ES": "https://x.com/es" },
+        },
+      },
+    ]);
+    expect(xml).toContain('xmlns:xhtml="http://www.w3.org/1999/xhtml"');
+    expect(xml).toContain(
+      '<xhtml:link rel="alternate" hreflang="en-US" href="https://x.com/en"/>',
+    );
+    expect(xml).toContain('hreflang="es-ES"');
+  });
+
+  test("no xhtml namespace when no alternates present", () => {
+    const xml = serializeSitemap([{ url: "https://x.com/" }]);
+    expect(xml.includes("xmlns:xhtml")).toBe(false);
+  });
+
+  test("skips entries without a string url", () => {
+    const xml = serializeSitemap([
+      { url: "https://x.com/ok" },
+      { url: undefined as any },
+      null as any,
+    ]);
+    expect((xml.match(/<url>/g) || []).length).toBe(1);
+  });
+});
+
+describe("serializeRobots", () => {
+  test("single rule with default user-agent", () => {
+    const txt = serializeRobots({ rules: { allow: "/", disallow: "/admin" } });
+    expect(txt).toContain("User-agent: *");
+    expect(txt).toContain("Allow: /");
+    expect(txt).toContain("Disallow: /admin");
+    expect(txt.endsWith("\n")).toBe(true);
+  });
+
+  test("array userAgent + array allow/disallow + crawlDelay", () => {
+    const txt = serializeRobots({
+      rules: {
+        userAgent: ["Googlebot", "Bingbot"],
+        disallow: ["/a", "/b"],
+        crawlDelay: 5,
+      },
+    });
+    expect(txt).toContain("User-agent: Googlebot");
+    expect(txt).toContain("User-agent: Bingbot");
+    expect(txt).toContain("Disallow: /a");
+    expect(txt).toContain("Disallow: /b");
+    expect(txt).toContain("Crawl-delay: 5");
+  });
+
+  test("multiple rules, sitemap (array) + host", () => {
+    const txt = serializeRobots({
+      rules: [
+        { userAgent: "*", disallow: "/private" },
+        { userAgent: "BadBot", disallow: "/" },
+      ],
+      sitemap: ["https://x.com/sitemap.xml", "https://x.com/news.xml"],
+      host: "https://x.com",
+    });
+    expect(txt).toContain("User-agent: BadBot");
+    expect(txt).toContain("Sitemap: https://x.com/sitemap.xml");
+    expect(txt).toContain("Sitemap: https://x.com/news.xml");
+    expect(txt).toContain("Host: https://x.com");
+  });
+
+  test("undefined robots → just a trailing newline", () => {
+    expect(serializeRobots(undefined)).toBe("\n");
+  });
+});
+
+describe("handleDataRoute (end-to-end import + serialize)", () => {
+  const tmpdirs: string[] = [];
+  const prevCwd = process.cwd();
+  afterEach(() => {
+    process.chdir(prevCwd);
+    for (const d of tmpdirs.splice(0)) {
+      try {
+        fs.rmSync(d, { recursive: true, force: true });
+      } catch {
+        /* best effort */
+      }
+    }
+  });
+
+  function fixture(file: string, src: string): void {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), "pylon-data-route-"));
+    tmpdirs.push(dir);
+    fs.mkdirSync(path.join(dir, "app"), { recursive: true });
+    fs.writeFileSync(path.join(dir, "app", file), src);
+    process.chdir(dir);
+  }
+
+  const collect = async (
+    component: string,
+    kind: "sitemap" | "robots",
+  ): Promise<any[]> => {
+    const sent: any[] = [];
+    const msg = { component, call_id: "c1" } as unknown as RenderRouteMessage;
+    await handleDataRoute(msg, kind, (m) => sent.push(m));
+    return sent;
+  };
+
+  test("async app/sitemap.ts → 200 application/xml with the rendered urls", async () => {
+    fixture(
+      "sitemap.ts",
+      `export default async function sitemap() {
+        return [{ url: "https://x.com/", priority: 1.0, changeFrequency: "daily" }];
+      }`,
+    );
+    const sent = await collect("app/sitemap", "sitemap");
+    const start = sent.find((m) => m.type === "response_start");
+    const chunk = sent.find((m) => m.type === "render_chunk");
+    expect(start.status).toBe(200);
+    expect(start.headers["content-type"]).toContain("application/xml");
+    expect(start.headers["cache-control"]).toBe("public, max-age=3600");
+    const body = Buffer.from(chunk.data, "base64").toString("utf8");
+    expect(body).toContain("<loc>https://x.com/</loc>");
+    expect(body).toContain("<priority>1</priority>");
+    expect(sent.some((m) => m.type === "render_done")).toBe(true);
+  });
+
+  test("app/robots.ts → 200 text/plain", async () => {
+    fixture(
+      "robots.ts",
+      `export default function robots() {
+        return { rules: { userAgent: "*", allow: "/", disallow: "/dashboard" }, sitemap: "https://x.com/sitemap.xml" };
+      }`,
+    );
+    const sent = await collect("app/robots", "robots");
+    const start = sent.find((m) => m.type === "response_start");
+    const body = Buffer.from(
+      sent.find((m) => m.type === "render_chunk").data,
+      "base64",
+    ).toString("utf8");
+    expect(start.headers["content-type"]).toContain("text/plain");
+    expect(body).toContain("Disallow: /dashboard");
+    expect(body).toContain("Sitemap: https://x.com/sitemap.xml");
+  });
+
+  test("a throwing sitemap surfaces as a 500 (does not wedge the runner)", async () => {
+    fixture(
+      "sitemap.ts",
+      `export default function sitemap() { throw new Error("boom"); }`,
+    );
+    const sent = await collect("app/sitemap", "sitemap");
+    const start = sent.find((m) => m.type === "response_start");
+    expect(start.status).toBe(500);
+    const body = Buffer.from(
+      sent.find((m) => m.type === "render_chunk").data,
+      "base64",
+    ).toString("utf8");
+    expect(body).toContain("boom");
+    expect(sent.some((m) => m.type === "render_done")).toBe(true);
+  });
+});