@mars-stack/cli 8.0.16 → 8.0.17

package/package.json

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

package/template/.cursor/skills/mars-cloud-codebase-runbook/SKILL.md

@@ -0,0 +1,160 @@
+# Skill: Mars monorepo — run and test (Cloud agents)
+
+Fast orientation for **this repository** (the Mars monorepo): install, run apps, exercise tests, and toggle behaviour. Use when you need “how do I run X?” without reading the whole tree.
+
+**Canonical context:** `AGENTS.md` (repo map, ports, known issues). **Scaffold / generator testing:** `.cursor/rules/scaffold-testing.mdc` and `docs/design-docs/scaffold-testing-strategy.md`.
+
+---
+
+## One-time setup (repo root)
+
+```bash
+cd <repo-root>
+yarn install
+```
+
+- **Node:** `>=20` (see root `package.json` `engines`).
+- **Package manager:** Yarn 1.x workspaces (`yarn@1.22.22`).
+
+Full build (Turbo order: core → ui → cli / other packages → Next apps):
+
+```bash
+yarn build
+```
+
+Run **all** package tests without stopping on first workspace failure:
+
+```bash
+yarn test --continue
+```
+
+Regenerate committed reference docs after manifest or package changes (pre-commit / CI enforce freshness):
+
+```bash
+npx tsx scripts/generate-docs.ts
+```
+
+---
+
+## By codebase area
+
+### Root scripts (`scripts/`)
+
+| Goal | Command |
+|------|---------|
+| Scaffold matrix (CLI + generated apps build) | `yarn test:scaffold` or `yarn tsx scripts/test-scaffold-matrix.ts` — add `minimal` for a single fixture |
+| Kitchen-sink Playwright catalog | `yarn test:e2e:kitchen-sink` (needs `DATABASE_URL`; see script / `template/e2e-kitchen-sink/`) |
+| Harness drift (template `.cursor` vs core) | `node scripts/sync-harness.mjs --check` — fix with `node scripts/sync-harness.mjs` |
+
+### `packages/core` (`@mars-stack/core`)
+
+Library: auth, env, logging, rate limit, skills source under `packages/core/cursor/` (mirrored from template harness via sync).
+
+```bash
+yarn workspace @mars-stack/core test
+yarn workspace @mars-stack/core build   # usually via turbo from root
+```
+
+**Skills / rules:** Canonical copies live under `template/.cursor/{skills,rules}/` (`mars-*` only). After editing skills there, run `node scripts/sync-harness.mjs`. **`packages/core/cursor/manifest.json`** is the skill registry (triggers, deps); update it when adding a skill, then regenerate docs (`scripts/generate-docs.ts`).
+
+### `packages/ui` (`@mars-stack/ui`)
+
+Must build before CLI scaffold tests and playground build.
+
+```bash
+yarn workspace @mars-stack/ui test
+yarn workspace @mars-stack/ui build
+```
+
+### `packages/cli` (`@mars-stack/cli`)
+
+```bash
+yarn workspace @mars-stack/cli build
+yarn workspace @mars-stack/cli test
+```
+
+Scaffold integration tests need `@mars-stack/ui` built first. Do **not** edit `packages/cli/template/` — it is a **build artifact**; change root `template/` and CLI build copies it.
+
+### `template/` (`@mars-stack/template`)
+
+The Next.js app that `mars create` copies. **This is where generator output and harness skills are authored** (then sync to core).
+
+| Goal | Command |
+|------|---------|
+| Dev server (embedded DB + Next) | `yarn workspace @mars-stack/template dev` — runs `scripts/ensure-db.mjs` then Next (Turbopack) |
+| Dev without ensure-db | `yarn workspace @mars-stack/template dev:no-db` |
+| Unit / contract tests | `yarn workspace @mars-stack/template test` |
+| Playwright (template tree) | `yarn workspace @mars-stack/template test:e2e` |
+| Production build | `yarn workspace @mars-stack/template build` |
+
+**Ports (Cursor Cloud):** template **3000**, docs **3001**, playground **3002**, platform **4000**.
+
+### `packages/docs` (`@mars-stack/docs`)
+
+Fumadocs site; no tests in package scripts.
+
+```bash
+yarn workspace @mars-stack/docs dev    # port 3001
+yarn workspace @mars-stack/docs build
+```
+
+### `packages/eslint-plugin-mars`
+
+```bash
+yarn workspace eslint-plugin-mars test
+```
+
+### `packages/playground` / `packages/platform`
+
+Next apps; **no `test` script**. Validate with `yarn workspace @mars-stack/playground build` / `yarn workspace @mars-stack/platform build` after `yarn build` or workspace build.
+
+---
+
+## Auth and “logging in” (template app)
+
+Used for manual or browser checks against `template`:
+
+1. Start: `yarn workspace @mars-stack/template dev` → **http://localhost:3000**
+2. Register via the app’s sign-up flow (`/register` or equivalent in current routes).
+3. **Email:** default `app.config.ts` uses **console** email — verification links appear in the **terminal** running dev. On `/verify`, use the in-page **“Click here to verify your email”** when console provider is active (no inbox).
+4. **`AUTO_VERIFY_EMAIL=true`** (e.g. in `.env.development.local`): skips verification for **new** signups on localhost-style URLs; see `template/AGENTS.md`.
+
+**Admin / roles:** seed or DB (Prisma Studio: `yarn workspace @mars-stack/template db:studio`) depending on what the template ships for your branch.
+
+---
+
+## Feature flags and optional behaviour
+
+### Build-time / scaffold flags
+
+**`template/src/config/app.config.ts`** — `appConfig.features.*` and `appConfig.services.*` gate code paths. Generators set these when you run `mars generate`; in the monorepo you often edit the template or CLI fixtures instead of toggling at runtime.
+
+### CLI / scaffold testing with different flag mixes
+
+Use **`packages/cli/src/__tests__/fixtures/`** profiles (`minimal`, `kitchen-sink`, `saas`, …) and `yarn tsx scripts/test-scaffold-matrix.ts [profile]` so each combination still installs, type-checks, and runs `next build`.
+
+### Runtime feature-flag system (optional feature)
+
+If **`featureFlags: true`** and the feature-flag module exists, behaviour may follow env / DB rules described in **`mars-configure-feature-flags`**. For a **minimal mental model:** prefer toggling **`app.config.ts`** and re-running tests; add env overrides only when that feature is actually present in the tree.
+
+---
+
+## Common gotchas (check before debugging)
+
+- **`yarn lint` at repo root** may fail for template/playground: Next 16 removed `next lint` — use package-level ESLint or `yarn format:check` where appropriate; see `AGENTS.md`.
+- **`@mars-stack/billing` / `blog` / `notifications`:** Vitest may exit **1** with “no tests” — use `yarn test --continue` for the full tree.
+- **Doc / manifest changes:** run `npx tsx scripts/generate-docs.ts` and commit `docs/generated/*` when `manifest.json` or packages change.
+- **PRs touching `packages/`, `template/`, `scripts/`, etc.:** add a **changeset** (see `.changeset/README.md`) or let CI add a patch changeset on in-repo branches.
+
+---
+
+## Updating this skill
+
+When you discover a new command, port, env var, or test workflow:
+
+1. **Edit this file:** `template/.cursor/skills/mars-cloud-codebase-runbook/SKILL.md` (canonical harness).
+2. **Sync to core:** `node scripts/sync-harness.mjs` so `packages/core/cursor/skills/` matches.
+3. If you add/rename skills: update **`packages/core/cursor/manifest.json`**, then run **`npx tsx scripts/generate-docs.ts`**.
+4. If behaviour belongs in the long-form guide: add a short pointer here and put detail in **`AGENTS.md`**, **`ARCHITECTURE.md`**, or the relevant **`docs/design-docs/`** file.
+
+Keep this skill **short and procedural**; defer deep rationale to design docs and `AGENTS.md`.