@mars-stack/cli 7.0.3 → 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.3",
+  "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,6 +92,19 @@ 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)`).
@@ -103,6 +117,7 @@ After **generator changes**, **template sync**, or before a **release**, run the
 
 ## 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)

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/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/);
+  });
+});