pan-wizard 2.8.1

package/pan-wizard-core/templates/codebase/integrations.md

@@ -0,0 +1,305 @@
+# External Integrations Template
+
+Template for `.planning/codebase/INTEGRATIONS.md` - captures external service dependencies.
+
+**Purpose:** Document what external systems this codebase communicates with. Focused on "what lives outside our code that we depend on."
+
+---
+
+## File Template
+
+```markdown
+# External Integrations
+
+**Analysis Date:** [YYYY-MM-DD]
+
+## Data Architecture
+
+### External Service Map
+
+```mermaid
+graph LR
+    App[Application] --> DB[(Database)]
+    App --> Cache[(Cache)]
+    App --> Auth[Auth Provider]
+    App --> API[External APIs]
+    App --> Storage[File Storage]
+    App --> Monitor[Monitoring]
+```
+
+### Entity Relationships
+
+[Include only when database/ORM is detected]
+
+```mermaid
+erDiagram
+    USER ||--o{ ORDER : places
+    ORDER ||--|{ LINE_ITEM : contains
+    PRODUCT ||--o{ LINE_ITEM : "appears in"
+```
+
+## APIs & External Services
+
+**Payment Processing:**
+- [Service] - [What it's used for: e.g., "subscription billing, one-time payments"]
+  - SDK/Client: [e.g., "stripe npm package v14.x"]
+  - Auth: [e.g., "API key in STRIPE_SECRET_KEY env var"]
+  - Endpoints used: [e.g., "checkout sessions, webhooks"]
+
+**Email/SMS:**
+- [Service] - [What it's used for: e.g., "transactional emails"]
+  - SDK/Client: [e.g., "sendgrid/mail v8.x"]
+  - Auth: [e.g., "API key in SENDGRID_API_KEY env var"]
+  - Templates: [e.g., "managed in SendGrid dashboard"]
+
+**External APIs:**
+- [Service] - [What it's used for]
+  - Integration method: [e.g., "REST API via fetch", "GraphQL client"]
+  - Auth: [e.g., "OAuth2 token in AUTH_TOKEN env var"]
+  - Rate limits: [if applicable]
+
+## Data Storage
+
+**Databases:**
+- [Type/Provider] - [e.g., "PostgreSQL on Supabase"]
+  - Connection: [e.g., "via DATABASE_URL env var"]
+  - Client: [e.g., "Prisma ORM v5.x"]
+  - Migrations: [e.g., "prisma migrate in migrations/"]
+
+**File Storage:**
+- [Service] - [e.g., "AWS S3 for user uploads"]
+  - SDK/Client: [e.g., "@aws-sdk/client-s3"]
+  - Auth: [e.g., "IAM credentials in AWS_* env vars"]
+  - Buckets: [e.g., "prod-uploads, dev-uploads"]
+
+**Caching:**
+- [Service] - [e.g., "Redis for session storage"]
+  - Connection: [e.g., "REDIS_URL env var"]
+  - Client: [e.g., "ioredis v5.x"]
+
+## Authentication & Identity
+
+**Auth Provider:**
+- [Service] - [e.g., "Supabase Auth", "Auth0", "custom JWT"]
+  - Implementation: [e.g., "Supabase client SDK"]
+  - Token storage: [e.g., "httpOnly cookies", "localStorage"]
+  - Session management: [e.g., "JWT refresh tokens"]
+
+**OAuth Integrations:**
+- [Provider] - [e.g., "Google OAuth for sign-in"]
+  - Credentials: [e.g., "GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET"]
+  - Scopes: [e.g., "email, profile"]
+
+## Monitoring & Observability
+
+**Error Tracking:**
+- [Service] - [e.g., "Sentry"]
+  - DSN: [e.g., "SENTRY_DSN env var"]
+  - Release tracking: [e.g., "via SENTRY_RELEASE"]
+
+**Analytics:**
+- [Service] - [e.g., "Mixpanel for product analytics"]
+  - Token: [e.g., "MIXPANEL_TOKEN env var"]
+  - Events tracked: [e.g., "user actions, page views"]
+
+**Logs:**
+- [Service] - [e.g., "CloudWatch", "Datadog", "none (stdout only)"]
+  - Integration: [e.g., "AWS Lambda built-in"]
+
+## CI/CD & Deployment
+
+**Hosting:**
+- [Platform] - [e.g., "Vercel", "AWS Lambda", "Docker on ECS"]
+  - Deployment: [e.g., "automatic on main branch push"]
+  - Environment vars: [e.g., "configured in Vercel dashboard"]
+
+**CI Pipeline:**
+- [Service] - [e.g., "GitHub Actions"]
+  - Workflows: [e.g., "test.yml, deploy.yml"]
+  - Secrets: [e.g., "stored in GitHub repo secrets"]
+
+## Environment Configuration
+
+**Development:**
+- Required env vars: [List critical vars]
+- Secrets location: [e.g., ".env.local (gitignored)", "1Password vault"]
+- Mock/stub services: [e.g., "Stripe test mode", "local PostgreSQL"]
+
+**Staging:**
+- Environment-specific differences: [e.g., "uses staging Stripe account"]
+- Data: [e.g., "separate staging database"]
+
+**Production:**
+- Secrets management: [e.g., "Vercel environment variables"]
+- Failover/redundancy: [e.g., "multi-region DB replication"]
+
+## Webhooks & Callbacks
+
+**Incoming:**
+- [Service] - [Endpoint: e.g., "/api/webhooks/stripe"]
+  - Verification: [e.g., "signature validation via stripe.webhooks.constructEvent"]
+  - Events: [e.g., "payment_intent.succeeded, customer.subscription.updated"]
+
+**Outgoing:**
+- [Service] - [What triggers it]
+  - Endpoint: [e.g., "external CRM webhook on user signup"]
+  - Retry logic: [if applicable]
+
+---
+
+*Integration audit: [date]*
+*Update when adding/removing external services*
+```
+
+<good_examples>
+```markdown
+# External Integrations
+
+**Analysis Date:** 2025-01-20
+
+## APIs & External Services
+
+**Payment Processing:**
+- Stripe - Subscription billing and one-time course payments
+  - SDK/Client: stripe npm package v14.8
+  - Auth: API key in STRIPE_SECRET_KEY env var
+  - Endpoints used: checkout sessions, customer portal, webhooks
+
+**Email/SMS:**
+- SendGrid - Transactional emails (receipts, password resets)
+  - SDK/Client: @sendgrid/mail v8.1
+  - Auth: API key in SENDGRID_API_KEY env var
+  - Templates: Managed in SendGrid dashboard (template IDs in code)
+
+**External APIs:**
+- OpenAI API - Course content generation
+  - Integration method: REST API via openai npm package v4.x
+  - Auth: Bearer token in OPENAI_API_KEY env var
+  - Rate limits: 3500 requests/min (tier 3)
+
+## Data Storage
+
+**Databases:**
+- PostgreSQL on Supabase - Primary data store
+  - Connection: via DATABASE_URL env var
+  - Client: Prisma ORM v5.8
+  - Migrations: prisma migrate in prisma/migrations/
+
+**File Storage:**
+- Supabase Storage - User uploads (profile images, course materials)
+  - SDK/Client: @supabase/supabase-js v2.x
+  - Auth: Service role key in SUPABASE_SERVICE_ROLE_KEY
+  - Buckets: avatars (public), course-materials (private)
+
+**Caching:**
+- None currently (all database queries, no Redis)
+
+## Authentication & Identity
+
+**Auth Provider:**
+- Supabase Auth - Email/password + OAuth
+  - Implementation: Supabase client SDK with server-side session management
+  - Token storage: httpOnly cookies via @supabase/ssr
+  - Session management: JWT refresh tokens handled by Supabase
+
+**OAuth Integrations:**
+- Google OAuth - Social sign-in
+  - Credentials: GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET (Supabase dashboard)
+  - Scopes: email, profile
+
+## Monitoring & Observability
+
+**Error Tracking:**
+- Sentry - Server and client errors
+  - DSN: SENTRY_DSN env var
+  - Release tracking: Git commit SHA via SENTRY_RELEASE
+
+**Analytics:**
+- None (planned: Mixpanel)
+
+**Logs:**
+- Vercel logs - stdout/stderr only
+  - Retention: 7 days on Pro plan
+
+## CI/CD & Deployment
+
+**Hosting:**
+- Vercel - Next.js app hosting
+  - Deployment: Automatic on main branch push
+  - Environment vars: Configured in Vercel dashboard (synced to .env.example)
+
+**CI Pipeline:**
+- GitHub Actions - Tests and type checking
+  - Workflows: .github/workflows/ci.yml
+  - Secrets: None needed (public repo tests only)
+
+## Environment Configuration
+
+**Development:**
+- Required env vars: DATABASE_URL, NEXT_PUBLIC_SUPABASE_URL, NEXT_PUBLIC_SUPABASE_ANON_KEY
+- Secrets location: .env.local (gitignored), team shared via 1Password vault
+- Mock/stub services: Stripe test mode, Supabase local dev project
+
+**Staging:**
+- Uses separate Supabase staging project
+- Stripe test mode
+- Same Vercel account, different environment
+
+**Production:**
+- Secrets management: Vercel environment variables
+- Database: Supabase production project with daily backups
+
+## Webhooks & Callbacks
+
+**Incoming:**
+- Stripe - /api/webhooks/stripe
+  - Verification: Signature validation via stripe.webhooks.constructEvent
+  - Events: payment_intent.succeeded, customer.subscription.updated, customer.subscription.deleted
+
+**Outgoing:**
+- None
+
+---
+
+*Integration audit: 2025-01-20*
+*Update when adding/removing external services*
+```
+</good_examples>
+
+<guidelines>
+**What belongs in INTEGRATIONS.md:**
+- External services the code communicates with
+- Authentication patterns (where secrets live, not the secrets themselves)
+- SDKs and client libraries used
+- Environment variable names (not values)
+- Webhook endpoints and verification methods
+- Database connection patterns
+- File storage locations
+- Monitoring and logging services
+
+**What does NOT belong here:**
+- Actual API keys or secrets (NEVER write these)
+- Internal architecture (that's ARCHITECTURE.md)
+- Code patterns (that's PATTERNS.md)
+- Technology choices (that's STACK.md)
+- Performance issues (that's CONCERNS.md)
+
+**When filling this template:**
+- Check .env.example or .env.template for required env vars
+- Look for SDK imports (stripe, @sendgrid/mail, etc.)
+- Check for webhook handlers in routes/endpoints
+- Note where secrets are managed (not the secrets)
+- Document environment-specific differences (dev/staging/prod)
+- Include auth patterns for each service
+
+**Useful for phase planning when:**
+- Adding new external service integrations
+- Debugging authentication issues
+- Understanding data flow outside the application
+- Setting up new environments
+- Auditing third-party dependencies
+- Planning for service outages or migrations
+
+**Security note:**
+Document WHERE secrets live (env vars, Vercel dashboard, 1Password), never WHAT the secrets are.
+</guidelines>

package/pan-wizard-core/templates/codebase/relationships.md

@@ -0,0 +1,124 @@
+# Relationships Template
+
+Template for `.planning/codebase/relationships.md` - maps module dependencies and coupling.
+
+**Purpose:** Document how modules relate to each other. Answers "what depends on what?" and "what breaks if I change X?"
+
+---
+
+## File Template
+
+```markdown
+# Module Relationships
+
+**Analysis Date:** [YYYY-MM-DD]
+
+## Dependency Overview
+
+| Metric | Value |
+|--------|-------|
+| Total modules | [N] |
+| Total import relationships | [N] |
+| Circular dependencies | [N] |
+| Orphan modules | [N] |
+| Entry points | [N] |
+
+## Module Dependency Graph
+
+```mermaid
+graph LR
+    [ModuleA] --> [ModuleB]
+    [ModuleB] --> [ModuleC]
+```
+
+## Circular Dependencies
+
+[If none: "No circular dependencies detected."]
+
+**Cycle [N]:** `[file-a]` -> `[file-b]` -> `[file-a]`
+- Severity: [High/Medium/Low]
+- Impact: [What breaks or is fragile]
+- Fix approach: [Extract shared code, invert dependency, use interface]
+
+## High-Coupling Modules
+
+Modules with the most connections (incoming + outgoing):
+
+| Module | Incoming | Outgoing | Total | Risk |
+|--------|----------|----------|-------|------|
+| `[path]` | [N] | [N] | [N] | [Hub/Gateway/Leaf] |
+
+## Orphan Modules
+
+Files that export symbols but are never imported (potential dead code):
+
+- `[path]` - exports `[function/class names]`
+
+[If none: "No orphan modules detected."]
+
+## Entry Points
+
+Application roots (files imported by nothing):
+
+- `[path]` - [Purpose: main entry, CLI entry, test runner, etc.]
+
+## Layer Boundaries
+
+[Describe the architectural layers detected in the codebase]
+
+**Layers:**
+1. [Layer name] - `[directory pattern]`
+2. [Layer name] - `[directory pattern]`
+
+## Layer Violations
+
+Imports that cross architectural boundaries:
+
+- `[source file]` imports `[target file]` - [Why this is a violation]
+
+[If none: "No layer violations detected."]
+
+## Import Patterns
+
+**Module system:** [CommonJS / ESM / Mixed]
+
+**Internal imports:** [Relative paths / Aliases / Barrel files]
+
+**External dependencies:** [How third-party packages are imported]
+
+---
+
+*Relationship analysis: [date]*
+*Update when module structure changes*
+```
+
+<guidelines>
+**What belongs in relationships.md:**
+- Module dependency graph (Mermaid)
+- Circular dependency warnings with fix suggestions
+- High-coupling modules (hub detection)
+- Orphan modules (dead code candidates)
+- Entry points (application roots)
+- Layer boundaries and violations
+- Import pattern summary
+
+**What does NOT belong here:**
+- Individual function signatures (that's ARCHITECTURE.md)
+- File listing (that's STRUCTURE.md)
+- Code quality issues (that's CONCERNS.md)
+- Technology choices (that's STACK.md)
+
+**When filling this template:**
+- Use pre-computed dependency graph data if provided in the prompt
+- Verify circular dependencies by tracing the import chain
+- Classify coupling risk: Hub (>10 connections), Gateway (5-10), Leaf (<5)
+- Entry points are files with zero incoming edges
+- Layer violations require understanding the intended architecture
+
+**Mermaid graph guidelines:**
+- Maximum 15 nodes per diagram
+- Use `graph LR` for dependency flow
+- Show module short names, not full paths
+- Highlight circular deps with red styling if supported
+- Add "... and N more" note for large graphs
+</guidelines>

package/pan-wizard-core/templates/codebase/stack.md

@@ -0,0 +1,199 @@
+# Technology Stack Template
+
+Template for `.planning/codebase/STACK.md` - captures the technology foundation.
+
+**Purpose:** Document what technologies run this codebase. Focused on "what executes when you run the code."
+
+---
+
+## File Template
+
+```markdown
+# Technology Stack
+
+**Analysis Date:** [YYYY-MM-DD]
+
+## Technology Architecture
+
+### Deployment Topology
+
+```mermaid
+graph TD
+    User[User/Developer] --> CLI[CLI / Browser]
+    CLI --> Runtime[Runtime Environment]
+    Runtime --> App[Application]
+    App --> FS[File System]
+    App --> ExtSvc[External Services]
+```
+
+## Languages
+
+**Primary:**
+- [Language] [Version] - [Where used: e.g., "all application code"]
+
+**Secondary:**
+- [Language] [Version] - [Where used: e.g., "build scripts, tooling"]
+
+## Runtime
+
+**Environment:**
+- [Runtime] [Version] - [e.g., "Node.js 20.x"]
+- [Additional requirements if any]
+
+**Package Manager:**
+- [Manager] [Version] - [e.g., "npm 10.x"]
+- Lockfile: [e.g., "package-lock.json present"]
+
+## Frameworks
+
+**Core:**
+- [Framework] [Version] - [Purpose: e.g., "web server", "UI framework"]
+
+**Testing:**
+- [Framework] [Version] - [e.g., "Jest for unit tests"]
+- [Framework] [Version] - [e.g., "Playwright for E2E"]
+
+**Build/Dev:**
+- [Tool] [Version] - [e.g., "Vite for bundling"]
+- [Tool] [Version] - [e.g., "TypeScript compiler"]
+
+## Key Dependencies
+
+[Only include dependencies critical to understanding the stack - limit to 5-10 most important]
+
+**Critical:**
+- [Package] [Version] - [Why it matters: e.g., "authentication", "database access"]
+- [Package] [Version] - [Why it matters]
+
+**Infrastructure:**
+- [Package] [Version] - [e.g., "Express for HTTP routing"]
+- [Package] [Version] - [e.g., "PostgreSQL client"]
+
+## Configuration
+
+**Environment:**
+- [How configured: e.g., ".env files", "environment variables"]
+- [Key configs: e.g., "DATABASE_URL, API_KEY required"]
+
+**Build:**
+- [Build config files: e.g., "vite.config.ts, tsconfig.json"]
+
+## Platform Requirements
+
+**Development:**
+- [OS requirements or "any platform"]
+- [Additional tooling: e.g., "Docker for local DB"]
+
+**Production:**
+- [Deployment target: e.g., "Vercel", "AWS Lambda", "Docker container"]
+- [Version requirements]
+
+---
+
+*Stack analysis: [date]*
+*Update after major dependency changes*
+```
+
+<good_examples>
+```markdown
+# Technology Stack
+
+**Analysis Date:** 2025-01-20
+
+## Languages
+
+**Primary:**
+- TypeScript 5.3 - All application code
+
+**Secondary:**
+- JavaScript - Build scripts, config files
+
+## Runtime
+
+**Environment:**
+- Node.js 20.x (LTS)
+- No browser runtime (CLI tool only)
+
+**Package Manager:**
+- npm 10.x
+- Lockfile: `package-lock.json` present
+
+## Frameworks
+
+**Core:**
+- None (vanilla Node.js CLI)
+
+**Testing:**
+- Vitest 1.0 - Unit tests
+- tsx - TypeScript execution without build step
+
+**Build/Dev:**
+- TypeScript 5.3 - Compilation to JavaScript
+- esbuild - Used by Vitest for fast transforms
+
+## Key Dependencies
+
+**Critical:**
+- commander 11.x - CLI argument parsing and command structure
+- chalk 5.x - Terminal output styling
+- fs-extra 11.x - Extended file system operations
+
+**Infrastructure:**
+- Node.js built-ins - fs, path, child_process for file operations
+
+## Configuration
+
+**Environment:**
+- No environment variables required
+- Configuration via CLI flags only
+
+**Build:**
+- `tsconfig.json` - TypeScript compiler options
+- `vitest.config.ts` - Test runner configuration
+
+## Platform Requirements
+
+**Development:**
+- macOS/Linux/Windows (any platform with Node.js)
+- No external dependencies
+
+**Production:**
+- Distributed as npm package
+- Installed globally via npm install -g
+- Runs on user's Node.js installation
+
+---
+
+*Stack analysis: 2025-01-20*
+*Update after major dependency changes*
+```
+</good_examples>
+
+<guidelines>
+**What belongs in STACK.md:**
+- Languages and versions
+- Runtime requirements (Node, Bun, Deno, browser)
+- Package manager and lockfile
+- Framework choices
+- Critical dependencies (limit to 5-10 most important)
+- Build tooling
+- Platform/deployment requirements
+
+**What does NOT belong here:**
+- File structure (that's STRUCTURE.md)
+- Architectural patterns (that's ARCHITECTURE.md)
+- Every dependency in package.json (only critical ones)
+- Implementation details (defer to code)
+
+**When filling this template:**
+- Check package.json for dependencies
+- Note runtime version from .nvmrc or package.json engines
+- Include only dependencies that affect understanding (not every utility)
+- Specify versions only when version matters (breaking changes, compatibility)
+
+**Useful for phase planning when:**
+- Adding new dependencies (check compatibility)
+- Upgrading frameworks (know what's in use)
+- Choosing implementation approach (must work with existing stack)
+- Understanding build requirements
+</guidelines>