@mars-stack/core 8.0.16 → 8.0.17
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/cursor/manifest.json
CHANGED
|
@@ -300,6 +300,19 @@
|
|
|
300
300
|
"capabilities": ["file-edit"],
|
|
301
301
|
"meta": true
|
|
302
302
|
},
|
|
303
|
+
"cloud-codebase-runbook": {
|
|
304
|
+
"file": "skills/mars-cloud-codebase-runbook/SKILL.md",
|
|
305
|
+
"triggers": [
|
|
306
|
+
"cloud codebase runbook",
|
|
307
|
+
"run mars monorepo",
|
|
308
|
+
"test mars monorepo",
|
|
309
|
+
"monorepo setup yarn",
|
|
310
|
+
"workspace test continue",
|
|
311
|
+
"template dev port 3000"
|
|
312
|
+
],
|
|
313
|
+
"dependencies": [],
|
|
314
|
+
"capabilities": ["terminal"]
|
|
315
|
+
},
|
|
303
316
|
"address-pr-comments": {
|
|
304
317
|
"file": "skills/mars-address-pr-comments/SKILL.md",
|
|
305
318
|
"triggers": ["address PR comments", "reply to PR comments", "fix review feedback", "respond to PR review", "reply to comments with fixes", "remedial changes"],
|
|
@@ -0,0 +1,160 @@
|
|
|
1
|
+
# Skill: Mars monorepo — run and test (Cloud agents)
|
|
2
|
+
|
|
3
|
+
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.
|
|
4
|
+
|
|
5
|
+
**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`.
|
|
6
|
+
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
## One-time setup (repo root)
|
|
10
|
+
|
|
11
|
+
```bash
|
|
12
|
+
cd <repo-root>
|
|
13
|
+
yarn install
|
|
14
|
+
```
|
|
15
|
+
|
|
16
|
+
- **Node:** `>=20` (see root `package.json` `engines`).
|
|
17
|
+
- **Package manager:** Yarn 1.x workspaces (`yarn@1.22.22`).
|
|
18
|
+
|
|
19
|
+
Full build (Turbo order: core → ui → cli / other packages → Next apps):
|
|
20
|
+
|
|
21
|
+
```bash
|
|
22
|
+
yarn build
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
Run **all** package tests without stopping on first workspace failure:
|
|
26
|
+
|
|
27
|
+
```bash
|
|
28
|
+
yarn test --continue
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
Regenerate committed reference docs after manifest or package changes (pre-commit / CI enforce freshness):
|
|
32
|
+
|
|
33
|
+
```bash
|
|
34
|
+
npx tsx scripts/generate-docs.ts
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
---
|
|
38
|
+
|
|
39
|
+
## By codebase area
|
|
40
|
+
|
|
41
|
+
### Root scripts (`scripts/`)
|
|
42
|
+
|
|
43
|
+
| Goal | Command |
|
|
44
|
+
|------|---------|
|
|
45
|
+
| Scaffold matrix (CLI + generated apps build) | `yarn test:scaffold` or `yarn tsx scripts/test-scaffold-matrix.ts` — add `minimal` for a single fixture |
|
|
46
|
+
| Kitchen-sink Playwright catalog | `yarn test:e2e:kitchen-sink` (needs `DATABASE_URL`; see script / `template/e2e-kitchen-sink/`) |
|
|
47
|
+
| Harness drift (template `.cursor` vs core) | `node scripts/sync-harness.mjs --check` — fix with `node scripts/sync-harness.mjs` |
|
|
48
|
+
|
|
49
|
+
### `packages/core` (`@mars-stack/core`)
|
|
50
|
+
|
|
51
|
+
Library: auth, env, logging, rate limit, skills source under `packages/core/cursor/` (mirrored from template harness via sync).
|
|
52
|
+
|
|
53
|
+
```bash
|
|
54
|
+
yarn workspace @mars-stack/core test
|
|
55
|
+
yarn workspace @mars-stack/core build # usually via turbo from root
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
**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`).
|
|
59
|
+
|
|
60
|
+
### `packages/ui` (`@mars-stack/ui`)
|
|
61
|
+
|
|
62
|
+
Must build before CLI scaffold tests and playground build.
|
|
63
|
+
|
|
64
|
+
```bash
|
|
65
|
+
yarn workspace @mars-stack/ui test
|
|
66
|
+
yarn workspace @mars-stack/ui build
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
### `packages/cli` (`@mars-stack/cli`)
|
|
70
|
+
|
|
71
|
+
```bash
|
|
72
|
+
yarn workspace @mars-stack/cli build
|
|
73
|
+
yarn workspace @mars-stack/cli test
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
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.
|
|
77
|
+
|
|
78
|
+
### `template/` (`@mars-stack/template`)
|
|
79
|
+
|
|
80
|
+
The Next.js app that `mars create` copies. **This is where generator output and harness skills are authored** (then sync to core).
|
|
81
|
+
|
|
82
|
+
| Goal | Command |
|
|
83
|
+
|------|---------|
|
|
84
|
+
| Dev server (embedded DB + Next) | `yarn workspace @mars-stack/template dev` — runs `scripts/ensure-db.mjs` then Next (Turbopack) |
|
|
85
|
+
| Dev without ensure-db | `yarn workspace @mars-stack/template dev:no-db` |
|
|
86
|
+
| Unit / contract tests | `yarn workspace @mars-stack/template test` |
|
|
87
|
+
| Playwright (template tree) | `yarn workspace @mars-stack/template test:e2e` |
|
|
88
|
+
| Production build | `yarn workspace @mars-stack/template build` |
|
|
89
|
+
|
|
90
|
+
**Ports (Cursor Cloud):** template **3000**, docs **3001**, playground **3002**, platform **4000**.
|
|
91
|
+
|
|
92
|
+
### `packages/docs` (`@mars-stack/docs`)
|
|
93
|
+
|
|
94
|
+
Fumadocs site; no tests in package scripts.
|
|
95
|
+
|
|
96
|
+
```bash
|
|
97
|
+
yarn workspace @mars-stack/docs dev # port 3001
|
|
98
|
+
yarn workspace @mars-stack/docs build
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
### `packages/eslint-plugin-mars`
|
|
102
|
+
|
|
103
|
+
```bash
|
|
104
|
+
yarn workspace eslint-plugin-mars test
|
|
105
|
+
```
|
|
106
|
+
|
|
107
|
+
### `packages/playground` / `packages/platform`
|
|
108
|
+
|
|
109
|
+
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.
|
|
110
|
+
|
|
111
|
+
---
|
|
112
|
+
|
|
113
|
+
## Auth and “logging in” (template app)
|
|
114
|
+
|
|
115
|
+
Used for manual or browser checks against `template`:
|
|
116
|
+
|
|
117
|
+
1. Start: `yarn workspace @mars-stack/template dev` → **http://localhost:3000**
|
|
118
|
+
2. Register via the app’s sign-up flow (`/register` or equivalent in current routes).
|
|
119
|
+
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).
|
|
120
|
+
4. **`AUTO_VERIFY_EMAIL=true`** (e.g. in `.env.development.local`): skips verification for **new** signups on localhost-style URLs; see `template/AGENTS.md`.
|
|
121
|
+
|
|
122
|
+
**Admin / roles:** seed or DB (Prisma Studio: `yarn workspace @mars-stack/template db:studio`) depending on what the template ships for your branch.
|
|
123
|
+
|
|
124
|
+
---
|
|
125
|
+
|
|
126
|
+
## Feature flags and optional behaviour
|
|
127
|
+
|
|
128
|
+
### Build-time / scaffold flags
|
|
129
|
+
|
|
130
|
+
**`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.
|
|
131
|
+
|
|
132
|
+
### CLI / scaffold testing with different flag mixes
|
|
133
|
+
|
|
134
|
+
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`.
|
|
135
|
+
|
|
136
|
+
### Runtime feature-flag system (optional feature)
|
|
137
|
+
|
|
138
|
+
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.
|
|
139
|
+
|
|
140
|
+
---
|
|
141
|
+
|
|
142
|
+
## Common gotchas (check before debugging)
|
|
143
|
+
|
|
144
|
+
- **`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`.
|
|
145
|
+
- **`@mars-stack/billing` / `blog` / `notifications`:** Vitest may exit **1** with “no tests” — use `yarn test --continue` for the full tree.
|
|
146
|
+
- **Doc / manifest changes:** run `npx tsx scripts/generate-docs.ts` and commit `docs/generated/*` when `manifest.json` or packages change.
|
|
147
|
+
- **PRs touching `packages/`, `template/`, `scripts/`, etc.:** add a **changeset** (see `.changeset/README.md`) or let CI add a patch changeset on in-repo branches.
|
|
148
|
+
|
|
149
|
+
---
|
|
150
|
+
|
|
151
|
+
## Updating this skill
|
|
152
|
+
|
|
153
|
+
When you discover a new command, port, env var, or test workflow:
|
|
154
|
+
|
|
155
|
+
1. **Edit this file:** `template/.cursor/skills/mars-cloud-codebase-runbook/SKILL.md` (canonical harness).
|
|
156
|
+
2. **Sync to core:** `node scripts/sync-harness.mjs` so `packages/core/cursor/skills/` matches.
|
|
157
|
+
3. If you add/rename skills: update **`packages/core/cursor/manifest.json`**, then run **`npx tsx scripts/generate-docs.ts`**.
|
|
158
|
+
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.
|
|
159
|
+
|
|
160
|
+
Keep this skill **short and procedural**; defer deep rationale to design docs and `AGENTS.md`.
|