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
56 changes: 29 additions & 27 deletions CLAUDE.md

Large diffs are not rendered by default.

5 changes: 2 additions & 3 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ This is a pnpm + Turbo monorepo (`packageManager: pnpm@10`, Node 20+ recommended
```sh
pnpm install
pnpm migrations:local # apply D1 migrations to the shared local dev state
pnpm dev # frontend :5173, api :8787, auth :8788, admin :8789
pnpm dev # frontend :5173, api :8787, admin :8789 (+ admin SPA :5174)
```

The dev servers share one local state at the monorepo root (`.wrangler/state`). Worker config lives only in each package's `cloudflare.config.ts` (+ `wrangler.config.ts` for build settings) - there is no `wrangler.toml`. Local migrations (`pnpm migrate`) pass `--persist-to ../../.wrangler/state` from the package directory; for ad-hoc local SQL use `node scripts/d1-local.mjs <main|auth> "<sql>"` while `pnpm dev` is running. All wrangler invocations go through `npx wrangler`.
Expand All @@ -16,7 +16,6 @@ The dev servers share one local state at the monorepo root (`.wrangler/state`).

- `packages/frontend` - React 19 SPA (Vite, Tailwind CSS 4, shadcn/ui)
- `packages/api` - Core Cloudflare Worker (projects, docs, files)
- `packages/auth` - Auth Cloudflare Worker (login, register, TOTP, WebAuthn, OIDC)
- `packages/admin` - Admin Cloudflare Worker + admin frontend
- `e2e` - Playwright end-to-end tests

Expand Down Expand Up @@ -63,5 +62,5 @@ When you add behavior in an area that already has a test suite, extend that suit
## Pull requests

- Keep PRs focused on one change; separate refactors from behavior changes.
- Schema changes: migrations live only in `packages/api/migrations/` and `packages/auth/migrations/`. A change to auth-DB columns read by `loadCurrentSession` requires redeploying auth + api + admin, in that order - call this out in the PR description.
- Schema changes: migrations live only in `packages/api/migrations/` (cubedocs-main, shared by the api and admin workers). A change to columns read by `loadCurrentSession` (users mirror, sessions, user_billing, user_preferences, user_deletions) needs both workers redeployed (api first) - call this out in the PR description. Accounts themselves live on auth.cubityfir.st.
- If you add or remove a runtime dependency in `packages/frontend`, update `src/lib/acknowledgements.ts` to match.
29 changes: 13 additions & 16 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -80,18 +80,15 @@ Create local secrets files for each Worker:

```bash
cp packages/api/.dev.vars.example packages/api/.dev.vars
cp packages/auth/.dev.vars.example packages/auth/.dev.vars
cp packages/admin/.dev.vars.example packages/admin/.dev.vars
```

Both Workers need a shared `JWT_SECRET`:

```ini
# packages/api/.dev.vars
JWT_SECRET=your-secret-here

# packages/auth/.dev.vars
JWT_SECRET=your-secret-here # must match api
```
Accounts live on the identity service at auth.cubityfir.st, and Annex signs
in through it with OpenID Connect. Locally you can either run that worker (its
repo, `npx wrangler dev --port 8790`) and register local clients as described
in the `.dev.vars.example` files, or skip it: with `DEV_QUICK_LOGIN=true` (the
default in the example) `/login` shows dev quick-login buttons. See
`memories/Identity-Client.md`.

**3. Apply local database migrations**

Expand All @@ -113,7 +110,7 @@ Starts all packages concurrently. Once running:
|---|---|
| Frontend | http://localhost:5173 |
| API Worker | http://localhost:8787 |
| Auth Worker | http://localhost:8788 |
| Admin Worker | http://localhost:8789 |
| Admin Dashboard | http://localhost:5174 |

The frontend dev server automatically proxies `/api` requests to the local Workers - no separate configuration needed.
Expand All @@ -138,7 +135,7 @@ Then `stripe login` once to authorise the CLI against your Stripe account.
**2. Add Stripe secrets to `.dev.vars`**

```ini
# packages/auth/.dev.vars
# packages/api/.dev.vars
STRIPE_SECRET_KEY=sk_test_... # from Stripe Dashboard → API keys (test mode)
STRIPE_WEBHOOK_SECRET=whsec_... # filled in step 3
STRIPE_INK_PRICE_ID=price_... # the test-mode Annex Ink price id
Expand All @@ -148,18 +145,18 @@ APP_ORIGIN=http://localhost:5173 # so Checkout redirects come back to loc
STRIPE_SECRET_KEY=sk_test_... # same value, for admin-driven cancels
```

**3. Forward Stripe webhooks to the local auth worker**
**3. Forward Stripe webhooks to the local api worker**

In a separate terminal alongside `pnpm dev`:

```bash
pnpm dev:stripe
# (equivalent to: stripe listen --forward-to http://localhost:8788/stripe/webhook)
# (equivalent to: stripe listen --forward-to http://localhost:8787/stripe/webhook)
```

The CLI prints a `whsec_...` at startup - paste it into `packages/auth/.dev.vars` as `STRIPE_WEBHOOK_SECRET`, then restart the auth worker dev so it picks up the new value. The `whsec_` printed by the CLI is only valid for events forwarded by that CLI session; it's separate from the live-mode webhook secret in the Stripe Dashboard.
The CLI prints a `whsec_...` at startup - paste it into `packages/api/.dev.vars` as `STRIPE_WEBHOOK_SECRET`, then restart the api worker dev so it picks up the new value. The `whsec_` printed by the CLI is only valid for events forwarded by that CLI session; it's separate from the live-mode webhook secret in the Stripe Dashboard.

Without `pnpm dev:stripe` running, the local auth worker will accept webhook POSTs from the public internet but won't see any. Local checkouts will succeed at Stripe, but local DB state won't update until events are forwarded.
Without `pnpm dev:stripe` running, the local api worker will accept webhook POSTs from the public internet but won't see any. Local checkouts will succeed at Stripe, but local DB state won't update until events are forwarded.

## Direct video streaming via presigned R2 URLs (optional)

Expand Down
6 changes: 3 additions & 3 deletions e2e/d1Local.ts
Original file line number Diff line number Diff line change
Expand Up @@ -6,12 +6,12 @@ const SCRIPT = resolve(__dirname, "../scripts/d1-local.mjs");
/**
* Run SQL against the local dev D1 (the shared .wrangler/state behind
* `pnpm dev`) via scripts/d1-local.mjs - the config-free replacement for
* `npx wrangler d1 execute <db> --local`. `main` = cubedocs-main (api DB),
* `auth` = cubedocs-auth. Needs the api dev server (:8787) running, which every
* `npx wrangler d1 execute <db> --local`. `main` = cubedocs-main (the only
* database). Needs the api dev server (:8787) running, which every
* e2e spec already does. Spawned without a shell, so SQL quotes pass through
* verbatim. Throws with the helper's error message on failure.
*/
export function d1Local(db: "main" | "auth", sql: string): void {
export function d1Local(db: "main", sql: string): void {
try {
execFileSync(process.execPath, [SCRIPT, db, sql], { stdio: "pipe" });
} catch (err) {
Expand Down
18 changes: 7 additions & 11 deletions e2e/global-teardown.ts
Original file line number Diff line number Diff line change
Expand Up @@ -10,12 +10,12 @@ import { d1Local } from "./d1Local";
// so it writes the local D1 directly (scripts/d1-local.mjs, via the running
// api dev server). It also runs on Playwright failure exits.
//
// FK cascades handle most of the auth-DB tail (sessions, webauthn, backup
// codes, moderation events). email_verification_tokens has no cascade, so we
// delete it explicitly first. On the API DB, deleting projects cascades
// everything below (docs, folders, files, members, invite links).
// Accounts live on auth.cubityfir.st; Annex keeps a users mirror in
// cubedocs-main, where deleting a mirror row cascades its sessions, billing
// and preferences. Deleting projects cascades everything below them (docs,
// folders, files, members, invite links).
export default async function globalTeardown() {
const run = (db: "main" | "auth", sql: string) => {
const run = (db: "main", sql: string) => {
try {
d1Local(db, sql);
} catch (err) {
Expand All @@ -25,12 +25,8 @@ export default async function globalTeardown() {
}
};

// Auth DB: orphan tokens first, then users (cascades the rest).
run(
"auth",
"DELETE FROM email_verification_tokens WHERE user_id IN (SELECT id FROM users WHERE email LIKE 'e2e-%@example.com');",
);
run("auth", "DELETE FROM users WHERE email LIKE 'e2e-%@example.com';");
// Users mirror (e2e users are dev quick-login users or e2e-* addresses).
run("main", "DELETE FROM users WHERE email LIKE 'e2e-%@example.com';");

// API DB: delete e2e-suite projects by name prefix (cascades everything).
// Patterns track the names used in app.spec.ts, invites.spec.ts, and
Expand Down
28 changes: 28 additions & 0 deletions e2e/signIn.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,28 @@
import type { Page } from "@playwright/test";

/**
* Signs a browser page in as a local-dev Annex user without the identity
* service. Accounts live on auth.cubityfir.st now, so the suites can no
* longer register through Annex's own forms; this uses the api worker's
* localhost-only POST /api/dev/quick-login (packages/api/src/routes/auth.ts),
* which needs `DEV_QUICK_LOGIN=true` and `APP_ORIGIN=http://localhost:5173`
* in packages/api/.dev.vars.
*
* The same email always maps to the same dev user, so a spec can sign the
* same person back in. Use `e2e-…@example.com` addresses so global-teardown
* cleans them up.
*/
export async function devSignIn(
page: Page,
user: { email: string; name?: string; admin?: boolean },
): Promise<{ token: string; userId: string }> {
const res = await page.request.post("/api/dev/quick-login", { data: user });
if (!res.ok()) throw new Error(`dev quick-login failed (${res.status()}): is DEV_QUICK_LOGIN=true set for the api worker?`);
const { data } = (await res.json()) as { data: { token: string; userId: string } };
// The SPA keeps its session JWT in localStorage["token"] (src/lib/auth.ts).
await page.goto("/");
await page.evaluate(token => window.localStorage.setItem("token", token), data.token);
// Land where a sign-in does.
await page.goto("/dashboard");
return data;
}
Loading
Loading