@mars-stack/core 2.0.1 → 3.0.1

package/cursor/rules/mars-data-access.mdc

@@ -4,13 +4,16 @@ globs: **/server/**
 alwaysApply: false
 ---
 
-## Prisma
+## Prisma (v7)
 
-- Import the lazy-loaded client: `import { prisma } from '@/lib/prisma'`.
+- Import the database client: `import { prisma } from '@/lib/prisma'`.
+- Import Prisma types (models, enums, namespaces): `import type { User } from '@db'` or `import { Prisma } from '@db'`. The `@db` alias maps to `prisma/generated/prisma/client`.
+- The `datasource` URL lives in `prisma.config.ts`, **not** in the schema file.
+- `PrismaClient` requires a driver adapter: `new PrismaClient({ adapter })` with `@prisma/adapter-pg`.
+- After changing the schema: `yarn db:generate` then `yarn db:push` (dev) or `yarn db:migrate` (with migration history). `prisma generate` no longer auto-runs.
 - User-scoped queries MUST include `userId` from the authenticated session in the `where` clause, never from request parameters.
 - Use `$transaction` for multi-step writes that must be atomic.
 - New models go in `prisma/schema/` as separate `.prisma` files (multi-file schema).
-- After changing the schema: `yarn db:push` (dev) or `yarn db:migrate dev` (with migration history).
 
 ## Error Handling
 

package/cursor/rules/mars-testing.mdc

@@ -12,8 +12,8 @@ alwaysApply: false
 
 ## Mocking
 
-- Use `@mars-stack/core/test-utils/mock-auth` to mock authenticated sessions in API route tests.
-- Use `@mars-stack/core/test-utils/factories` for consistent test data.
+- Use `@mars-stack/core/test-utils` to mock authenticated sessions in API route tests.
+- Use `@mars-stack/core/test-utils` for consistent test data.
 - Mock Prisma with `vi.mock('@/lib/prisma')` and provide typed mocks for each model method.
 
 ## Patterns

package/cursor/rules/mars-ui-conventions.mdc

@@ -17,13 +17,13 @@ MARS uses a three-layer CSS token system. Never use raw Tailwind colour classes
 
 ## Component Architecture
 
-- **Primitives** (`@mars-stack/ui`): Single-responsibility, fully styled via tokens, accept `className` for overrides. Examples: `Button`, `Input`, `Badge`, `Avatar`, `Spinner`.
-- **Patterns** (`@mars-stack/ui`): Compose primitives, no business logic. Examples: `Card`, `Modal`, `Toast`, `FormField`, `EmptyState`.
+- **Primitives** (`@mars-stack/ui` (primitives)): Single-responsibility, fully styled via tokens, accept `className` for overrides. Examples: `Button`, `Input`, `Badge`, `Avatar`, `Spinner`.
+- **Patterns** (`@mars-stack/ui` (patterns)): Compose primitives, no business logic. Examples: `Card`, `Modal`, `Toast`, `FormField`, `EmptyState`.
 - **Feature components** (`src/features/<name>/components/`): Contain business logic, compose primitives and patterns.
 
 ## Rules
 
-- Always import components from `@mars-stack/ui` (both primitives and patterns are exported from this package).
+- Always import components from barrel exports: `@mars-stack/ui` or `@mars-stack/ui`.
 - Use `clsx` for conditional class composition.
-- New shared primitives go in the `@mars-stack/ui` package.
+- New primitives go in `@mars-stack/ui` (primitives) with a barrel re-export.
 - Components MUST support dark mode via the token system (tokens swap automatically with `.dark` class).

package/cursor/skills/mars-add-api-route/SKILL.md

@@ -44,7 +44,9 @@ export const GET = withAuthNoParams(async (request: AuthenticatedRequest) => {
 
 ```typescript
 import { handleApiError } from '@/lib/mars';
-import { checkRateLimit, getClientIP, RATE_LIMITS, rateLimitResponse } from '@mars-stack/core/rate-limit';
+import {
+  checkRateLimit, getClientIP, RATE_LIMITS, rateLimitResponse,
+} from '@mars-stack/core/rate-limit';
 import { NextResponse } from 'next/server';
 
 export async function POST(request: Request) {

package/cursor/skills/mars-add-component/SKILL.md

@@ -144,7 +144,7 @@ When adding overlay buttons inside an input (e.g. password visibility toggle):
 
 ## After Creating
 
-1. Add the export to the appropriate barrel in the `@mars-stack/ui` package.
+1. Add the export to the `@mars-stack/ui` package barrel file.
 2. Export both the component and its props type.
 
 ## Checklist

package/cursor/skills/mars-add-feature/SKILL.md

@@ -143,9 +143,9 @@ If the feature should be toggleable, add it to `appConfig.features` in `src/conf
 Create `route.test.ts` next to each API route. Mock Prisma and auth:
 
 ```typescript
+import { mockAuth } from '@mars-stack/core/test-utils';
 import { describe, it, expect, vi, beforeEach } from 'vitest';
 import { GET, POST } from './route';
-import { mockAuth } from '@mars-stack/core/test-utils';
 
 vi.mock('@/lib/prisma', () => ({
   prisma: {

package/cursor/skills/mars-add-page/SKILL.md

@@ -19,8 +19,7 @@ The middleware at `src/middleware.ts` handles auth redirects automatically based
 ## Protected Page Template
 
 ```tsx
-import { Card, CardHeader, CardBody } from '@mars-stack/ui';
-import { H1, Paragraph } from '@mars-stack/ui';
+import { Card, CardHeader, CardBody, H1, Paragraph } from '@mars-stack/ui';
 
 export default function WidgetsPage() {
   return (
@@ -69,9 +68,8 @@ For pages that need client-side data, create a client component in the feature m
 // src/features/widgets/components/WidgetList.tsx
 'use client';
 
+import { Card, CardBody, Spinner, Badge, EmptyState } from '@mars-stack/ui';
 import { useEffect, useState } from 'react';
-import { Card, CardBody, EmptyState } from '@mars-stack/ui';
-import { Spinner, Badge } from '@mars-stack/ui';
 import type { Widget } from '@/features/widgets/types';
 
 export function WidgetList() {

package/cursor/skills/mars-add-server-action/SKILL.md

@@ -117,9 +117,9 @@ export async function createItem(formData: FormData) {
 ```tsx
 'use client';
 
+import { Button, Input } from '@mars-stack/ui';
 import { useActionState } from 'react';
 import { updateProfile } from '@/features/settings/server/actions';
-import { Button, Input } from '@mars-stack/ui';
 
 export function ProfileForm({ currentName }: { currentName: string }) {
   const [state, formAction, isPending] = useActionState(updateProfile, {

package/cursor/skills/mars-add-webhook/SKILL.md

@@ -172,7 +172,7 @@ async function processEvent(eventId: string, handler: () => Promise<void>) {
 
 ## Environment Variables
 
-Add webhook secrets to your env validation schema:
+Add webhook secrets to `src/core/env/index.ts` in `buildEnvSchema()`:
 
 ```typescript
 base.STRIPE_WEBHOOK_SECRET = z.string().min(1).optional();

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

@@ -171,10 +171,9 @@ Before writing any code, create an execution plan:
 **Skill:** `update-architecture-docs`
 
 1. Update `docs/QUALITY_SCORE.md` with the new feature grade
-2. Update `ARCHITECTURE.md` if the feature introduces new patterns
-3. Update `template/AGENTS.md` if the template structure changed
-4. Mark the execution plan as complete
-5. Move the plan from `active/` to `completed/`
+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
 

package/cursor/skills/mars-build-data-table/SKILL.md

@@ -15,11 +15,10 @@ MARS provides `Table` primitives (`Table`, `TableHead`, `TableBody`, `TableRow`,
 ```tsx
 'use client';
 
-import { useEffect, useState, useCallback } from 'react';
 import {
-  Table, TableHead, TableBody, TableRow, TableHeaderCell, TableCell,
-  Badge, Button, Spinner, Card, CardHeader, CardBody, EmptyState,
+  Table, TableHead, TableBody, TableRow, TableHeaderCell, TableCell, Badge, Button, Spinner, Card, CardHeader, CardBody, EmptyState,
 } from '@mars-stack/ui';
+import { useEffect, useState, useCallback } from 'react';
 
 interface Item {
   id: string;

package/cursor/skills/mars-build-form/SKILL.md

@@ -19,8 +19,10 @@ MARS forms use:
 ```tsx
 'use client';
 
+import {
+  Button, Input, Select, Textarea, Checkbox, Card, CardHeader, CardBody, CardFooter, H2,
+} from '@mars-stack/ui';
 import { useState, type FormEvent } from 'react';
-import { Button, Input, Select, Textarea, Checkbox, Card, CardHeader, CardBody, CardFooter, H2 } from '@mars-stack/ui';
 import { z } from 'zod';
 
 const formSchema = z.object({

package/cursor/skills/mars-configure-email/SKILL.md

@@ -8,7 +8,7 @@ Use this skill when the user asks to configure email, set up SendGrid, add Resen
 
 ## Architecture
 
-MARS uses a pluggable email service via `@/lib/mars` (which re-exports from `@mars-stack/core`). The active provider is set in `appConfig.services.email.provider`.
+MARS uses a pluggable email service re-exported via `@/lib/mars`. The active provider is set in `appConfig.services.email.provider`.
 
 Available providers:
 - `console` -- logs emails to terminal (default, no setup needed)
@@ -42,7 +42,7 @@ RESEND_FROM_EMAIL="noreply@yourdomain.com"
 
 ### Step 3: Update Env Validation
 
-The env validation schema already conditionally validates email vars:
+In `src/core/env/index.ts`, the schema already conditionally validates email vars:
 
 ```typescript
 if (appConfig.services.email.provider !== 'console') {
@@ -61,7 +61,7 @@ yarn add resend
 
 ### Step 2: Add the Provider
 
-In the email service module (via `@mars-stack/core`):
+In the email service module (wired through `@/lib/mars`):
 
 ```typescript
 async function sendWithResend(params: SendEmailParams): Promise<void> {

package/cursor/skills/mars-configure-oauth/SKILL.md

@@ -31,7 +31,7 @@ GOOGLE_CLIENT_ID="your-client-id.apps.googleusercontent.com"
 GOOGLE_CLIENT_SECRET="your-client-secret"
 ```
 
-Update the env validation schema to validate these:
+Update `src/core/env/index.ts` to validate these:
 
 ```typescript
 if (appConfig.features.googleOAuth) {

package/cursor/skills/mars-configure-payments/SKILL.md

@@ -81,8 +81,8 @@ model Subscription {
 ```typescript
 // src/app/api/protected/billing/checkout/route.ts
 import { handleApiError, withAuthNoParams, type AuthenticatedRequest } from '@/lib/mars';
-import { getStripe } from '@/features/billing/server';
 import { prisma } from '@/lib/prisma';
+import { getStripe } from '@/features/billing/server';
 import { NextResponse } from 'next/server';
 import { z } from 'zod';
 
@@ -133,8 +133,8 @@ export const POST = withAuthNoParams(async (request: AuthenticatedRequest) => {
 ```typescript
 // src/app/api/protected/billing/portal/route.ts
 import { handleApiError, withAuthNoParams, type AuthenticatedRequest } from '@/lib/mars';
-import { getStripe } from '@/features/billing/server';
 import { prisma } from '@/lib/prisma';
+import { getStripe } from '@/features/billing/server';
 import { NextResponse } from 'next/server';
 
 export const POST = withAuthNoParams(async (request: AuthenticatedRequest) => {

package/cursor/skills/mars-configure-storage/SKILL.md

@@ -181,8 +181,8 @@ export const POST = withAuthNoParams(async (request: AuthenticatedRequest) => {
 ```tsx
 'use client';
 
-import { useState, useRef } from 'react';
 import { Button, Spinner } from '@mars-stack/ui';
+import { useState, useRef } from 'react';
 
 interface FileUploadProps {
   onUpload: (result: { url: string; pathname: string }) => void;
@@ -265,7 +265,7 @@ export function FileUpload({ onUpload, accept = 'image/*', maxSize = 10 }: FileU
 
 - [ ] Storage SDK installed
 - [ ] Environment variables set
-- [ ] Storage service created (note: storage will be available via `@mars-stack/core` in a future release)
+- [ ] Storage service created (`src/core/storage/index.ts`)
 - [ ] Upload API route with size and type validation
 - [ ] Upload paths scoped by userId
 - [ ] Client upload component

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

@@ -627,16 +627,11 @@ If certain routes should only be accessible to team members, add team verificati
 | Teams | B | Team CRUD, invitations, role hierarchy, org switching |
 ```
 
-2. Update `ARCHITECTURE.md`:
-   - Add teams to the data model section
-   - Document the multi-tenancy pattern
-   - Add the role hierarchy diagram
-
-3. Update `template/AGENTS.md`:
+2. Update `AGENTS.md`:
    - Add teams feature to directory listing
    - Document team-scoped query pattern
 
-4. Mark execution plan as complete
+3. Mark execution plan as complete
 
 ## Data Scoping Decision
 
@@ -683,6 +678,5 @@ model Project {
 - [ ] Invitation emails (if email configured)
 - [ ] Unit tests for all API routes
 - [ ] E2E test for invitation flow
-- [ ] ARCHITECTURE.md updated with tenancy pattern
 - [ ] QUALITY_SCORE.md updated
 - [ ] Execution plan completed

package/cursor/skills/mars-test-api-route/SKILL.md

@@ -18,9 +18,9 @@ MARS API route tests:
 
 ```typescript
 // src/app/api/protected/projects/route.test.ts
+import { mockAuth, createTestRequest, createTestRequestWithBody } from '@mars-stack/core/test-utils';
 import { describe, it, expect, vi, beforeEach } from 'vitest';
 import { GET, POST } from './route';
-import { mockAuth, createTestRequest, createTestRequestWithBody } from '@mars-stack/core/test-utils';
 
 // Mock database
 const mockFindMany = vi.fn();

package/cursor/skills/mars-update-architecture-docs/SKILL.md

@@ -1,20 +1,18 @@
 # Skill: Update Architecture Docs
 
-Keep the Mars project documentation in sync with code changes. Covers when and how to update ARCHITECTURE.md, AGENTS.md, QUALITY_SCORE.md, and generated docs.
+Keep the project documentation in sync with code changes. Covers when and how to update AGENTS.md, QUALITY_SCORE.md, and related docs.
 
 ## When to Use
 
 Use this skill when:
-- You have just added a new feature, service, or package
+- You have just added a new feature, service, or module
 - You have changed the database schema
-- You have added or removed a skill or rule
 - You have completed an execution plan
 - The user asks to update docs, sync docs, or refresh documentation
 - Another skill's checklist includes "update docs"
 
 ## Prerequisites
 
-- Read `ARCHITECTURE.md` to understand the current documented state.
 - Read `AGENTS.md` for the project-level agent guide.
 - Read `docs/QUALITY_SCORE.md` for current quality grades.
 
@@ -23,49 +21,21 @@ Use this skill when:
 | Document | Location | Purpose | Update frequency |
 |----------|----------|---------|------------------|
 | `AGENTS.md` | Repo root | First file any agent reads. Overview + pointers | On structure changes |
-| `ARCHITECTURE.md` | Repo root | Detailed technical architecture | On arch changes |
 | `docs/QUALITY_SCORE.md` | Docs | Quality grades by domain | After every improvement |
-| `docs/generated/package-map.md` | Docs | Auto-generated package structure | Regenerate on package changes |
-| `docs/generated/skill-inventory.md` | Docs | Auto-generated skill list | Regenerate on skill changes |
-| `template/AGENTS.md` | Template | Consumer-facing project guide | On template structure changes |
-| `packages/core/cursor/manifest.json` | Core | Skill index with triggers | On skill add/remove |
+| `docs/design-docs/` | Docs | Architecture decisions and design documents | On architectural changes |
 
 ## When to Update Each Document
 
-### ARCHITECTURE.md
+### AGENTS.md
 
 Update when:
-- A new package is added to the monorepo
-- The build pipeline changes (new build step, tool change)
-- A new export path is added to a package
-- The security model changes (new auth pattern, new middleware)
-- The skill/rule system changes
-
-What to update:
-1. Package layering diagram (if dependency graph changed)
-2. Package export table (if new exports added)
-3. Build pipeline section (if build process changed)
-4. Security architecture section (if auth patterns changed)
-5. Skills and rules section (if skill system changed)
-
-### AGENTS.md (Root)
-
-Update when:
-- A new top-level directory is added
-- A new CLI command is added
-- The "How to Run" commands change
-- A new "How to" section is needed (e.g., "How to Add a Plugin")
-
-Keep it concise — AGENTS.md should fit in a single context window.
-
-### template/AGENTS.md
-
-Update when:
-- The template directory structure changes
-- New route groups are added
-- New feature modules are added to the template
+- The directory structure changes (new route groups, new features)
+- New feature modules are added
 - The config structure changes
 - New "How to Run" commands are added
+- Key constraints change
+
+Keep it concise — AGENTS.md should fit in a single context window.
 
 ### docs/QUALITY_SCORE.md
 
@@ -78,31 +48,11 @@ How to update:
 1. Find the relevant row in the appropriate table
 2. Update the grade (A/B/C/D/F)
 3. Update the notes to reflect current state
-4. Add date reference if significant change
 
 ```markdown
 | Dashboard | B | Basic layout with stat cards. Missing: chart widgets, date range filter |
 ```
 
-### Generated Docs
-
-Regenerate `docs/generated/package-map.md` when:
-- A package's exports change
-- A new package is added
-- A package is removed
-
-Regenerate `docs/generated/skill-inventory.md` when:
-- A skill is added, removed, or renamed
-- Skill triggers or dependencies change
-
-### manifest.json
-
-Update when:
-- A new skill is added (add entry with triggers, dependencies, capabilities)
-- A skill is removed (remove entry)
-- Skill triggers change (update triggers array)
-- Skill dependencies change (update dependencies array)
-
 ## Step-by-Step: After Adding a Feature
 
 1. **QUALITY_SCORE.md** — Update the grade for the relevant domain:
@@ -111,61 +61,24 @@ Update when:
 | Billing | B | Stripe checkout, portal, webhook. Missing: usage-based billing |
 ```
 
-2. **ARCHITECTURE.md** — If the feature introduces a new architectural pattern:
-
-```markdown
-### Billing Architecture
-
-The billing system uses Stripe as the payment provider...
-```
-
-3. **template/AGENTS.md** — If the feature adds new directories or conventions:
+2. **AGENTS.md** — If the feature adds new directories or conventions:
 
 ```markdown
 ├── features/
 │   └── billing/         # Subscription management
 ```
 
-4. **Execution plan** — Mark tasks complete, update verification:
+3. **Execution plan** — Mark tasks complete, update verification:
 
 ```markdown
 - [x] **3.1 Billing page** — Done. `src/app/(protected)/billing/page.tsx`
 ```
 
-## Step-by-Step: After Adding a Skill
-
-1. **manifest.json** — Add the skill entry:
-
-```json
-"new-skill-name": {
-  "file": "skills/mars-new-skill-name/SKILL.md",
-  "triggers": ["trigger phrase 1", "trigger phrase 2"],
-  "dependencies": ["dependency-skill"],
-  "capabilities": ["file-edit", "terminal"]
-}
-```
-
-2. **skill-inventory.md** — Regenerate or manually add:
-
-```markdown
-| new-skill-name | Add a new thing | file-edit, terminal |
-```
-
-3. **AGENTS.md** — If the skill represents a new "How to" workflow:
-
-```markdown
-## How to Add a New Thing
-
-1. Create the skill file
-2. Add to manifest
-3. ...
-```
-
 ## Step-by-Step: After a Schema Change
 
-1. **ARCHITECTURE.md** — Update if the change affects the data model section
-2. **template/AGENTS.md** — Update the schema file listing if new files added
-3. **QUALITY_SCORE.md** — Update database-related grades
+1. **AGENTS.md** — Update the schema file listing if new schema files added
+2. **QUALITY_SCORE.md** — Update database-related grades
+3. **Design docs** — Add a design doc if the schema change represents a significant architectural decision
 
 ## Validation
 
@@ -179,11 +92,8 @@ After updating docs, verify:
 ## Checklist
 
 - [ ] Identified which documents need updating
-- [ ] ARCHITECTURE.md updated (if architectural change)
 - [ ] AGENTS.md updated (if structure or workflow change)
-- [ ] template/AGENTS.md updated (if template structure change)
 - [ ] QUALITY_SCORE.md grades updated
-- [ ] manifest.json updated (if skill change)
-- [ ] Generated docs regenerated (if package or skill change)
+- [ ] Design docs updated (if architectural decision)
 - [ ] No broken internal links
 - [ ] Execution plan marked as complete (if applicable)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mars-stack/core",
-  "version": "2.0.1",
+  "version": "3.0.1",
   "license": "MIT",
   "repository": {
     "type": "git",

package/scripts/postinstall.mjs

@@ -45,6 +45,20 @@ function detectIdeEnvironment() {
 const ide = detectIdeEnvironment();
 
 // Cursor: copy rules + skills into .cursor/ (primary target)
+const cursorDir = path.join(projectRoot, '.cursor');
+const managedListPath = path.join(cursorDir, '.mars-managed');
+
+let previouslyManaged = [];
+if (fs.existsSync(managedListPath)) {
+  try {
+    previouslyManaged = JSON.parse(fs.readFileSync(managedListPath, 'utf-8'));
+  } catch {
+    previouslyManaged = [];
+  }
+}
+
+const currentlyManaged = [];
+
 const copies = [
   { src: 'rules', dest: '.cursor/rules' },
   { src: 'skills', dest: '.cursor/skills' },
@@ -59,21 +73,48 @@ for (const { src, dest } of copies) {
 
   const entries = fs.readdirSync(srcDir, { withFileTypes: true });
   for (const entry of entries) {
-    if (entry.isFile() && entry.name.startsWith('mars-')) {
-      fs.copyFileSync(
-        path.join(srcDir, entry.name),
-        path.join(destDir, entry.name),
-      );
-    } else if (entry.isDirectory() && entry.name.startsWith('mars-')) {
-      fs.cpSync(
-        path.join(srcDir, entry.name),
-        path.join(destDir, entry.name),
-        { recursive: true },
-      );
+    if (!entry.name.startsWith('mars-')) continue;
+
+    const destPath = path.join(destDir, entry.name);
+    const managedKey = `${dest}/${entry.name}`;
+    currentlyManaged.push(managedKey);
+
+    if (entry.isFile()) {
+      fs.copyFileSync(path.join(srcDir, entry.name), destPath);
+    } else if (entry.isDirectory()) {
+      fs.cpSync(path.join(srcDir, entry.name), destPath, { recursive: true });
+    }
+
+    // Remove unprefixed duplicate from old naming scheme (e.g. security.mdc → removed)
+    const unprefixedName = entry.name.replace(/^mars-/, '');
+    const unprefixedPath = path.join(destDir, unprefixedName);
+    if (fs.existsSync(unprefixedPath)) {
+      fs.rmSync(unprefixedPath, { recursive: true, force: true });
     }
   }
 }
 
+// Remove stale mars-* entries from previous versions that are no longer shipped
+const currentSet = new Set(currentlyManaged);
+for (const oldEntry of previouslyManaged) {
+  if (!currentSet.has(oldEntry)) {
+    const stalePath = path.join(projectRoot, oldEntry);
+    if (fs.existsSync(stalePath)) {
+      fs.rmSync(stalePath, { recursive: true, force: true });
+    }
+  }
+}
+
+// Write the managed list for future cleanup
+fs.mkdirSync(cursorDir, { recursive: true });
+fs.writeFileSync(managedListPath, JSON.stringify(currentlyManaged, null, 2));
+
+// Copy manifest.json so it's available in scaffolded projects
+const manifestSrc = path.join(packageDir, '..', 'cursor', 'manifest.json');
+if (fs.existsSync(manifestSrc)) {
+  fs.copyFileSync(manifestSrc, path.join(cursorDir, 'manifest.json'));
+}
+
 // Generate IDE-specific adapter files for non-Cursor environments
 if (ide !== 'cursor') {
   const manifestPath = path.join(packageDir, '..', 'cursor', 'manifest.json');