@mars-stack/cli 0.2.0 → 1.0.2

package/template/.cursor/skills/build-complete-feature/SKILL.md

@@ -0,0 +1,227 @@
+# Skill: Build Complete Feature (Meta-Skill)
+
+Orchestrate the end-to-end implementation of a new feature from database schema through UI to tests and documentation. This meta-skill chains multiple sub-skills in the correct order.
+
+## When to Use
+
+Use this skill when the user asks to:
+- Build a complete feature end-to-end
+- Add a new domain with full CRUD (e.g., "add blog posts", "add projects", "add invoices")
+- Implement a feature from scratch with all layers (database, API, UI, tests)
+
+This is the right skill when the request implies multiple layers of work, not just a single API route or page.
+
+## Prerequisites
+
+- Read `AGENTS.md` to understand the project structure.
+- Read `src/config/app.config.ts` to check existing feature flags.
+- Read `prisma/schema/` to see existing models and relations.
+
+## Execution Order
+
+```
+┌─────────────────────────────────────────────────────┐
+│ Phase 0: Plan                                        │
+│   create-execution-plan                              │
+├─────────────────────────────────────────────────────┤
+│ Phase 1: Data Layer                                  │
+│   add-prisma-model → db:push                        │
+├─────────────────────────────────────────────────────┤
+│ Phase 2: Feature Module                              │
+│   add-feature (directory, types, validation, server) │
+├─────────────────────────────────────────────────────┤
+│ Phase 3: API Layer                                   │
+│   add-api-route (collection) → add-crud-routes       │
+│   ↳ If webhooks needed: add-webhook                  │
+├─────────────────────────────────────────────────────┤
+│ Phase 4: UI Layer                                    │
+│   add-page → add-component (list, form, detail)     │
+│   ↳ If data table needed: build-data-table           │
+│   ↳ If form needed: build-form                       │
+├─────────────────────────────────────────────────────┤
+│ Phase 5: Testing                                     │
+│   test-api-route → add-e2e-test                     │
+├─────────────────────────────────────────────────────┤
+│ Phase 6: Documentation                               │
+│   update-architecture-docs                           │
+└─────────────────────────────────────────────────────┘
+```
+
+## Phase 0: Create Execution Plan
+
+**Skill:** `create-execution-plan`
+
+Before writing any code, create an execution plan:
+
+1. Read existing code to understand the current state
+2. Create `docs/exec-plans/active/<feature-name>.md`
+3. List all tasks with phase prefixes
+4. Define verification criteria
+
+## Phase 1: Data Layer
+
+**Skill:** `add-prisma-model`
+
+1. Design the data model based on requirements
+2. Create `prisma/schema/<feature>.prisma` with the model(s)
+3. Add relations to existing models (e.g., User) in their respective schema files
+4. Run `yarn db:push` to sync
+
+**Outputs passed to Phase 2:**
+- Model name(s) and field names
+- Relation fields added to User or other models
+- Index definitions
+
+### Decision: Does this feature need multiple models?
+
+- **Single entity** (e.g., blog posts) → One model
+- **Entity with metadata** (e.g., posts with tags) → Two+ models with relations
+- **Entity with history** (e.g., orders with line items) → Parent-child models
+
+## Phase 2: Feature Module
+
+**Skill:** `add-feature`
+
+1. Create the feature directory structure:
+   ```
+   src/features/<name>/
+   ├── components/
+   ├── server/
+   ├── hooks/ (optional)
+   ├── validation/
+   └── types.ts
+   ```
+
+2. Create types based on the Prisma model
+3. Create Zod validation schemas for create/update inputs
+4. Create server module with queries and mutations (import `'server-only'`)
+
+**Outputs passed to Phase 3:**
+- Validation schema exports
+- Server function exports (findAll, findById, create, update, delete)
+- Type exports
+
+## Phase 3: API Layer
+
+**Skill:** `add-api-route` + `add-crud-routes`
+
+1. Create collection route: `src/app/api/protected/<name>/route.ts` (GET list, POST create)
+2. Create item route: `src/app/api/protected/<name>/[id]/route.ts` (GET one, PUT update, DELETE)
+
+**Conditional branches:**
+
+- **If the feature needs admin-only routes:**
+  Use `withRole(['admin'], ...)` for admin routes under `src/app/api/protected/admin/<name>/`
+
+- **If the feature receives external callbacks:**
+  **Skill:** `add-webhook` — Create webhook handler at `src/app/api/webhooks/<service>/`
+
+- **If the feature needs ownership-gated access:**
+  Use `withOwnership` in the item route to verify the user owns the resource
+
+**Outputs passed to Phase 4:**
+- API endpoint paths for client-side data fetching
+- Response shapes for TypeScript types
+
+## Phase 4: UI Layer
+
+**Skill:** `add-page` + `add-component`
+
+1. Create the main page: `src/app/(protected)/<name>/page.tsx`
+2. Create `loading.tsx` for Suspense fallback
+3. Create feature components in `src/features/<name>/components/`:
+
+**Conditional branches:**
+
+- **If the feature has a list view:**
+  **Skill:** `build-data-table` — Create a data table component with sorting, filtering, pagination
+
+- **If the feature has a create/edit form:**
+  **Skill:** `build-form` — Create a form component with validation, error handling, loading states
+
+- **If the feature has a detail view:**
+  Create a detail component that fetches a single item by ID
+
+4. Add route to `src/config/routes.ts`
+5. Add navigation link (if applicable)
+
+### Component breakdown
+
+| Component | Location | Purpose |
+|-----------|----------|---------|
+| `<Feature>List` | `src/features/<name>/components/` | List view with data table |
+| `<Feature>Form` | `src/features/<name>/components/` | Create/edit form |
+| `<Feature>Detail` | `src/features/<name>/components/` | Single item detail view |
+
+## Phase 5: Testing
+
+**Skill:** `test-api-route` + `add-e2e-test`
+
+1. Create unit tests for each API route (`route.test.ts` next to `route.ts`)
+2. Create unit tests for server module functions
+3. Create E2E tests for critical user flows:
+   - Can create a new item
+   - Can view the list
+   - Can edit an item
+   - Can delete an item
+   - Unauthorised access is rejected
+
+## Phase 6: Documentation
+
+**Skill:** `update-architecture-docs`
+
+1. Update `docs/QUALITY_SCORE.md` with the new feature grade
+2. Update `AGENTS.md` if the feature introduces new patterns
+3. Mark the execution plan as complete
+4. Move the plan from `active/` to `completed/`
+
+## Feature Flag Integration
+
+If the feature should be toggleable:
+
+1. Add flag to `appConfig.features` in `src/config/app.config.ts`
+2. Gate the API routes:
+   ```typescript
+   if (!appConfig.features.<name>) {
+     return NextResponse.json({ error: 'Feature not available' }, { status: 404 });
+   }
+   ```
+3. Gate the navigation link
+4. Gate the page (redirect if disabled)
+
+## Complete Example: Adding a "Projects" Feature
+
+```
+Phase 0: Create docs/exec-plans/active/add-projects.md
+Phase 1: Create prisma/schema/projects.prisma (Project model)
+         Add projects relation to User in auth.prisma
+         Run yarn db:push
+Phase 2: Create src/features/projects/ directory structure
+         Create types.ts, validation/schemas.ts, server/index.ts
+Phase 3: Create src/app/api/protected/projects/route.ts (GET, POST)
+         Create src/app/api/protected/projects/[id]/route.ts (GET, PUT, DELETE)
+Phase 4: Create src/app/(protected)/projects/page.tsx
+         Create ProjectList, ProjectForm components
+         Add to routes.ts
+Phase 5: Write route.test.ts for both API routes
+         Write projects.spec.ts E2E test
+Phase 6: Update QUALITY_SCORE.md
+         Complete execution plan
+```
+
+## Checklist
+
+- [ ] Execution plan created before starting
+- [ ] Prisma model(s) created and `db:push` run
+- [ ] Feature directory with correct structure
+- [ ] Server module with `'server-only'` import
+- [ ] Validation schemas for all inputs
+- [ ] CRUD API routes with auth wrappers
+- [ ] Page with loading state
+- [ ] List, form, and detail components
+- [ ] Route added to `routes.ts`
+- [ ] Feature flag in `app.config.ts` (if toggleable)
+- [ ] Unit tests for API routes
+- [ ] E2E tests for critical flows
+- [ ] QUALITY_SCORE.md updated
+- [ ] Execution plan marked complete

package/template/.cursor/skills/build-dashboard/SKILL.md

@@ -0,0 +1,211 @@
+# Skill: Build a Dashboard
+
+Create a dashboard page with stat cards, charts, recent activity, and quick actions using MARS design system components.
+
+## When to Use
+
+Use this skill when the user asks to build a dashboard, overview page, home screen, or analytics view.
+
+## Layout Architecture
+
+MARS dashboards use a responsive grid with Cards as the primary container:
+
+```tsx
+<div className="mx-auto max-w-7xl space-y-6 p-6">
+  {/* Header */}
+  <div>
+    <H1>Dashboard</H1>
+    <Paragraph className="text-text-secondary">Overview of your account.</Paragraph>
+  </div>
+
+  {/* Stat Cards Row */}
+  <div className="grid grid-cols-1 gap-4 sm:grid-cols-2 lg:grid-cols-4">
+    {/* ...stat cards */}
+  </div>
+
+  {/* Main Content */}
+  <div className="grid grid-cols-1 gap-6 lg:grid-cols-3">
+    <div className="lg:col-span-2">{/* Primary content */}</div>
+    <div>{/* Sidebar content */}</div>
+  </div>
+</div>
+```
+
+## Template: Stat Card
+
+```tsx
+import { Card, CardBody } from '@mars-stack/ui';
+
+interface StatCardProps {
+  title: string;
+  value: string | number;
+  change?: { value: number; label: string };
+  icon?: React.ReactNode;
+}
+
+function StatCard({ title, value, change, icon }: StatCardProps) {
+  return (
+    <Card>
+      <CardBody className="flex items-start justify-between">
+        <div>
+          <p className="text-sm font-medium text-text-secondary">{title}</p>
+          <p className="mt-1 text-2xl font-bold text-text-primary">{value}</p>
+          {change && (
+            <p className={`mt-1 text-sm ${change.value >= 0 ? 'text-text-success' : 'text-text-error'}`}>
+              {change.value >= 0 ? '↑' : '↓'} {Math.abs(change.value)}% {change.label}
+            </p>
+          )}
+        </div>
+        {icon && (
+          <div className="rounded-lg bg-brand-primary-muted p-2 text-brand-primary">
+            {icon}
+          </div>
+        )}
+      </CardBody>
+    </Card>
+  );
+}
+```
+
+## Template: Full Dashboard Page
+
+```tsx
+import { Card, CardHeader, CardBody, Badge, Spinner, H1, Paragraph } from '@mars-stack/ui';
+import type { Metadata } from 'next';
+
+export const metadata: Metadata = { title: 'Dashboard' };
+
+export default function DashboardPage() {
+  return (
+    <div className="mx-auto max-w-7xl space-y-6 p-6">
+      <div>
+        <H1>Dashboard</H1>
+        <Paragraph className="text-text-secondary">
+          Welcome back. Here&apos;s what&apos;s happening.
+        </Paragraph>
+      </div>
+
+      {/* Stats Row */}
+      <div className="grid grid-cols-1 gap-4 sm:grid-cols-2 lg:grid-cols-4">
+        <StatCard title="Total Users" value="1,234" change={{ value: 12, label: 'vs last month' }} />
+        <StatCard title="Revenue" value="£9,450" change={{ value: 8, label: 'vs last month' }} />
+        <StatCard title="Active Projects" value="23" />
+        <StatCard title="Completion Rate" value="94%" change={{ value: -2, label: 'vs last month' }} />
+      </div>
+
+      {/* Main Content Grid */}
+      <div className="grid grid-cols-1 gap-6 lg:grid-cols-3">
+        {/* Recent Activity */}
+        <Card className="lg:col-span-2">
+          <CardHeader>
+            <h2 className="text-lg font-semibold text-text-primary">Recent Activity</h2>
+          </CardHeader>
+          <CardBody>
+            <RecentActivityList />
+          </CardBody>
+        </Card>
+
+        {/* Quick Actions */}
+        <Card>
+          <CardHeader>
+            <h2 className="text-lg font-semibold text-text-primary">Quick Actions</h2>
+          </CardHeader>
+          <CardBody className="space-y-2">
+            <QuickActionButton label="Create New Project" href="/projects/new" />
+            <QuickActionButton label="Invite Team Member" href="/settings/team" />
+            <QuickActionButton label="View Reports" href="/reports" />
+          </CardBody>
+        </Card>
+      </div>
+    </div>
+  );
+}
+```
+
+## Template: Recent Activity List
+
+```tsx
+interface ActivityItem {
+  id: string;
+  action: string;
+  subject: string;
+  timestamp: string;
+  status?: 'success' | 'warning' | 'error' | 'info';
+}
+
+function RecentActivityList({ items }: { items: ActivityItem[] }) {
+  return (
+    <ul className="divide-y divide-border-divider">
+      {items.map((item) => (
+        <li key={item.id} className="flex items-center justify-between py-3">
+          <div>
+            <p className="text-sm font-medium text-text-primary">{item.action}</p>
+            <p className="text-sm text-text-secondary">{item.subject}</p>
+          </div>
+          <div className="flex items-center gap-3">
+            {item.status && <Badge variant={item.status}>{item.status}</Badge>}
+            <span className="text-xs text-text-muted whitespace-nowrap">
+              {new Date(item.timestamp).toLocaleDateString()}
+            </span>
+          </div>
+        </li>
+      ))}
+    </ul>
+  );
+}
+```
+
+## Template: Quick Action Button
+
+```tsx
+import { LinkButton } from '@mars-stack/ui';
+
+function QuickActionButton({ label, href }: { label: string; href: string }) {
+  return (
+    <LinkButton href={href} variant="subtle" className="w-full justify-start">
+      {label}
+    </LinkButton>
+  );
+}
+```
+
+## Data Fetching Pattern
+
+Dashboards typically aggregate data from multiple sources. Use parallel fetches:
+
+```typescript
+// API route: /api/protected/dashboard/route.ts
+export const GET = withAuthNoParams(async (request: AuthenticatedRequest) => {
+  try {
+    const userId = request.session.userId;
+
+    const [stats, recentActivity] = await Promise.all([
+      getDashboardStats(userId),
+      getRecentActivity(userId, 10),
+    ]);
+
+    return NextResponse.json({ stats, recentActivity });
+  } catch (error) {
+    return handleApiError(error, { endpoint: '/api/protected/dashboard' });
+  }
+});
+```
+
+## Responsive Breakpoints
+
+| Breakpoint | Stat Cards | Main Grid |
+|-----------|-----------|-----------|
+| Mobile (`< sm`) | 1 column | 1 column |
+| Tablet (`sm`) | 2 columns | 1 column |
+| Desktop (`lg`) | 4 columns | 2:1 ratio |
+
+## Checklist
+
+- [ ] Page wrapped in max-width container with padding
+- [ ] Stat cards in responsive grid (1/2/4 columns)
+- [ ] Main content in 2:1 grid layout at `lg`
+- [ ] All colours use semantic tokens
+- [ ] Loading state for async data
+- [ ] Empty states for sections with no data
+- [ ] SEO metadata exported
+- [ ] Data fetched via protected API route