@mars-stack/cli 0.2.0 → 1.0.2

package/template/.cursor/skills/create-execution-plan/SKILL.md

@@ -0,0 +1,204 @@
+# Skill: Create Execution Plan
+
+Create and manage execution plans in `docs/exec-plans/` to track multi-step implementation work with clear goals, tasks, and verification criteria.
+
+## When to Use
+
+Use this skill when:
+- Starting a large or multi-step implementation task
+- The user asks to plan work, create a plan, or organise tasks
+- A meta-skill needs to create a plan before executing
+- You need to track progress across multiple related changes
+
+## Prerequisites
+
+- Read `docs/exec-plans/` to see existing plans and the directory structure.
+- Read `docs/QUALITY_SCORE.md` to understand current quality grades.
+
+## Plan Directory Structure
+
+```
+docs/exec-plans/
+├── active/              # Plans currently being worked on
+│   └── <plan-name>.md
+├── completed/           # Finished plans (moved from active/)
+│   └── <plan-name>.md
+└── templates/           # (optional) Plan templates
+```
+
+## Step 1: Choose a Plan Name
+
+Use kebab-case that describes the goal, not the method:
+
+| Good | Bad |
+|------|-----|
+| `add-billing-system` | `stripe-integration` |
+| `fix-auth-redirects` | `update-middleware` |
+| `setup-team-management` | `prisma-models` |
+
+## Step 2: Create the Plan File
+
+```markdown
+# Execution Plan: <Title>
+
+**Status:** Active
+**Priority:** P0 / P1 / P2
+**Created:** <YYYY-MM-DD>
+**Estimated effort:** S / M / L / XL
+
+## Goal
+
+<1-2 sentences describing the end state. What does "done" look like? Focus on user-visible outcomes.>
+
+## Context
+
+<Why is this work needed? What problem does it solve? Link to related issues, quality score entries, or design docs.>
+
+## Tasks
+
+- [ ] **1.1 <Task title>** — <Brief description of what to do and why>
+- [ ] **1.2 <Task title>** — <Brief description>
+- [ ] **2.1 <Task title>** — <Brief description (new section number = new phase)>
+- [ ] **2.2 <Task title>** — <Brief description>
+
+## Verification
+
+- [ ] <Concrete, testable assertion about the end state>
+- [ ] <Another testable assertion>
+- [ ] <Build passes: `yarn build` succeeds>
+- [ ] <Tests pass: `yarn test` succeeds>
+
+## Quality Score Updates
+
+After completion, update these entries in `docs/QUALITY_SCORE.md`:
+
+| Domain | Current | Target | Notes |
+|--------|---------|--------|-------|
+| <domain> | <current grade> | <target grade> | <what changes> |
+
+## Notes
+
+<Any constraints, risks, open questions, or design decisions made during planning.>
+```
+
+## Step 3: Writing Good Tasks
+
+### Task granularity
+
+Each task should be completable in a single focused session. If a task would take multiple hours, break it down.
+
+### Task ordering
+
+Number tasks with a phase prefix (`1.x`, `2.x`, `3.x`) where:
+- **Phase 1** — Schema and data model changes
+- **Phase 2** — Server-side logic (services, API routes)
+- **Phase 3** — Client-side UI (pages, components)
+- **Phase 4** — Testing and documentation
+
+Tasks within a phase can be done in any order. Phases should be sequential.
+
+### Task dependencies
+
+If a task depends on another, note it:
+
+```markdown
+- [ ] **2.1 Create billing service** — Depends on 1.1. Server module in `src/features/billing/server/`.
+```
+
+## Step 4: Writing Verification Criteria
+
+Verification items should be:
+- **Specific** — Not "it works", but "navigating to `/billing` shows subscription status"
+- **Testable** — Can be verified in under 2 minutes
+- **User-centric** — Focus on observable behaviour, not implementation details
+
+```markdown
+## Verification
+
+- [ ] `mars create test-app` produces a project that passes `yarn build`
+- [ ] Navigating to `/billing` shows the current subscription status
+- [ ] Clicking "Upgrade" creates a Stripe Checkout session and redirects
+- [ ] Webhook processes `checkout.session.completed` and updates the DB
+- [ ] Non-subscribed users see the pricing page instead of premium features
+```
+
+## Step 5: Update Progress
+
+As work progresses, check off tasks and add notes:
+
+```markdown
+- [x] **1.1 Add Subscription model** — Done. Added `prisma/schema/billing.prisma`.
+- [ ] **1.2 Add webhook event model** — In progress.
+```
+
+## Step 6: Complete the Plan
+
+When all tasks and verification criteria are met:
+
+1. Update the status to `Completed`:
+
+```markdown
+**Status:** Completed
+**Completed:** <YYYY-MM-DD>
+```
+
+2. Move the file from `active/` to `completed/`:
+
+```bash
+mv docs/exec-plans/active/<plan>.md docs/exec-plans/completed/<plan>.md
+```
+
+3. Update `docs/QUALITY_SCORE.md` with new grades.
+
+## Step 7: Link from QUALITY_SCORE.md
+
+When creating a plan that addresses quality score gaps, add a reference:
+
+```markdown
+| Dashboard | D | Empty placeholder page | → [exec-plan: add-dashboard](exec-plans/active/add-dashboard.md) |
+```
+
+## Templates for Common Plans
+
+### Feature addition plan
+
+```markdown
+## Tasks
+
+- [ ] **1.1 Prisma schema** — Add models to `prisma/schema/<name>.prisma`
+- [ ] **1.2 Run db:push** — Sync schema to dev database
+- [ ] **2.1 Feature directory** — Create `src/features/<name>/` with server/, components/, validation/
+- [ ] **2.2 Server module** — Implement queries and mutations
+- [ ] **2.3 Validation schemas** — Zod schemas for API inputs
+- [ ] **3.1 API routes** — CRUD routes under `src/app/api/protected/<name>/`
+- [ ] **3.2 Page** — Create page at `src/app/(protected)/<name>/page.tsx`
+- [ ] **3.3 Components** — Feature-specific UI components
+- [ ] **4.1 Tests** — API route tests with mocked Prisma and auth
+- [ ] **4.2 E2E tests** — Playwright tests for critical user flows
+- [ ] **4.3 Update docs** — Update ARCHITECTURE.md and QUALITY_SCORE.md
+```
+
+### Bug fix plan
+
+```markdown
+## Tasks
+
+- [ ] **1.1 Reproduce** — Create a minimal reproduction of the issue
+- [ ] **1.2 Root cause** — Identify why the bug occurs
+- [ ] **2.1 Fix** — Implement the fix
+- [ ] **2.2 Regression test** — Add test that would have caught this bug
+- [ ] **3.1 Verify** — Confirm the fix in dev environment
+- [ ] **3.2 Update quality score** — Update grades in QUALITY_SCORE.md
+```
+
+## Checklist
+
+- [ ] Plan file created in `docs/exec-plans/active/`
+- [ ] Title is descriptive and goal-oriented
+- [ ] Status, priority, date, and effort estimate included
+- [ ] Goal section describes the end state clearly
+- [ ] Tasks are numbered with phase prefixes
+- [ ] Each task has a title and brief description
+- [ ] Verification criteria are specific and testable
+- [ ] Quality Score update table included
+- [ ] Plan linked from QUALITY_SCORE.md if addressing a gap

package/template/.cursor/skills/create-seed/SKILL.md

@@ -0,0 +1,191 @@
+# Skill: Create a Database Seed
+
+Create a Prisma seed script to populate the database with development data.
+
+## When to Use
+
+Use this skill when the user asks to add seed data, test data, sample data, or wants to populate the database for development.
+
+## Setup
+
+### Step 1: Create the Seed File
+
+Create `prisma/seed.ts`:
+
+```typescript
+import { PrismaClient } from '@db';
+import { PrismaPg } from '@prisma/adapter-pg';
+import { hash } from 'bcryptjs';
+
+const adapter = new PrismaPg({ connectionString: process.env.DATABASE_URL! });
+const prisma = new PrismaClient({ adapter });
+
+async function main() {
+  console.log('Seeding database...');
+
+  // Clean existing data (order matters for foreign keys)
+  await prisma.verificationToken.deleteMany();
+  await prisma.session.deleteMany();
+  await prisma.account.deleteMany();
+  await prisma.user.deleteMany();
+
+  // Create admin user
+  const adminPassword = await hash('admin123456', 12);
+  const admin = await prisma.user.create({
+    data: {
+      email: 'admin@example.com',
+      name: 'Admin User',
+      password: adminPassword,
+      role: 'admin',
+      emailVerified: new Date(),
+      termsAcceptedAt: new Date(),
+      privacyAcceptedAt: new Date(),
+    },
+  });
+  console.log(`  Created admin: ${admin.email}`);
+
+  // Create regular users
+  const userPassword = await hash('user123456', 12);
+  const users = await Promise.all(
+    Array.from({ length: 5 }, (_, i) =>
+      prisma.user.create({
+        data: {
+          email: `user${i + 1}@example.com`,
+          name: `Test User ${i + 1}`,
+          password: userPassword,
+          role: 'user',
+          emailVerified: new Date(),
+          termsAcceptedAt: new Date(),
+          privacyAcceptedAt: new Date(),
+        },
+      }),
+    ),
+  );
+  console.log(`  Created ${users.length} users`);
+
+  // Seed feature-specific data here
+  // Example: create items for the first user
+  // await prisma.item.createMany({
+  //   data: Array.from({ length: 10 }, (_, i) => ({
+  //     name: `Item ${i + 1}`,
+  //     userId: users[0].id,
+  //   })),
+  // });
+
+  console.log('Seeding complete.');
+}
+
+main()
+  .catch((error) => {
+    console.error('Seed error:', error);
+    process.exit(1);
+  })
+  .finally(() => prisma.$disconnect());
+```
+
+### Step 2: Configure package.json
+
+Add the seed command to `package.json`:
+
+```json
+{
+  "prisma": {
+    "schema": "prisma/schema",
+    "seed": "tsx prisma/seed.ts"
+  }
+}
+```
+
+### Step 3: Install tsx (if not already)
+
+```bash
+yarn add -D tsx
+```
+
+### Step 4: Run the Seed
+
+```bash
+yarn db:seed
+```
+
+Or automatically after reset:
+
+```bash
+npx prisma migrate reset    # Runs seed automatically after reset
+```
+
+## Patterns
+
+### Deterministic IDs (for testing)
+
+Use fixed IDs so tests can reference specific records:
+
+```typescript
+const admin = await prisma.user.create({
+  data: {
+    id: 'seed-admin-001',
+    email: 'admin@example.com',
+    // ...
+  },
+});
+```
+
+### Realistic Data with Helpers
+
+```typescript
+function randomDate(start: Date, end: Date): Date {
+  return new Date(start.getTime() + Math.random() * (end.getTime() - start.getTime()));
+}
+
+function randomElement<T>(array: T[]): T {
+  return array[Math.floor(Math.random() * array.length)];
+}
+
+const statuses = ['draft', 'active', 'archived'] as const;
+
+await prisma.item.createMany({
+  data: Array.from({ length: 50 }, (_, i) => ({
+    name: `Item ${i + 1}`,
+    status: randomElement(statuses),
+    createdAt: randomDate(new Date('2024-01-01'), new Date()),
+    userId: randomElement(users).id,
+  })),
+});
+```
+
+### Conditional Seeding
+
+Only seed data relevant to enabled features:
+
+```typescript
+import { appConfig } from '../src/config/app.config';
+
+if (appConfig.features.billing) {
+  // Seed subscription plans, etc.
+}
+
+if (appConfig.features.blog) {
+  // Seed blog posts, categories, etc.
+}
+```
+
+## Rules
+
+- **Never use seed scripts in production.** Guard with an environment check if needed.
+- **Clean data in reverse dependency order** (child tables first, then parent tables).
+- **Use `createMany` for bulk inserts** -- significantly faster than individual `create` calls.
+- **Hash passwords properly** -- use the same `bcryptjs` library as the auth system.
+- **Don't seed secrets** -- use placeholder values for development only.
+- **Make seeds idempotent** -- always delete existing data before inserting.
+
+## Checklist
+
+- [ ] Seed file at `prisma/seed.ts`
+- [ ] `prisma.seed` configured in `package.json`
+- [ ] `tsx` added as dev dependency
+- [ ] Admin user with known credentials seeded
+- [ ] Regular test users seeded
+- [ ] Feature-specific data seeded
+- [ ] Data cleaned before seeding (idempotent)
+- [ ] Passwords hashed with bcryptjs
+- [ ] `yarn db:seed` runs without errors

package/template/.cursor/skills/deploy-to-vercel/SKILL.md

@@ -0,0 +1,300 @@
+# Skill: Deploy to Vercel
+
+Step-by-step guide for deploying a Mars application to Vercel, including CLI setup, environment variables, database provisioning, and post-deploy verification.
+
+## When to Use
+
+Use this skill when the user asks to deploy to Vercel, set up hosting, go to production, configure deployment, or publish their application.
+
+## Prerequisites
+
+- A Vercel account at [vercel.com](https://vercel.com)
+- The application builds locally with `yarn build`
+- Git repository initialized and pushed to GitHub/GitLab/Bitbucket
+
+## Step 1: Install Vercel CLI
+
+```bash
+yarn global add vercel
+# or
+npm i -g vercel
+```
+
+Login to Vercel:
+
+```bash
+vercel login
+```
+
+## Step 2: Link the Project
+
+From the project root:
+
+```bash
+vercel link
+```
+
+This creates `.vercel/project.json` with the project ID. Add `.vercel` to `.gitignore` if not already present.
+
+## Step 3: Provision Database
+
+### Option A: Vercel Postgres (recommended for simplicity)
+
+```bash
+vercel env pull .env.local
+```
+
+1. Go to your Vercel project dashboard → Storage → Create Database → Postgres
+2. Vercel automatically adds `POSTGRES_URL`, `POSTGRES_PRISMA_URL`, etc. to your project env vars.
+
+Update `prisma/schema/base.prisma` to use the Vercel Postgres URL:
+
+```prisma
+datasource db {
+  provider  = "postgresql"
+  url       = env("POSTGRES_PRISMA_URL")
+  directUrl = env("POSTGRES_URL_NON_POOLING")
+}
+```
+
+### Option B: Neon (recommended for production)
+
+1. Create a database at [neon.tech](https://neon.tech)
+2. Copy the connection string
+3. Set it in Vercel:
+
+```bash
+vercel env add DATABASE_URL production
+vercel env add DATABASE_URL preview
+```
+
+### Run Migrations
+
+After database provisioning, push the schema:
+
+```bash
+# Pull production env vars locally
+vercel env pull .env.production.local
+
+# Push schema to production database
+DATABASE_URL="<production-url>" npx prisma db push
+```
+
+## Step 4: Provision KV Store (Rate Limiting)
+
+Mars uses Upstash Redis for rate limiting in production.
+
+### Option A: Vercel KV
+
+1. Vercel Dashboard → Storage → Create Database → KV
+2. Vercel automatically adds `KV_REST_API_URL` and `KV_REST_API_TOKEN`
+
+### Option B: Upstash Directly
+
+1. Create a database at [upstash.com](https://upstash.com)
+2. Set environment variables:
+
+```bash
+vercel env add UPSTASH_REDIS_REST_URL production
+vercel env add UPSTASH_REDIS_REST_TOKEN production
+```
+
+## Step 5: Set Environment Variables
+
+Required variables for a Mars app:
+
+```bash
+# Authentication (REQUIRED)
+vercel env add JWT_SECRET production       # Generate: openssl rand -base64 32
+vercel env add JWT_SECRET preview          # Use a different secret for preview
+
+# App URL (REQUIRED)
+vercel env add APP_URL production          # https://your-domain.com
+vercel env add NEXT_PUBLIC_APP_URL production  # Same as APP_URL
+
+# Database (set during provisioning)
+# POSTGRES_URL / DATABASE_URL — already set if using Vercel Postgres
+
+# Rate Limiting (REQUIRED for production)
+# UPSTASH_REDIS_REST_URL — already set if using Vercel KV
+# UPSTASH_REDIS_REST_TOKEN — already set if using Vercel KV
+```
+
+Optional variables based on enabled features:
+
+```bash
+# Email (if appConfig.features.email is true)
+vercel env add RESEND_API_KEY production
+vercel env add EMAIL_FROM production       # noreply@yourdomain.com
+
+# Payments (if appConfig.features.billing is true)
+vercel env add STRIPE_SECRET_KEY production
+vercel env add STRIPE_WEBHOOK_SECRET production
+vercel env add NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY production
+
+# Storage (if appConfig.features.storage is true)
+vercel env add BLOB_READ_WRITE_TOKEN production
+
+# Error Reporting (optional)
+vercel env add NEXT_PUBLIC_SENTRY_DSN production
+vercel env add SENTRY_ORG production
+vercel env add SENTRY_PROJECT production
+
+# Cron Jobs (if using Vercel Cron)
+vercel env add CRON_SECRET production      # Generate: openssl rand -base64 32
+```
+
+## Step 6: Configure `vercel.json` (Optional)
+
+```json
+{
+  "framework": "nextjs",
+  "buildCommand": "yarn build",
+  "installCommand": "yarn install --frozen-lockfile",
+  "regions": ["iad1"],
+  "headers": [
+    {
+      "source": "/api/(.*)",
+      "headers": [
+        { "key": "X-Content-Type-Options", "value": "nosniff" },
+        { "key": "X-Frame-Options", "value": "DENY" }
+      ]
+    }
+  ],
+  "crons": []
+}
+```
+
+## Step 7: Deploy
+
+### First Deploy (Preview)
+
+```bash
+vercel
+```
+
+This deploys to a preview URL. Test thoroughly before promoting.
+
+### Production Deploy
+
+```bash
+vercel --prod
+```
+
+### Git Integration (Recommended)
+
+Push to your default branch for automatic production deployments:
+
+```bash
+git push origin main
+```
+
+Vercel automatically deploys:
+- `main` branch → Production
+- Other branches → Preview deployments
+
+## Step 8: Configure Custom Domain
+
+1. Vercel Dashboard → Settings → Domains
+2. Add your domain (e.g., `app.yourdomain.com`)
+3. Update DNS records as shown by Vercel
+4. Wait for SSL certificate provisioning
+
+After domain is live, update:
+
+```bash
+vercel env add APP_URL production          # https://app.yourdomain.com
+vercel env add NEXT_PUBLIC_APP_URL production  # https://app.yourdomain.com
+```
+
+Redeploy to pick up the new URL:
+
+```bash
+vercel --prod
+```
+
+## Step 9: Post-Deploy Verification
+
+Run through this checklist after each production deployment:
+
+### Automated checks
+
+```bash
+# Health check (if endpoint exists)
+curl -f https://your-app.vercel.app/api/health
+
+# Check the deployment is accessible
+curl -s -o /dev/null -w "%{http_code}" https://your-app.vercel.app
+```
+
+### Manual verification
+
+1. **Auth flow** — Register, login, logout, password reset
+2. **CSRF protection** — API calls include CSRF token, reject without it
+3. **Rate limiting** — Rapid requests get 429 responses
+4. **Protected routes** — Unauthenticated access redirects to login
+5. **Email delivery** — Test verification and password reset emails
+6. **Database connectivity** — Data persists across requests
+7. **Environment** — `process.env.NODE_ENV === 'production'` in server logs
+
+### Monitoring
+
+- Vercel Dashboard → Logs for runtime errors
+- Vercel Dashboard → Analytics for performance metrics
+- Vercel Dashboard → Speed Insights for Core Web Vitals
+
+## Stripe Webhook Setup (If Billing Enabled)
+
+After deployment, configure the production webhook:
+
+1. Go to [Stripe Dashboard → Webhooks](https://dashboard.stripe.com/webhooks)
+2. Add endpoint: `https://your-domain.com/api/webhooks/stripe`
+3. Select events: `checkout.session.completed`, `customer.subscription.updated`, `customer.subscription.deleted`
+4. Copy the webhook signing secret
+5. Set it in Vercel:
+
+```bash
+vercel env add STRIPE_WEBHOOK_SECRET production
+vercel --prod  # Redeploy
+```
+
+## Troubleshooting
+
+| Issue | Cause | Fix |
+|-------|-------|-----|
+| Build fails | Missing env vars | Check Vercel build logs, add missing vars |
+| 500 errors | Database not connected | Verify `DATABASE_URL` env var is set correctly |
+| CSRF errors | `APP_URL` mismatch | Ensure `APP_URL` matches the actual deployment URL |
+| Rate limiting disabled | Missing Upstash vars | Provision KV store and set `UPSTASH_*` variables |
+| Emails not sending | Missing `RESEND_API_KEY` | Add the key and verify domain in Resend dashboard |
+
+## Preview Deployments
+
+Preview deployments use separate env vars. Set preview-specific values:
+
+```bash
+vercel env add JWT_SECRET preview
+vercel env add APP_URL preview    # Will be overridden by VERCEL_URL
+```
+
+For preview deployments, consider using `VERCEL_URL`:
+
+```typescript
+const appUrl = process.env.APP_URL
+  ?? (process.env.VERCEL_URL ? `https://${process.env.VERCEL_URL}` : 'http://localhost:3000');
+```
+
+## Checklist
+
+- [ ] Vercel CLI installed and logged in
+- [ ] Project linked with `vercel link`
+- [ ] Database provisioned and schema pushed
+- [ ] KV store provisioned for rate limiting
+- [ ] All required environment variables set
+- [ ] `JWT_SECRET` is unique per environment (production/preview)
+- [ ] `APP_URL` matches the deployment URL
+- [ ] Custom domain configured (optional)
+- [ ] Stripe webhook configured (if billing enabled)
+- [ ] Post-deploy verification completed
+- [ ] Git integration working (push = deploy)
+- [ ] Preview deployments tested