workspace-cloud

Imported from json-choi/dopedb (workspace-cloud/AGENTS.md). Install upstream with npx skills add json-choi/dopedb --skill workspace-cloud. Copyright stays with the author.

workspace-cloud

Purpose

Workspace Web: the authenticated web and API control plane for DopeDB workspaces, deployed as its own Next.js 16 (App Router) application built with @opennextjs/cloudflare onto Cloudflare Workers (app.dopedb.dev), separate from the Tauri desktop app in ../src/../src-tauri and from the marketing ../site. It is a distinct trust boundary: Cloudflare D1 (via the WORKSPACE_DB binding declared in wrangler.jsonc) is the live store for workspace identity, membership, audit metadata, secret-free shared connection templates, and encrypted provider-integration material. Per the product's shared-access axis (root AGENTS.md/CLAUDE.md), this app must never store a member-local database password, an ordinary query result row, or any other long-lived secret in a shared record; managed access is issued as short-lived, member-specific credentials at request time. Workspace administration (members, DB access, providers, backups and deletion, account sessions) is a DopeDB Desktop Settings surface (../src/features/workspaceAdmin/, ADR ../docs/adr/0009-desktop-workspace-administration.md) that calls this app's /api/v1 routes with the account's Bearer session; the browser keeps only sign-in, Desktop approval, invitation acceptance, provider authorization start/complete pages, public Articles, and a settings-moved notice. A companion Cloudflare Worker in infrastructure/ (a separate deploy target) mints the short-lived Workload Identity Federation tokens this app uses to reach GCP; it is not part of the Next.js build.

Key Files

Subdirectories

For AI Agents

Working In This Directory

• This is a separate pnpm project inside the repo (its own pnpm-lock.yaml/pnpm-workspace.yaml); run its scripts with pnpm --dir workspace-cloud <script> or the repo-root pnpm workspace:cloud:* aliases, not from the repo root directly.
• D1 (lib/d1/schema/, migrated via d1-migrations/) owns the current production schema.
• app/analyses/[slug]/PublicAnalysisArticle.tsx imports AnalysisArticleBody directly from the sibling Tauri desktop app's ../../src/design-system/components/AnalysisArticleBody.tsx (also referenced by a Tailwind @source scan in app/globals.css) — this is a real, intentional cross-project dependency for the shared Analysis Article rendering primitive, not an accident; keep it in sync with the desktop src/design-system/ component if either changes.
• Public Analysis Article publications are immutable HTML snapshots that never execute the saved query at read time (see docs/adr/0007-analysis-article-bi-domain.md at the repo root); middleware.ts additionally forces cache-control: private, no-store on /analyses/*, /article-invitations/*, and /open-article/* so a revoked publication or a private handoff link cannot be served from a shared cache.
• Long-lived secrets are never written into a shared/workspace record; managed provider credentials are issued as short-lived, member-specific leases at request time (see lib/AGENTS.md, lib/provider-integrations/AGENTS.md, and the connection-lease routes in app/AGENTS.md).
• Provider OAuth started from Desktop opens only this origin's /auth/provider/start page, which never consumes the state and continues to the provider only for the browser account that started it. The PlanetScale and GCP callbacks must keep checking the cookie session's user against the state's user; never relax them to trust the state alone (ADR 0009).
• Follow the repo-root AGENTS.md/CLAUDE.md rule that connecting, reconnecting, importing, repairing, or issuing/revoking credentials must never rewrite a pre-existing application user, role membership, grant, default privilege, or ACL; this app's D1 schema only ever records DopeDB's own workspace-management state (see d1-migrations/AGENTS.md).
• No provider API is ever called directly from application code outside the officially adapted flows this app owns (OAuth/API-key provider integrations for GCP Cloud SQL, Neon, PlanetScale, Vault); the AI-provider "official CLI only" rule in root CLAUDE.md is a separate boundary and does not apply to this sub-project's own database-provider integrations.

Testing Requirements

• pnpm workspace:cloud:build (repo root) / pnpm --dir workspace-cloud build — Next.js build; the baseline check for any change here.
• pnpm --dir workspace-cloud test:contracts (repo-root alias pnpm check:knowledge) — Vitest wire-contract/serialization suite (lib/control-plane-contracts.harness.ts, lib/d1-storage.harness.ts); does not exercise app/** route handlers directly.
• bash scripts/test-provider-import-d1.sh (repo root; execs workspace-cloud/scripts/test-d1-migrations.mjs, equivalently pnpm --dir workspace-cloud test:d1-import) — run for any change to d1-migrations/, scripts/migrate-d1.mjs, or scripts/migrate-production.sh; exercises the production migration entry point against an isolated, disposable local D1.
• pnpm workspace:cloud:verify-deployment <worker-version-id> (repo root, runs scripts/check-workspace-deployment.mjs) — required before reporting a deployment as successful; confirms the named Worker version is receiving 100% of production traffic and matches the live production-domain deployment receipt. A local build or test pass alone is never deployment evidence.
• pnpm lint (repo root; lint:hooks → eslint src workspace-cloud site --ext .ts,.tsx --max-warnings 0) lints this directory's .ts/.tsx files with zero warnings allowed, despite its script name.
• Any UI change under app/ or features/ also needs a manual check per root AGENTS.md/CLAUDE.md; there is no route-level HTTP integration test suite for app/api/** in this repository.

Common Patterns

• Server-only data/session logic lives in lib/; app/**/route.ts and page.tsx files are thin HTTP/RSC boundaries over it, and page-spanning feature modules (currently only articleSharing/) live in features/. See app/AGENTS.md for the six-step mutating-route pattern (origin check → capability authorization → optimistic-revision check → scoped DB lookup → body validation → versioned/gated commit) that most route.ts files follow.
• Wire contracts are hand-validated at both the sender and receiver (strict parsers rejecting unexpected shape) rather than trusted from a shared type import alone — see the Desktop administration parsers under ../src/features/workspaceAdmin/ (e.g. providers/neonBranches/branchInventory.ts) and lib/AGENTS.md's contract files.

Dependencies

Internal

• ../src/design-system/components/AnalysisArticleBody.tsx (see note above), WorkspaceIdentity.tsx (identity shell primitives for the auth, invitation, handoff, settings-moved, and error pages), DopeDBMarkGraphic.tsx (app/components/Brand.tsx), and ../src/design-system/workspace.css (imported by app/globals.css) — the cross-project imports from the Tauri desktop app's frontend.
• ../docs/adr/0007-analysis-article-bi-domain.md — the ADR this app's Analysis Article sharing/publication model implements.
• ../docs/adr/0009-desktop-workspace-administration.md and ../src/features/workspaceAdmin/ — the decision that moved workspace administration out of this app, and the Desktop Settings client of its administration routes.
• ../scripts/deploy-workspace-cloudflare.mjs, ../scripts/check-workspace-deployment.mjs, ../scripts/test-provider-import-d1.sh — repo-root automation that builds, deploys, and verifies this sub-project.

External

• next 16, react/react-dom 19, drizzle-orm 0.45 + drizzle-kit, better-auth + @better-auth/drizzle-adapter, @neondatabase/serverless, sanitize-html, pretendard (font).
• wrangler, @opennextjs/cloudflare, miniflare (devDependencies; Cloudflare build/deploy/local-runtime tooling).
• vitest (contract and provider-harness test runners).