@pylonsync/create-pylon 0.19.0 → 0.20.0

package/templates/ai-chat/functions/respond.ts

@@ -0,0 +1,88 @@
+import { action, v } from "@pylonsync/functions";
+import { siteConfig } from "../lib/site.config";
+import { isAllowedModel, modelAllowedFor, type LlmTurn } from "../lib/chat";
+
+// Generate the assistant's reply to the latest message in a conversation.
+//
+// Call it with `streamFn("respond", …)`: text streams back as it generates.
+// Every function stream is resumable, and `_beginTurn` stores this call's
+// stream id on the assistant message, so another tab (or this tab after a
+// reload) attaches to the same reply with `resumeStream(streamId)`. The final
+// text is written to the message row, which syncs to every open tab.
+//
+// Guests can call it. `_beginTurn` enforces the hourly limits from
+// lib/site.config.ts and allows one generation per person at a time; the model
+// must be one listed there, and guests are limited to `guestModels`.
+export default action({
+  auth: "guest",
+  // Streaming does not extend the call deadline; long replies need the room.
+  timeout: 300,
+  args: {
+    conversationId: v.string(),
+    content: v.optional(v.string()),
+    regenerate: v.optional(v.boolean()),
+    model: v.string(),
+  },
+  async handler(ctx, args) {
+    // A refused turn (limit, busy, bad input) resolves with its code instead
+    // of throwing: a thrown code does not survive `streamFn`, and the client
+    // branches on it.
+    if (!isAllowedModel(args.model)) {
+      return { status: "rejected" as const, errorCode: "MODEL_NOT_ALLOWED", message: "That model is not available." };
+    }
+    if (!modelAllowedFor(args.model, ctx.auth.isGuest)) {
+      return { status: "rejected" as const, errorCode: "MODEL_NEEDS_ACCOUNT", message: "Sign in to use that model." };
+    }
+
+    let turn: { messageId: string; history: LlmTurn[] };
+    try {
+      turn = await ctx.runMutation("_beginTurn", {
+        conversationId: args.conversationId,
+        content: args.content,
+        regenerate: args.regenerate ?? false,
+        model: args.model,
+        streamId: ctx.stream.id,
+      });
+    } catch (err) {
+      const e = err as { code?: string; message?: string };
+      return { status: "rejected" as const, errorCode: e.code ?? "INTERNAL", message: e.code ? (e.message ?? "") : "" };
+    }
+
+    let streamed = "";
+    try {
+      const res = await ctx.llm.stream(
+        {
+          system: siteConfig.chat.systemPrompt,
+          messages: turn.history,
+          model: args.model,
+          max_tokens: siteConfig.chat.maxOutputTokens,
+        },
+        (e) => {
+          if (e.type === "text_delta") {
+            streamed += e.text;
+            ctx.stream.write(e.text);
+          }
+        },
+      );
+      const text = res.content
+        .filter((b): b is { type: "text"; text: string } => b.type === "text")
+        .map((b) => b.text)
+        .join("");
+      await ctx.runMutation("_finishTurn", {
+        messageId: turn.messageId,
+        content: text || streamed,
+        status: "done",
+      });
+      return { messageId: turn.messageId, status: "done" as const };
+    } catch (err) {
+      const errorCode = (err as { code?: string }).code ?? "LLM_FAILED";
+      await ctx.runMutation("_finishTurn", {
+        messageId: turn.messageId,
+        content: streamed,
+        status: "error",
+        errorCode,
+      });
+      return { messageId: turn.messageId, status: "error" as const, errorCode };
+    }
+  },
+});

package/templates/ai-chat/functions/seedExamples.ts

@@ -0,0 +1,46 @@
+import { mutation } from "@pylonsync/functions";
+import { exampleConversations } from "../lib/examples";
+import { providerStatus } from "../lib/provider";
+
+// Write the example conversations from lib/examples.ts into the caller's
+// history. Runs only while no provider key is configured and only for a
+// caller with no conversations, so it never adds to a real history. Each row
+// is marked `example: true`; the thread labels it and keeps it read-only.
+export default mutation({
+  auth: "guest",
+  args: {},
+  async handler(ctx) {
+    const userId = ctx.auth.userId;
+    if (!userId || providerStatus(ctx.env).configured) return { seeded: 0 };
+
+    await ctx.db.advisoryLock(`ai-chat:seed:${userId}`);
+    const existing = (await ctx.db.unsafe.query("Conversation", { userId, $limit: 1 })) as unknown[];
+    if (existing.length > 0) return { seeded: 0 };
+
+    const now = Date.now();
+    // Conversation and Message inserts are denied to clients by policy; these
+    // rows belong to the caller.
+    for (const ex of exampleConversations) {
+      const start = now - ex.hoursAgo * 60 * 60 * 1000;
+      const last = new Date(start + (ex.messages.length - 1) * 60_000).toISOString();
+      const conversationId = await ctx.db.unsafe.insert("Conversation", {
+        userId,
+        title: ex.title,
+        example: true,
+        createdAt: new Date(start).toISOString(),
+        updatedAt: last,
+      });
+      for (const [i, m] of ex.messages.entries()) {
+        await ctx.db.unsafe.insert("Message", {
+          conversationId,
+          userId,
+          role: m.role,
+          content: m.content,
+          status: "done",
+          createdAt: new Date(start + i * 60_000).toISOString(),
+        });
+      }
+    }
+    return { seeded: exampleConversations.length };
+  },
+});

package/templates/ai-chat/functions/stopResponse.ts

@@ -0,0 +1,30 @@
+import { mutation, v } from "@pylonsync/functions";
+import { siteConfig } from "../lib/site.config";
+
+// Stop the reply streaming in a conversation. The client sends the text it
+// has shown so far; the message keeps it with status "stopped", and
+// `_finishTurn` checks it against the model's output when the call ends.
+//
+// The provider call itself runs to completion on the server: `ctx.llm.stream`
+// has no mid-generation cancel, so tokens after Stop are generated and billed
+// but not stored. `_beginTurn` refuses a new turn until that call ends.
+export default mutation({
+  auth: "guest",
+  args: { conversationId: v.string(), content: v.string() },
+  async handler(ctx, args) {
+    // Message updates are denied to clients by policy; only the caller's own
+    // streaming reply in this conversation is touched.
+    const rows = (await ctx.db.unsafe.query("Message", {
+      conversationId: args.conversationId,
+      role: "assistant",
+      status: "streaming",
+    })) as { id: string; userId: string }[];
+    const msg = rows.find((m) => m.userId === ctx.auth.userId);
+    if (!msg) return { ok: true, stopped: false };
+    await ctx.db.unsafe.update("Message", msg.id, {
+      status: "stopped",
+      content: args.content.slice(0, siteConfig.chat.maxOutputTokens * 8),
+    });
+    return { ok: true, stopped: true };
+  },
+});

package/templates/ai-chat/lib/brand-icon.ts

@@ -0,0 +1,7 @@
+import { siteConfig } from "./site.config";
+
+// The brand mark as an SVG data URL, used as the browser tab icon. Same
+// shapes as BrandMark in components/chat/icons.tsx.
+const svg = `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32"><rect width="32" height="32" rx="9" fill="${siteConfig.colors.brand}"/><circle cx="16" cy="16" r="8.5" fill="none" stroke="#fff" stroke-opacity="0.35" stroke-width="1.5"/><circle cx="13.5" cy="13.5" r="4" fill="#fff"/></svg>`;
+
+export const brandIcon = { url: `data:image/svg+xml,${encodeURIComponent(svg)}`, type: "image/svg+xml" };

package/templates/ai-chat/lib/chat.ts

@@ -0,0 +1,277 @@
+// Pure chat logic shared by the server functions and the UI. No React, no db,
+// so every rule here is covered by tests/chat.test.ts without a server.
+
+import { siteConfig, type ChatModel } from "./site.config";
+
+/* ------------------------------ row shapes ------------------------------ */
+
+export type MessageRole = "user" | "assistant";
+
+// `streaming`: the reply is being generated. `done`: finished. `stopped`: the
+// user pressed Stop, content holds what they saw. `error`: the provider call
+// failed, `errorCode` says why.
+export type MessageStatus = "streaming" | "done" | "stopped" | "error";
+
+export interface ConversationRow {
+  id: string;
+  userId: string;
+  title: string;
+  example?: boolean;
+  createdAt: string;
+  updatedAt?: string | null;
+}
+
+export interface MessageRow {
+  id: string;
+  conversationId: string;
+  userId: string;
+  role: string;
+  content: string;
+  status?: string | null;
+  errorCode?: string | null;
+  streamId?: string | null;
+  model?: string | null;
+  createdAt: string;
+}
+
+/* ------------------------------- models -------------------------------- */
+
+export function findModel(id: string | null | undefined): ChatModel | undefined {
+  return siteConfig.chat.models.find((m) => m.id === id);
+}
+
+export function isAllowedModel(id: string | null | undefined): id is string {
+  return findModel(id) !== undefined;
+}
+
+export function modelLabel(id: string | null | undefined): string {
+  return findModel(id)?.label ?? id ?? "";
+}
+
+/* ------------------------------- titles -------------------------------- */
+
+const TITLE_MAX = 60;
+
+// A conversation title from the first message: first non-empty line, collapsed
+// whitespace, cut at a word boundary.
+export function titleFromMessage(text: string): string {
+  const line =
+    text
+      .split("\n")
+      .map((l) => l.replace(/\s+/g, " ").trim())
+      .find((l) => l.length > 0) ?? "";
+  if (line.length === 0) return "New chat";
+  if (line.length <= TITLE_MAX) return line;
+  const cut = line.slice(0, TITLE_MAX);
+  const space = cut.lastIndexOf(" ");
+  return `${(space > 30 ? cut.slice(0, space) : cut).trimEnd()}...`;
+}
+
+export function cleanTitle(text: string): string | null {
+  const t = text.replace(/\s+/g, " ").trim().slice(0, 80);
+  return t.length > 0 ? t : null;
+}
+
+/* ------------------------------ history -------------------------------- */
+
+export interface LlmTurn {
+  role: MessageRole;
+  content: string;
+}
+
+const HISTORY_MAX_MESSAGES = 40;
+const HISTORY_MAX_CHARS = 60_000;
+
+// The transcript sent to the model. Keeps finished and stopped replies, drops
+// failed and in-flight ones, joins consecutive turns from the same role (a
+// failed reply leaves two user turns in a row, which providers reject), and
+// keeps the newest turns within the size caps. The result always starts with
+// a user turn.
+export function buildHistory(messages: MessageRow[]): LlmTurn[] {
+  const turns: LlmTurn[] = [];
+  for (const m of sortMessages(messages)) {
+    if (m.role !== "user" && m.role !== "assistant") continue;
+    if (m.role === "assistant" && m.status !== "done" && m.status !== "stopped") continue;
+    const content = m.content.trim();
+    if (content.length === 0) continue;
+    const last = turns[turns.length - 1];
+    if (last && last.role === m.role) {
+      last.content = `${last.content}\n\n${content}`;
+    } else {
+      turns.push({ role: m.role, content });
+    }
+  }
+
+  let kept = turns.slice(-HISTORY_MAX_MESSAGES);
+  let chars = kept.reduce((n, t) => n + t.content.length, 0);
+  while (kept.length > 1 && chars > HISTORY_MAX_CHARS) {
+    chars -= kept[0].content.length;
+    kept = kept.slice(1);
+  }
+  while (kept.length > 0 && kept[0].role !== "user") kept = kept.slice(1);
+  return kept;
+}
+
+export function sortMessages<T extends { createdAt: string; id: string }>(rows: T[]): T[] {
+  return [...rows].sort((a, b) =>
+    a.createdAt === b.createdAt ? a.id.localeCompare(b.id) : a.createdAt < b.createdAt ? -1 : 1,
+  );
+}
+
+/* ---------------------------- stream liveness ---------------------------- */
+
+// A reply still marked `streaming` after this long belongs to a generation
+// that died (server restart, crash). The UI shows it as interrupted and the
+// server lets a new turn start.
+export const STALE_STREAM_MS = 5 * 60 * 1000;
+
+export function isStaleStream(m: Pick<MessageRow, "status" | "createdAt">, now: number): boolean {
+  if (m.status !== "streaming") return false;
+  const t = Date.parse(m.createdAt);
+  return Number.isFinite(t) && now - t > STALE_STREAM_MS;
+}
+
+/* ---------------------------- sidebar groups ---------------------------- */
+
+export interface ConversationGroup {
+  label: string;
+  items: ConversationRow[];
+}
+
+function startOfDay(ms: number): number {
+  const d = new Date(ms);
+  d.setHours(0, 0, 0, 0);
+  return d.getTime();
+}
+
+export function lastActivity(c: ConversationRow): string {
+  return c.updatedAt || c.createdAt;
+}
+
+// Newest first, bucketed the way chat apps show history: Today, Yesterday,
+// Previous 7 days, Previous 30 days, then one group per month.
+export function groupConversations(rows: ConversationRow[], now: number): ConversationGroup[] {
+  const today = startOfDay(now);
+  const day = 24 * 60 * 60 * 1000;
+  const sorted = [...rows].sort((a, b) => (lastActivity(a) < lastActivity(b) ? 1 : -1));
+  const groups: ConversationGroup[] = [];
+  for (const c of sorted) {
+    const t = Date.parse(lastActivity(c));
+    let label: string;
+    if (!Number.isFinite(t) || t >= today) label = "Today";
+    else if (t >= today - day) label = "Yesterday";
+    else if (t >= today - 7 * day) label = "Previous 7 days";
+    else if (t >= today - 30 * day) label = "Previous 30 days";
+    else label = new Date(t).toLocaleDateString("en-US", { month: "long", year: "numeric" });
+    const last = groups[groups.length - 1];
+    if (last && last.label === label) last.items.push(c);
+    else groups.push({ label, items: [c] });
+  }
+  return groups;
+}
+
+/* ----------------------------- rate limits ------------------------------ */
+
+export const RATE_WINDOW_MS = 60 * 60 * 1000;
+
+export function replyLimit(isGuest: boolean): number {
+  const { guest, user } = siteConfig.chat.repliesPerHour;
+  return isGuest ? guest : user;
+}
+
+export function modelAllowedFor(id: string | null | undefined, isGuest: boolean): boolean {
+  if (!isAllowedModel(id)) return false;
+  return !isGuest || siteConfig.chat.guestModels.includes(id);
+}
+
+/* ---------------------------- error messages ---------------------------- */
+
+export interface ErrorCopy {
+  title: string;
+  body: string;
+  retry: boolean;
+}
+
+// What the thread shows for a failed reply, by the error code the server
+// stored on the message.
+export function describeError(code: string | null | undefined): ErrorCopy {
+  switch (code) {
+    case "LLM_NOT_CONFIGURED":
+      return {
+        title: "No model provider is configured",
+        body: "Add a provider key to .env and restart the server. Your message is saved.",
+        retry: true,
+      };
+    case "MODEL_NEEDS_ACCOUNT":
+      return {
+        title: "That model needs an account",
+        body: "Sign in to use it, or pick another model.",
+        retry: true,
+      };
+    case "BUSY":
+      return {
+        title: "A reply is already being written",
+        body: "Wait for it to finish, then send again.",
+        retry: true,
+      };
+    case "MODEL_NOT_ALLOWED":
+      return {
+        title: "That model is not enabled",
+        body: "Pick another model, or add this one to chat.models in lib/site.config.ts.",
+        retry: true,
+      };
+    case "RATE_LIMITED":
+    case "PROVIDER_HTTP_429":
+      return {
+        title: "Rate limit reached",
+        body: "Too many replies in the last hour. Try again later.",
+        retry: true,
+      };
+    case "PROVIDER_HTTP_401":
+    case "PROVIDER_HTTP_403":
+      return {
+        title: "The provider rejected the API key",
+        body: "Check the key in .env and restart the server.",
+        retry: true,
+      };
+    case "PROVIDER_UNREACHABLE":
+      return {
+        title: "Could not reach the model provider",
+        body: "Check the network connection and try again.",
+        retry: true,
+      };
+    default:
+      return {
+        title: "The reply failed",
+        body: "Something went wrong while generating this reply. Try again.",
+        retry: true,
+      };
+  }
+}
+
+/* ------------------------------- guests -------------------------------- */
+
+export function isGuestId(userId: string | null | undefined): boolean {
+  return typeof userId === "string" && userId.startsWith("guest_");
+}
+
+/* ------------------------------ redirects ------------------------------ */
+
+// A post-sign-in destination from `?next=`. Only same-site paths are
+// accepted, so the parameter cannot send a user to another origin.
+export function safeNextPath(next: string | null | undefined): string {
+  if (!next) return "/";
+  // Any control character is refused: browsers strip tabs and newlines while
+  // parsing, which turns "/\t/evil.test" into "//evil.test".
+  if (/[\u0000-\u001f\u007f\\]/.test(next)) return "/";
+  if (!next.startsWith("/") || next.startsWith("//")) return "/";
+  const base = "http://same.invalid";
+  let url: URL;
+  try {
+    url = new URL(next, base);
+  } catch {
+    return "/";
+  }
+  if (url.origin !== base) return "/";
+  return url.pathname + url.search + url.hash;
+}

package/templates/ai-chat/lib/claim.ts

@@ -0,0 +1,15 @@
+// One-time codes for moving a guest's history to an account. The code is 32
+// random bytes as hex; only its SHA-256 hash is stored.
+
+export const CLAIM_TTL_MS = 15 * 60 * 1000;
+
+export function newClaimCode(): string {
+  const bytes = new Uint8Array(32);
+  crypto.getRandomValues(bytes);
+  return Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
+}
+
+export async function hashClaimCode(code: string): Promise<string> {
+  const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(code));
+  return Array.from(new Uint8Array(digest), (b) => b.toString(16).padStart(2, "0")).join("");
+}

package/templates/ai-chat/lib/examples.ts

@@ -0,0 +1,179 @@
+// Example conversations for a fresh install with no model provider. The
+// `seedExamples` function writes them into a visitor's history (marked
+// `example: true`) so the sidebar and thread show real layouts before a key is
+// set. The thread labels each one as an example written for the template; none
+// of this text came from a model. Delete this file and `functions/seedExamples.ts`
+// once your app has a provider.
+
+export interface ExampleMessage {
+  role: "user" | "assistant";
+  content: string;
+}
+
+export interface ExampleConversation {
+  title: string;
+  // How long ago the conversation happened, in hours. Spreads the examples
+  // across the sidebar's day groups.
+  hoursAgo: number;
+  messages: ExampleMessage[];
+}
+
+export const exampleConversations: ExampleConversation[] = [
+  {
+    title: "Debounce a search input in React",
+    hoursAgo: 2,
+    messages: [
+      {
+        role: "user",
+        content:
+          "My search box fires a request on every keystroke. How do I debounce it in React without a library, and cancel requests that come back out of order?",
+      },
+      {
+        role: "assistant",
+        content: `There are two separate problems here, and they need two separate fixes:
+
+1. **Too many requests.** Debounce the *value*, so a request only starts after the user pauses typing.
+2. **Out-of-order responses.** A slow response for \`"rea"\` can land after a fast one for \`"react"\`. Cancel the previous request with an \`AbortController\` when a new one starts.
+
+## A \`useDebouncedValue\` hook
+
+Debouncing the value (not the handler) keeps the input responsive: the text field updates on every keystroke, and only the derived value waits.
+
+\`\`\`tsx
+import { useEffect, useState } from "react";
+
+export function useDebouncedValue<T>(value: T, delayMs = 250): T {
+  const [debounced, setDebounced] = useState(value);
+
+  useEffect(() => {
+    const id = setTimeout(() => setDebounced(value), delayMs);
+    // A new keystroke clears the pending timer before it fires.
+    return () => clearTimeout(id);
+  }, [value, delayMs]);
+
+  return debounced;
+}
+\`\`\`
+
+## Fetch with cancellation
+
+The effect's cleanup runs before the next effect, so aborting there cancels the stale request every time the query changes.
+
+\`\`\`tsx
+function Search() {
+  const [query, setQuery] = useState("");
+  const debounced = useDebouncedValue(query.trim(), 250);
+  const [results, setResults] = useState<Result[]>([]);
+
+  useEffect(() => {
+    if (!debounced) return setResults([]);
+    const controller = new AbortController();
+
+    fetch(\`/api/search?q=\${encodeURIComponent(debounced)}\`, {
+      signal: controller.signal,
+    })
+      .then((res) => res.json())
+      .then(setResults)
+      .catch((err) => {
+        if (err.name !== "AbortError") throw err;
+      });
+
+    return () => controller.abort();
+  }, [debounced]);
+
+  return <input value={query} onChange={(e) => setQuery(e.target.value)} />;
+}
+\`\`\`
+
+## Choosing the delay
+
+| Delay | Feels like | Use it for |
+| --- | --- | --- |
+| 150 ms | Instant | Local filtering, small lists |
+| 250 ms | Responsive | Most server search |
+| 400 ms+ | Laggy | Expensive queries only |
+
+A few details that matter in production:
+
+- **Trim before debouncing**, so \`"react "\` and \`"react"\` do not trigger two requests.
+- **Ignore \`AbortError\`**. It is the expected result of a cancelled request, not a failure.
+- **Keep the last results visible** while the next request is in flight. Clearing them on every keystroke makes the list flicker.
+
+If you later add a data library such as TanStack Query, keep the debounced value and pass it as part of the query key. The library then handles cancellation for you.`,
+      },
+      {
+        role: "user",
+        content: "Does the cleanup still run if the component unmounts mid-request?",
+      },
+      {
+        role: "assistant",
+        content: `Yes. React runs the effect's cleanup on unmount as well as before each re-run, so \`controller.abort()\` fires and the pending \`fetch\` rejects with an \`AbortError\`.
+
+That also means \`setResults\` is never called on an unmounted component, so you do not need an \`isMounted\` flag.`,
+      },
+    ],
+  },
+  {
+    title: "Index for a status and created_at query",
+    hoursAgo: 30,
+    messages: [
+      {
+        role: "user",
+        content:
+          "This Postgres query is slow on a 40M row table:\n\nSELECT * FROM orders WHERE status = 'pending' ORDER BY created_at DESC LIMIT 50;\n\nWhat index should I add?",
+      },
+      {
+        role: "assistant",
+        content: `Add a composite index with the equality column first and the sort column second:
+
+\`\`\`sql
+CREATE INDEX CONCURRENTLY orders_status_created_at_idx
+  ON orders (status, created_at DESC);
+\`\`\`
+
+With this index, Postgres jumps to the \`pending\` entries, reads them already sorted by \`created_at\`, and stops after 50 rows. There is no sort step and no scan of the other statuses.
+
+If \`pending\` is a small share of the table, a **partial index** is smaller and faster to maintain:
+
+\`\`\`sql
+CREATE INDEX CONCURRENTLY orders_pending_created_at_idx
+  ON orders (created_at DESC)
+  WHERE status = 'pending';
+\`\`\`
+
+Check the plan after you add it:
+
+\`\`\`sql
+EXPLAIN (ANALYZE, BUFFERS)
+SELECT * FROM orders
+WHERE status = 'pending'
+ORDER BY created_at DESC
+LIMIT 50;
+\`\`\`
+
+You want to see an \`Index Scan\` on the new index and a \`Limit\` node with no \`Sort\` above it. Use \`CONCURRENTLY\` on a live table so the build does not block writes.`,
+      },
+    ],
+  },
+  {
+    title: "Shorter product update email",
+    hoursAgo: 24 * 9,
+    messages: [
+      {
+        role: "user",
+        content:
+          "Make this shorter: \"We wanted to take a moment to reach out and let you know that, after a lot of careful consideration, we have decided to make some changes to the way our pricing works, which will take effect starting next month.\"",
+      },
+      {
+        role: "assistant",
+        content: `Here are three versions, from shortest to most formal:
+
+1. "Our pricing changes next month."
+2. "Starting next month, our pricing is changing. Here is what that means for you."
+3. "We are updating our pricing, effective next month. The details and your options are below."
+
+The second works best for most customers: it states the change and promises the details in one line. Put the date and the new prices directly under it.`,
+      },
+    ],
+  },
+];