@mars-stack/cli 0.2.0 → 1.0.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mars-stack/cli",
-  "version": "0.2.0",
+  "version": "1.0.2",
   "description": "MARS CLI: scaffold, configure, and maintain SaaS apps",
   "license": "MIT",
   "repository": {
@@ -22,7 +22,7 @@
     "mars": "./dist/index.js"
   },
   "publishConfig": {
-    "access": "restricted"
+    "access": "public"
   },
   "files": [
     "dist",
@@ -34,9 +34,10 @@
     "start": "node dist/index.js",
     "test": "vitest run",
     "test:scaffold": "tsx ../../scripts/test-scaffold-matrix.ts",
-    "prepublishOnly": "yarn build"
+    "prepublishOnly": "yarn build && node scripts/copy-template.mjs"
   },
   "dependencies": {
+    "@mars-stack/ui": "*",
     "commander": "^14.0.3",
     "fs-extra": "^11.0.0",
     "ora": "^8.0.0",

package/template/.cursor/rules/composition-patterns.mdc

@@ -0,0 +1,186 @@
+---
+description: React composition patterns — compound components, state lifting, explicit variants
+globs: **/*.tsx
+alwaysApply: false
+---
+
+## Composition Over Configuration
+
+When building components, prefer composition over boolean props. These patterns apply to all feature components and any new primitives/patterns added to `@mars-stack/ui`.
+
+Source: [Vercel Composition Patterns](https://github.com/vercel-labs/agent-skills/tree/main/skills/composition-patterns)
+
+## 1. No Boolean Prop Proliferation (CRITICAL)
+
+Don't add boolean props like `isThread`, `isEditing`, `isCompact` to customise component behaviour. Each boolean doubles possible states and creates unmaintainable conditional logic.
+
+**Wrong:**
+
+```tsx
+function Composer({ isThread, isEditing, isForwarding, showAttachments }: Props) {
+  return (
+    <form>
+      <Input />
+      {isThread ? <ThreadField /> : isEditing ? <EditActions /> : <DefaultActions />}
+      {showAttachments && <Attachments />}
+    </form>
+  );
+}
+```
+
+**Right — create explicit variants that compose shared parts:**
+
+```tsx
+function ThreadComposer({ channelId }: { channelId: string }) {
+  return (
+    <Composer.Frame>
+      <Composer.Input />
+      <AlsoSendToChannelField channelId={channelId} />
+      <Composer.Footer>
+        <Composer.Submit />
+      </Composer.Footer>
+    </Composer.Frame>
+  );
+}
+
+function EditComposer() {
+  return (
+    <Composer.Frame>
+      <Composer.Input />
+      <Composer.Footer>
+        <Composer.CancelEdit />
+        <Composer.SaveEdit />
+      </Composer.Footer>
+    </Composer.Frame>
+  );
+}
+```
+
+## 2. Compound Components with Shared Context (HIGH)
+
+Structure complex components as compound components. Subcomponents access shared state via context, not props. Consumers compose the pieces they need.
+
+```tsx
+const ComposerContext = createContext<ComposerContextValue | null>(null);
+
+function ComposerFrame({ children }: { children: React.ReactNode }) {
+  return <form>{children}</form>;
+}
+
+function ComposerInput() {
+  const { state, actions: { update } } = use(ComposerContext);
+  return <TextInput value={state.input} onChangeText={(text) => update((s) => ({ ...s, input: text }))} />;
+}
+
+const Composer = {
+  Frame: ComposerFrame,
+  Input: ComposerInput,
+  Submit: ComposerSubmit,
+  // ...
+};
+```
+
+Export compound components as a namespace object, not individual exports.
+
+## 3. Generic Context Interfaces (HIGH)
+
+Define context with three parts: `state`, `actions`, `meta`. This interface is a contract that any provider can implement — enabling the same UI to work with different state implementations.
+
+```tsx
+interface ComposerContextValue {
+  state: { input: string; attachments: Attachment[]; isSubmitting: boolean };
+  actions: { update: (updater: (s: State) => State) => void; submit: () => void };
+  meta: { inputRef: React.RefObject<HTMLTextAreaElement> };
+}
+```
+
+UI components consume the interface. Providers implement it. Swap the provider, keep the UI.
+
+## 4. Lift State into Providers (HIGH)
+
+Move state into dedicated provider components. This lets sibling components outside the main UI access state without prop drilling.
+
+**Wrong — state trapped in component:**
+
+```tsx
+function ForwardDialog() {
+  return (
+    <Dialog>
+      <ForwardComposer />
+      <MessagePreview /> {/* Can't access composer state */}
+      <ForwardButton /> {/* Can't call submit */}
+    </Dialog>
+  );
+}
+```
+
+**Right — state in provider, UI siblings can access it:**
+
+```tsx
+function ForwardDialog() {
+  return (
+    <ForwardProvider>
+      <Dialog>
+        <ForwardComposer />
+        <MessagePreview /> {/* Reads state from context */}
+        <ForwardButton /> {/* Calls submit from context */}
+      </Dialog>
+    </ForwardProvider>
+  );
+}
+```
+
+Components that need shared state don't have to be visually nested — they just need to be within the same provider.
+
+## 5. Decouple State from UI (MEDIUM)
+
+The provider is the only place that knows how state is managed. UI components consume the context interface — they don't know if state comes from `useState`, Zustand, or a server sync.
+
+```tsx
+// Local state provider
+function ForwardProvider({ children }: { children: React.ReactNode }) {
+  const [state, setState] = useState(initialState);
+  return <Composer.Provider state={state} actions={{ update: setState, submit }}>{children}</Composer.Provider>;
+}
+
+// Global synced state provider — same UI works with both
+function ChannelProvider({ channelId, children }: Props) {
+  const { state, update, submit } = useGlobalChannel(channelId);
+  return <Composer.Provider state={state} actions={{ update, submit }}>{children}</Composer.Provider>;
+}
+```
+
+## 6. Children Over Render Props (MEDIUM)
+
+Use `children` for composition. Use render props only when the parent needs to pass data back to the child (e.g., list items with index).
+
+**Wrong:**
+
+```tsx
+<Composer renderHeader={() => <Header />} renderFooter={() => <Footer />} />
+```
+
+**Right:**
+
+```tsx
+<Composer.Frame>
+  <Header />
+  <Composer.Input />
+  <Footer />
+</Composer.Frame>
+```
+
+## 7. React 19 APIs
+
+This project uses React 19. Follow these conventions:
+
+- **No `forwardRef`** — `ref` is a regular prop in React 19.
+- **Use `use()` instead of `useContext()`** — `use()` can be called conditionally.
+
+```tsx
+// Right (React 19)
+function ComposerInput({ ref, ...props }: Props & { ref?: React.Ref<HTMLTextAreaElement> }) {
+  const { state } = use(ComposerContext);
+  return <textarea ref={ref} value={state.input} {...props} />;
+}
+```

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

@@ -0,0 +1,29 @@
+---
+description: Database and data access patterns
+globs: **/server/**
+alwaysApply: false
+---
+
+## Prisma (v7)
+
+- 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).
+
+## Error Handling
+
+- API route catch blocks MUST use `handleApiError(error, { endpoint })` from `@/lib/mars`.
+- `handleApiError` automatically detects Prisma errors and logs actionable diagnostics (connection refused, auth failed, missing tables, SSL issues) to the terminal.
+- Database errors return HTTP 503 to clients. Zod validation errors return 400. Everything else returns 500.
+- Never expose raw database error messages to the client.
+
+## File Handling
+
+- File proxy routes MUST stream `response.body` instead of buffering with `arrayBuffer()`.
+- Enforce max file size checks from the DB record before fetching.
+- Sanitize filenames in `Content-Disposition` headers.

package/template/.cursor/rules/project-structure.mdc

@@ -0,0 +1,34 @@
+---
+description: Project structure and import conventions
+globs:
+alwaysApply: true
+---
+
+## Directory Layout
+
+- `src/lib/` -- Wiring layer: `mars.ts` (re-exports logger, email, api-error, auth middleware, session, CSRF from `@mars-stack/core`) and `prisma.ts` (database client).
+- UI primitives (Button, Input, Select, etc.) and patterns (Card, Modal, FormField) come from the `@mars-stack/ui` package.
+- Shared hooks come from `@mars-stack/ui/hooks`.
+- `src/features/<name>/` -- Feature modules with their own `components/`, `server/`, `hooks/`, `validation/`.
+- `src/config/` -- `app.config.ts` (single source of truth) and `routes.ts`.
+- `src/styles/` -- Design tokens: `primitives.css` → `tokens.css` → `theme.css`.
+
+## Import Rules
+
+- Use `@/lib/prisma` for the database client, `@/lib/mars` for core infrastructure (logger, email, api-error, auth wrappers, session, CSRF).
+- Use `@mars-stack/ui` for UI primitives and patterns, `@mars-stack/ui/hooks` for shared hooks.
+- Use `@mars-stack/core/rate-limit` for rate limiting, `@mars-stack/core/test-utils` for test utilities, `@mars-stack/core/auth/hooks` for auth hooks, `@mars-stack/core/auth/validation` for auth validation schemas.
+- `features/` may import from `@/lib/`, `@mars-stack/*`, and `config/`. Features MUST NOT import from other features.
+- `app/` may import from anywhere.
+
+## Naming
+
+- Use named exports. Default exports only for Next.js pages/layouts.
+- Prefer explicit TypeScript types. No `any` -- use `unknown` and narrow.
+- Barrel exports (`index.ts`) at the boundary of each module for clean imports.
+
+## Config
+
+- `app.config.ts` is the single source of truth for app identity, feature flags, theme, and service providers.
+- Check `appConfig.features.*` before wiring up optional functionality.
+- Environment variables are validated lazily via `src/core/env/`. Add new vars to `buildEnvSchema()`.

package/template/.cursor/rules/security.mdc

@@ -0,0 +1,25 @@
+---
+description: Security guardrails for all code changes
+globs:
+alwaysApply: true
+---
+
+## Authentication & Authorization
+
+- Every API route under `src/app/api/protected/` MUST use `withAuth`, `withAuthNoParams`, `withRole`, or `withOwnership` from `@/lib/mars`.
+- Admin-only routes MUST use `withRole(['admin'], ...)` which verifies the role against the database on every request. Never trust the JWT role claim alone.
+- Ownership-gated routes MUST use `withOwnership`. Never accept a `userId` parameter from the client for authorization.
+- Public auth endpoints (`login`, `signup`, `forgot`, `reset`, `verify`) MUST call `checkRateLimit` with the appropriate `RATE_LIMITS` config from `@mars-stack/core/rate-limit`.
+
+## Secrets
+
+- Use constant-time comparison (`constantTimeEqual`) for all secret/token/signature comparisons. Never use `===` for secrets.
+- CSRF keys are derived from `JWT_SECRET` via HMAC with a domain separator; never reuse `JWT_SECRET` directly.
+- Never log secrets, tokens, or full authorization headers.
+- Server-only modules MUST import `"server-only"` at the top to prevent client-side bundling.
+
+## Serverless Constraints
+
+- No `setInterval` / `setTimeout` for background cleanup; use lazy-on-read patterns.
+- No in-memory queues or global mutable state that assumes process persistence.
+- Background processing should fire a separate HTTP request, not rely on fire-and-forget promises.

package/template/.cursor/rules/testing.mdc

@@ -0,0 +1,24 @@
+---
+description: Testing conventions
+globs: **/*.test.ts,**/*.test.tsx
+alwaysApply: false
+---
+
+## Framework
+
+- Unit tests: Vitest (`yarn test`). Config at `vitest.config.ts`.
+- E2E tests: Playwright (`yarn test:e2e`). Config at `playwright.config.ts`.
+- Test files live next to the code they test: `route.test.ts` beside `route.ts`.
+
+## Mocking
+
+- 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
+
+- Test API routes by calling the exported handler directly, not via HTTP.
+- Assert both the response body and status code.
+- Test error paths: invalid input (Zod), unauthorized, not found, database errors.
+- Unit tests MUST NOT depend on external services (database, Redis, email). Mock everything.

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

@@ -0,0 +1,29 @@
+---
+description: UI component and styling conventions
+globs: **/*.tsx
+alwaysApply: false
+---
+
+## Design Token System
+
+MARS uses a three-layer CSS token system. Never use raw Tailwind colour classes (e.g., `text-gray-900`). Always use semantic tokens:
+
+- **Surfaces**: `bg-surface-background`, `bg-surface-card`, `bg-surface-elevated`, `bg-surface-input`
+- **Text**: `text-text-primary`, `text-text-secondary`, `text-text-muted`, `text-text-link`, `text-text-error`
+- **Borders**: `border-border-default`, `border-border-input`, `border-border-focus`, `border-border-error`
+- **Brand**: `bg-brand-primary`, `bg-brand-primary-hover`, `text-text-on-brand`
+- **Feedback**: `bg-success-muted`, `text-text-success`, `bg-error-muted`, `text-text-error`
+- **Interactive**: `bg-ghost-hover`, `bg-ghost-active`, `bg-danger-bg`, `focus:ring-ring-focus`
+
+## Component Architecture
+
+- **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 barrel exports: `@mars-stack/ui` or `@mars-stack/ui`.
+- Use `clsx` for conditional class composition.
+- 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/template/.cursor/skills/add-api-route/SKILL.md

@@ -0,0 +1,122 @@
+# Skill: Add an API Route
+
+Create a new Next.js API route following MARS conventions for authentication, validation, error handling, and testing.
+
+## When to Use
+
+Use this skill when the user asks to create a new endpoint, API route, or backend handler.
+
+## Decision: Public or Protected?
+
+| Type | Location | Auth Wrapper | Use Case |
+|------|----------|-------------|----------|
+| Public | `src/app/api/<name>/route.ts` | None (but add rate limiting) | Auth endpoints, webhooks, health checks |
+| Protected | `src/app/api/protected/<name>/route.ts` | `withAuth` / `withRole` / `withOwnership` | User data, settings, admin |
+
+## Protected Route Template
+
+```typescript
+import { handleApiError, withAuthNoParams, type AuthenticatedRequest } from '@/lib/mars';
+import { NextResponse } from 'next/server';
+
+export const GET = withAuthNoParams(async (request: AuthenticatedRequest) => {
+  try {
+    const userId = request.session.userId;
+    // ... business logic using userId for scoping
+    return NextResponse.json({ data: result });
+  } catch (error) {
+    return handleApiError(error, { endpoint: '/api/protected/<name>' });
+  }
+});
+```
+
+### Auth Wrapper Reference
+
+| Wrapper | Signature | When to Use |
+|---------|-----------|-------------|
+| `withAuth` | `(request, { params })` | Routes with dynamic URL params |
+| `withAuthNoParams` | `(request)` | Routes without URL params |
+| `withAuthSimple` | `()` | Routes that only need session verification |
+| `withRole` | `withRole(['admin'], handler)` | Admin-only routes (verifies role from DB) |
+| `withOwnership` | `withOwnership(getResourceUserId, handler)` | User must own the resource |
+
+## Public Route Template (with Rate Limiting)
+
+```typescript
+import { handleApiError } from '@/lib/mars';
+import {
+  checkRateLimit, getClientIP, RATE_LIMITS, rateLimitResponse,
+} from '@mars-stack/core/rate-limit';
+import { NextResponse } from 'next/server';
+
+export async function POST(request: Request) {
+  const ip = getClientIP(request);
+  const rateLimit = await checkRateLimit(ip, RATE_LIMITS.default);
+  if (!rateLimit.success) return rateLimitResponse(rateLimit.resetAt);
+
+  try {
+    // ... business logic
+    return NextResponse.json({ data: result });
+  } catch (error) {
+    return handleApiError(error, { endpoint: '/api/<name>' });
+  }
+}
+```
+
+## Input Validation
+
+Always validate request bodies with Zod before use:
+
+```typescript
+import { z } from 'zod';
+
+const schema = z.object({
+  name: z.string().min(1).max(100),
+  email: z.string().email(),
+});
+
+// Inside the handler:
+const body = schema.parse(await request.json());
+```
+
+`handleApiError` will automatically catch `ZodError` and return a 400 with the first error message.
+
+## Dynamic Routes
+
+For routes with URL parameters like `/api/protected/widgets/[id]/route.ts`:
+
+```typescript
+export const GET = withAuth(async (request, context) => {
+  try {
+    const { id } = await context.params;
+    const userId = request.session.userId;
+    // ... fetch by id, scoped to userId
+  } catch (error) {
+    return handleApiError(error, { endpoint: '/api/protected/widgets/[id]' });
+  }
+});
+```
+
+## Error Handling Reference
+
+`handleApiError` from `@/lib/mars` handles:
+
+| Error Type | HTTP Status | Client Response |
+|-----------|-------------|----------------|
+| `ZodError` | 400 | First validation error message |
+| Prisma / Database | 503 | "Service temporarily unavailable" + detailed terminal diagnostics |
+| All others | 500 | Custom `fallbackMessage` or "An unexpected error occurred" |
+
+## Testing
+
+Create `route.test.ts` beside the route file. See the `add-feature` skill for the full testing pattern.
+
+## Checklist
+
+- [ ] Correct directory (public vs protected)
+- [ ] Appropriate auth wrapper applied
+- [ ] Rate limiting on public endpoints
+- [ ] Zod validation for all inputs
+- [ ] Queries scoped by `request.session.userId`
+- [ ] `handleApiError` in every catch block
+- [ ] Test file created