@pylonsync/create-pylon 0.3.344 → 0.3.346

package/templates/inventory/tests/stock.test.ts

@@ -0,0 +1,255 @@
+import { describe, expect, test } from "bun:test";
+import {
+  REASONS,
+  isValidReason,
+  money,
+  needsReorder,
+  onHand,
+  onHandByProduct,
+  parseAmount,
+  parseCount,
+  reasonAllows,
+  signedQuantity,
+  stockState,
+  summarize,
+  type Movement,
+  type Product,
+} from "../lib/stock";
+
+const product = (over: Partial<Product> = {}): Product => ({
+  id: "p1",
+  sku: "SKU-1",
+  name: "Thing",
+  unitCostCents: 1000,
+  reorderPoint: 5,
+  ...over,
+});
+
+const move = (over: Partial<Movement> = {}): Movement => ({
+  id: "m1",
+  productId: "p1",
+  delta: 10,
+  reason: "received",
+  ...over,
+});
+
+describe("onHand", () => {
+  test("is the sum of the ledger, not a stored number", () => {
+    expect(
+      onHand("p1", [
+        move({ id: "a", delta: 60 }),
+        move({ id: "b", delta: -8 }),
+        move({ id: "c", delta: -11 }),
+      ]),
+    ).toBe(41);
+  });
+
+  test("two concurrent receipts both count", () => {
+    // The bug this design exists to prevent: with a mutable column, both
+    // readers see 10, both write 15, and five units vanish.
+    expect(
+      onHand("p1", [
+        move({ id: "start", delta: 10 }),
+        move({ id: "a", delta: 5 }),
+        move({ id: "b", delta: 5 }),
+      ]),
+    ).toBe(20);
+  });
+
+  test("ignores other products", () => {
+    expect(onHand("p1", [move({ productId: "p2", delta: 999 })])).toBe(0);
+  });
+
+  test("no movements is zero", () => {
+    expect(onHand("p1", [])).toBe(0);
+  });
+
+  test("a corrupt delta doesn't poison the total", () => {
+    expect(
+      onHand("p1", [move({ delta: 5 }), move({ id: "x", delta: NaN as unknown as number })]),
+    ).toBe(5);
+  });
+});
+
+describe("onHandByProduct", () => {
+  test("matches the per-product version for every product", () => {
+    const movements = [
+      move({ id: "a", productId: "p1", delta: 10 }),
+      move({ id: "b", productId: "p1", delta: -3 }),
+      move({ id: "c", productId: "p2", delta: 4 }),
+    ];
+    const map = onHandByProduct(movements);
+    expect(map.get("p1")).toBe(onHand("p1", movements));
+    expect(map.get("p2")).toBe(onHand("p2", movements));
+  });
+
+  test("an empty ledger is an empty map, not zeroes for phantom products", () => {
+    expect(onHandByProduct([]).size).toBe(0);
+  });
+});
+
+describe("stockState", () => {
+  test("zero or less is out, whatever the reorder point", () => {
+    expect(stockState(0, 5)).toBe("out");
+    expect(stockState(0, null)).toBe("out");
+    expect(stockState(-2, 5)).toBe("out");
+  });
+
+  test("at or below the reorder point is low", () => {
+    expect(stockState(5, 5)).toBe("low");
+    expect(stockState(4, 5)).toBe("low");
+  });
+
+  test("above it is fine", () => {
+    expect(stockState(6, 5)).toBe("ok");
+  });
+
+  test("no reorder point means only zero is notable", () => {
+    expect(stockState(1, 0)).toBe("ok");
+    expect(stockState(1, null)).toBe("ok");
+  });
+});
+
+describe("reasonAllows", () => {
+  test("a sale can only remove stock", () => {
+    // A "Sold" that ADDS is a mis-click; letting it through makes the ledger
+    // untrustworthy, which is the only thing the ledger has going for it.
+    expect(reasonAllows("sold", -3)).toBe(true);
+    expect(reasonAllows("sold", 3)).toBe(false);
+  });
+
+  test("a receipt can only add", () => {
+    expect(reasonAllows("received", 5)).toBe(true);
+    expect(reasonAllows("received", -5)).toBe(false);
+  });
+
+  test("a stock count goes either way", () => {
+    expect(reasonAllows("count", 4)).toBe(true);
+    expect(reasonAllows("count", -4)).toBe(true);
+  });
+
+  test("zero and unknown reasons are refused", () => {
+    expect(reasonAllows("received", 0)).toBe(false);
+    expect(reasonAllows("nonsense", 5)).toBe(false);
+  });
+
+  test("every reason declares a direction", () => {
+    expect(REASONS.every((r) => ["in", "out", "either"].includes(r.direction))).toBe(true);
+    expect(isValidReason("damaged")).toBe(true);
+    expect(isValidReason("Damaged")).toBe(false);
+  });
+});
+
+describe("summarize", () => {
+  const products = [
+    product({ id: "ok", sku: "A", reorderPoint: 5, unitCostCents: 1000 }),
+    product({ id: "low", sku: "B", reorderPoint: 5, unitCostCents: 500 }),
+    product({ id: "out", sku: "C", reorderPoint: 5, unitCostCents: 200 }),
+    product({ id: "gone", sku: "D", archived: true, unitCostCents: 9999 }),
+  ];
+  const movements = [
+    move({ id: "1", productId: "ok", delta: 20 }),
+    move({ id: "2", productId: "low", delta: 3 }),
+    move({ id: "3", productId: "gone", delta: 50 }),
+  ];
+
+  test("counts active SKUs and units", () => {
+    const s = summarize(products, movements);
+    expect(s.skuCount).toBe(3);
+    expect(s.unitCount).toBe(23);
+  });
+
+  test("values stock at COST", () => {
+    // 20 x $10.00 + 3 x $5.00
+    expect(summarize(products, movements).valuationCents).toBe(21_500);
+  });
+
+  test("archived lines are excluded entirely", () => {
+    // Their history stays for auditing, but they aren't stock you hold.
+    const s = summarize(products, movements);
+    expect(s.unitCount).not.toBe(73);
+    expect(s.valuationCents).toBeLessThan(500_000);
+  });
+
+  test("flags low and out separately", () => {
+    const s = summarize(products, movements);
+    expect(s.lowCount).toBe(1);
+    expect(s.outCount).toBe(1);
+  });
+
+  test("negative stock doesn't credit the valuation", () => {
+    // It's a data error to surface, not value to subtract.
+    const s = summarize(
+      [product({ id: "bad", unitCostCents: 1000, reorderPoint: 0 })],
+      [move({ productId: "bad", delta: -4 })],
+    );
+    expect(s.valuationCents).toBe(0);
+    expect(s.unitCount).toBe(0);
+  });
+
+  test("an empty shelf is zeroes", () => {
+    expect(summarize([], [])).toEqual({
+      skuCount: 0,
+      unitCount: 0,
+      valuationCents: 0,
+      lowCount: 0,
+      outCount: 0,
+    });
+  });
+});
+
+describe("needsReorder", () => {
+  test("lists low and out, most urgent first", () => {
+    const products = [
+      product({ id: "ok", reorderPoint: 2 }),
+      product({ id: "low", reorderPoint: 5 }),
+      product({ id: "out", reorderPoint: 5 }),
+    ];
+    const movements = [
+      move({ id: "1", productId: "ok", delta: 20 }),
+      move({ id: "2", productId: "low", delta: 3 }),
+    ];
+    expect(needsReorder(products, movements).map((r) => r.product.id)).toEqual([
+      "out",
+      "low",
+    ]);
+  });
+
+  test("excludes archived products", () => {
+    expect(
+      needsReorder([product({ id: "gone", archived: true, reorderPoint: 5 })], []),
+    ).toEqual([]);
+  });
+});
+
+describe("formatting", () => {
+  test("money is exact", () => {
+    expect(money(21_500)).toBe("$215.00");
+    expect(money(5)).toBe("$0.05");
+    expect(money(null)).toBe("$0.00");
+  });
+
+  test("the sign is always shown on a delta", () => {
+    expect(signedQuantity(5)).toBe("+5");
+    expect(signedQuantity(-3)).toBe("−3");
+    expect(signedQuantity(0)).toBe("0");
+  });
+});
+
+describe("parsing", () => {
+  test("amounts become cents", () => {
+    expect(parseAmount("9.40")).toBe(940);
+    expect(parseAmount("$1,234")).toBe(123_400);
+    expect(parseAmount("abc")).toBeNull();
+    expect(parseAmount("")).toBeNull();
+  });
+
+  test("counts are whole units only", () => {
+    // Half a physical thing is a unit-of-measure mistake, not a quantity.
+    expect(parseCount("12")).toBe(12);
+    expect(parseCount("-3")).toBe(-3);
+    expect(parseCount("1.5")).toBeNull();
+    expect(parseCount("abc")).toBeNull();
+    expect(parseCount("")).toBeNull();
+  });
+});

package/templates/inventory/tsconfig.json

@@ -0,0 +1,33 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "jsx": "react",
+    "esModuleInterop": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "lib": [
+      "ES2022",
+      "DOM"
+    ],
+    "types": [
+      "react",
+      "react-dom",
+      "node"
+    ],
+    "baseUrl": ".",
+    "paths": {
+      "@/*": [
+        "./*"
+      ]
+    }
+  },
+  "include": [
+    "app.ts",
+    "app/**/*",
+    "components/**/*",
+    "lib/**/*",
+    "functions/**/*"
+  ]
+}

package/templates/invoices/AGENTS.md

@@ -0,0 +1,116 @@
+# AGENTS.md: working in a Pylon project
+
+Pylon serves the API, auth, sync, WebSocket, SSE, and native React 19 SSR from one Rust process on one port. Treat this app as production infrastructure: it supports real auth, SQLite or Postgres, row-level policies, jobs, search, and one-command deploys. Declare entities, policies, and server functions in TypeScript; the binary handles the runtime. Read the full API reference at https://docs.pylonsync.com/llms-full.txt before guessing an API name.
+
+## Directory conventions
+
+**Unified SSR app:**
+- `app.ts`: data model + manifest (`entity()` + `field.*`, queries/actions/policies, `routes: await discoverAppRoutes()`). Ends with `console.log(JSON.stringify(manifest))`.
+- `app/`: file-based SSR routes. `app/page.tsx` → `/`, `app/about/page.tsx` → `/about`, `app/blog/[slug]/page.tsx` → `/blog/:slug`. `app/layout.tsx` is the shell; `app/error.tsx` / `app/not-found.tsx` are boundaries.
+- `app/globals.css`: Tailwind v4 entrypoint (auto-compiled and injected).
+- `functions/`: server functions, one per file, `default`-exported.
+- `.pylon/`: local dev state (SQLite, jobs, sessions, uploads). Created by `pylon dev`. Do not commit.
+
+**Monorepo app:** backend is `apps/api/` (entry `apps/api/schema.ts`, handlers in `apps/api/functions/`); frontend in `apps/web/`. `pylon.manifest.json` / `pylon.client.ts` are generated; do not hand-edit.
+
+## The core authoring loop
+
+1. **Define an entity:** `entity("Thing", { name: field.string(), done: field.boolean().default(false) })`. Modifiers: `.optional()`, `.unique()`, `.readonly()` (settable on insert, rejected on client update; use for `authorId`/`orgId`), `.serverOnly()` (never in HTTP responses), `.encrypted()` (AEAD at rest, needs `PYLON_ENCRYPTION_KEY`), `.crdt("text")` (collaborative).
+2. **Write a policy:** `policy({ entity: "Thing", allowRead, allowInsert, allowUpdate, allowDelete })` with CEL-like expressions over `auth.*` / `data.*` (e.g. `"auth.userId == data.authorId"`). Omitted actions deny by default. `pylon lint` flags wide-open development policies such as `allow*: "true"`; tighten them before shipping.
+3. **Author a function** in `functions/<name>.ts`: `query` (read-only), `mutation` (transactional read+write), or `action` (external I/O, no direct `ctx.db`). Import `{ query, mutation, action, v }` from `@pylonsync/functions`. `auth` defaults to `"user"` (secure-by-default); set `"public"` explicitly for unauthenticated access. Use `ctx.db.*`, `ctx.auth.userId`, `ctx.error(code, msg)`.
+4. **Read it on the client:** `db.useQuery("Thing")` (live, re-renders on any write) or `db.useQueryOne("Thing", id)`. Call functions with `db.fn(name, args)` / `callFn`. On SSR pages, read via `use(serverData.list("Thing"))` inside `<Suspense>`.
+
+## Key gotchas
+
+- **Policies deny by default; server functions BYPASS them.** Direct client CRUD (`/api/entities/*`) and sync are policy-checked. Functions run with full DB access; enforce trust with `ctx.auth` checks inside the handler, not policies.
+- **Type page props from the SDK, don't hand-roll them.** `import type { PageProps, Metadata } from "@pylonsync/react"`. Every page/layout gets `{ url, params, searchParams, auth, response, serverData }`; `PageProps<{ slug: string }>` types a `[slug]` route's params. Request headers/cookies are intentionally NOT on `PageProps`; they're server-only and stripped from hydration, so reading them in the render would mismatch.
+- **Anonymous output caching is opt-in and conditional.** `export const revalidate = 60` makes a page CDN-cacheable (`public, s-maxage=60`) only when the render is auth-independent: it must not read `props.auth`, set a cookie, or run with strict per-caller policies (`PYLON_STRICT_FN_POLICIES`). `export const dynamic = "force-static"` caches until the next deploy; `"force-dynamic"` never caches. When any condition fails, the page is `no-cache`. Eligible renders also use the origin disk cache at `.pylon/.cache/ssr`: a cookie-less GET without a query string is served from disk for the TTL and rerendered when stale. The cache is namespaced per deploy, cleared by each build, disabled in `pylon dev`, and invalidated by the `revalidate` TTL or the next deploy.
+- **No-JS forms use `route.ts` and `<Form>`.** Add `app/.../route.ts` exporting `export const POST: RouteHandler = async ({ form, db, response, auth }) => { await db.insert("X", {...}); response.redirect("/x?ok=1"); }` (303 POST-redirect-GET by default). Render `<Form action="/x">` from `@pylonsync/react` with plain `<input name=...>`. It uses native POST → handler → redirect without JavaScript and no-reload enhancement with JavaScript. The handler's `db` is read+write under the mutation trust model, so gate it on `auth`. CSRF protection is automatic through the Origin gate and SameSite=Lax. Multipart uploads are not supported yet; use URL-encoded forms and `/api/files`.
+- **`loading.tsx` streams a skeleton while the page's data resolves.** Drop `app/.../loading.tsx` (default export, page props) and the nearest one becomes a route-level Suspense fallback: Pylon flushes the shell + skeleton immediately, then reveals the real page when its top-level `use(serverData…)` resolves (no blank page). It only shows when the PAGE suspends; a page that wraps its own `<Suspense>` around a child (like `/dashboard` in this template) handles that itself. The skeleton is SERVER-ONLY: don't read `serverData` in it. A page with no `loading.tsx` is buffered (unchanged).
+- **`export const streaming = true` streams a page's inner `<Suspense>` boundaries.** Without it or a `loading.tsx`, the page is buffered until all suspended children resolve. With it, the shell and fallbacks flush immediately, then each boundary streams its content. Streaming commits the HTTP head before suspended subtrees finish, so the page is never CDN- or disk-cacheable; do not combine it with `export const revalidate`. Calls to `response.setStatus`, `setCookie`, `redirect`, or `notFound` only take effect during the synchronous shell render. A call from a suspended subtree is dropped and logged. An error from a deep `<Suspense>` child resolves through the nearest `error.tsx` at HTTP 200 rather than 5xx. Type the config with `import type { RouteSegmentConfig } from "@pylonsync/react"`.
+- **`error.tsx` / `not-found.tsx` boundaries are HYDRATED (interactive).** `app/.../error.tsx` catches a throw below it (HTTP 500) and receives `{ error: { message, digest }, reset }` (`import type { ErrorBoundaryProps }`); `reset()` re-attempts the route; the stack NEVER reaches the client (dev overlay + logs only). `app/.../not-found.tsx` renders at 404 (also for `response.notFound()`) and gets the page props (`NotFoundProps`), no `reset`. Both run useState/onClick/hooks.
+- **Client navigation hooks live in @pylonsync/react.** `useRouter()` → `{ push, replace, back, forward, refresh, prefetch }`; `useSearchParams()` → reactive `URLSearchParams`; `usePathname()` → reactive pathname. The hooks are CLIENT-reactive; during SSR they return defaults (empty params / "/"); for server-side URL values read the `url` / `searchParams` page props.
+- **Dynamic + catch-all routes follow Next conventions.** `app/blog/[slug]/page.tsx` → `params.slug`. `app/docs/[...path]/page.tsx` is a catch-all (matches `/docs/a/b/c`; `params.path === "a/b/c"`; `.split("/")` for segments). `app/shop/[[...filters]]/page.tsx` is an optional catch-all (also matches the bare `/shop`, with `params.filters === ""`). A catch-all must be the last segment; static beats dynamic beats catch-all on overlap.
+- **`serverData` (SSR) is READ-ONLY.** No write methods; the runtime rejects write frames (`SSR_WRITE_FORBIDDEN`). Mutations belong in actions/functions, never in a page render.
+- **`response.*` / `response.redirect()` / `response.notFound()` must fire in the synchronous shell render**, before any `await` / `<Suspense>`. The HTTP head commits when the shell is ready; status/headers/cookies set from a suspended subtree are lost, and `redirect`/`notFound` thrown below a Suspense boundary are swallowed.
+- **`ctx.llm` and `ctx.connections` are on mutation + action only, NOT query** (reactive purity). `action` has no direct `ctx.db`; use `ctx.runQuery` / `ctx.runMutation`.
+- **It's `db.useQueryOne`, not `useOne`.** Validators and field types have aliases: `v.bool`/`v.boolean`, `v.float`/`v.number`.
+- **Use the supported file and scheduling APIs.** Files go through `<FileUpload>` and `/api/files/*`; there is no `ctx.files`. One-shot work uses `ctx.scheduler.runAfter`, `runAt`, or `cancel`; there is no `defineWorkflow` or `defineJob`. Recurring work uses `cron("0 * * * *", "fnName")` in `buildManifest({ crons: [...] })`, imported from `@pylonsync/sdk`. Make the target function `internal: true`. It runs with anonymous auth, but its own `ctx.db.*` calls are server-side and bypass policies. Use `ctx.auth.elevate({ admin: true, reason: "..." })`, with a mandatory reason, only when chaining another internal function through `ctx.scheduler`.
+
+## Testing
+
+`pylon test` discovers every `*.test.ts` / `*.test.tsx` file under `tests/` (or `functions/`) and runs it with **Bun's test runner** (`import { test, expect } from "bun:test"`). Run the suite with `pylon test` (or `npm test`); filter with `pylon test <substring>`. This template ships `bunfig.toml` + `tests/setup.ts` (registers happy-dom) so component tests render out of the box, plus starter tests under `tests/`; replace them with your own.
+
+**Tier 1: pure logic (start here).** Keep access and plan gating, pricing, credit math, validation, and formatting in pure functions under `lib/`, and test them exhaustively. These tests need no server and run instantly. Keep `query`, `mutation`, and `action` handlers as thin wrappers so their decision logic remains testable without a running app.
+
+```ts
+import { expect, test } from "bun:test";
+import { productBySlug } from "../lib/site.config";
+
+test("unknown slug → undefined", () => {
+  expect(productBySlug("nope")).toBeUndefined();
+});
+```
+
+**Tier 2: React components.** `@testing-library/react` and happy-dom are already wired through `tests/setup.ts`. Render and assert. The template uses the classic JSX transform, so add `import React from "react"` in `.tsx` tests. For a component that reads Pylon data hooks, mock the boundary, then dynamically import the component so the mock is in place first:
+
+```tsx
+import { test, expect, mock } from "bun:test";
+import React from "react";
+import { render, screen } from "@testing-library/react";
+
+mock.module("@pylonsync/react", () => ({
+  db: { useQuery: () => ({ data: [{ id: "1", name: "Acme" }], loading: false }) },
+}));
+const { OrgList } = await import("../app/orgs/org-list"); // your component
+
+test("renders orgs from the query", () => {
+  render(<OrgList />);
+  expect(screen.getByText("Acme")).toBeDefined();
+});
+```
+
+**Tier 3: functions over HTTP.** Use this tier when pure logic tests cannot cover the behavior. A handler's policies, `ctx.db` calls, and auth run in the app. Start `pylon dev` in another terminal and call the API. `resetDb()` from `@pylonsync/functions` clears the in-memory database between cases; it does nothing when the server is down and refuses to run in production.
+
+```ts
+import { afterEach, expect, test } from "bun:test";
+import { resetDb } from "@pylonsync/functions";
+
+const BASE = "http://localhost:4321";
+afterEach(() => resetDb(BASE)); // or installTestIsolation(BASE) once at top-of-file
+
+test("createThing then read it back", async () => {
+  const t = await fetch(`${BASE}/api/fn/createThing`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ name: "hello" }),
+  }).then((r) => r.json());
+  const rows = await fetch(`${BASE}/api/entities/Thing`).then((r) => r.json());
+  expect(rows.some((r: { id: string }) => r.id === t.id)).toBe(true);
+});
+```
+
+`pylon test:security` is a separate adversarial probe; it hits a running app and reports auth/policy holes (run `pylon dev`, then `pylon test:security`).
+
+## Use the CLI
+
+| Need | Command |
+|---|---|
+| Run the app (SSR + API, hot reload, one port `:4321`) | `pylon dev` (or `npm run dev`) |
+| Regenerate manifest + typed client | `pylon codegen` (Swift client: `pylon codegen client --target swift`) |
+| Validate / diff / push schema | `pylon schema check` \| `diff` \| `push` |
+| Migrations | `pylon migrate create <name>` \| `plan` \| `apply` |
+| Lint policies (PYL001–PYL004) | `pylon lint --strict` |
+| Tests | `pylon test` |
+| Adversarial security probe | `pylon test:security` |
+| Inspect cloud request logs (agent-safe) | `pylon logs --json --limit 50` |
+| Inspect data / entities | `pylon data entities` \| `pylon data list <Entity>` |
+| Call a function | `pylon fn <name> key=value` |
+| Health snapshot | `pylon status` |
+| Build for prod | `pylon build` |
+| Deploy (Pylon Cloud by default) | `pylon deploy` |
+| Look up an error code | `pylon explain <CODE>` |
+
+`--json` works on every command for machine-readable output. Prefer one-shot/agent-safe flags (`pylon logs --limit N`, not a blocking `--follow`).
+
+For full signatures, env vars, the complete CLI, and SSR/client/server-primitive details: **https://docs.pylonsync.com/llms-full.txt**.

package/templates/invoices/CLAUDE.md

@@ -0,0 +1,7 @@
+# CLAUDE.md
+
+Agent guidance for this Pylon project lives in **AGENTS.md**, the cross-editor
+standard read by Claude Code, Cursor, Codex, and other agents. The import below
+makes it available to Claude Code:
+
+@AGENTS.md

package/templates/invoices/README.md

@@ -0,0 +1,99 @@
+# __APP_NAME__
+
+Invoicing for a small business — clients, line items, and payments. One
+[Pylon](https://pylonsync.com) app: SSR frontend, API, auth, and realtime sync
+from one process on one port.
+
+## Develop
+
+```bash
+__RUN_DEV__
+```
+
+Open http://localhost:4321 and create an account. The first sign-in seeds a
+realistic book — including one invoice already overdue and one part-paid — so
+those states are visible rather than theoretical. Delete
+`functions/seedWorkspace.ts` and `lib/seed.ts` once you're billing real clients.
+
+## What's interesting here
+
+**Money is integer cents, everywhere.** Floating-point dollars is how an invoice
+ends up a penny off after tax, and a penny on a bill is a support ticket.
+Quantities are thousandths for the same reason. Conversion happens only at the
+edges — `parseAmount` on input, `money` on output.
+
+**Totals and ageing are derived, never stored.** An invoice becomes overdue by
+the clock passing, so nothing has to run at midnight to flip a column, and the
+figure on screen always reconciles with the lines you can see. Tax is applied to
+the rounded subtotal, which is what a customer can reproduce from the printed
+invoice.
+
+**The balance is computed server-side.** `recordPayment` recomputes from the
+line items and existing payments before accepting anything — trusting a
+client-sent balance would let a stale tab overpay, or mark an invoice settled
+that isn't. Overpayment is rejected rather than silently producing a credit.
+
+**It's live.** Recording a payment flips the balance and status on every open
+tab, so two people chasing the same overdue invoice stop the moment one of them
+marks it paid.
+
+**Numbers come from the series, not a counter.** `nextNumber` derives the next
+one from the existing rows: a counter in a synced replica is a race, and gaps in
+an invoice series get asked about by accountants. `number` is unique in the
+schema, so a genuine collision fails loudly.
+
+## Layout
+
+```
+app.ts                    entities + policies
+app/
+  page.tsx                "/" — the invoice list
+  invoices-view.tsx       list container
+  workspace.tsx           app shell — the ONLY place that touches `db`
+  invoices/[id]/          invoice detail, line items, payments
+  clients/                client list
+  login/                  email/password auth
+components/               presentational — props in, callbacks out
+  ui/                     shadcn primitives
+lib/billing.ts            money, totals, ageing, numbering — pure
+lib/format.ts             time + initials — pure
+functions/                server functions
+tests/                    pure logic + component tests
+```
+
+The data boundary lives in exactly one module (`app/workspace.tsx`). Everything
+under `components/` takes data as props and reports changes through callbacks,
+which is why the component tests render them with fixtures and mock nothing.
+
+## A deliberate limitation
+
+**A sent invoice can't have its lines edited.** It's a document someone is
+paying against, and silently mutating it desyncs your copy from the one in their
+inbox. Correct a sent invoice by voiding it and issuing another — the way paper
+accounting has always worked, and the way an auditor expects.
+
+## Access
+
+Every entity is readable and writable by any **signed-in** user, and by nobody
+else. There is **no client portal**, and no policy allows an anonymous read.
+Adding one means a separate, narrower policy scoped to that client's own
+invoices, not loosening these.
+
+## Grow it
+
+- **Change the tax model:** `totals` in `lib/billing.ts`. Per-line tax is a
+  small change there and nowhere else.
+- **Add a status:** `STATUSES` in the same file. Note that `overdue` is
+  deliberately derived and not settable.
+- **Email an invoice:** an action that renders the lines and sends through
+  `ctx.email` — the totals helper already gives you every figure.
+
+## Deploy
+
+```bash
+pylon lint --strict
+pylon test
+pylon deploy
+```
+
+Docs: https://docs.pylonsync.com

package/templates/invoices/app/clients/clients-view.tsx

@@ -0,0 +1,130 @@
+"use client";
+
+import React, { useState } from "react";
+import { db } from "@pylonsync/react";
+import { Plus, Users } from "lucide-react";
+import { Button } from "@/components/ui/button";
+import { PageHeader } from "@/components/page-header";
+import { DataTable, type ColumnDef } from "@/components/data-table";
+import { EmptyState } from "@/components/empty-state";
+import { RecordDialog } from "@/components/record-dialog";
+import { Avatar } from "@/components/avatar";
+import { money, totals } from "@/lib/billing";
+import { Workspace, type ClientRow } from "../workspace";
+
+export function ClientsView({ email }: { email: string }) {
+  const [open, setOpen] = useState(false);
+
+  return (
+    <Workspace email={email} pathname="/clients">
+      {(data) => {
+        // Outstanding per client, derived rather than stored — one less thing
+        // to keep in sync when a payment lands.
+        const outstanding = (clientId: string) =>
+          data.invoices
+            .filter((invoice) => invoice.clientId === clientId && invoice.status === "sent")
+            .reduce(
+              (sum, invoice) =>
+                sum + totals(invoice, data.items, data.payments).balanceCents,
+              0,
+            );
+
+        const columns: ColumnDef<ClientRow>[] = [
+          {
+            key: "name",
+            header: "Client",
+            cell: (row) => (
+              <span className="flex items-center gap-2">
+                <Avatar name={row.name} size="sm" />
+                <span className="truncate font-medium">{row.name}</span>
+              </span>
+            ),
+          },
+          {
+            key: "email",
+            header: "Email",
+            cell: (row) =>
+              row.email ? (
+                <a
+                  href={`mailto:${row.email}`}
+                  onClick={(event) => event.stopPropagation()}
+                  className="text-muted-foreground underline-offset-2 hover:text-foreground hover:underline"
+                >
+                  {row.email}
+                </a>
+              ) : (
+                <span className="text-muted-foreground">—</span>
+              ),
+          },
+          {
+            key: "invoices",
+            header: "Invoices",
+            numeric: true,
+            cell: (row) =>
+              data.invoices.filter((invoice) => invoice.clientId === row.id).length,
+          },
+          {
+            key: "outstanding",
+            header: "Outstanding",
+            numeric: true,
+            cell: (row) => {
+              const value = outstanding(row.id);
+              return (
+                <span className={value > 0 ? "" : "text-muted-foreground"}>
+                  {money(value)}
+                </span>
+              );
+            },
+          },
+        ];
+
+        const rows = [...data.clients].sort((a, b) => a.name.localeCompare(b.name));
+
+        return (
+          <>
+            <PageHeader title="Clients" count={rows.length}>
+              <Button size="sm" onClick={() => setOpen(true)}>
+                <Plus />
+                New client
+              </Button>
+            </PageHeader>
+
+            <DataTable
+              rows={rows}
+              columns={columns}
+              empty={
+                <EmptyState
+                  icon={<Users />}
+                  title="No clients yet"
+                  description="Who you bill. Their address appears on the invoice, so add it once here."
+                  action={
+                    <Button size="sm" onClick={() => setOpen(true)}>
+                      <Plus />
+                      New client
+                    </Button>
+                  }
+                />
+              }
+            />
+
+            <RecordDialog
+              open={open}
+              title="New client"
+              submitLabel="Create client"
+              onOpenChange={setOpen}
+              fields={[
+                { name: "name", label: "Name", required: true, placeholder: "Northwind Logistics" },
+                { name: "email", label: "Billing email", type: "email", placeholder: "ap@northwind.co" },
+                { name: "address", label: "Address", placeholder: "412 Dock Road, Rotterdam" },
+                { name: "taxId", label: "Tax ID", placeholder: "VAT / company number" },
+              ]}
+              onCreate={async (values) => {
+                await db.insert("Client", values);
+              }}
+            />
+          </>
+        );
+      }}
+    </Workspace>
+  );
+}

package/templates/invoices/app/clients/page.tsx

@@ -0,0 +1,17 @@
+import React, { use } from "react";
+import type { Metadata, PageProps } from "@pylonsync/react";
+import { ClientsView } from "./clients-view";
+
+export const metadata: Metadata = {
+  title: "Clients",
+  robots: "noindex",
+};
+
+export default function ClientsPage({ auth, response, serverData }: PageProps) {
+  if (!auth.user_id || auth.user_id.startsWith("guest_")) {
+    response.redirect("/login");
+    return null;
+  }
+  const me = use(serverData.get<{ email?: string }>("User", auth.user_id));
+  return <ClientsView email={me?.email ?? ""} />;
+}