@mars-stack/core 0.4.0

package/cursor/skills/mars-design-tokens/SKILL.md

@@ -0,0 +1,138 @@
+# Skill: Work with the Design Token System
+
+Understand and extend the MARS three-layer design token architecture for theming and UI consistency.
+
+## When to Use
+
+Use this skill when the user asks about theming, changing colours, adding dark mode support, creating new design tokens, or understanding the styling system.
+
+## Architecture Overview
+
+```
+Layer 1: Primitive Palette     (@mars-stack/ui/styles/primitives.css)
+  ↓ referenced by
+Layer 2: Semantic Tokens       (@mars-stack/ui/styles/tokens.css)
+  ↓ registered as
+Layer 3: Tailwind Theme        (@mars-stack/ui/styles/theme.css via @theme)
+  ↓ used in
+Components                     (via Tailwind utility classes)
+```
+
+### Layer 1: Primitive Palette (`@mars-stack/ui/styles/primitives.css`)
+
+Raw colour scales generated from the primary colour. These are building blocks, never used directly in components.
+
+```css
+:root {
+  --brand-50: oklch(0.97 0.01 250);
+  --brand-100: oklch(0.93 0.03 250);
+  /* ... full 50-950 scale */
+  --gray-50: oklch(0.985 0 0);
+  --gray-100: oklch(0.97 0 0);
+  /* ... */
+}
+```
+
+### Layer 2: Semantic Tokens (`@mars-stack/ui/styles/tokens.css`)
+
+What colours *mean*. These swap between light and dark themes.
+
+```css
+:root {
+  --surface-card: white;
+  --text-primary: var(--gray-900);
+  --border-input: var(--gray-300);
+  --brand-primary: var(--brand-600);
+}
+
+.dark {
+  --surface-card: var(--gray-900);
+  --text-primary: var(--gray-100);
+  --border-input: var(--gray-700);
+  --brand-primary: var(--brand-500);
+}
+```
+
+### Layer 3: Tailwind Theme (`@mars-stack/ui/styles/theme.css`)
+
+Registers semantic tokens as Tailwind utilities via `@theme`:
+
+```css
+@theme {
+  --color-surface-background: var(--surface-background);
+  --color-surface-card: var(--surface-card);
+  --color-text-primary: var(--text-primary);
+  --color-border-default: var(--border-default);
+  --color-brand-primary: var(--brand-primary);
+  /* ... */
+}
+```
+
+This enables `bg-surface-card`, `text-text-primary`, `border-border-default`, etc. in components.
+
+## Token Categories
+
+| Category | Prefix | Examples |
+|----------|--------|---------|
+| Surfaces | `surface-` | `bg-surface-background`, `bg-surface-card`, `bg-surface-input` |
+| Text | `text-` | `text-text-primary`, `text-text-secondary`, `text-text-muted` |
+| Borders | `border-` | `border-border-default`, `border-border-input`, `border-border-focus` |
+| Brand | `brand-` | `bg-brand-primary`, `hover:bg-brand-primary-hover` |
+| Feedback | varies | `bg-success-muted`, `text-text-error`, `border-border-success` |
+| Interactive | varies | `bg-ghost-hover`, `focus:ring-ring-focus`, `bg-danger-bg` |
+| Navigation | `nav-` | `text-nav-item`, `bg-nav-item-active-bg` |
+| Table | `table-` | `bg-table-header-bg`, `hover:bg-table-row-hover` |
+| Avatar | `avatar-` | `bg-avatar-bg`, `text-avatar-text` |
+
+## How to Change the Theme
+
+### Change Primary Colour
+
+1. Edit `@mars-stack/ui/styles/primitives.css` -- update the `--brand-*` scale to your new colour's oklch values.
+2. Everything else (semantic tokens, components) updates automatically.
+
+### Add a New Semantic Token
+
+1. Define the token in `@mars-stack/ui/styles/tokens.css` for both `:root` and `.dark`:
+   ```css
+   :root { --sidebar-accent: var(--brand-100); }
+   .dark { --sidebar-accent: var(--brand-900); }
+   ```
+
+2. Register it in `@mars-stack/ui/styles/theme.css`:
+   ```css
+   @theme {
+     --color-sidebar-accent: var(--sidebar-accent);
+   }
+   ```
+
+3. Use in components: `bg-sidebar-accent`.
+
+### Add a New Colour Scale
+
+1. Add the full 50-950 scale in `@mars-stack/ui/styles/primitives.css`.
+2. Add semantic tokens that reference it in `@mars-stack/ui/styles/tokens.css`.
+3. Register the semantic tokens in `@mars-stack/ui/styles/theme.css`.
+
+## Rules
+
+- **Never use raw Tailwind colours** (`text-gray-900`, `bg-blue-500`) in components. Always use semantic tokens.
+- **Always define dark mode counterparts** when adding new semantic tokens.
+- **Components get their colours from Layer 3** (Tailwind utilities backed by semantic tokens). They never reference Layer 1 directly.
+- The `app.config.ts` `theme.primaryColor` field is used by the CLI during scaffolding to generate the correct primitive palette. At runtime, the CSS tokens are the source of truth.
+
+## Breakpoints
+
+Responsive breakpoints are defined in `@mars-stack/ui/styles/breakpoints.css` and registered in theme.css:
+
+```css
+@theme {
+  --breakpoint-sm: 640px;
+  --breakpoint-md: 768px;
+  --breakpoint-lg: 1024px;
+  --breakpoint-xl: 1280px;
+  --breakpoint-2xl: 1536px;
+}
+```
+
+Use as standard Tailwind responsive prefixes: `md:grid-cols-2`, `lg:px-8`.

package/cursor/skills/mars-setup-billing/SKILL.md

@@ -0,0 +1,322 @@
+# Skill: Setup Billing (Meta-Skill)
+
+Orchestrate the complete billing and subscription system: Stripe integration, webhook handling, subscription UI, customer portal, and documentation updates.
+
+## When to Use
+
+Use this skill when the user asks to:
+- Set up billing or subscriptions
+- Add a paywall or premium features
+- Integrate Stripe end-to-end
+- Add pricing page with checkout
+
+This meta-skill chains sub-skills in the correct order. For just the Stripe SDK setup, use `configure-payments` instead.
+
+## Prerequisites
+
+- A Stripe account at [stripe.com](https://stripe.com)
+- Read `src/config/app.config.ts` to check if billing is already flagged
+- Read `prisma/schema/` to check for existing billing models
+
+## Execution Order
+
+```
+┌─────────────────────────────────────────────────────┐
+│ Phase 0: Plan                                        │
+│   create-execution-plan                              │
+├─────────────────────────────────────────────────────┤
+│ Phase 1: Payment Provider                            │
+│   configure-payments (Stripe SDK, env vars, client)  │
+├─────────────────────────────────────────────────────┤
+│ Phase 2: Data Layer                                  │
+│   add-prisma-model (Subscription, WebhookEvent)     │
+├─────────────────────────────────────────────────────┤
+│ Phase 3: Webhook                                     │
+│   add-webhook (Stripe webhook handler)               │
+├─────────────────────────────────────────────────────┤
+│ Phase 4: Feature Module                              │
+│   add-feature (billing service, checkout, portal)    │
+├─────────────────────────────────────────────────────┤
+│ Phase 5: API Routes                                  │
+│   add-api-route (checkout, portal, subscription)     │
+├─────────────────────────────────────────────────────┤
+│ Phase 6: UI                                          │
+│   add-page (pricing, billing dashboard)              │
+│   ↳ If pricing page needed: build-landing-page       │
+├─────────────────────────────────────────────────────┤
+│ Phase 7: Testing & Docs                              │
+│   test-api-route → update-architecture-docs          │
+└─────────────────────────────────────────────────────┘
+```
+
+## Phase 0: Create Execution Plan
+
+**Skill:** `create-execution-plan`
+
+Create `docs/exec-plans/active/setup-billing.md` with all tasks listed below.
+
+## Phase 1: Payment Provider Setup
+
+**Skill:** `configure-payments`
+
+1. Install Stripe SDK: `yarn add stripe`
+2. Set environment variables:
+   - `STRIPE_SECRET_KEY`
+   - `STRIPE_WEBHOOK_SECRET`
+   - `NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY`
+3. Create the lazy Stripe client at `src/features/billing/server/stripe.ts`
+4. Enable the billing feature flag:
+
+```typescript
+// src/config/app.config.ts
+features: {
+  billing: true,
+}
+```
+
+**Decision: Payment model?**
+
+| Model | Use when | Stripe mode |
+|-------|----------|-------------|
+| Subscription | Monthly/annual recurring billing | `mode: 'subscription'` |
+| One-time | Single purchases, credits | `mode: 'payment'` |
+| Usage-based | Pay per API call, storage, etc. | `mode: 'subscription'` + metered billing |
+
+## Phase 2: Data Layer
+
+**Skill:** `add-prisma-model`
+
+### Subscription model
+
+```prisma
+// prisma/schema/billing.prisma
+model Subscription {
+  id                   String    @id @default(cuid())
+  userId               String    @unique
+  stripeCustomerId     String    @unique
+  stripeSubscriptionId String?   @unique
+  stripePriceId        String?
+  status               String    @default("inactive")
+  currentPeriodEnd     DateTime?
+  cancelAtPeriodEnd    Boolean   @default(false)
+  createdAt            DateTime  @default(now())
+  updatedAt            DateTime  @updatedAt
+
+  user User @relation(fields: [userId], references: [id], onDelete: Cascade)
+
+  @@index([stripeCustomerId])
+  @@index([status])
+}
+```
+
+### Webhook event model (for idempotency)
+
+```prisma
+model WebhookEvent {
+  id          String   @id @default(cuid())
+  externalId  String   @unique
+  type        String
+  processedAt DateTime @default(now())
+
+  @@index([externalId])
+}
+```
+
+Run `yarn db:push`.
+
+## Phase 3: Webhook Handler
+
+**Skill:** `add-webhook`
+
+Create `src/app/api/webhooks/stripe/route.ts`:
+
+1. Verify Stripe signature using `stripe.webhooks.constructEvent`
+2. Check idempotency (has this event been processed?)
+3. Handle key events:
+
+| Event | Handler | Action |
+|-------|---------|--------|
+| `checkout.session.completed` | `handleCheckoutCompleted` | Create/update subscription, set status to active |
+| `customer.subscription.updated` | `handleSubscriptionUpdated` | Sync status, price, period end, cancel flag |
+| `customer.subscription.deleted` | `handleSubscriptionDeleted` | Set status to canceled |
+| `invoice.payment_failed` | `handlePaymentFailed` | Notify user, set status to past_due |
+
+4. Exclude webhook route from CSRF in middleware
+5. Return 200 quickly — do heavy processing inline (Vercel has 10s limit)
+
+**If payment model is one-time instead of subscription:**
+
+Handle `checkout.session.completed` to record the purchase. Skip subscription update/delete events.
+
+**If payment model is usage-based:**
+
+Additionally handle `invoice.created` to add usage line items before the invoice is finalized.
+
+## Phase 4: Feature Module
+
+**Skill:** `add-feature`
+
+Create `src/features/billing/`:
+
+```
+src/features/billing/
+├── components/
+│   ├── PricingCard.tsx       # Individual plan card
+│   ├── PricingTable.tsx      # All plans side by side
+│   ├── SubscriptionStatus.tsx # Current plan display
+│   └── index.ts
+├── server/
+│   ├── stripe.ts             # Lazy Stripe client (from Phase 1)
+│   ├── index.ts              # Subscription queries + helpers
+│   └── checkout.ts           # Checkout session creation
+├── validation/
+│   └── schemas.ts            # Zod schemas for billing inputs
+└── types.ts                  # Billing TypeScript types
+```
+
+Key server functions:
+
+```typescript
+// src/features/billing/server/index.ts
+export { getStripe } from './stripe';
+
+export async function getUserSubscription(userId: string) { ... }
+export async function isSubscribed(userId: string): Promise<boolean> { ... }
+export async function getSubscriptionStatus(userId: string) { ... }
+```
+
+## Phase 5: API Routes
+
+**Skill:** `add-api-route`
+
+| Route | Method | Auth | Purpose |
+|-------|--------|------|---------|
+| `/api/protected/billing/checkout` | POST | `withAuthNoParams` | Create Stripe Checkout session |
+| `/api/protected/billing/portal` | POST | `withAuthNoParams` | Create Stripe Customer Portal session |
+| `/api/protected/billing/subscription` | GET | `withAuthNoParams` | Get current subscription status |
+
+### Checkout route
+
+Accepts `{ priceId: string }`. Creates or retrieves Stripe customer, then creates a Checkout Session with success/cancel URLs.
+
+### Portal route
+
+Creates a Billing Portal session for subscription management. Requires an existing Stripe customer.
+
+### Subscription route
+
+Returns the current subscription status, plan, and renewal date for display in the UI.
+
+## Phase 6: UI
+
+**Skill:** `add-page`
+
+### Pricing page (public)
+
+Create `src/app/(public)/pricing/page.tsx` or include in the landing page:
+
+```tsx
+// Uses PricingTable component
+// Shows plans with features and CTAs
+// Unauthenticated users → redirect to signup with plan param
+// Authenticated users → redirect to checkout
+```
+
+### Billing dashboard (protected)
+
+Create `src/app/(protected)/billing/page.tsx`:
+
+```tsx
+// Shows current subscription status
+// "Manage Subscription" → opens Stripe Customer Portal
+// "Upgrade" → creates checkout session
+// Shows billing history (if available)
+```
+
+**Conditional: If a pricing page is needed on the landing page:**
+
+**Skill:** `build-landing-page` — Include a pricing section with plan comparison.
+
+### Subscription gate component
+
+```tsx
+// src/features/billing/components/SubscriptionGate.tsx
+'use client';
+
+export function SubscriptionGate({
+  children,
+  fallback,
+}: {
+  children: React.ReactNode;
+  fallback?: React.ReactNode;
+}) {
+  // Check subscription status
+  // If subscribed, render children
+  // If not, render fallback (upgrade prompt)
+}
+```
+
+## Phase 7: Testing & Documentation
+
+**Skill:** `test-api-route` + `update-architecture-docs`
+
+### Tests
+
+1. Unit test checkout route (mock Stripe, verify session creation)
+2. Unit test portal route (mock Stripe, verify portal session)
+3. Unit test webhook handler (mock signature verification, verify DB updates)
+4. Unit test `isSubscribed` helper
+5. E2E test: full checkout flow (requires Stripe test mode)
+
+### Webhook local testing
+
+```bash
+stripe listen --forward-to localhost:3000/api/webhooks/stripe
+```
+
+### Documentation updates
+
+1. Update `docs/QUALITY_SCORE.md`:
+
+```markdown
+| Billing | B | Stripe checkout, portal, webhook, subscription gate |
+```
+
+2. Update `ARCHITECTURE.md` if this is the first payment integration
+3. Mark execution plan as complete
+
+## Environment Variables Summary
+
+```bash
+# Required
+STRIPE_SECRET_KEY=sk_test_...
+STRIPE_WEBHOOK_SECRET=whsec_...
+NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_test_...
+
+# Optional
+STRIPE_PRICE_ID_MONTHLY=price_...
+STRIPE_PRICE_ID_YEARLY=price_...
+```
+
+## Checklist
+
+- [ ] Execution plan created
+- [ ] Stripe SDK installed
+- [ ] Environment variables set
+- [ ] Lazy Stripe client created
+- [ ] Subscription + WebhookEvent Prisma models
+- [ ] Webhook handler with signature verification and idempotency
+- [ ] Webhook excluded from CSRF in middleware
+- [ ] Billing feature module with server/components/validation
+- [ ] Checkout API route
+- [ ] Portal API route
+- [ ] Subscription status API route
+- [ ] Pricing page (public or landing page section)
+- [ ] Billing dashboard page (protected)
+- [ ] SubscriptionGate component for premium features
+- [ ] `isSubscribed` helper for server-side gating
+- [ ] Feature flag `appConfig.features.billing` set to `true`
+- [ ] Unit tests for API routes and webhook
+- [ ] Local webhook testing verified
+- [ ] QUALITY_SCORE.md updated
+- [ ] Execution plan completed

package/cursor/skills/mars-setup-project/SKILL.md

@@ -0,0 +1,104 @@
+# Skill: Set Up a MARS Project
+
+Guide for setting up a new MARS project from scratch or getting an existing one running locally.
+
+## When to Use
+
+Use this skill when the user asks how to get started, set up their project, run locally, or troubleshoot a fresh install.
+
+## New Project (via CLI)
+
+```bash
+npx @mars-stack/cli create
+```
+
+The CLI will prompt for project name, features, services, and theme, then scaffold a ready-to-run project.
+
+## Existing Project Setup
+
+### 1. Install Dependencies
+
+```bash
+yarn install
+```
+
+### 2. Environment Variables
+
+Copy the example and fill in required values:
+
+```bash
+cp .env.example .env
+```
+
+**Required variables:**
+- `DATABASE_URL` -- Postgres connection string
+- `JWT_SECRET` -- Minimum 32 characters (generate with `openssl rand -hex 32`)
+
+**Optional (based on features):**
+- `SENDGRID_API_KEY` / `SENDGRID_FROM_EMAIL` -- if email provider is SendGrid
+- `STRIPE_SECRET_KEY` / `STRIPE_WEBHOOK_SECRET` -- if payments enabled
+- `UPSTASH_REDIS_REST_URL` / `UPSTASH_REDIS_REST_TOKEN` -- for production rate limiting
+
+### 3. Database
+
+**Option A: Local Docker (recommended for development)**
+
+```bash
+yarn dev:services          # Starts Postgres + Redis via Docker Compose
+yarn db:push               # Push schema to database
+```
+
+**Option B: Cloud database (Neon, Supabase, etc.)**
+
+Set `DATABASE_URL` in `.env` to your cloud connection string. For Neon:
+```
+DATABASE_URL="postgresql://user:pass@ep-xxx.region.aws.neon.tech/dbname?sslmode=require"
+```
+
+Then: `yarn db:push`
+
+### 4. Start Development
+
+```bash
+yarn dev                   # Starts Next.js with Turbopack
+```
+
+The app will be available at `http://localhost:3000`.
+
+## Health Check
+
+Run the built-in doctor to verify your setup:
+
+```bash
+npx @mars-stack/cli doctor
+```
+
+This checks: Node.js version, Yarn, Docker, Git, `.env` file, Prisma schema, database connection, and JWT_SECRET.
+
+## Common Issues
+
+### "Cannot connect to the database"
+- Is Docker running? `docker ps`
+- Start services: `yarn dev:services`
+- Check `DATABASE_URL` in `.env`
+
+### "Database tables are missing"
+- Run `yarn db:push` to create tables from the Prisma schema
+
+### "JWT_SECRET is required"
+- Generate one: `openssl rand -hex 32`
+- Add to `.env`: `JWT_SECRET="<generated-value>"`
+
+### Build fails with environment errors
+- The env validation is lazy and skips during build. Ensure `.env` exists for runtime.
+- `APP_URL` is optional (falls back to `localhost:3000` in dev).
+
+## Key Files
+
+| File | Purpose |
+|------|---------|
+| `src/config/app.config.ts` | App identity, features, services, theme |
+| `.env` | Environment secrets (never commit) |
+| `docker-compose.yml` | Local Postgres + Redis |
+| `prisma/schema/` | Database models (multi-file) |
+| `src/middleware.ts` | Auth redirects, CSRF, coming-soon mode |