diff --git a/.env.example b/.env.example index a432c9c..f088b6b 100644 --- a/.env.example +++ b/.env.example @@ -1,9 +1,60 @@ -# Database +# ============================================================================= +# Environment variables — copy this file to .env and fill in your values. +# See docs/guides/runbook.md for the full reference. +# ============================================================================= + +# --- Required for `pnpm dev` --- + +# Postgres connection. Matches `docker compose up -d` default. DATABASE_URL=postgresql://postgres:postgres@localhost:5433/template -# Payload CMS -PAYLOAD_SECRET=your-secret-here +# Payload CMS encryption key. Any random 32+ char string in dev. +PAYLOAD_SECRET=replace-with-a-random-32-char-string + +# --- Optional: app URLs (defaults work in dev) --- -# App URLs NEXT_PUBLIC_APP_URL=http://localhost:3000 CMS_URL=http://localhost:3001 + +# Force dev-seed binders (mock repos) regardless of NODE_ENV. Useful for +# running pnpm dev without Payload booted. +# USE_DEV_SEED=true + +# --- Optional: Sentry observability --- +# Leaving these unset → instrumentation falls back to the no-op tracer/logger. +# Set the DSN for any app you want OTel + Sentry on. + +# WEB_NEXT_SENTRY_DSN= +# NEXT_PUBLIC_WEB_NEXT_SENTRY_DSN= +# CMS_SENTRY_DSN= +# WEB_TANSTACK_SENTRY_DSN= +# VITE_WEB_TANSTACK_SENTRY_DSN= + +# Source-map upload at build time (production only). +# SENTRY_AUTH_TOKEN= +# SENTRY_ORG= +# SENTRY_PROJECT_WEB_NEXT= +# SENTRY_PROJECT_CMS= +# SENTRY_PROJECT_WEB_TANSTACK= + +# OTel trace sample rate (0.0 = none, 1.0 = all). 0.1 recommended in dev. +# SENTRY_TRACES_SAMPLE_RATE=0.1 +# SENTRY_ENVIRONMENT=development + +# --- Optional: git commit SHA for releases --- + +# VERCEL_GIT_COMMIT_SHA= +# NEXT_PUBLIC_VERCEL_GIT_COMMIT_SHA= +# VITE_GIT_COMMIT_SHA= + +# --- Optional: core-audit (only when `gen core-package audit` is scaffolded) --- + +# Salt for GDPR pseudonymisation. PRODUCTION MUST set this to a stable secret. +# AUDIT_PSEUDONYM_SALT= + +# --- Optional: sandcastle dispatch (only when running `pnpm work dispatch --execute`) --- + +# ANTHROPIC_API_KEY= +# OPENAI_API_KEY= +# GITHUB_TOKEN= +# SANDCASTLE_PROVIDER=docker diff --git a/CLAUDE.md b/CLAUDE.md index 6413b53..6385f7c 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -3,20 +3,30 @@ ## Quick Start ```bash -pnpm install # Install all dependencies -pnpm dev # Start all dev servers -pnpm build # Build all packages -pnpm test # Run all tests -pnpm turbo boundaries # Validate workspace dependency graph -pnpm turbo gen feature # Scaffold a new feature package (see docs/guides/scaffolding-a-feature.md) -pnpm turbo gen event # Scaffold an event contract (publish) or handler (consume) -pnpm turbo gen job # Scaffold a background job -pnpm turbo gen realtime # Scaffold a realtime channel or inbound handler -pnpm turbo gen core-package # Scaffold an optional core package (see docs/scaffolding/core-package-generator.md) -pnpm turbo gen core-ui-component # Scaffold a core-ui atomic-design component (see docs/scaffolding/core-ui-component-generator.md) -docker compose up -d # Start PostgreSQL +pnpm install # Install + auto-wire husky pre-commit hooks +pnpm dev # Start all dev servers +pnpm build # Build all packages +pnpm test # Run all tests +pnpm typecheck # TypeScript across all packages +pnpm lint # ESLint (incl. 8 conformance/* rules) +pnpm conformance # Cross-feature event closure +pnpm fallow # Whole-codebase: dead exports, dupes, complexity +pnpm fallow:audit # AI-change audit (run before commits) +pnpm turbo boundaries # Workspace dependency graph +pnpm work status # docs/work/ epic + story state +pnpm work next # Next ready story +pnpm work dispatch # Print next dispatch plan (use --execute to invoke sandcastle) +pnpm turbo gen feature # Scaffold a new feature package +pnpm turbo gen event # Scaffold an event contract or handler +pnpm turbo gen job # Scaffold a background job +pnpm turbo gen realtime # Scaffold a realtime channel or handler +pnpm turbo gen core-package # Scaffold an optional core package +pnpm turbo gen core-ui-component # Scaffold an atomic-design component +docker compose up -d # Start PostgreSQL ``` +**First time?** Read [`docs/guides/runbook.md`](./docs/guides/runbook.md) end-to-end. + ## TDD ```bash diff --git a/README.md b/README.md index 6907290..8784754 100644 --- a/README.md +++ b/README.md @@ -1,22 +1,51 @@ # Clean Architecture Monorepo Template -Turborepo + pnpm monorepo organized by vertical features. See `CLAUDE.md` for the full conventions reference and `AGENTS.md` for the package map. +Turborepo + pnpm monorepo organised by vertical features, with an **agent-first workflow** and **five conformance gates**. -## Quick Start +## Start here + +Read [`docs/guides/runbook.md`](./docs/guides/runbook.md) — day-1 onboarding (prerequisites, env vars, daily commands, troubleshooting). + +## Quick reference ```bash -pnpm install # Install all dependencies -pnpm dev # Start all dev servers -pnpm build # Build all packages -pnpm test # Run all tests -pnpm turbo boundaries # Validate workspace dependency graph -pnpm turbo gen feature # Scaffold a new feature package +pnpm install # Install + auto-wire husky pre-commit hooks +pnpm dev # All dev servers (web-next:3000, cms:3001, web-tanstack:3002, storybook:6006) +pnpm test # All tests +pnpm typecheck # TypeScript across all packages +pnpm lint # ESLint (incl. 8 conformance/* rules) +pnpm conformance # Cross-feature event closure +pnpm fallow # Whole-codebase: dead exports, dupes, complexity +pnpm turbo boundaries # Workspace dependency graph +pnpm work status # docs/work/ epic + story state docker compose up -d # Start PostgreSQL ``` +## Documentation map + +- **[`docs/guides/runbook.md`](./docs/guides/runbook.md)** — start here +- **[`CLAUDE.md`](./CLAUDE.md)** — full conventions reference +- **[`AGENTS.md`](./AGENTS.md)** — package map + boundary rules +- **[`docs/guides/conformance-quickref.md`](./docs/guides/conformance-quickref.md)** — manifest + 5-gate daily reference +- **[`docs/architecture/agent-first-workflow-and-conformance.md`](./docs/architecture/agent-first-workflow-and-conformance.md)** — full design +- **[`docs/architecture/feature-conformance-explainer.html`](./docs/architecture/feature-conformance-explainer.html)** — interactive explainer + +## Scaffolding + +```bash +pnpm turbo gen feature # Lazar-conformant feature (manifest + contracts + tests) +pnpm turbo gen event # Event contract or handler (requires gen core-package events) +pnpm turbo gen job # Background job +pnpm turbo gen realtime # Realtime channel (requires gen core-package realtime) +pnpm turbo gen core-package # Optional core: events / realtime / trpc / ui / audit +pnpm turbo gen core-ui-component # Atomic-design component +``` + +**Generator-first is non-negotiable** — hand-rolled feature/event/job/realtime/component code is rejected by reviewer agents and may fail the CI scaffold-drift check. + ## Optional packages -The default template includes the must-have core packages and all 5 feature packages. Five core packages are optional and scaffold on demand: +Five core packages scaffold on demand: ```bash pnpm turbo gen core-package realtime # Socket.IO realtime layer (ADR-016) @@ -26,14 +55,4 @@ pnpm turbo gen core-package ui # Design system pnpm turbo gen core-package audit # DPA-compliant audit logging (ADR-018) ``` -See `docs/architecture/template-tiers.md` for the full tier list. - -## Key ports - -| Service | Port | -|---|---| -| Next.js | 3000 | -| Payload CMS | 3001 | -| TanStack Start | 3002 | -| PostgreSQL | 5432 | -| Storybook | 6006 | +See [`docs/architecture/template-tiers.md`](./docs/architecture/template-tiers.md) for the full tier list.