Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .claude/skills/podbay-change/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -38,7 +38,7 @@ Podbay stores other people's mail. The way of working is part of the product: ev
| Edit a file that came from the seed | `node scripts/checks/copies.ts --fix` |
| Remove lint warnings or shrink an oversized file | `node scripts/checks/ratchets.ts --update` (it only ever goes down) |
| Finish or reorder roadmap work | [`docs/roadmap.md`](../../../docs/roadmap.md) |
| Add a dependency | An exact version at least three days old (`node scripts/pins.ts --resolve <name>`); a 0.x one needs a dated `pinExceptions` entry |
| Add a dependency | An exact version at least three days old (`node scripts/pins.ts --resolve <name>`), written in the catalog of `pnpm-workspace.yaml`, with `catalog:` in the package; a 0.x one needs a dated `pinExceptions` entry in the root `package.json` |

6. **Commit.** Conventional commits, signed off (`git commit -s`). Code with its tests in one commit, documents in another when both are large. Add files by explicit path, then read `git show --stat` of each commit: a commit must contain what its message says. Never push, publish, deploy or open a pull request unless asked.

Expand Down
4 changes: 2 additions & 2 deletions .claude/skills/podbay-security/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -125,8 +125,8 @@ Each boundary below has the same five lines: what crosses it, the invariant, the

- **Crosses:** every package version with its install scripts and licence, every file copied from the seed, and third-party text such as the vendored skill.
- **Invariant:** exact pins, at least three days old, installed from a frozen lockfile; build scripts approved one by one. Licences from the allow-list; no AGPL or GPL. No code, schema, test, text, translation or asset from any other mail product, and none named. Every seed file is listed in `copies.json`. The vendored skill is byte-identical to its manifest.
- **Code today:** `scripts/pins.ts`, `scripts/checks/licences.ts`, `names.ts`, `copies.ts`, `vendored-skills.ts`; `minimumReleaseAge` and `allowBuilds` in `pnpm-workspace.yaml`. On every pull request the job `dependency review` (GitHub's action, pinned by commit, read-only) fails on what the pull request adds with a known vulnerability of any severity, or with a licence off the same allow-list.
- **Proof today:** `pnpm static pins`, `licences`, `names`, `copies`, `vendored`; `test/unit/pins.test.ts`, `test/unit/checks.test.ts` (licences, names), `test/unit/vendored-skills.test.ts`; `test/unit/dependency-review.test.ts` (the review's licences and exemptions equal the static check's and the lockfile's); CI installs with `--frozen-lockfile`; `.github/dependabot.yml` opens weekly update pull requests.
- **Code today:** `scripts/pins.ts` and `scripts/workspace.ts` (every package of the workspace, and the catalog of `pnpm-workspace.yaml` where every version is written once), `scripts/checks/licences.ts` (every package, `-r`), `names.ts`, `copies.ts`, `vendored-skills.ts`; `minimumReleaseAge`, which holds for a catalog entry as for any version (tried on 2026-11-19), and `allowBuilds` in `pnpm-workspace.yaml`. On every pull request the job `dependency review` (GitHub's action, pinned by commit, read-only) fails on what the pull request adds with a known vulnerability of any severity, or with a licence off the same allow-list.
- **Proof today:** `pnpm static pins`, `licences`, `names`, `copies`, `vendored`; `test/unit/pins.test.ts` and `test/unit/licences-workspace.test.ts` (a second package of a workspace held to both rules), `test/unit/checks.test.ts` (licences, names), `test/unit/vendored-skills.test.ts`; `test/unit/dependency-review.test.ts` (the review's licences and exemptions equal the static check's and the lockfile's); CI installs with `--frozen-lockfile`; `.github/dependabot.yml` opens weekly update pull requests.
- **Open:** a unit test for the `copies` check, the vulnerability audit job (S15), the scheduled job that fails on a pin more than one major behind (V2).

### B10. CI and releases
Expand Down
2 changes: 1 addition & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -63,7 +63,7 @@ curl -X POST 'http://localhost:5173/cdn-cgi/local/email?from=a@sender.test&to=he

Short form; the full text and the reason for each is in [docs/engineering-rules.md](docs/engineering-rules.md). **A rule without an automated check is not a rule**, so the table under it says which checks exist today.

1. **Latest, pinned.** Every dependency is one exact stable version, at least three days old when installed. A 0.x package needs a dated `pinExceptions` entry in `package.json`. (V1, V3, V6)
1. **Latest, pinned.** Every dependency is one exact stable version, at least three days old when installed, written once in the catalog of `pnpm-workspace.yaml`; a package names it as `catalog:`. A 0.x package needs a dated `pinExceptions` entry in the root `package.json`. (V1, V3, V6)
2. **Original work only.** No code, schema, test, text, translation or asset from any other mail product, and no other product named in this repository. No dependency under AGPL or GPL. A file that came from the seed stays listed in `copies.json`; when you change one, run `node scripts/checks/copies.ts --fix`. (S17, S15)
3. **Deny by default.** Every API route is in `workers/auth/route-table.ts` with the right it needs; the guard refuses a route that is not there. Access is decided only by `authorize` in `workers/auth/authorize.ts`. A person who is not a member of a mailbox gets 404, whatever their instance role: managing is not reading. The one exception is who the members are: an owner or administrator of the instance sees and changes them without a membership, with fresh proof and on a record the mailbox's owners read. Accounts are never created over HTTP. (S1, S10)
4. **Mail is hostile bytes.** Route by the envelope recipient, never by a header. A name or id from a message or a request never becomes a storage key without going through `workers/lib/inbound.ts` or `workers/lib/filenames.ts`. (S2, S3)
Expand Down
8 changes: 8 additions & 0 deletions biome.json
Original file line number Diff line number Diff line change
Expand Up @@ -34,6 +34,14 @@
"style": {
"noNonNullAssertion": "error"
}
},
"domains": {
"drizzle": "recommended",
"playwright": "recommended",
"react": "recommended",
"tailwind": "recommended",
"tanstackQuery": "recommended",
"test": "recommended"
}
},
"javascript": {
Expand Down
2 changes: 1 addition & 1 deletion docs/engineering-rules.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@

| Rule | Enforcement |
|---|---|
| **V1.** Every dependency starts at its latest stable version and is pinned exactly in one place: the package manifest today, a pnpm catalog once the repository has more than one package | The pins check fails on a range or a pre-release |
| **V1.** Every dependency starts at its latest stable version and is pinned exactly in one place: the catalog of `pnpm-workspace.yaml`, which every package of the workspace names as `catalog:` | The pins check reads every package and fails on a range or a pre-release in the catalog and on a version written in a package |
| **V2.** Updates arrive as automated weekly pull requests. A new major is adopted within 30 days or gets a dated exception in the catalog. A security fix is merged within 48 hours | Update bot; a scheduled job fails when a pin is more than one major behind without an exception |
| **V3.** No pre-release package in production dependencies without a written exception | The pins test rejects `-alpha`, `-beta`, `-rc` and `0.0.x` versions that are not on the exception list |
| **V4.** The Workers `compatibility_date` moves forward every month, with the full test run | Scheduled job opens the pull request |
Expand Down
6 changes: 3 additions & 3 deletions docs/status.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,13 +9,13 @@

| Check | Rules | Where |
|---|---|---|
| Exact pins, 0.x exceptions | V1, V3 | `pnpm static pins`, unit tests |
| Exact pins, 0.x exceptions: every version of the workspace once, in the catalog of `pnpm-workspace.yaml`; every package of the workspace names it as `catalog:` (or `workspace:` for a package of the workspace), and a version written in a package is refused. The exceptions stay in the root `package.json`: a pnpm the project pins refuses a setting of ours in `pnpm-workspace.yaml`. The workspace file is read line by line, and a shape the check does not read (a named catalog) is refused. Biome turns a domain of rules on by itself only for a dependency with a version, so `biome.json` names the domains the catalog would have turned on, and `pnpm static schemas` keeps them in step | V1, V3 | `pnpm static pins`, `pnpm static schemas`; `test/unit/pins.test.ts` (a second package of a fixture workspace that writes its own version is refused), `test/unit/schemas.test.ts` |
| Minimum release age | V6 | `pnpm-workspace.yaml` (`minimumReleaseAge`) |
| Weekly update pull requests | V2 | `.github/dependabot.yml` |
| Compatibility date at most 60 days old | V4 | `pnpm static compat` |
| Every Cloudflare surface in the configuration has a sourced ledger entry | V5 | `pnpm static ledger` |
| Copied files listed, modified ones marked | S17 | `pnpm static copies` |
| Licence allow-list over every installed package | S15, S17 | `pnpm static licences` |
| Licence allow-list over every installed package, of every package of the workspace (`pnpm licenses list -r`: without `-r` it reads the root's dependencies alone, tried on 2026-11-19 with pnpm 12.10.1) | S15, S17 | `pnpm static licences`; `test/unit/licences-workspace.test.ts` (a throwaway workspace whose second package's dependency is GPL is refused) |
| What a pull request adds to the dependencies is read before it merges: it fails on a known vulnerability of any severity in every scope, and on a licence the static check does not allow (the same list, and the same LGPL packages of the toolchain). A licence it cannot detect is reported there and fails only `pnpm static licences`. A required check on `main` since 2026-11-18 | V2, S15, S17 | The job `dependency review` in `.github/workflows/checks.yml` (GitHub's `actions/dependency-review-action`, v5.0.0 pinned by commit); `test/unit/dependency-review.test.ts` holds its inputs to the static check's lists and the lockfile |
| No other mail product named | S17 | `pnpm static names` |
| No credential shapes, no tracked environment file | S6 | `pnpm static secrets` |
Expand All @@ -29,7 +29,7 @@
| The guidance is consistent: `AGENTS.md` is one page and names every skill and subagent; skills are named as their folders; a rule's paths still match files; a subagent names only skills that exist and cannot edit; the settings keep local secrets unread and ask before a push or a deploy | D15 | `pnpm static guidance`, `test/unit/guidance.test.ts` |
| No lint warning: every rule has one level for every file, no file is exempt, and `pnpm lint` fails on a warning (`--error-on-warnings`), so a clean run prints none. A rule is kept off at a place only by a `biome-ignore` that says why (two keyed lists that are never reordered). File size only goes down | D1, D4 | `pnpm lint`, `pnpm static ratchets` (lint warnings at 0) |
| The app's controls are Kumo's (`pnpm static controls`): no `<select>`, `<textarea>`, `<input>` or `<button>` written by hand in `app/`, unless kept on purpose with its reason; no height, size, padding, corner, type size or line height written by hand on a Kumo control, one of its dotted parts or a wrapper of `app/components/controls/`, with or without the important mark, and no `style` attribute on one; no plain element with the role of a control. A tag is read whole, across lines. The controls written by hand before the check came in (62 places in 30 files, six pill buttons, and one list with the role `listbox`) are a debt that only goes down, paid by #82 and #83. Not proven by the check: a control made with `createElement` or a tag in a variable, a Kumo control imported under another name, and a class from a variable or after a `${…}`; those are held by review. A changed screen is looked at in a real browser at both widths and in both themes, with the pictures in the pull request: the skill and the template ask it, and no check holds it | D9 | `scripts/checks/controls.ts`; `test/unit/controls.test.ts`; the `podbay-ui` skill (rule 6, "Before you finish") and `.github/pull_request_template.md` |
| `biome.json` names the schema of the Biome `package.json` pins: an update of the tool cannot leave its configuration behind | V1 | `pnpm static schemas`; `test/unit/schemas.test.ts` |
| `biome.json` names the schema of the Biome the catalog pins: an update of the tool cannot leave its configuration behind | V1 | `pnpm static schemas`; `test/unit/schemas.test.ts` |
| Lint errors, formatting | D1 | `pnpm lint` |
| Types | D1 | `pnpm typecheck` |
| Every API route is in the route table; a non-member gets 404 on every mailbox route; readers cannot change, senders cannot manage | S1 | `test/workerd/access.test.ts`, `test/unit/authorize.test.ts` |
Expand Down
102 changes: 51 additions & 51 deletions package.json
Original file line number Diff line number Diff line change
Expand Up @@ -32,59 +32,59 @@
"auth:ddl": "node scripts/auth-ddl.ts --check"
},
"dependencies": {
"@ai-sdk/provider": "4.0.38",
"@ai-sdk/react": "4.0.177",
"@better-auth/passkey": "1.7.25",
"@cloudflare/ai-chat": "0.12.2",
"@cloudflare/kumo": "2.18.1",
"@modelcontextprotocol/sdk": "1.32.2",
"@modelcontextprotocol/server": "2.4.0",
"@phosphor-icons/react": "2.1.10",
"@tanstack/react-query": "5.107.1",
"@tanstack/react-router": "1.170.46",
"@tiptap/extension-color": "3.34.0",
"@tiptap/extension-highlight": "3.34.0",
"@tiptap/extension-image": "3.34.0",
"@tiptap/extension-link": "3.34.0",
"@tiptap/extension-text-align": "3.34.0",
"@tiptap/extension-text-style": "3.34.0",
"@tiptap/extension-underline": "3.34.0",
"@tiptap/pm": "3.34.0",
"@tiptap/react": "3.34.0",
"@tiptap/starter-kit": "3.34.0",
"agents": "0.33.0",
"ai": "7.0.173",
"better-auth": "1.7.25",
"dompurify": "3.4.18",
"drizzle-orm": "0.45.4",
"hono": "4.13.18",
"jose": "6.2.17",
"postal-mime": "4.2.1",
"react": "19.3.1",
"react-dom": "19.3.1",
"react-markdown": "10.1.0",
"remark-gfm": "4.0.1",
"uqr": "0.1.3",
"zod": "4.6.7",
"zustand": "5.1.0"
"@ai-sdk/provider": "catalog:",
"@ai-sdk/react": "catalog:",
"@better-auth/passkey": "catalog:",
"@cloudflare/ai-chat": "catalog:",
"@cloudflare/kumo": "catalog:",
"@modelcontextprotocol/sdk": "catalog:",
"@modelcontextprotocol/server": "catalog:",
"@phosphor-icons/react": "catalog:",
"@tanstack/react-query": "catalog:",
"@tanstack/react-router": "catalog:",
"@tiptap/extension-color": "catalog:",
"@tiptap/extension-highlight": "catalog:",
"@tiptap/extension-image": "catalog:",
"@tiptap/extension-link": "catalog:",
"@tiptap/extension-text-align": "catalog:",
"@tiptap/extension-text-style": "catalog:",
"@tiptap/extension-underline": "catalog:",
"@tiptap/pm": "catalog:",
"@tiptap/react": "catalog:",
"@tiptap/starter-kit": "catalog:",
"agents": "catalog:",
"ai": "catalog:",
"better-auth": "catalog:",
"dompurify": "catalog:",
"drizzle-orm": "catalog:",
"hono": "catalog:",
"jose": "catalog:",
"postal-mime": "catalog:",
"react": "catalog:",
"react-dom": "catalog:",
"react-markdown": "catalog:",
"remark-gfm": "catalog:",
"uqr": "catalog:",
"zod": "catalog:",
"zustand": "catalog:"
},
"devDependencies": {
"@biomejs/biome": "2.6.8",
"@cloudflare/vite-plugin": "1.69.1",
"@cloudflare/vitest-plugin": "1.8.2",
"@playwright/test": "1.65.1",
"@tailwindcss/vite": "4.3.5",
"@types/jsdom": "30.0.0",
"@types/node": "24.19.2",
"@types/react": "19.3.0",
"@types/react-dom": "19.3.0",
"@vitejs/plugin-react": "6.3.0",
"jsdom": "31.0.1",
"tailwindcss": "4.3.5",
"typescript": "7.0.2",
"vite": "8.3.8",
"vitest": "5.1.0",
"wrangler": "4.162.0"
"@biomejs/biome": "catalog:",
"@cloudflare/vite-plugin": "catalog:",
"@cloudflare/vitest-plugin": "catalog:",
"@playwright/test": "catalog:",
"@tailwindcss/vite": "catalog:",
"@types/jsdom": "catalog:",
"@types/node": "catalog:",
"@types/react": "catalog:",
"@types/react-dom": "catalog:",
"@vitejs/plugin-react": "catalog:",
"jsdom": "catalog:",
"tailwindcss": "catalog:",
"typescript": "catalog:",
"vite": "catalog:",
"vitest": "catalog:",
"wrangler": "catalog:"
},
"pinExceptions": {
"@cloudflare/ai-chat": "2026-11-17: 0.x, no stable release exists; the agent is optional and off by default",
Expand Down
Loading
Loading