diff --git a/.eslintrc.json b/.eslintrc.json new file mode 100644 index 0000000..09b042e --- /dev/null +++ b/.eslintrc.json @@ -0,0 +1,7 @@ +{ + "extends": "next/core-web-vitals", + "rules": { + "@typescript-eslint/no-unused-vars": "warn", + "@typescript-eslint/no-explicit-any": "warn" + } +} diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml new file mode 100644 index 0000000..4431d31 --- /dev/null +++ b/.github/workflows/ci.yml @@ -0,0 +1,101 @@ +name: CI + +on: + push: + branches: [main, develop] + pull_request: + branches: [main, develop] + +jobs: + lint: + name: Lint + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-node@v4 + with: + node-version: "20" + cache: "npm" + - run: npm ci + - run: npm run lint + + test: + name: Unit Tests + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-node@v4 + with: + node-version: "20" + cache: "npm" + - run: npm ci + - run: npm test -- --coverage + - uses: codecov/codecov-action@v3 + with: + fail_ci_if_error: false + + e2e: + name: E2E Tests + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-node@v4 + with: + node-version: "20" + cache: "npm" + - run: npm ci + - run: npx playwright install --with-deps + - run: npm run build + - run: npm run test:e2e + - uses: actions/upload-artifact@v4 + if: failure() + with: + name: playwright-report + path: playwright-report/ + retention-days: 7 + + build: + name: Build + runs-on: ubuntu-latest + needs: [lint, test] + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-node@v4 + with: + node-version: "20" + cache: "npm" + - run: npm ci + - run: npm run build + - uses: actions/upload-artifact@v4 + with: + name: build + path: .next/ + retention-days: 1 + + deploy-preview: + name: Deploy Preview + runs-on: ubuntu-latest + needs: build + if: github.event_name == 'pull_request' + steps: + - uses: actions/checkout@v4 + - uses: amondnet/vercel-action@v25 + with: + vercel-token: ${{ secrets.VERCEL_TOKEN }} + vercel-org-id: ${{ secrets.VERCEL_ORG_ID }} + vercel-project-id: ${{ secrets.VERCEL_PROJECT_ID }} + + deploy-production: + name: Deploy Production + runs-on: ubuntu-latest + needs: [build, e2e] + if: github.ref == 'refs/heads/main' && github.event_name == 'push' + environment: production + steps: + - uses: actions/checkout@v4 + - uses: amondnet/vercel-action@v25 + with: + vercel-token: ${{ secrets.VERCEL_TOKEN }} + vercel-org-id: ${{ secrets.VERCEL_ORG_ID }} + vercel-project-id: ${{ secrets.VERCEL_PROJECT_ID }} + vercel-args: "--prod" diff --git a/.log b/.log new file mode 100644 index 0000000..0bf7010 --- /dev/null +++ b/.log @@ -0,0 +1,15 @@ +# Execution Log + +## 2024-12-23 fix: Plan name shows as undefined on upgrade page + +- **Root cause:** Components passed undefined planId directly to getPlanById(), which returns undefined. This undefined value was rendered as text "undefined" in the UI when users had no subscription. +- **Solution:** Added two new helper functions: + - `getDisplayPlanName(planId)` - Returns "Free" for undefined/null/unknown planIds + - `getPlanOrDefault(planId)` - Returns Free plan object for undefined/null/unknown planIds + - Updated UpgradePage.tsx and BillingOverview.tsx to use getPlanOrDefault() +- **Files changed:** + - src/lib/plans.ts (added helper functions) + - src/components/UpgradePage.tsx (use getPlanOrDefault) + - src/components/BillingOverview.tsx (use getPlanOrDefault) + - tests/plan-display.test.ts (added verification tests) +- **Tests:** 19 passing diff --git a/.tasks b/.tasks index 617cfac..b852cd5 100644 --- a/.tasks +++ b/.tasks @@ -2,13 +2,13 @@ ## Format # [ ] Not started -# [~] In progress +# [~] In progress # [x] Done (YYYY-MM-DD) # [!] Stuck - needs help # [REVIEW] tag = Claude stops for approval ## Tasks -[ ] First feature to build -[ ] Second feature -[ ] Payment integration [REVIEW] +[x] Add aria-label to upgrade button in UpgradePage (2024-12-23) +[x] Add TypeScript strict null check to tsconfig (2024-12-23) +[x] Update package.json description (2024-12-23) diff --git a/DESIGN-SYSTEM.md b/DESIGN-SYSTEM.md new file mode 100644 index 0000000..fe04add --- /dev/null +++ b/DESIGN-SYSTEM.md @@ -0,0 +1,149 @@ +# Design System: Billing Dashboard + +> Generated by Claude Code V7.7 on 2024-12-23 + +## Color Palette + +### Semantic Tokens + +```css +:root { + /* Primary */ + --color-primary: #3b82f6; + --color-primary-hover: #2563eb; + + /* Feedback */ + --color-success: #22c55e; + --color-warning: #f59e0b; + --color-error: #ef4444; + + /* Neutral */ + --color-background: #ffffff; + --color-surface: #f9fafb; + --color-text: #111827; + --color-text-muted: #6b7280; + --color-border: #e5e7eb; +} + +/* Dark mode */ +[data-theme="dark"] { + --color-background: #111827; + --color-surface: #1f2937; + --color-text: #f9fafb; +} +``` + +## Typography + +| Role | Font | Size | Weight | +| --------- | ----- | -------- | ------ | +| Heading 1 | Inter | 2rem | 700 | +| Heading 2 | Inter | 1.5rem | 600 | +| Body | Inter | 1rem | 400 | +| Caption | Inter | 0.875rem | 400 | + +## Spacing Scale + +``` +4px - xs +8px - sm +12px - md +16px - lg +24px - xl +32px - 2xl +48px - 3xl +``` + +## Component Library + +**Choice:** Custom components with Tailwind CSS + +**Installed Components:** + +- [x] Button +- [x] Card +- [x] BillingOverview +- [x] UpgradePage +- [x] UsageMetrics _(new)_ + +## Components + +### UsageMetricsCard + +**Purpose:** Display current usage metrics (API calls, storage, team members) with progress bars. + +**File:** `src/components/UsageMetrics.tsx` + +**Props:** + +```typescript +interface UsageMetricsProps { + metrics: UsageMetrics | null; + planLimits: { apiCalls: number; storageUsed: number; teamMembers: number }; + isLoading?: boolean; + error?: string | null; +} +``` + +**States:** + +| State | Component | Description | +| ------- | ----------------- | ---------------------------------------------- | +| Loading | `LoadingSkeleton` | Skeleton placeholders with aria-busy | +| Empty | `EmptyState` | Guidance: "Start using the API to see metrics" | +| Error | `ErrorState` | Error message + "Try Again" button | +| Success | `SuccessState` | Three metric cards with progress bars | + +**Metrics Displayed:** + +- API Calls (count / limit) +- Storage (GB / limit) +- Team Members (seats / limit) + +**Visual Indicators:** + +- Green bar: < 80% usage +- Yellow bar: 80-99% usage +- Red bar: 100%+ usage (over limit) + +**Accessibility:** + +- `aria-busy="true"` on loading state +- `role="alert"` on error state +- `aria-label` on retry button +- `aria-hidden` on decorative icons + +**Usage:** + +```tsx + +``` + +--- + +### BillingOverview + +**Purpose:** Display current plan with upgrade CTA. + +**File:** `src/components/BillingOverview.tsx` + +**States:** Loading, Success only (simple component) + +--- + +### UpgradePage + +**Purpose:** Show plan options and allow upgrades. + +**File:** `src/components/UpgradePage.tsx` + +**States:** Loading, Success + +--- + +_Last updated: 2024-12-23_ diff --git a/README.md b/README.md index e9b3e75..92003c4 100644 --- a/README.md +++ b/README.md @@ -1,154 +1,158 @@ -# Claude Code V7.7 +# Billing Dashboard -**From Coding Assistant to Production App Builder** +> A SaaS billing dashboard built with Next.js, Stripe, and React Native companion app. -Claude Code V7.7 transforms from a coding assistant into a production app builder by adding domain expertise, progressive documentation, and minimal subagents. +## Quick Start -## What's New in V7.7 +```bash +# Clone the repository +git clone https://github.com/example/billing-dashboard.git +cd billing-dashboard -### Domain Skills (11 NEW) +# Install dependencies +npm install -Skills provide domain expertise without agent overhead (~500 tokens vs ~15x for agents): +# Copy environment variables +cp .env.example .env.local -| Skill | Purpose | Auto-generates | -|-------|---------|----------------| -| `ui-design` | Visual design, design systems | DESIGN-SYSTEM.md | -| `frontend` | React, state management | - | -| `backend` | APIs, business logic | docs/API-CONTRACTS.md | -| `database` | Schema, queries, Supabase | docs/DATA-MODELS.md | -| `testing` | Jest, Playwright, E2E | - | -| `performance` | Core Web Vitals, optimization | - | -| `accessibility` | WCAG compliance | - | -| `devops` | CI/CD, deployment | docs/DEPLOYMENT.md, RUNBOOK.md, MONITORING.md | -| `integration` | Stripe, Auth0, third-party | Appends to API-CONTRACTS.md | -| `mobile` | React Native, Expo | - | -| `documentation` | README, guides | README.md | +# Run development server +npm run dev -### New Agents (2) +# Open http://localhost:3000 +``` -| Agent | Purpose | -|-------|---------| -| `initializer` | Project setup (Anthropic two-agent pattern) | -| `researcher` | External API verification with web access | +## Tech Stack -### Enhanced Agents (2) +| Layer | Technology | +| ------------- | ----------------------- | +| **Framework** | Next.js 14 (App Router) | +| **Language** | TypeScript | +| **Styling** | Tailwind CSS | +| **Payments** | Stripe | +| **Analytics** | Plausible | +| **Testing** | Jest + Playwright | +| **Mobile** | React Native + Expo | -- **explorer** - Now returns structured output, max 2000 tokens -- **reviewer** - Now checks if documentation was updated +## Project Structure -### New Command +``` +billing-dashboard/ +├── src/ +│ ├── app/ # Next.js App Router pages +│ ├── components/ # React components +│ │ ├── BillingOverview.tsx +│ │ ├── Dashboard.tsx +│ │ ├── UpgradePage.tsx +│ │ └── UsageMetrics.tsx +│ ├── lib/ # Utilities +│ │ ├── plans.ts # Plan data and helpers +│ │ └── subscription.ts +│ ├── hooks/ # Custom React hooks +│ └── types/ # TypeScript types +├── tests/ # Jest unit tests +├── e2e/ # Playwright E2E tests +├── mobile/ # React Native companion app +├── docs/ # Documentation +│ ├── DEPLOYMENT.md +│ ├── RUNBOOK.md +│ └── MONITORING.md +└── .github/workflows/ # CI/CD +``` -- `/launch` - Production readiness checklist +## Environment Variables + +| Variable | Required | Description | +| ------------------------ | -------- | ----------------------------- | +| `DATABASE_URL` | Yes | PostgreSQL connection string | +| `NEXTAUTH_SECRET` | Yes | Auth encryption key | +| `NEXTAUTH_URL` | Yes | App base URL | +| `STRIPE_SECRET_KEY` | Yes | Stripe secret key | +| `STRIPE_PUBLISHABLE_KEY` | Yes | Stripe publishable key | +| `STRIPE_WEBHOOK_SECRET` | Yes | Stripe webhook signing secret | +| `PLAUSIBLE_DOMAIN` | No | Plausible analytics domain | + +## Available Scripts + +```bash +npm run dev # Start development server +npm run build # Production build +npm run start # Start production server +npm run lint # Run ESLint +npm test # Run unit tests +npm run test:e2e # Run Playwright E2E tests +npm run test:e2e:ui # Run Playwright with UI +``` -### Document Templates (10) +## Features -Pre-built templates ensure consistent documentation: -- ARCHITECTURE.template.md -- DESIGN-SYSTEM.template.md -- API-CONTRACTS.template.md -- DATA-MODELS.template.md -- AUTH-FLOWS.template.md -- DEPLOYMENT.template.md -- RUNBOOK.template.md -- MONITORING.template.md -- SECURITY.template.md -- PRODUCTION-CHECKLIST.template.md +### Billing Dashboard -## Quick Start +- View current subscription plan +- Display usage metrics (API calls, storage, team members) +- Upgrade/downgrade plans +- Access Stripe Customer Portal -1. Copy `.claude/` folder to your project root -2. Copy `CLAUDE.md` to your project root -3. Start coding: `/build "add user authentication"` +### Usage Analytics -## Architecture +- Real-time usage tracking +- Progress bars with limit warnings +- Color-coded status (green/yellow/red) -``` -┌─────────────────────────────────────────────────────────────────┐ -│ MAIN AGENT (Coding Agent) │ -│ │ -│ - Receives user commands (/build, /fix, /quick, /launch) │ -│ - Loads skills on-demand (20 skills) │ -│ - Follows Iron Laws (TDD, Verification, Debugging) │ -│ - Skills auto-generate documentation as they work │ -│ │ -└─────────────────────────────────────────────────────────────────┘ - │ │ │ │ - ▼ ▼ ▼ ▼ - ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ - │initializer│ │ explorer │ │ reviewer │ │researcher│ - │ │ │ │ │ │ │ │ - │ Project │ │ Read-only│ │ Code │ │ API/docs │ - │ setup │ │ explore │ │ review │ │ verify │ - └──────────┘ └──────────┘ └──────────┘ └──────────┘ -``` +### Mobile App + +- React Native companion app +- View plan details on the go +- Same features as web dashboard -## Key Decisions +## Testing -### Skills > Agents for Domain Expertise +### Unit Tests (Jest) -Each subagent spawns with a fresh 200K context window, adding ~15x token overhead. Skills load into the main context (~500 tokens each) and share context with the workflow. +```bash +npm test +``` -### Progressive Documentation +### E2E Tests (Playwright) -Documents aren't generated upfront. Skills append to docs as they work: -- Create API endpoint → Append to API-CONTRACTS.md -- Create UI component → Append to DESIGN-SYSTEM.md -- Create table → Append to DATA-MODELS.md +```bash +npm run test:e2e +``` -### Four Agents Only +### Test Coverage Targets -1. **initializer** - Project setup -2. **explorer** - Read-only codebase investigation -3. **reviewer** - Code review before commit -4. **researcher** - External API verification +- Unit tests: 80%+ coverage +- E2E tests: Critical user journeys -## Version History +## Deployment -| Version | Key Changes | -|---------|-------------| -| V7.7 | Domain skills, progressive docs, 4 agents, /launch | -| V7.6 | Skills-based, softer guidance, 9/10 stress test | -| V7.4 | Iron Laws, rationalization tables | -| V7.0 | Skills architecture | +See [docs/DEPLOYMENT.md](docs/DEPLOYMENT.md) for complete deployment guide. -## Files +Quick deploy to Vercel: -``` -project/ -├── CLAUDE.md # Project instructions -├── ARCHITECTURE.md # Generated on first /build -├── DESIGN-SYSTEM.md # Generated by ui-design skill -├── SCRATCHPAD.md # Session continuity -├── .tasks # Task queue -├── .log # Execution history -│ -├── docs/ -│ ├── API-CONTRACTS.md # Generated by backend skill -│ ├── DATA-MODELS.md # Generated by database skill -│ ├── AUTH-FLOWS.md # Generated by security skill -│ ├── DEPLOYMENT.md # Generated by devops skill -│ ├── RUNBOOK.md # Generated by devops skill -│ ├── MONITORING.md # Generated by devops skill -│ └── PRODUCTION-CHECKLIST.md # Generated by /launch -│ -└── .claude/ - ├── settings.json # Hook configuration - ├── skills/ # 20 skills - ├── agents/ # 4 agents - ├── commands/ # 8 commands - ├── templates/ # 10 doc templates - ├── hooks/ # 6 hooks - └── state/ # Workflow state +```bash +vercel --prod ``` -## Iron Laws (Preserved) +## Documentation -``` -1. NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST -2. NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST -3. NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE -``` +| Document | Description | +| ------------------------------------ | --------------------- | +| [DESIGN-SYSTEM.md](DESIGN-SYSTEM.md) | Component library | +| [DEPLOYMENT.md](docs/DEPLOYMENT.md) | Deployment procedures | +| [RUNBOOK.md](docs/RUNBOOK.md) | Incident response | +| [MONITORING.md](docs/MONITORING.md) | Metrics and alerts | + +## Contributing + +1. Create a feature branch +2. Write tests first (TDD) +3. Submit PR for review +4. CI must pass before merge ## License MIT + +--- + +_Built with Claude Code V7.7_ diff --git a/SCRATCHPAD.md b/SCRATCHPAD.md new file mode 100644 index 0000000..3a53497 --- /dev/null +++ b/SCRATCHPAD.md @@ -0,0 +1,150 @@ +# Scratchpad + +## Session Continuity + +This file tracks the current session state, API verifications, and investigation notes. + +## Current Status + +- Project: Billing Dashboard +- Phase: Part 2 Testing +- Last Updated: 2024-12-23 + +## API Verifications + +### Plausible Analytics (via Researcher Agent + WebSearch/WebFetch) + +**Verified:** 2024-12-23 +**Documentation:** https://plausible.io/docs + +| Method | Status | Notes | +| ------------------ | ----------- | -------------------------------------------------------------------------- | +| JavaScript Snippet | ✅ Verified | `