@mars-stack/cli 3.0.2 → 4.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mars-stack/cli",
-  "version": "3.0.2",
+  "version": "4.0.0",
   "description": "MARS CLI: scaffold, configure, and maintain SaaS apps",
   "license": "MIT",
   "repository": {

package/template/.cursor/skills/mars-upgrade-scaffold/SKILL.md

@@ -0,0 +1,70 @@
+# Skill: Upgrade Mars scaffold (template sync)
+
+Apply upstream template fixes to an existing Mars project without regenerating the app. Use when the user wants to pull in fixes for ensure-db, auth verify page, signup route, or other scaffold plumbing.
+
+## When to Use
+
+Use this skill when:
+- The user asks to **upgrade mars template**, **sync scaffold with upstream**, **apply template fixes**, or **pull in ensure-db / verify page / signup fixes**
+- The project was scaffolded earlier and is missing fixes that landed in the Mars template (e.g. Strict Mode verify page, AUTO_VERIFY_EMAIL for localhost, ensure-db portable DB check)
+- The user says they cannot upgrade via CLI because `mars upgrade` only updates npm packages
+
+## Prerequisites
+
+- Confirm the project is a Mars scaffold: `package.json` has `"mars": true` and dependencies on `@mars-stack/core` and/or `@mars-stack/ui`.
+- **Source of truth for the plan:** [docs/exec-plans/active/scaffold-template-sync-upgrade.md](https://github.com/greaveselliott/mars/blob/main/docs/exec-plans/active/scaffold-template-sync-upgrade.md) (or the same path in the Mars monorepo if you have it).
+
+## Allowlisted “plumbing” paths (safe to overwrite with template version)
+
+Only these paths are candidates for **verbatim replace** from the upstream template. Do **not** overwrite user-owned files (e.g. `src/config/app.config.ts`, feature code the user added, or files outside this list) without explicit user approval.
+
+| Path (relative to project root) | Purpose |
+|---------------------------------|---------|
+| `scripts/ensure-db.mjs` | Dev DB provisioning; portable DB ping, prisma generate + push |
+| `src/app/(auth)/verify/page.tsx` | Verify email page; dev link must survive Strict Mode |
+| `src/app/api/auth/signup/route.ts` | Signup; AUTO_VERIFY_EMAIL + authLogger |
+
+If the exec plan or a future manifest adds more paths, follow that list. When in doubt, **propose a diff** and let the user approve before writing.
+
+## Step-by-Step
+
+1. **Confirm Mars project** — Check `package.json` for `"mars": true` and `@mars-stack/*` deps. If not present, stop and tell the user this skill applies only to Mars scaffolds.
+
+2. **Obtain upstream template** — User must provide the source:
+   - **Option A:** Path to the Mars monorepo `template/` (e.g. `../mars/template` or a branch they have checked out).
+   - **Option B:** They run `npx @mars-stack/cli create temp-sync --skip-install` in a temp dir and you copy from `temp-sync/` (then they can delete it).
+   - Do not assume a path; ask or use the path they give.
+
+3. **For each allowlisted path:**
+   - If the file does not exist in the project, copy from template.
+   - If the file exists, **diff** template version vs project version. If the project file has only template-like content (or user has not clearly customized it), propose replacing with the template version. If the project file has substantial customizations, **show the diff** and ask the user whether to overwrite or merge manually.
+
+4. **Never overwrite without user approval** when:
+   - The file is not in the allowlist above.
+   - The file contains user-specific config (e.g. `app.config.ts` feature flags, theme, URLs).
+   - You are unsure; in that case, output the diff and ask.
+
+5. **After applying changes:**
+   - Run `yarn db:push` (or `npm run db:push`) if `scripts/ensure-db.mjs` or any Prisma-related path was updated.
+   - Suggest running `yarn dev` to confirm the app starts and auth flow works.
+
+## Verification
+
+- [ ] Project is a Mars scaffold
+- [ ] Only allowlisted plumbing paths were modified (or user explicitly approved others)
+- [ ] Diff was shown for any overwrite of an existing file
+- [ ] `yarn build` or at least `yarn dev` runs after changes (user can confirm)
+- [ ] If ensure-db was updated, user knows to use `yarn dev` (not raw `next dev`) so the script runs
+
+## Checklist
+
+- [ ] Confirmed `package.json` has `mars: true` and `@mars-stack/*` deps
+- [ ] Obtained template source path from user or instructions
+- [ ] For each allowlisted file: compared, proposed replace or left as-is with reason
+- [ ] No overwrite of app.config, user features, or unlisted paths without approval
+- [ ] Post-change: suggested `yarn db:push` if needed and `yarn dev` smoke test
+
+## Related
+
+- **Exec plan:** [scaffold-template-sync-upgrade](https://github.com/greaveselliott/mars/blob/main/docs/exec-plans/active/scaffold-template-sync-upgrade.md) — full problem statement, CLI track (future), and task list. In the Mars monorepo the path is `docs/exec-plans/active/scaffold-template-sync-upgrade.md`.
+- **Local-first dev:** Template `AGENTS.md` and [local-first-development](https://github.com/greaveselliott/mars/blob/main/docs/design-docs/local-first-development.md): embedded DB, ensure-db, AUTO_VERIFY_EMAIL.

package/template/AGENTS.md

@@ -76,7 +76,7 @@ src/
 ## How to Run
 
 ```bash
-yarn dev              # Start Next.js dev server
+yarn dev              # ensure-db (embedded Postgres) + Next.js — use this, not raw next dev
 yarn build            # Production build
 yarn test             # Run Vitest unit tests
 yarn test:e2e         # Run Playwright e2e tests
@@ -87,6 +87,10 @@ yarn db:seed          # Seed database
 yarn db:studio        # Open Prisma Studio
 ```
 
+**Database (local):** `yarn dev` runs `scripts/ensure-db.mjs` first: embedded Postgres via `prisma dev` (PGlite), `DATABASE_URL` written to `.env.development.local`. No Docker. Same zero-setup idea as an in-memory DB; data lives under `.prisma/dev` until you reset it. Use a cloud `DATABASE_URL` in `.env` only when you intentionally dev against Neon/Supabase.
+
+**Email verification (local):** With console email, after register you land on `/verify` and use **“Click here to verify your email”** (no inbox needed). Set `AUTO_VERIFY_EMAIL=true` to skip that for **new** signups instead. `AUTO_VERIFY_EMAIL` applies when `yarn dev` runs or `APP_URL` points at `localhost` / `127.0.0.1`; ignored on Vercel production. Older accounts stay unverified until you use the link or Prisma Studio.
+
 ## Working Discipline
 
 1. **Commit after every step.** When executing a plan, commit after each completed task — not at the end. Version control is the progress log. Each commit message should reference the plan and step (e.g., `feat(billing): add Subscription model (billing-plan step 1.1)`).

package/template/scripts/ensure-db.mjs

@@ -3,11 +3,13 @@
 /**
  * Ensures a local database is available before starting development.
  *
+ * Default dev datastore: embedded Postgres via `prisma dev` (PGlite-backed, no Docker).
+ * Same “zero setup” goal as an in-memory DB — data persists under .prisma/dev until reset.
+ *
  * Strategy (in order):
- * 1. If DATABASE_URL connects to a reachable database, use it and sync schema.
- * 2. Otherwise, start an embedded PostgreSQL via `prisma dev` (PGlite-powered).
- *    No Docker. No installation. No external processes.
- * 3. Sync the Prisma schema automatically.
+ * 1. If DATABASE_URL connects (verified with a real query), use it and sync schema.
+ * 2. Otherwise start embedded Postgres, write DATABASE_URL to .env.development.local
+ *    (overrides commented/placeholder .env), then sync schema.
  */
 
 import { execSync } from 'node:child_process';
@@ -58,11 +60,14 @@ function loadEnvFile() {
 }
 
 function canConnectToDb() {
+  if (!process.env.DATABASE_URL?.trim()) return false;
   try {
-    execSync('npx prisma db execute --stdin <<< "SELECT 1"', {
+    execSync('npx prisma db execute --stdin', {
       cwd: ROOT,
-      stdio: 'ignore',
-      timeout: 8000,
+      input: 'SELECT 1;\n',
+      stdio: ['pipe', 'ignore', 'ignore'],
+      timeout: 15000,
+      env: { ...process.env },
     });
     return true;
   } catch {
@@ -72,11 +77,12 @@ function canConnectToDb() {
 
 function pushSchema() {
   try {
-    execSync('npx prisma db push --skip-generate --accept-data-loss', {
+    execSync('npx prisma generate && npx prisma db push --accept-data-loss', {
       cwd: ROOT,
       stdio: 'inherit',
-      timeout: 30000,
+      timeout: 120000,
       env: { ...process.env },
+      shell: true,
     });
     return true;
   } catch {

package/template/src/app/(auth)/verify/page.tsx

@@ -11,17 +11,16 @@ function VerifyContent() {
 
   useEffect(() => {
     const stored = sessionStorage.getItem('verify-email');
-    if (stored) {
-      setEmail(stored);
-      sessionStorage.removeItem('verify-email');
-    }
+    if (stored) setEmail(stored);
     const storedDevLink = sessionStorage.getItem('verify-dev-link');
-    if (storedDevLink) {
-      setDevLink(storedDevLink);
-      sessionStorage.removeItem('verify-dev-link');
-    }
+    if (storedDevLink) setDevLink(storedDevLink);
   }, []);
 
+  const clearVerifyStorage = () => {
+    sessionStorage.removeItem('verify-email');
+    sessionStorage.removeItem('verify-dev-link');
+  };
+
   return (
     <div className="text-center">
       <div className="mx-auto mb-6 flex h-16 w-16 items-center justify-center rounded-full bg-success-muted">
@@ -50,6 +49,7 @@ function VerifyContent() {
           </Text.Paragraph>
           <a
             href={devLink}
+            onClick={clearVerifyStorage}
             className="mt-1 inline-block text-sm font-medium text-text-link hover:text-text-link-hover hover:underline"
           >
             Click here to verify your email →
@@ -58,6 +58,7 @@ function VerifyContent() {
       )}
       <Link
         href={routes.signIn}
+        onClick={clearVerifyStorage}
         className="mt-8 inline-block text-sm text-text-link hover:text-text-link-hover hover:underline"
       >
         Back to sign in

package/template/src/app/(protected)/dashboard/page.tsx

@@ -1,22 +1,239 @@
 import { verifySession } from '@/lib/mars';
-import { Card } from '@mars-stack/ui';
+import { appConfig } from '@/config/app.config';
+import { routes } from '@/config/routes';
+import { Card, Badge, LinkButton } from '@mars-stack/ui';
+
+type FeatureKey = keyof typeof appConfig.features;
+
+interface FeatureMeta {
+  label: string;
+  description: string;
+  route?: string;
+  category: 'core' | 'engagement' | 'monetization' | 'developer';
+}
+
+const FEATURE_REGISTRY: Partial<Record<FeatureKey, FeatureMeta>> = {
+  auth: {
+    label: 'Authentication',
+    description: 'Email/password auth, sessions, and password reset.',
+    route: routes.settings,
+    category: 'core',
+  },
+  admin: {
+    label: 'Admin Panel',
+    description: 'Role-based admin dashboard for user management.',
+    route: routes.admin,
+    category: 'core',
+  },
+  darkMode: {
+    label: 'Dark Mode',
+    description: 'Automatic theme switching with system preference detection.',
+    category: 'core',
+  },
+  notifications: {
+    label: 'Notifications',
+    description: 'In-app notifications with real-time delivery.',
+    category: 'engagement',
+  },
+  onboarding: {
+    label: 'Onboarding',
+    description: 'Guided setup flow for new users.',
+    route: routes.onboarding,
+    category: 'engagement',
+  },
+  billing: {
+    label: 'Billing',
+    description: 'Stripe subscriptions, pricing page, and customer portal.',
+    route: routes.billing,
+    category: 'monetization',
+  },
+  blog: {
+    label: 'Blog',
+    description: 'Content management with markdown posts.',
+    route: routes.blog,
+    category: 'engagement',
+  },
+  seo: {
+    label: 'SEO',
+    description: 'Meta tags, Open Graph, structured data, and sitemaps.',
+    category: 'developer',
+  },
+  analytics: {
+    label: 'Analytics',
+    description: 'Page views, events, and user behavior tracking.',
+    category: 'developer',
+  },
+  ai: {
+    label: 'AI Assistant',
+    description: 'Chat interface with streaming AI completions.',
+    route: '/ai',
+    category: 'engagement',
+  },
+  fileUpload: {
+    label: 'File Upload',
+    description: 'Drag-and-drop uploads with progress and file management.',
+    route: routes.files,
+    category: 'engagement',
+  },
+  search: {
+    label: 'Search',
+    description: 'Full-text search across your application data.',
+    category: 'engagement',
+  },
+  commandPalette: {
+    label: 'Command Palette',
+    description: 'Keyboard-first navigation with Cmd+K shortcut.',
+    category: 'developer',
+  },
+  cookieConsent: {
+    label: 'Cookie Consent',
+    description: 'GDPR-compliant cookie consent banner.',
+    category: 'core',
+  },
+  realtime: {
+    label: 'Realtime',
+    description: 'Live updates via server-sent events or WebSockets.',
+    category: 'developer',
+  },
+};
+
+const CATEGORY_LABELS: Record<string, string> = {
+  core: 'Core',
+  engagement: 'Engagement',
+  monetization: 'Monetization',
+  developer: 'Developer Tools',
+};
+
+function FeatureIcon({ category }: { category: string }) {
+  const iconClass = 'h-5 w-5 text-text-muted';
+
+  switch (category) {
+    case 'core':
+      return (
+        <svg className={iconClass} fill="none" viewBox="0 0 24 24" strokeWidth={1.5} stroke="currentColor">
+          <path strokeLinecap="round" strokeLinejoin="round" d="M9 12.75L11.25 15 15 9.75m-3-7.036A11.959 11.959 0 013.598 6 11.99 11.99 0 003 9.749c0 5.592 3.824 10.29 9 11.623 5.176-1.332 9-6.03 9-11.622 0-1.31-.21-2.571-.598-3.751h-.152c-3.196 0-6.1-1.248-8.25-3.285z" />
+        </svg>
+      );
+    case 'engagement':
+      return (
+        <svg className={iconClass} fill="none" viewBox="0 0 24 24" strokeWidth={1.5} stroke="currentColor">
+          <path strokeLinecap="round" strokeLinejoin="round" d="M18 18.72a9.094 9.094 0 003.741-.479 3 3 0 00-4.682-2.72m.94 3.198l.001.031c0 .225-.012.447-.037.666A11.944 11.944 0 0112 21c-2.17 0-4.207-.576-5.963-1.584A6.062 6.062 0 016 18.719m12 0a5.971 5.971 0 00-.941-3.197m0 0A5.995 5.995 0 0012 12.75a5.995 5.995 0 00-5.058 2.772m0 0a3 3 0 00-4.681 2.72 8.986 8.986 0 003.74.477m.94-3.197a5.971 5.971 0 00-.94 3.197M15 6.75a3 3 0 11-6 0 3 3 0 016 0zm6 3a2.25 2.25 0 11-4.5 0 2.25 2.25 0 014.5 0zm-13.5 0a2.25 2.25 0 11-4.5 0 2.25 2.25 0 014.5 0z" />
+        </svg>
+      );
+    case 'monetization':
+      return (
+        <svg className={iconClass} fill="none" viewBox="0 0 24 24" strokeWidth={1.5} stroke="currentColor">
+          <path strokeLinecap="round" strokeLinejoin="round" d="M2.25 8.25h19.5M2.25 9h19.5m-16.5 5.25h6m-6 2.25h3m-3.75 3h15a2.25 2.25 0 002.25-2.25V6.75A2.25 2.25 0 0019.5 4.5h-15a2.25 2.25 0 00-2.25 2.25v10.5A2.25 2.25 0 004.5 19.5z" />
+        </svg>
+      );
+    case 'developer':
+    default:
+      return (
+        <svg className={iconClass} fill="none" viewBox="0 0 24 24" strokeWidth={1.5} stroke="currentColor">
+          <path strokeLinecap="round" strokeLinejoin="round" d="M17.25 6.75L22.5 12l-5.25 5.25m-10.5 0L1.5 12l5.25-5.25m7.5-3l-4.5 16.5" />
+        </svg>
+      );
+  }
+}
+
+function FeatureCard({ featureKey: _featureKey, meta }: { featureKey: string; meta: FeatureMeta }) {
+  const hasRoute = !!meta.route;
+
+  return (
+    <Card className="flex flex-col justify-between">
+      <div>
+        <div className="flex items-start justify-between gap-2">
+          <div className="flex items-center gap-2.5">
+            <FeatureIcon category={meta.category} />
+            <h3 className="text-sm font-semibold text-text-primary">{meta.label}</h3>
+          </div>
+          <Badge variant={hasRoute ? 'success' : 'neutral'}>
+            {hasRoute ? 'Active' : 'Enabled'}
+          </Badge>
+        </div>
+        <p className="mt-2 text-sm text-text-secondary leading-relaxed">{meta.description}</p>
+      </div>
+
+      {hasRoute && (
+        <div className="mt-4">
+          <LinkButton href={meta.route!} variant="subtle" size="sm">
+            Open {meta.label}
+          </LinkButton>
+        </div>
+      )}
+    </Card>
+  );
+}
+
+function QuickLinks({ isAdmin }: { isAdmin: boolean }) {
+  return (
+    <Card>
+      <h3 className="text-sm font-semibold text-text-primary">Quick Links</h3>
+      <div className="mt-3 flex flex-wrap gap-2">
+        <LinkButton href={routes.settings} variant="subtle" size="sm">
+          Settings
+        </LinkButton>
+        {isAdmin && (
+          <LinkButton href={routes.admin} variant="subtle" size="sm">
+            Admin Panel
+          </LinkButton>
+        )}
+        <LinkButton href={routes.home} variant="subtle" size="sm">
+          Home
+        </LinkButton>
+      </div>
+    </Card>
+  );
+}
 
 export default async function Dashboard() {
   const session = await verifySession();
 
+  const enabledFeatures = Object.entries(appConfig.features)
+    .filter(([, enabled]) => enabled)
+    .map(([key]) => key as FeatureKey)
+    .filter((key) => FEATURE_REGISTRY[key])
+    .map((key) => ({ key, meta: FEATURE_REGISTRY[key]! }));
+
+  const categories = [...new Set(enabledFeatures.map((f) => f.meta.category))];
+
+  const activeCount = enabledFeatures.filter((f) => f.meta.route).length;
+  const totalEnabled = enabledFeatures.length;
+
   return (
     <div className="mx-auto max-w-7xl px-4 py-8 sm:px-6 lg:px-8">
-      <h1 className="text-3xl font-bold text-text-primary">Dashboard</h1>
-      <p className="mt-2 text-text-secondary">Welcome back, {session.name}.</p>
-
-      <div className="mt-8 grid gap-6 sm:grid-cols-2 lg:grid-cols-3">
-        <Card>
-          <h3 className="text-lg font-semibold text-text-primary">Getting Started</h3>
-          <p className="mt-2 text-sm text-text-secondary">
-            This is a placeholder dashboard. Replace this with your app&apos;s content.
-          </p>
-        </Card>
+      <div className="flex flex-col gap-1 sm:flex-row sm:items-center sm:justify-between">
+        <div>
+          <h1 className="text-3xl font-bold text-text-primary">Dashboard</h1>
+          <p className="mt-1 text-text-secondary">Welcome back, {session.name}.</p>
+        </div>
+        <div className="mt-2 flex items-center gap-3 sm:mt-0">
+          <Badge variant="success">{activeCount} active</Badge>
+          <Badge variant="neutral">{totalEnabled} enabled</Badge>
+        </div>
       </div>
+
+      {categories.map((category) => {
+        const categoryFeatures = enabledFeatures.filter((f) => f.meta.category === category);
+        if (categoryFeatures.length === 0) return null;
+
+        return (
+          <section key={category} className="mt-8">
+            <h2 className="text-xs font-semibold uppercase tracking-wider text-text-muted mb-4">
+              {CATEGORY_LABELS[category] ?? category}
+            </h2>
+            <div className="grid gap-4 sm:grid-cols-2 lg:grid-cols-3">
+              {categoryFeatures.map(({ key, meta }) => (
+                <FeatureCard key={key} featureKey={key} meta={meta} />
+              ))}
+            </div>
+          </section>
+        );
+      })}
+
+      <section className="mt-8">
+        <QuickLinks isAdmin={session.role === 'admin'} />
+      </section>
     </div>
   );
 }

package/template/src/app/(protected)/files/page.tsx

@@ -0,0 +1,30 @@
+'use client';
+
+import { useState, useCallback } from 'react';
+import { FileUploader, FileList } from '@/features/uploads';
+
+export default function FilesPage() {
+  const [refreshKey, setRefreshKey] = useState(0);
+
+  const handleUploadComplete = useCallback(() => {
+    setRefreshKey((prev) => prev + 1);
+  }, []);
+
+  return (
+    <div className="space-y-8">
+      <div>
+        <h1 className="text-2xl font-bold text-text-primary">Files</h1>
+        <p className="mt-1 text-text-secondary">Upload, manage, and download your files.</p>
+      </div>
+
+      <FileUploader onUploadComplete={handleUploadComplete} />
+
+      <section>
+        <h2 className="text-xs font-semibold uppercase tracking-wider text-text-muted mb-4">
+          Your Files
+        </h2>
+        <FileList refreshKey={refreshKey} />
+      </section>
+    </div>
+  );
+}

package/template/src/app/(protected)/layout.tsx

@@ -8,11 +8,24 @@ import { useAuth } from '@/features/auth/context/AuthContext';
 import { routes } from '@/config/routes';
 import { appConfig } from '@/config/app.config';
 
-const NAV_ITEMS = [
+const STATIC_NAV_ITEMS = [
   { label: 'Dashboard', href: routes.dashboard },
   { label: 'Settings', href: routes.settings },
 ] as const;
 
+function buildNavItems() {
+  const items: Array<{ label: string; href: string }> = [...STATIC_NAV_ITEMS];
+  if (appConfig.features.billing) {
+    items.push({ label: 'Billing', href: routes.billing });
+  }
+  if (appConfig.features.fileUpload) {
+    items.push({ label: 'Files', href: routes.files });
+  }
+  return items;
+}
+
+const NAV_ITEMS = buildNavItems();
+
 function NavLink({ href, label, active }: { href: string; label: string; active: boolean }) {
   return (
     <Link