chadtmiller.com/pds.js

Switch repository

Loading…

# App Platform — Phase 1: Serve Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** Serve static sites from the account repo (blobs + a `dev.pdsjs.site.deploy` manifest record) on the deployment's apex and one-label subdomains, via a new `@pdsjs/sites` package and one hostname-dispatch seam in core, with a deploy CLI and an account-UI Sites page.

**Architecture:** New workspace package `packages/sites`, workspace-only dependency on `@pdsjs/core`. Core gains `config.siteHandler` / `config.siteBrowser` and one hostname check at the top of `fetch()`; platform packages gate on `PDS_SITE_DOMAIN` and compose the handler from ports. Site content never renders on the PDS origin.

**Tech Stack:** plain ESM JS + JSDoc types, vitest, biome (single quotes, 2-space indent), one commit per task.

## Global Constraints

- Spec: `docs/superpowers/specs/2026-08-06-app-platform-serve.md`.
- `@pdsjs/sites` has **zero external dependencies**; workspace-only dependency on `@pdsjs/core`. `src/cli.js` is the only file allowed to import `node:*` modules, and nothing on the serve path imports it.
- `@pdsjs/core` must never import `@pdsjs/sites`. Dependency direction is one-way.
- **No dependency on `@pdsjs/spaces`** in any direction; everything works with `PDS_ENABLE_SPACES` off.
- No `any` in library type annotations; `/** @type {any} */` casts are allowed only in test mocks.
- Tests at `packages/sites/test/*.test.js` (vitest already includes them). CI runs biome + `tsc --noEmit` + unit tests only — unit coverage gates everything.
- The flag-off path is load-bearing: with no `siteHandler`, foreign-Host requests behave byte-identically to today. Explicit test.
- Branch: `app-platform-serve`.

---

### Task 1: Spec + scaffolding + hostname resolution
Create `packages/sites/{package.json, src/index.js, src/hostname.js, src/lexicons.js}` and `test/hostname.test.js` (apex match, valid/invalid labels, case folding, 63-char bounds, multi-label, unrelated domains → null).

### Task 2: Manifest loading
`src/manifest.js`: `getRecord` → `cborDecode` → one-hop `base` merge (refuse deeper) → `Map<path, entry>`; module-level LRU (≤32) keyed by record CID. Tests with an in-memory actorStorage mock built on `cborEncodeDagCbor`.

### Task 3: Serve handler
`src/serve.js` + `src/handler.js` (`createSiteHandler(ctx)`), per the spec's serving semantics §3. Tests: null on unrelated host; unknown-site 404; index/trailing-slash/301; traversal + bad-encoding 400s; SPA fallback 200; ETag/304 and HEAD asserted to make zero blob reads (mock call counts); MIME precedence; cacheControl override; 405s incl. OPTIONS; `/.well-known/atproto-did`.

### Task 4: Core seam
`packages/core/src/pds.js`: `siteHandler`/`siteBrowser` constructor options, `sitesEnabled`, hostname check at top of `fetch()` (before the OPTIONS short-circuit, outside `withDpopNonce`, no `addCorsHeaders`, before the account-app intercept). `packages/core/src/ports.js`: `SiteBrowserPort`. Seam tests via `pds.fetch` with foreign Host headers per spec §10; audit that no fall-through path derives OAuth issuer URLs from `url.host`.

### Task 5: Site browser + account API
`src/browser.js`; core `handleApiSites` / `handleApiSiteDelete` via the `accountApi` wrapper, route-table lines, `features.sites`. Tests in the account-page style + a readOnly-mode test.

### Task 6: Cloudflare wiring
Env typedef (`PDS_SITE_DOMAIN`, `PDS_SITE_APEX_NAME`), DO-constructor gate next to spaces, config passthrough; `examples/cloudflare/wrangler.toml` route/DNS comments; `.dev.vars` note. Tests: flag-off/flag-on via the d1-shim harness.

### Task 7: Node/Deno wiring
Dynamic import behind `PDS_SITE_DOMAIN`, optional peer dep, README notes (reverse proxy, wildcard certs). Tests: flag-off/flag-on.

### Task 8: Deploy CLI
`src/deploy.js` pure helpers (walk/diff/record-build) + `src/cli.js` (`pdsjs-site deploy`). Tests: CID-stable diff/skip, oversize abort, record-size abort, MIME assignment.

### Task 9: Account-UI Sites page
`packages/account-ui/src/pages/sites.jsx`, `app.jsx` wiring (sectionsFor/PAGES/dispatch), `queryKeys.sites`; rebuild assets.

### Task 10: README
Root README package table, architecture diagram arrow (platforms → sites → core), env-var docs.

### Later phases (not this plan)
Grant (install gate + consent skip), store/install flow + Store UI, Query, React, Schedule — sketched in the spec §9.