@pylonsync/functions 0.4.29 → 0.5.2

package/dist/ssr-form-runtime.d.ts

@@ -9,6 +9,8 @@ export interface HandleFormMessage {
     params: Record<string, string>;
     search_params: Record<string, string>;
     form: Record<string, string | string[]>;
+    /** The raw request body, as sent. Empty for GET. */
+    body: string;
     headers: Record<string, string>;
     cookies: Record<string, string>;
     auth: {

package/dist/ssr-runtime.d.ts

@@ -598,6 +598,41 @@ export interface Robots {
 }
 /** Serialize sitemap entries to a sitemaps.org 0.9 XML document. */
 export declare function serializeSitemap(entries: Sitemap | undefined): string;
+/** One link in an `llms.txt` section. */
+export interface LlmsLink {
+    title: string;
+    url: string;
+    /** Short note after the link — what an agent finds there. */
+    notes?: string;
+}
+/** An H2-delimited section of file links. */
+export interface LlmsSection {
+    title: string;
+    links: LlmsLink[];
+}
+/**
+ * Return type of a default export in `app/llms.ts`, serialized to
+ * <https://llmstxt.org> format.
+ *
+ * The spec's order is fixed and load-bearing, because the file is parsed by
+ * "standard programmatic-based tools": an H1 title, a blockquote summary, free
+ * prose with NO headings, then H2 sections of markdown links.
+ */
+export interface LlmsTxt {
+    /** H1 — the site or project name. The one required element. */
+    title: string;
+    /** The blockquote under it: what this is, in one or two sentences. */
+    summary?: string;
+    /**
+     * Prose paragraphs between the summary and the first section. Headings are
+     * not allowed here — the parser reads the first H2 as the start of the link
+     * lists, so a heading in this block would swallow the rest of the file.
+     */
+    details?: string | string[];
+    sections?: LlmsSection[];
+}
+/** Serialize an {@link LlmsTxt} to llmstxt.org format. */
+export declare function serializeLlms(doc: LlmsTxt | undefined): string;
 /** Serialize a robots config to robots.txt text. */
 export declare function serializeRobots(robots: Robots | undefined): string;
 /**
@@ -606,7 +641,7 @@ export declare function serializeRobots(robots: Robots | undefined): string;
  * 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 declare function handleDataRoute(msg: RenderRouteMessage, kind: "sitemap" | "robots", send: Send): Promise<void>;
+export declare function handleDataRoute(msg: RenderRouteMessage, kind: "sitemap" | "robots" | "llms", send: Send): Promise<void>;
 /**
  * Import an `opengraph-image.tsx`, call its default export, render the
  * returned `ImageResponse` (or raw React element) to a PNG via Satori +

package/package.json

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

package/src/hydrationAppName.test.ts

@@ -0,0 +1,44 @@
+// Regression: the browser client namespaces its storage by the app's manifest
+// name, but the name only lives server-side. The SSR runtime surfaces it as
+// PYLON_APP_NAME and buildHydrationTail forwards it into __PYLON_DATA__ as `app`
+// so the client can `configureClient({ appName })` at hydrate — before any token
+// read. These pin that the field appears exactly when the env is set.
+
+import { expect, test } from "bun:test";
+
+import { buildHydrationTail } from "./ssr-runtime";
+
+const base = {
+  component: "app/page.tsx",
+  layouts: [] as string[],
+  props: {},
+  ssrData: {},
+  manifestRoute: null,
+  publicPrefix: "/_pylon/build/",
+  manifestErr: null,
+  dataOnly: true, // return just the __PYLON_DATA__ script
+};
+
+function withEnv(value: string | undefined, fn: () => void) {
+  const prev = process.env.PYLON_APP_NAME;
+  if (value === undefined) delete process.env.PYLON_APP_NAME;
+  else process.env.PYLON_APP_NAME = value;
+  try {
+    fn();
+  } finally {
+    if (prev === undefined) delete process.env.PYLON_APP_NAME;
+    else process.env.PYLON_APP_NAME = prev;
+  }
+}
+
+test("injects app from PYLON_APP_NAME", () => {
+  withEnv("revtrail", () => {
+    expect(buildHydrationTail(base)).toContain('"app":"revtrail"');
+  });
+});
+
+test("omits app when PYLON_APP_NAME is unset", () => {
+  withEnv(undefined, () => {
+    expect(buildHydrationTail(base)).not.toContain('"app"');
+  });
+});

package/src/ssr-client-bundler.ts

@@ -330,6 +330,7 @@ const CLIENT_RUNTIME_SOURCE = `// Generated by Pylon SSR (Phase 2 client runtime
 
 import { createElement } from "react";
 import { hydrateRoot } from "react-dom/client";
+import { configureClient } from "@pylonsync/react";
 import { createPylonBoundary, nearestBoundaryComponent } from "./client-boundary";
 import { LOADING_MODULES } from "./loading-registry";
 import { createNavPayloadCache } from "./nav-cache";
@@ -672,6 +673,13 @@ export function hydrate(component, Page, Layouts) {
   // of all prefetching. In flight from here, it resolves during hydration.
   void loadManifest();
   const data = readPylonData();
+  // Namespace client storage by the app's manifest name (injected into
+  // __PYLON_DATA__ as \`app\`) BEFORE any db hook / auth helper reads a token.
+  // Without this every app on a shared origin (all localhost:4321 in dev)
+  // shares the default \`pylon_token\` and clobbers each other's sessions.
+  // configureClient runs once here; it also migrates a legacy default-keyspace
+  // token so an existing session survives the switch.
+  if (data && data.app) configureClient({ appName: data.app });
   // First hydrate: the entry's component MATCHES the SSR'd page.
   // Establish the root + install the click + popstate handlers
   // exactly once.

package/src/ssr-form-runtime.ts

@@ -6,14 +6,19 @@
 // POST-redirect-GET: write something, then `response.redirect("/x?ok=1")`
 // (303 by default here) so the no-JS browser follows with a GET.
 //
-// A `GET` export is special: it's a RAW handler. Instead of returning void +
-// shaping the reply through `response`, it returns
+// ANY handler may instead RETURN a raw response —
 //   { body, contentType?, status?, headers? }
-// which is streamed verbatim — no React render, no hydration tail. This is the
-// mechanism behind dynamic raw GET routes (RSS/Atom feeds, dynamic XML, text,
-// JSON, .well-known files) — the GET analogue of `app/sitemap.ts`/`robots.ts`,
-// but at an arbitrary route path. A GET handler may still throw
-// `response.redirect()`/`notFound()` instead of returning a body.
+// — which is streamed verbatim, with no React render and no hydration tail.
+// For `GET` that is the normal shape (dynamic RSS/Atom, XML, text, JSON: the
+// GET analogue of `app/sitemap.ts`/`robots.ts` at an arbitrary path, where the
+// default status is 200 rather than the form default of 303).
+//
+// The same return works on POST/PUT/PATCH/DELETE, because an endpoint that
+// answers a machine has to answer with a body: a JSON API, a webhook receiver
+// that must echo a challenge, a JSON-RPC endpoint such as MCP. Without it the
+// only reply a non-GET route could make was a redirect, which is right for a
+// browser form and wrong for everything else. Returning nothing keeps the
+// POST-redirect-GET behavior, so existing handlers are untouched.
 import {
   makeResponseController,
   PylonRouteControl,
@@ -35,6 +40,8 @@ export interface HandleFormMessage {
   params: Record<string, string>;
   search_params: Record<string, string>;
   form: Record<string, string | string[]>;
+  /** The raw request body, as sent. Empty for GET. */
+  body: string;
   headers: Record<string, string>;
   cookies: Record<string, string>;
   auth: {
@@ -97,6 +104,9 @@ export async function handleForm(
   const response = makeResponseController(responseState, 303);
   const req = {
     form: makeFormFields(msg.form ?? {}),
+    // The exact bytes. `form` is only populated for urlencoded bodies, so a
+    // JSON API / JSON-RPC / signature-verifying webhook handler reads this.
+    body: msg.body ?? "",
     params: msg.params,
     searchParams: msg.search_params,
     auth: msg.auth,
@@ -156,10 +166,18 @@ export async function handleForm(
 
   try {
     const out = await handler(req);
-    if (method === "GET") {
-      // Raw GET: stream `out.body` with the handler's content-type/status/
-      // headers (merged with anything set via the response controller). No
-      // React, no hydration tail — verbatim bytes, like sitemap/robots.
+    // A returned object is a RAW response, whatever the method. GET always
+    // takes this path (its return value IS the reply, even when empty); the
+    // other methods take it only when the handler actually returned one, so a
+    // form handler that returns void still gets POST-redirect-GET.
+    const returnedRaw =
+      out != null &&
+      typeof out === "object" &&
+      ("body" in out || "contentType" in out || "status" in out || "headers" in out);
+    if (method === "GET" || returnedRaw) {
+      // Stream `out.body` with the handler's content-type/status/headers
+      // (merged with anything set via the response controller). No React, no
+      // hydration tail — verbatim bytes, like sitemap/robots.
       const raw = (out ?? {}) as {
         body?: unknown;
         contentType?: string;
@@ -174,7 +192,12 @@ export async function handleForm(
       for (const [k, v] of Object.entries(raw.headers ?? {})) {
         extra[k.toLowerCase()] = String(v);
       }
-      const rawStatus = raw.status ?? responseState.status;
+      // A non-GET handler's response state still defaults to 303 (the form
+      // default). A raw return that names no status means 200 — a JSON reply
+      // with an accidental 303 and no Location is a broken response.
+      const rawStatus =
+        raw.status ??
+        (method === "GET" || responseState.status !== 303 ? responseState.status : 200);
       send({
         type: "response_start",
         call_id: msg.call_id,

package/src/ssr-llms.test.ts

@@ -0,0 +1,175 @@
+// Tests for the app/llms.ts → /llms.txt data-route convention: the pure
+// serializer (where the llmstxt.org element order and the newline-escaping
+// bugs live) plus handleDataRoute end-to-end.
+//
+// The format is parsed by tools, not just read by models, so the tests assert
+// on exact document structure rather than on "contains the word".
+
+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,
+  serializeLlms,
+  type RenderRouteMessage,
+} from "./ssr-runtime";
+
+describe("serializeLlms", () => {
+  test("emits the spec's element order", () => {
+    const txt = serializeLlms({
+      title: "Acme",
+      summary: "Invoicing for freelancers.",
+      details: ["Use Acme to issue an invoice.", "Free tier, no card."],
+      sections: [
+        {
+          title: "Docs",
+          links: [
+            { title: "API", url: "https://acme.com/api", notes: "REST + webhooks" },
+            { title: "CLI", url: "https://acme.com/cli" },
+          ],
+        },
+        { title: "Optional", links: [{ title: "Blog", url: "https://acme.com/blog" }] },
+      ],
+    });
+    expect(txt).toBe(
+      [
+        "# Acme",
+        "",
+        "> Invoicing for freelancers.",
+        "",
+        "Use Acme to issue an invoice.",
+        "",
+        "Free tier, no card.",
+        "",
+        "## Docs",
+        "",
+        "- [API](https://acme.com/api): REST + webhooks",
+        "- [CLI](https://acme.com/cli)",
+        "",
+        "## Optional",
+        "",
+        "- [Blog](https://acme.com/blog)",
+        "",
+      ].join("\n"),
+    );
+  });
+
+  test("title alone is a valid document", () => {
+    expect(serializeLlms({ title: "Acme" })).toBe("# Acme\n");
+  });
+
+  test("no title → empty, rather than a headless document", () => {
+    expect(serializeLlms(undefined)).toBe("");
+    expect(serializeLlms({ title: "   " } as any)).toBe("");
+  });
+
+  test("newlines inside a summary or link cannot break the structure", () => {
+    // A multi-line summary would end the blockquote after the first line and
+    // silently turn the rest into prose.
+    const txt = serializeLlms({
+      title: "Acme",
+      summary: "Line one.\nLine two.",
+      sections: [
+        {
+          title: "Docs",
+          links: [{ title: "A\nB", url: "https://acme.com/a", notes: "x\ny" }],
+        },
+      ],
+    });
+    expect(txt).toContain("> Line one. Line two.");
+    expect(txt).toContain("- [A B](https://acme.com/a): x y");
+    expect(txt.split("\n").filter((l) => l.startsWith(">")).length).toBe(1);
+  });
+
+  test("headings in the details block are stripped", () => {
+    // The first H2 marks where link sections begin; a heading in the prose
+    // would swallow everything after it.
+    const txt = serializeLlms({
+      title: "Acme",
+      details: "## Sneaky\nreal prose",
+    });
+    expect(txt).not.toContain("## Sneaky");
+    expect(txt).toContain("Sneaky");
+    expect(txt).toContain("real prose");
+  });
+
+  test("incomplete links and sections are dropped, not half-emitted", () => {
+    const txt = serializeLlms({
+      title: "Acme",
+      sections: [
+        { title: "Docs", links: [{ title: "", url: "https://a" } as any, { title: "B", url: "" } as any] },
+        { title: "", links: [{ title: "C", url: "https://c" }] } as any,
+      ],
+    });
+    expect(txt).toContain("## Docs");
+    expect(txt).not.toContain("](");
+    expect(txt).not.toContain("https://c");
+  });
+});
+
+describe("handleDataRoute — llms", () => {
+  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-llms-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): Promise<any[]> => {
+    const sent: any[] = [];
+    const msg = { component, call_id: "c1" } as unknown as RenderRouteMessage;
+    await handleDataRoute(msg, "llms", (m) => sent.push(m));
+    return sent;
+  };
+
+  test("async app/llms.ts → 200 text/plain with the rendered document", async () => {
+    fixture(
+      "llms.ts",
+      `export default async function llms() {
+        return {
+          title: "Acme",
+          summary: "Invoicing.",
+          sections: [{ title: "Docs", links: [{ title: "API", url: "https://acme.com/api" }] }],
+        };
+      }`,
+    );
+    const sent = await collect("app/llms");
+    const start = sent.find((m) => m.type === "response_start");
+    expect(start.status).toBe(200);
+    expect(start.headers["content-type"]).toContain("text/plain");
+    expect(start.headers["cache-control"]).toBe("public, max-age=3600");
+    const body = Buffer.from(
+      sent.find((m) => m.type === "render_chunk").data,
+      "base64",
+    ).toString("utf8");
+    expect(body.startsWith("# Acme\n")).toBe(true);
+    expect(body).toContain("- [API](https://acme.com/api)");
+    expect(sent.some((m) => m.type === "render_done")).toBe(true);
+  });
+
+  test("a throwing llms.ts surfaces as a 500 (does not wedge the runner)", async () => {
+    fixture("llms.ts", `export default function llms() { throw new Error("boom"); }`);
+    const sent = await collect("app/llms");
+    expect(sent.find((m) => m.type === "response_start").status).toBe(500);
+    const body = Buffer.from(
+      sent.find((m) => m.type === "render_chunk").data,
+      "base64",
+    ).toString("utf8");
+    expect(body).toContain("boom");
+  });
+});

package/src/ssr-runtime.ts

@@ -2030,6 +2030,14 @@ export function buildHydrationTail(args: {
     props: serializableProps,
     ssrData: args.ssrData,
   };
+  // App name (from the manifest, surfaced by the runtime as PYLON_APP_NAME) so
+  // the client namespaces its localStorage/IndexedDB per-app at hydrate. Without
+  // it every app on a shared origin (all localhost:4321 in dev) collides on the
+  // default `pylon_token`. App-global + identity-free, so it stays byte-identical
+  // across users — safe in the PPR-bucketed shared tail too.
+  const appName =
+    typeof process !== "undefined" ? process.env.PYLON_APP_NAME : undefined;
+  if (appName) hydrationPayload.app = appName;
   if (args.kind) hydrationPayload.kind = args.kind;
   const json = escapeScriptJson(JSON.stringify(hydrationPayload));
   let tail = `<script id="__PYLON_DATA__" type="application/json">${json}</script>`;
@@ -2729,6 +2737,79 @@ export function serializeSitemap(entries: Sitemap | undefined): string {
   return `<?xml version="1.0" encoding="UTF-8"?>\n<urlset ${ns}>${body}</urlset>\n`;
 }
 
+/** One link in an `llms.txt` section. */
+export interface LlmsLink {
+  title: string;
+  url: string;
+  /** Short note after the link — what an agent finds there. */
+  notes?: string;
+}
+
+/** An H2-delimited section of file links. */
+export interface LlmsSection {
+  title: string;
+  links: LlmsLink[];
+}
+
+/**
+ * Return type of a default export in `app/llms.ts`, serialized to
+ * <https://llmstxt.org> format.
+ *
+ * The spec's order is fixed and load-bearing, because the file is parsed by
+ * "standard programmatic-based tools": an H1 title, a blockquote summary, free
+ * prose with NO headings, then H2 sections of markdown links.
+ */
+export interface LlmsTxt {
+  /** H1 — the site or project name. The one required element. */
+  title: string;
+  /** The blockquote under it: what this is, in one or two sentences. */
+  summary?: string;
+  /**
+   * Prose paragraphs between the summary and the first section. Headings are
+   * not allowed here — the parser reads the first H2 as the start of the link
+   * lists, so a heading in this block would swallow the rest of the file.
+   */
+  details?: string | string[];
+  sections?: LlmsSection[];
+}
+
+/** Serialize an {@link LlmsTxt} to llmstxt.org format. */
+export function serializeLlms(doc: LlmsTxt | undefined): string {
+  if (!doc || typeof doc.title !== "string" || !doc.title.trim()) {
+    return "";
+  }
+  // A stray newline would end the blockquote / list item early and silently
+  // reshape the document.
+  const oneLine = (s: unknown): string =>
+    String(s).replace(/\s*\n+\s*/g, " ").trim();
+  const out: string[] = [`# ${oneLine(doc.title)}`];
+  if (doc.summary && oneLine(doc.summary)) {
+    out.push("", `> ${oneLine(doc.summary)}`);
+  }
+  const details =
+    doc.details == null
+      ? []
+      : Array.isArray(doc.details)
+        ? doc.details
+        : [doc.details];
+  for (const p of details) {
+    const text = String(p).trim();
+    if (!text) continue;
+    // Headings here would be read as the start of a link section.
+    out.push("", text.replace(/^#+\s*/gm, ""));
+  }
+  for (const section of doc.sections ?? []) {
+    if (!section || !section.title) continue;
+    out.push("", `## ${oneLine(section.title)}`, "");
+    for (const link of section.links ?? []) {
+      if (!link || !link.title || !link.url) continue;
+      const notes = link.notes ? `: ${oneLine(link.notes)}` : "";
+      out.push(`- [${oneLine(link.title)}](${oneLine(link.url)})${notes}`);
+    }
+  }
+  return `${out.join("\n").trim()}\n`;
+}
+
 /** Serialize a robots config to robots.txt text. */
 export function serializeRobots(robots: Robots | undefined): string {
   const arr = (v: string | string[] | undefined): string[] =>
@@ -2761,7 +2842,7 @@ export function serializeRobots(robots: Robots | undefined): string {
  */
 export async function handleDataRoute(
   msg: RenderRouteMessage,
-  kind: "sitemap" | "robots",
+  kind: "sitemap" | "robots" | "llms",
   send: Send,
 ): Promise<void> {
   const emit = (status: number, contentType: string, body: string): void => {
@@ -2788,6 +2869,10 @@ export async function handleDataRoute(
     const data = typeof exp === "function" ? await exp() : exp;
     if (kind === "sitemap") {
       emit(200, "application/xml; charset=utf-8", serializeSitemap(data as Sitemap));
+    } else if (kind === "llms") {
+      // text/plain, not text/markdown: llms.txt is fetched by name, and a
+      // `.txt` served as markdown makes some clients offer a download.
+      emit(200, "text/plain; charset=utf-8", serializeLlms(data as LlmsTxt));
     } else {
       emit(200, "text/plain; charset=utf-8", serializeRobots(data as Robots));
     }
@@ -2910,13 +2995,15 @@ export async function handleRenderRoute(
   // 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(
+  const dataKind: "sitemap" | "robots" | "llms" | null = /(^|[\\/])sitemap$/.test(
     msg.component,
   )
     ? "sitemap"
     : /(^|[\\/])robots$/.test(msg.component)
       ? "robots"
-      : null;
+      : /(^|[\\/])llms$/.test(msg.component)
+        ? "llms"
+        : null;
   if (dataKind) return handleDataRoute(msg, dataKind, send);
 
   // `opengraph-image` (and future `twitter-image`) render to a PNG, not
@@ -3419,6 +3506,13 @@ export async function handleRenderRoute(
           : cacheable
             ? { "x-pylon-cacheable": String(revalidateSecs) }
             : {}),
+        // `export const markdown = false` — this page declines its markdown
+        // representation (an app shell whose value is the interaction, not the
+        // prose). The host reads this AFTER the render: a client that also
+        // accepts HTML gets the HTML we just produced, one that doesn't gets a
+        // 406, and the `<path>.md` URL 404s. Trusted channel, stripped by the
+        // host, so a page can't forge the inverse and force a conversion.
+        ...((mod as any).markdown === false ? { "x-pylon-md": "0" } : {}),
         // Dev-only: the host parses this into its diagnostics ring (served at
         // /_pylon/dev/diagnostics + `pylon diagnostics`). Single-line JSON, no
         // newlines. Stripped before the client like every x-pylon-* header.