@mars-stack/core 3.0.2 → 4.0.1

package/cursor/manifest.json

@@ -305,6 +305,12 @@
       "triggers": ["address PR comments", "reply to PR comments", "fix review feedback", "respond to PR review", "reply to comments with fixes", "remedial changes"],
       "dependencies": [],
       "capabilities": ["file-edit", "terminal"]
+    },
+    "upgrade-scaffold": {
+      "file": "skills/mars-upgrade-scaffold/SKILL.md",
+      "triggers": ["upgrade mars template", "sync scaffold with upstream", "sync template", "apply template fixes", "pull in ensure-db fix", "upgrade scaffold", "template sync"],
+      "dependencies": [],
+      "capabilities": ["file-edit", "terminal"]
     }
   }
 }

package/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/package.json

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