@mars-stack/cli 7.0.2 → 7.0.4

package/README.md

@@ -36,6 +36,7 @@ mars create my-app
 ### `mars add feature <name>`
 
 Generate a feature module at `src/features/<name>/` with:
+
 - `server/index.ts` -- typed CRUD operations with `import 'server-only'`
 - `types.ts` -- Zod validation schemas and TypeScript types
 
@@ -121,6 +122,18 @@ mars upgrade           # upgrade to latest
 mars upgrade --dry-run # preview what would change
 ```
 
+### `mars template sync`
+
+Copy upstream **template plumbing** (scripts, auth shell files, and other manifest-listed paths) from the CLI-bundled template into an **existing** Mars project. Requires `.mars/scaffold.json` at the project root (from `mars create`); exits with an error if missing.
+
+```bash
+mars template sync --dry-run              # list planned changes, no writes
+mars template sync                        # default: plumbing category only
+mars template sync --only user-owned --force  # overwrite user-owned paths too (backups under .mars/backups/)
+```
+
+**vs `mars upgrade`:** `mars upgrade` bumps Mars npm packages only — it does **not** re-copy template source files. Use `mars template sync` when a CLI release includes fixes to `ensure-db.mjs`, proxy, or other synced paths. See the Mars monorepo [scaffold-template-sync-upgrade](https://github.com/greaveselliott/mars/blob/main/docs/exec-plans/active/scaffold-template-sync-upgrade.md) exec plan for the safety model and path inventory.
+
 ### `mars telemetry <enable|disable>`
 
 Opt in or out of anonymous usage analytics. Stored in `~/.marsrc`. Tracks command usage and feature selections only -- never project names, file contents, or env vars.

package/package.json

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

package/template/AGENTS.md

@@ -68,6 +68,7 @@ src/
 ## Config
 
 `src/config/app.config.ts` is the single source of truth for:
+
 - App identity (name, URL, support email)
 - Feature flags (auth, admin, billing, notifications, etc.)
 - Service providers (email, storage, database, payments, etc.)
@@ -91,18 +92,36 @@ yarn db:studio        # Open Prisma Studio
 
 **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.
 
+## Updating scaffold plumbing (`mars template sync`)
+
+When you install a newer **`@mars-stack/cli`**, pull upstream template fixes into this repo with **`mars template sync`** from the project root (requires `.mars/scaffold.json` from `mars create`). If that file is missing, the CLI reports that the directory is not a Mars scaffold — you cannot sync a non-Mars project.
+
+- **`mars template sync --dry-run`** — print the planned file operations; no writes.
+- **Default** — sync **plumbing** paths from the bundled template manifest (scripts, shared shell, etc.).
+- **`--force`** — also apply **user-owned** manifest entries; previous files are copied to **`.mars/backups/<timestamp>/`** before overwrite. Use when you deliberately want upstream versions of those paths.
+- **`--only <category>`** — e.g. `plumbing` or `user-owned` (latter typically with `--force`).
+
+Deep context: [scaffold-template-sync-upgrade](https://github.com/greaveselliott/mars/blob/main/docs/exec-plans/active/scaffold-template-sync-upgrade.md) in the Mars monorepo (path inventory and safety model). Skill for agents: [.cursor/skills/mars-upgrade-scaffold/](.cursor/skills/mars-upgrade-scaffold/).
+
+**vs `mars upgrade`:** `mars upgrade` only bumps Mars **npm** packages and reinstalls — it does **not** re-copy template files. Use template sync when plumbing (e.g. `ensure-db.mjs`) changed in a CLI release.
+
 ## 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)`).
 2. **Document every executed plan.** All plans — whether they started in a chat, a Cursor plan file, or someone's head — must end up in `docs/exec-plans/completed/` with decisions, discoveries, and outcomes recorded. Use the `capture-conversation-context` skill.
 3. **Feed conversations back.** Decisions, discoveries, and context that live only in chat threads are invisible to future agents. See [docs/design-docs/conversation-as-system-record.md](docs/design-docs/conversation-as-system-record.md).
 
+## Dogfood QA
+
+After **generator changes**, **template sync**, or before a **release**, run the manual checklist in **[docs/exec-plans/QA-dogfood-matrix.md](docs/exec-plans/QA-dogfood-matrix.md)** (happy path + edges × local / preview / prod smoke). Unchecked rows mean **not verified**. If a feature is off in `app.config.ts`, mark the row **N/A** instead of removing it.
+
 ## Pointers
 
+- **Updating your app:** [README.md](README.md) — entry point; this section and `mars template sync` above.
 - **Architecture details:** [docs/design-docs/](docs/design-docs/)
 - **Core beliefs:** [docs/design-docs/core-beliefs.md](docs/design-docs/core-beliefs.md)
 - **Conversation feedback:** [docs/design-docs/conversation-as-system-record.md](docs/design-docs/conversation-as-system-record.md)
-- **Execution plans:** [docs/exec-plans/](docs/exec-plans/)
+- **Execution plans:** [docs/exec-plans/](docs/exec-plans/) — includes [QA dogfood matrix](docs/exec-plans/QA-dogfood-matrix.md)
 - **Quality scores:** [docs/QUALITY_SCORE.md](docs/QUALITY_SCORE.md)
 - **Skills:** [.cursor/skills/](.cursor/skills/) — all skills use the `mars-` prefix (e.g., `mars-add-api-route/`, `mars-configure-email/`)
 - **Rules:** [.cursor/rules/](.cursor/rules/) — all rules use the `mars-` prefix (e.g., `mars-security.mdc`, `mars-data-access.mdc`)

package/template/README.md

@@ -0,0 +1,30 @@
+# Mars application template
+
+This directory is the **Next.js app template** copied by `mars create` into a new project. In the Mars monorepo it is developed and tested here; published **`@mars-stack/cli`** bundles the same tree at release time.
+
+## Updating your Mars app
+
+After you upgrade **`@mars-stack/cli`** or want upstream fixes for scaffold **plumbing** (scripts, auth shell files, shared wiring listed in the sync manifest), run from your **project root**:
+
+```bash
+mars template sync --dry-run   # preview planned copies
+mars template sync             # apply (default: plumbing only)
+```
+
+**Requirements:** the project must be a Mars scaffold with **`.mars/scaffold.json`**. If that file is missing, the CLI exits with an error — this command does not apply to arbitrary Next.js repos.
+
+**Flags:**
+
+| Flag                | Meaning                                                                                                        |
+| ------------------- | -------------------------------------------------------------------------------------------------------------- |
+| `--dry-run`         | Show what would change; no files written                                                                       |
+| `--force`           | Also sync **user-owned** manifest paths; always backs up replaced files under **`.mars/backups/<timestamp>/`** |
+| `--only <category>` | Limit to `plumbing` (default) or `user-owned` (usually with `--force`)                                         |
+
+**Safety:** Default sync overwrites **plumbing** files that the CLI owns (infrastructure). **User-owned** paths are skipped unless you pass **`--force`**, and overwrites are preceded by backups. Do not use `--force` on a dirty tree without reviewing `--dry-run` output.
+
+**Not `mars upgrade`:** `mars upgrade` bumps **`@mars-stack/core`** and **`@mars-stack/ui`** in `package.json` and reinstalls — it does **not** copy template source files. Use **both** commands when you need new package versions **and** refreshed plumbing (e.g. `scripts/ensure-db.mjs`).
+
+**Further reading (Mars monorepo):** [scaffold-template-sync-upgrade](https://github.com/greaveselliott/mars/blob/main/docs/exec-plans/active/scaffold-template-sync-upgrade.md) — full manifest, path inventory, and task history.
+
+**Agents:** see [.cursor/skills/mars-upgrade-scaffold/](.cursor/skills/mars-upgrade-scaffold/) and [AGENTS.md](AGENTS.md).

package/template/docs/exec-plans/QA-dogfood-matrix.md

@@ -0,0 +1,111 @@
+# Dogfood QA matrix (generated app)
+
+Manual and automated verification that the **entire shipped surface** of this app behaves correctly end-to-end—including edge cases—in **local**, **preview**, and **production-class** environments.
+
+**Source:** Mars monorepo [dogfood guard-rails plan](https://github.com/greaveselliott/mars/blob/main/docs/exec-plans/active/dogfood-guard-rails-generated-apps-p0.md). Update this file when you add or remove first-class features.
+
+## How to use
+
+1. Work **row by row**. Check the box only after the **happy path and listed edges** are exercised for that row in the given environment.
+2. **Unchecked boxes mean “not verified”—not “passed”.** Do not infer green status from silence.
+3. After each run, fill **Last run** with **date** (ISO `YYYY-MM-DD` is fine), **environment** (`local` / `preview` / `prod smoke`), and **commit** (short SHA or release tag you tested).
+4. Run this matrix after **major generator or template upgrades**, before a **release**, or when changing **auth, CSRF, billing, or uploads**.
+
+## Feature flags (`app.config.ts`)
+
+- If a feature is **disabled** in `src/config/app.config.ts`, mark the row **N/A** in the notes column (feature not present) instead of deleting the row. If the feature is enabled but you are **skipping** verification temporarily, mark **Skip** with a short reason—still not a pass.
+- If you **customized** Mars plumbing files, treat **user-owned** paths per `mars template sync` / upgrade docs before assuming failures are product bugs.
+
+---
+
+## Matrix
+
+### Auth
+
+- [ ] **Verified**
+  - **Happy path + edges:** sign-in, sign-up, forgot/reset, verify email, session expiry, wrong password, locked account, already logged-in redirect to dashboard.
+  - **Local** — Date: _____________  Env: _____________  Commit: _____________
+  - **Preview** — Date: _____________  Env: _____________  Commit: _____________
+  - **Prod smoke** — Date: _____________  Env: _____________  Commit: _____________
+  - **Notes (N/A / Skip):**
+
+### Protected shell
+
+- [ ] **Verified**
+  - **Happy path + edges:** nav, search, notifications, command palette (⌘K), theme toggle, user menu, **logout** (cookie cleared, lands on expected page).
+  - **Local** — Date: _____________  Env: _____________  Commit: _____________
+  - **Preview** — Date: _____________  Env: _____________  Commit: _____________
+  - **Prod smoke** — Date: _____________  Env: _____________  Commit: _____________
+  - **Notes (N/A / Skip):**
+
+### Onboarding
+
+- [ ] **Verified**
+  - **Happy path + edges:** all steps, skip where allowed, **CSRF** on step POST, mobile stepper layout.
+  - **Local** — Date: _____________  Env: _____________  Commit: _____________
+  - **Preview** — Date: _____________  Env: _____________  Commit: _____________
+  - **Prod smoke** — Date: _____________  Env: _____________  Commit: _____________
+  - **Notes (N/A / Skip):**
+
+### Settings
+
+- [ ] **Verified**
+  - **Happy path + edges:** display name, password change, **session list** (copy vs multi-row behaviour), revoke one / revoke all.
+  - **Local** — Date: _____________  Env: _____________  Commit: _____________
+  - **Preview** — Date: _____________  Env: _____________  Commit: _____________
+  - **Prod smoke** — Date: _____________  Env: _____________  Commit: _____________
+  - **Notes (N/A / Skip):**
+
+### Billing / pricing
+
+- [ ] **Verified**
+  - **Happy path + edges:** checkout/portal where Stripe enabled; gated UI when disabled.
+  - **Local** — Date: _____________  Env: _____________  Commit: _____________
+  - **Preview** — Date: _____________  Env: _____________  Commit: _____________
+  - **Prod smoke** — Date: _____________  Env: _____________  Commit: _____________
+  - **Notes (N/A / Skip):**
+
+### Files
+
+- [ ] **Verified**
+  - **Happy path + edges:** upload (XHR + **CSRF**), list, download, delete (**CSRF**), size limit error.
+  - **Local** — Date: _____________  Env: _____________  Commit: _____________
+  - **Preview** — Date: _____________  Env: _____________  Commit: _____________
+  - **Prod smoke** — Date: _____________  Env: _____________  Commit: _____________
+  - **Notes (N/A / Skip):**
+
+### AI
+
+- [ ] **Verified**
+  - **Happy path + edges:** chat send, stream, **CSRF**, provider-none vs configured behaviour.
+  - **Local** — Date: _____________  Env: _____________  Commit: _____________
+  - **Preview** — Date: _____________  Env: _____________  Commit: _____________
+  - **Prod smoke** — Date: _____________  Env: _____________  Commit: _____________
+  - **Notes (N/A / Skip):**
+
+### Admin
+
+- [ ] **Verified**
+  - **Happy path + edges:** users list, forbidden for non-admin.
+  - **Local** — Date: _____________  Env: _____________  Commit: _____________
+  - **Preview** — Date: _____________  Env: _____________  Commit: _____________
+  - **Prod smoke** — Date: _____________  Env: _____________  Commit: _____________
+  - **Notes (N/A / Skip):**
+
+### Blog, dashboard, landing, coming-soon, legal, cookie consent
+
+- [ ] **Verified**
+  - **Happy path + edges:** load + critical interaction for blog, files page, dashboard cards, landing, coming-soon, legal pages, cookie consent as applicable.
+  - **Local** — Date: _____________  Env: _____________  Commit: _____________
+  - **Preview** — Date: _____________  Env: _____________  Commit: _____________
+  - **Prod smoke** — Date: _____________  Env: _____________  Commit: _____________
+  - **Notes (N/A / Skip):**
+
+### Edge cases (cross-cutting)
+
+- [ ] **Verified**
+  - **Happy path + edges:** **403 CSRF** surfaces clear message (not `SyntaxError`), **mobile ~375px**, **dark mode**, **slow network** / abort, **two tabs** same user.
+  - **Local** — Date: _____________  Env: _____________  Commit: _____________
+  - **Preview** — Date: _____________  Env: _____________  Commit: _____________
+  - **Prod smoke** — Date: _____________  Env: _____________  Commit: _____________
+  - **Notes (N/A / Skip):**

package/template/scripts/dogfood-matrix-contract.test.ts

@@ -0,0 +1,45 @@
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { describe, expect, it } from 'vitest';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const matrixPath = join(__dirname, '../docs/exec-plans/QA-dogfood-matrix.md');
+
+/** Minimum feature slices from docs/exec-plans/active/dogfood-guard-rails-generated-apps-p0.md */
+const REQUIRED_SECTION_TITLES = [
+  'Auth',
+  'Protected shell',
+  'Onboarding',
+  'Settings',
+  'Billing / pricing',
+  'Files',
+  'AI',
+  'Admin',
+  'Blog, dashboard, landing, coming-soon, legal, cookie consent',
+  'Edge cases (cross-cutting)',
+] as const;
+
+describe('QA dogfood matrix contract', () => {
+  const content = readFileSync(matrixPath, 'utf8');
+
+  it('exists and documents last-run fields per environment', () => {
+    expect(content).toContain('**Local**');
+    expect(content).toContain('**Preview**');
+    expect(content).toContain('**Prod smoke**');
+    expect(content).toMatch(/Date:\s+_+.*Commit:/s);
+  });
+
+  it('states that unchecked rows are not verified', () => {
+    expect(content).toMatch(/not verified|Not verified/i);
+  });
+
+  it('documents N/A vs Skip for disabled or deferred features', () => {
+    expect(content).toMatch(/N\/A|Skip/);
+    expect(content).toMatch(/app\.config\.ts/);
+  });
+
+  it.each(REQUIRED_SECTION_TITLES)('includes matrix section: %s', (title) => {
+    expect(content).toContain(`### ${title}`);
+  });
+});

package/template/src/__tests__/template-readme-contract.test.ts

@@ -0,0 +1,21 @@
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { describe, expect, it } from 'vitest';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const readmePath = join(__dirname, '../../README.md');
+
+/** MARS-046: user-facing template sync docs stay discoverable in copied scaffolds */
+describe('template README (mars template sync)', () => {
+  const content = readFileSync(readmePath, 'utf8');
+
+  it('documents dry-run, force, scaffold fingerprint, backups, and upgrade distinction', () => {
+    expect(content).toMatch(/`--dry-run`/);
+    expect(content).toMatch(/`--force`/);
+    expect(content).toMatch(/\.mars\/scaffold\.json/);
+    expect(content).toMatch(/\.mars\/backups/);
+    expect(content).toMatch(/`mars upgrade`/);
+    expect(content).toMatch(/mars template sync/);
+  });
+});

package/template/vitest.config.ts

@@ -8,7 +8,7 @@ export default defineConfig({
     environment: 'jsdom',
     globals: true,
     setupFiles: ['./vitest.setup.ts'],
-    include: ['src/**/*.test.{ts,tsx}'],
+    include: ['src/**/*.test.{ts,tsx}', 'scripts/**/*.test.ts'],
     passWithNoTests: true,
     coverage: {
       provider: 'v8',