saasaloy 0.6.1 → 0.7.0

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.
Files changed (55) hide show
  1. package/README.md +7 -7
  2. package/dist/index.js +3952 -1899
  3. package/dist/index.js.map +1 -1
  4. package/package.json +2 -1
  5. package/schemas/manifest.schema.json +32 -1
  6. package/schemas/registry-item.schema.json +57 -2
  7. package/schemas/saasaloy-lock.schema.json +9 -0
  8. package/schemas/saasaloy.schema.json +12 -0
  9. package/templates/base/AGENTS.md +86 -19
  10. package/templates/base/README.md +16 -1
  11. package/templates/base/_agents/skills/saasaloy-config/SKILL.md +131 -0
  12. package/templates/base/_agents/skills/saasaloy-deploy/SKILL.md +280 -0
  13. package/templates/base/_agents/skills/saasaloy-env/SKILL.md +8 -7
  14. package/templates/base/_agents/skills/saasaloy-landing-copy/SKILL.md +10 -9
  15. package/templates/base/_agents/skills/saasaloy-setup/SKILL.md +30 -22
  16. package/templates/base/_agents/skills/saasaloy-testing/SKILL.md +85 -0
  17. package/templates/base/_gitignore +4 -0
  18. package/templates/base/_prettierignore +5 -0
  19. package/templates/base/_saasaloy-base.json +6 -2
  20. package/templates/base/apps/web/package.json +1 -0
  21. package/templates/base/apps/web/src/layouts/Layout.astro +2 -1
  22. package/templates/base/apps/web/src/pages/privacy.astro +2 -0
  23. package/templates/base/apps/web/src/pages/terms.astro +2 -0
  24. package/templates/base/docs/runbook-deploy.md +72 -0
  25. package/templates/base/oxlint.config.mjs +28 -0
  26. package/templates/base/package.json +7 -4
  27. package/templates/base/packages/config/package.json +19 -0
  28. package/templates/base/packages/config/src/define.test.ts +134 -0
  29. package/templates/base/packages/config/src/define.ts +135 -0
  30. package/templates/base/packages/config/src/index.ts +34 -0
  31. package/templates/base/packages/config/src/project.ts +25 -0
  32. package/templates/base/packages/config/src/sections/app.ts +27 -0
  33. package/templates/base/packages/config/src/sections.ts +22 -0
  34. package/templates/base/packages/config/tsconfig.json +4 -0
  35. package/templates/base/packages/env/package.json +2 -1
  36. package/templates/base/packages/env/src/deploy.ts +3 -2
  37. package/templates/base/packages/env/src/services.test.ts +27 -11
  38. package/templates/base/packages/tooling/package.json +21 -0
  39. package/templates/base/packages/tooling/src/deploy-production.test.ts +923 -0
  40. package/templates/base/packages/tooling/src/deploy-production.ts +1041 -0
  41. package/templates/base/packages/tooling/src/deploy.config.ts +30 -0
  42. package/templates/base/packages/tooling/src/link-skills.test.ts +126 -0
  43. package/templates/base/packages/tooling/src/link-skills.ts +142 -0
  44. package/templates/base/packages/tooling/src/release.test.ts +205 -0
  45. package/templates/base/packages/tooling/src/release.ts +228 -0
  46. package/templates/base/packages/tooling/src/targets.ts +38 -0
  47. package/templates/base/packages/tooling/src/types.ts +78 -0
  48. package/templates/base/packages/tooling/tsconfig.json +11 -0
  49. package/templates/base/packages/ui/package.json +1 -0
  50. package/templates/base/packages/ui/src/blocks/footer.tsx +5 -3
  51. package/templates/base/packages/ui/src/content/landing.ts +2 -4
  52. package/templates/base/packages/ui/src/index.ts +10 -5
  53. package/templates/base/saasaloy.json +2 -1
  54. package/templates/base/turbo.json +1 -5
  55. package/templates/base/vitest.config.ts +5 -1
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "saasaloy",
3
- "version": "0.6.1",
3
+ "version": "0.7.0",
4
4
  "description": "Composable SaaS accelerator kit.",
5
5
  "keywords": [
6
6
  "saas",
@@ -45,6 +45,7 @@
45
45
  "start": "node ./dist/index.js",
46
46
  "typecheck": "tsc --noEmit",
47
47
  "test": "vitest run --coverage",
48
+ "test:tooling": "vitest run --config vitest.tooling.config.ts",
48
49
  "test:e2e": "vitest run --config vitest.integration.config.ts test/e2e",
49
50
  "test:matrix": "vitest run --config vitest.integration.config.ts test/matrix",
50
51
  "release": "release-it",
@@ -6,6 +6,30 @@
6
6
  "type": "object",
7
7
  "additionalProperties": false,
8
8
  "required": ["managed"],
9
+ "$defs": {
10
+ "when": {
11
+ "type": "object",
12
+ "additionalProperties": false,
13
+ "minProperties": 1,
14
+ "description": "The descriptor `when` the entry was written under (#242). `remove X` reads it offline to also remove another module's entries whose `installed` names X.",
15
+ "properties": {
16
+ "testing": {
17
+ "const": true,
18
+ "description": "Ship only when testing.mode is `tests-after` or `tdd`. The one allowed value is `true`; leave the key out for an entry that ships in every mode."
19
+ },
20
+ "installed": {
21
+ "type": "array",
22
+ "minItems": 1,
23
+ "uniqueItems": true,
24
+ "description": "Ship only when every named module is installed. `remove` of a named module also removes the entry.",
25
+ "items": {
26
+ "type": "string",
27
+ "pattern": "^[a-z0-9][a-z0-9-]*$"
28
+ }
29
+ }
30
+ }
31
+ }
32
+ },
9
33
  "properties": {
10
34
  "$schema": {
11
35
  "type": "string",
@@ -37,6 +61,12 @@
37
61
  "type": "string",
38
62
  "minLength": 1,
39
63
  "description": "Module-relative POSIX source path this file was copied from (e.g. `files/lib/email.ts`). `update` uses it to fetch the same file at the old and new commit SHAs. Optional — entries written before this field shipped fall back to re-deriving the target from the module descriptor."
64
+ },
65
+ "when": { "$ref": "#/$defs/when" },
66
+ "mergedWith": {
67
+ "type": "string",
68
+ "pattern": "^[a-f0-9]{64}$",
69
+ "description": "sha256 of the module's version a merge took in, set by `saasaloy update --resolved <path>`. The entry's `hash` is then of the merged bytes. While the module still ships that version `update` skips the file; once it moves, the file goes to the merge plan rather than being overwritten. Cleared the first time the tool writes the file itself."
40
70
  }
41
71
  }
42
72
  }
@@ -105,7 +135,8 @@
105
135
  }
106
136
  },
107
137
  "description": "The op as authored (kind + payload + file), re-applicable at execute time."
108
- }
138
+ },
139
+ "when": { "$ref": "#/$defs/when" }
109
140
  }
110
141
  }
111
142
  }
@@ -6,6 +6,30 @@
6
6
  "type": "object",
7
7
  "additionalProperties": false,
8
8
  "required": ["name", "type"],
9
+ "$defs": {
10
+ "when": {
11
+ "type": "object",
12
+ "additionalProperties": false,
13
+ "minProperties": 1,
14
+ "description": "Ship this entry only while the condition holds (#242, ADR 0054). The keys combine with AND: `testing` ships it only when the project's testing mode is not `off`, and `installed` only when every named module is in the resolved install set. The applier tests it before `onlyWith`, and a target whose entries it drops is skipped, not refused. It decides the first write only: an entry already in the manifest stays managed in every mode. Backfill writes the entry once the condition turns true.",
15
+ "properties": {
16
+ "testing": {
17
+ "const": true,
18
+ "description": "Ship only when testing.mode is `tests-after` or `tdd`. The one allowed value is `true`; leave the key out for an entry that ships in every mode."
19
+ },
20
+ "installed": {
21
+ "type": "array",
22
+ "minItems": 1,
23
+ "uniqueItems": true,
24
+ "description": "Ship only when every named module is installed. `remove` of a named module also removes the entry.",
25
+ "items": {
26
+ "type": "string",
27
+ "pattern": "^[a-z0-9][a-z0-9-]*$"
28
+ }
29
+ }
30
+ }
31
+ }
32
+ },
9
33
  "properties": {
10
34
  "$schema": {
11
35
  "type": "string",
@@ -21,6 +45,25 @@
21
45
  "enum": ["saasaloy:capability", "saasaloy:feature"],
22
46
  "description": "`saasaloy:capability` scaffolds an app/package and establishes extension points; `saasaloy:feature` extends capabilities by dropping files into their conventions."
23
47
  },
48
+ "description": {
49
+ "type": "string",
50
+ "pattern": "^[^\\r\\n]+$",
51
+ "description": "One line on what the module gives a project. `saasaloy list --json` prints it, so an agent can pick a module without reading its skill. Optional in the schema; `saasaloy doctor` on a registry fails a descriptor without it (#223)."
52
+ },
53
+ "stage": {
54
+ "type": "string",
55
+ "enum": ["validate", "mvp", "teams", "money", "scale"],
56
+ "description": "The product stage that usually earns this module: `validate` (landing page and waitlist), `mvp` (sign-in, admin, email), `teams` (organizations, tenancy, roles), `money` (billing and payments) or `scale` (jobs, caching, files, rate limits, API access). A supporting module the README's stage table does not name takes the earliest stage of the modules that need it, and a provider or a driver takes its capability's stage."
57
+ },
58
+ "needs": {
59
+ "type": "array",
60
+ "description": "What the module needs outside the repo before it works in production: `cloudflare-paid` (a paid Workers plan), `stripe` (a Stripe account), `domain` (a domain onboarded by hand) or `vendor-account` (an account with another vendor). An empty array means nothing beyond the free tier.",
61
+ "uniqueItems": true,
62
+ "items": {
63
+ "type": "string",
64
+ "enum": ["cloudflare-paid", "stripe", "domain", "vendor-account"]
65
+ }
66
+ },
24
67
  "requires": {
25
68
  "type": "object",
26
69
  "additionalProperties": false,
@@ -103,6 +146,12 @@
103
146
  "type": "string",
104
147
  "pattern": "^[a-z0-9][a-z0-9-]*$",
105
148
  "description": "Install this file only when the named module is in the resolved install set — this run's dependsOn graph plus what saasaloy.json already records (#99). Two entries may share one `target` when their conditions are disjoint: that is how a module ships a per-driver variant of a dialect-bound file. A target whose entries are all conditional and none matches is a plan-time refusal, not a silently missing file."
149
+ },
150
+ "when": { "$ref": "#/$defs/when" },
151
+ "untested": {
152
+ "type": "string",
153
+ "minLength": 1,
154
+ "description": "Why this file ships with no test beside it (#242). Reserved for a later descriptor guard (#243), which is to read the reason rather than fail the file."
106
155
  }
107
156
  }
108
157
  }
@@ -193,7 +242,8 @@
193
242
  "nav-entry"
194
243
  ],
195
244
  "description": "Which codemod applies this patch. `const-array`, `plugin-array`, `chained-route`, `wrangler-binding`, `drizzle-column` and `nav-entry` have removal inverses."
196
- }
245
+ },
246
+ "when": { "$ref": "#/$defs/when" }
197
247
  },
198
248
  "allOf": [
199
249
  {
@@ -445,13 +495,18 @@
445
495
  "type": "string",
446
496
  "pattern": "^[a-z0-9][a-z0-9-]*$",
447
497
  "description": "Install this file only when the named module is in the resolved install set — this run's dependsOn graph plus what saasaloy.json already records (#99). Same rule as a top-level files[] entry: two entries may share one `target` when their conditions are disjoint, and a target no candidate matches is a plan-time refusal. auth's per-driver db-provider.ts lives here rather than in files[], which is why both shapes carry the keyword."
448
- }
498
+ },
499
+ "when": { "$ref": "#/$defs/when" }
449
500
  }
450
501
  }
451
502
  }
452
503
  }
453
504
  }
454
505
  },
506
+ "enablesTesting": {
507
+ "const": true,
508
+ "description": "Adding this module turns testing on (#242, ADR 0054): on a project whose testing.mode is `off`, `add` plans with `tests-after`, saves it once the apply succeeds, and backfills every gated entry. It leaves `tdd` alone, and `remove` never changes the mode."
509
+ },
455
510
  "agent": {
456
511
  "type": "object",
457
512
  "description": "AI context contributed by this module. A module ships skill folder(s) that `add` copies into .claude/skills/ (recorded in the manifest for a clean `remove`); it never edits the committed AGENTS.md/CLAUDE.md.",
@@ -78,6 +78,15 @@
78
78
  "type": "string",
79
79
  "pattern": "^[a-z0-9][a-z0-9-]*$"
80
80
  }
81
+ },
82
+ "requiresOneOf": {
83
+ "type": "array",
84
+ "description": "The module's declared `requiresOneOf` list, recorded because descriptors aren't kept after install — this is what lets `doctor` report a module none of whose options is installed.",
85
+ "uniqueItems": true,
86
+ "items": {
87
+ "type": "string",
88
+ "pattern": "^[a-z0-9][a-z0-9-]*$"
89
+ }
81
90
  }
82
91
  }
83
92
  }
@@ -33,6 +33,18 @@
33
33
  "pattern": "^[a-z0-9][a-z0-9-]*$",
34
34
  "description": "The base app `saasaloy init` scaffolded (e.g. `web`). It is not a module: the tool never applied it, it has no descriptor and no lock entry, so it never takes part in dependsOn resolution or conflict checks. Absent in a project scaffolded before this field existed; `saasaloy` migrates such a project on its next write."
35
35
  },
36
+ "testing": {
37
+ "type": "object",
38
+ "description": "The project's testing mode (#242, ADR 0053). `off` ships no module tests, `tests-after` ships each module's tests and asks for a test with every change, `tdd` asks for the failing test first. `saasaloy init` writes it and `saasaloy testing <mode>` changes it, together with the marked block in the root `AGENTS.md`. Absent in a project scaffolded before this field existed; the tool then reads `off`.",
39
+ "additionalProperties": false,
40
+ "required": ["mode"],
41
+ "properties": {
42
+ "mode": {
43
+ "type": "string",
44
+ "enum": ["off", "tests-after", "tdd"]
45
+ }
46
+ }
47
+ },
36
48
  "installed": {
37
49
  "type": "array",
38
50
  "description": "Modules present in this project. Grows as `saasaloy add` runs; drives dependsOn resolution.",
@@ -2,12 +2,15 @@
2
2
 
3
3
  This is a SaaS project scaffolded with Saasaloy.
4
4
 
5
+ ## Find the right skill
6
+
7
+ Every installed module ships a skill in `.agents/skills/<name>/SKILL.md`, linked into `.claude/skills/`. Before you change a module's code, list `.agents/skills/` or run `saasaloy list --installed --json`, which gives each installed module's `skill`, `description` and `stage`, and read that skill first.
5
8
 
6
9
  ## Project Structure
7
10
 
8
11
  This is a **pnpm workspace monorepo** managed by **Turborepo**.
9
12
 
10
- - **Root**: Configuration files, shared tooling
13
+ - **Root**: Configuration files only. Repository tooling lives in `packages/tooling` (see "Code at the Root")
11
14
  - **`apps/*`**: Applications (Next.js, Astro apps - currently empty, will be added)
12
15
  - **`packages/*`**: Shared packages
13
16
 
@@ -39,6 +42,12 @@ Rules for a new app or service:
39
42
  - **Update both allow-lists when you add a browser origin**: `DEV_ORIGINS` in
40
43
  `apps/api/src/index.ts` and `DEV_ORIGINS` in `packages/auth/src/auth.ts`.
41
44
 
45
+ ### Code at the Root
46
+
47
+ No code lives at the repository root. The root holds configuration only: `package.json`, `turbo.json`, the lint and format configs, `vitest.config.ts`. A tool, a script or a codemod goes into a workspace, where it gets a `tsconfig.json`, a `typecheck` script, the type-aware lint pass and the root Vitest run. A root `scripts/` folder gets none of them.
48
+
49
+ `packages/tooling` (`@repo/tooling`) is the workspace for the repository's own tooling. It holds the deploy command (`src/deploy-production.ts`) and the skill linker (`src/link-skills.ts`). A root script that runs one of them names the file: `node packages/tooling/src/<name>.ts`. Two of its files are yours: `src/deploy.config.ts` and `src/targets.ts`. `saasaloy update` never writes them again after `saasaloy init`. The other files are managed.
50
+
42
51
  ### Workspace Commands
43
52
 
44
53
  - Filter to specific package: `pnpm --filter <package-name> <command>`
@@ -102,11 +111,7 @@ command that distributes it, one typed gate in front of the capabilities.
102
111
  is a workspace that reads a `.env` — `api`, `web`, `admin` — and
103
112
  `packages/env/src/services.ts` is the table. The `deploy` row has no file: it holds the
104
113
  Cloudflare credentials a deploy loads in memory.
105
- - **`pnpm deploy:production` deploys every Worker.** It checks every service's production
106
- values first, then runs `turbo run deploy`, where each deployable workspace runs
107
- `env-deploy <service>`: build with the production values in the environment, then
108
- `wrangler deploy --secrets-file`. The `local` source reads production values from the
109
- gitignored `packages/env/.env.prod`. Nothing writes a production value under `apps/`.
114
+ - **`pnpm deploy:production` deploys every Worker.** It checks the git gates and every service's production values first, then deploys each Worker one at a time in the order `packages/tooling/src/targets.ts` gives. Each Worker runs its own `env-deploy <service>`: build with the production values in the environment, then `wrangler deploy --secrets-file`. The `local` source reads production values from the gitignored `packages/env/.env.prod`. Nothing writes a production value under `apps/`. The `saasaloy-deploy` skill covers the gates, the flags and the rollback.
110
115
  - **`createEnv` is the gate.** `apiEnv(c.env)` on the server, `webEnv()` in a frontend.
111
116
  It validates on the first call and throws once naming every failing key, its module and
112
117
  what the key is for.
@@ -120,6 +125,43 @@ command that distributes it, one typed gate in front of the capabilities.
120
125
  The `saasaloy-env` skill is the runbook: adding a key, the section rule, the server/client
121
126
  split, blank-on-purpose keys, and the offline rule.
122
127
 
128
+ ### The `@repo/config` Value Layer
129
+
130
+ `packages/config` (`@repo/config`) owns the values this project checks into its repo and ships
131
+ identically to every environment: the product name, the locale, the legal paths, and each
132
+ installed module's section. Read it with a plain import, from any app or package:
133
+
134
+ ```ts
135
+ import { config } from "@repo/config";
136
+
137
+ config.app.name; // `siteName` in @repo/ui re-exports this
138
+ config.app.locale; // the shared layout's <html lang>
139
+ ```
140
+
141
+ It is a frozen plain object, built once at module load. It has **zero runtime dependencies and
142
+ imports nothing**, which is what lets every app, every package and every browser bundle import it.
143
+
144
+ **config or `.env`?** Two deployments of *this* project — production and staging. If the value can
145
+ differ between them it is an env var, secret or not. If it cannot, it is config. A database URL is
146
+ env; the product's name is config.
147
+
148
+ **The landing copy is not config.** Prices, tier ids and every sentence on the page stay in
149
+ `@repo/ui/content/landing.ts`.
150
+
151
+ Four files, and only one is yours:
152
+
153
+ | Path | Who owns it |
154
+ |------|-------------|
155
+ | `src/project.ts` | **You.** The only file here you edit. Nothing overwrites it. |
156
+ | `src/sections.ts` | The section registry. `saasaloy add` patches one line in; don't hand-edit the array. |
157
+ | `src/sections/<key>.ts` | The module that installed it (`app` is the base's). |
158
+ | `src/define.ts` | The base template. The composition core. |
159
+
160
+ The merge goes **one level below the section**: `app: { name: "..." }` replaces the name and keeps
161
+ the rest of `app`, while a nested record or an array is replaced whole. A key no installed section
162
+ defines is a `typecheck` error, which is the only validation there is — the values are literals in
163
+ this repo. Run `/saasaloy-config` for the whole runbook.
164
+
123
165
  ### The `@repo/ui` Design Layer
124
166
 
125
167
  `packages/ui` owns the design layer: the Tailwind 4 theme in `src/styles/`, the `cn()` helper and the client-state stores in `src/lib/`, the vendored [shadcn](https://ui.shadcn.com) primitives in `src/components/`, the **blocks** in `src/blocks/`, the shells and layouts in `src/containers/`, and the copy in `src/content/`.
@@ -154,7 +196,7 @@ With the admin app installed, `apps/admin/DESIGN.md` records the admin tokens in
154
196
 
155
197
  Primitives, blocks and containers are reached by subpath — none is re-exported from the
156
198
  package root, so importing one never drags in the rest. The root export is project-wide
157
- constants only (`siteName`):
199
+ constants only (`siteName`, which re-exports `config.app.name`):
158
200
 
159
201
  ```ts
160
202
  import { siteName } from "@repo/ui";
@@ -400,9 +442,11 @@ Blocks, like primitives, are source you own — they are meant to be edited, not
400
442
  every user-visible string on the landing page, in two namespaces:
401
443
 
402
444
  - **`landing.*`** — marketing copy. What the product is, who it is for, what it costs.
403
- This is the whole surface a copy rewrite touches. The brand itself is not here: `siteName`
404
- lives in `packages/ui/src/index.ts`, is not translated, and is set once by
405
- `saasaloy-setup`.
445
+ This is the whole surface a copy rewrite touches. The brand itself is not here: it is
446
+ `config.app.name` in `packages/config/src/project.ts`, is not translated, and is set once
447
+ by `saasaloy-setup`. The currency symbol and the tier ids and names are read from
448
+ `@repo/config` for the same reason — they are ids and numbers, and `packages/billing`
449
+ charges against the same ids.
406
450
  - **`ui.*`** — chrome and accessibility labels (`Monthly`, `Most popular`, `Close menu`,
407
451
  `Billing period`). Nothing here says anything about the product, so a copy pass never
408
452
  rewrites it. It does get translated, key for key, when `landing.*` is written in some
@@ -451,27 +495,29 @@ the theme toggle's labels deliberately stay in `packages/ui/src/lib/theme.ts`: t
451
495
  inlined verbatim into a pre-paint `<script>` and is import-free on purpose.
452
496
 
453
497
  **The default copy is Saasaloy's own.** A fresh project's page describes Saasaloy, and
454
- `siteName` in `packages/ui/src/index.ts` defaults to `"Saasaloy"`, so the brand and the
498
+ `config.app.name` in `packages/config/src/sections/app.ts` defaults to `"Saasaloy"`, so the brand and the
455
499
  words agree until you replace both. The two skills below replace them in one pass.
456
500
 
457
- **Making this project yours.** Three skills ship with the base (linked at
501
+ **Making this project yours.** Four skills ship with the base (linked at
458
502
  `.claude/skills/`, real files in `.agents/skills/`). The first two run in order:
459
503
 
460
504
  1. **`saasaloy-setup`** asks ten questions about the product — starting with its name — and
461
505
  writes the answers to `docs/product-brief.md`. Every question carries sample answers you
462
- can take, edit, or ignore. It also sets `siteName` and the page's `lang`. Nothing else
506
+ can take, edit, or ignore. It also sets `config.app.name` and `config.app.locale`. Nothing else
463
507
  reads your product knowledge out of your head, so run it first; other skills read the
464
508
  brief rather than interviewing you again.
465
509
  2. **`saasaloy-landing-copy`** turns that brief into the landing page's words. It drafts
466
510
  into `docs/landing-copy-draft.md` for you to review and edit, then writes
467
511
  `packages/ui/src/content/landing.ts` once you approve, then deletes the draft.
468
512
 
469
- The third has no place in that order, because it runs whenever the UI moves:
513
+ The other two have no place in that order, because they run whenever the thing they own moves:
470
514
 
471
515
  3. **`saasaloy-design`** keeps `apps/web/DESIGN.md` true, and `apps/admin/DESIGN.md` when the admin app is installed. Its `theme` flow swaps the
472
516
  preset and re-derives the contract; `update` re-derives after you change `web.css` or
473
517
  add components; `audit` reports where the code and the contract disagree. It reads the
474
518
  product brief when one exists and never writes it.
519
+ 4. **`saasaloy-config`** covers `@repo/config`: the config-versus-`.env` rule, adding a
520
+ section, the merge rule, and why an override is not taking effect.
475
521
 
476
522
  Invoke them rather than editing thirteen blocks by hand — and if you do edit by hand, keep the
477
523
  strings in the content module so the next pass finds them.
@@ -493,12 +539,12 @@ owning formatting. All four run from `oxlint.config.mjs`, `prettier.config.js` a
493
539
  cannot consume one (`extends` takes file paths, JSON only).
494
540
 
495
541
  - `pnpm lint` — the gate. Four passes, in order:
496
- 1. `lint:types` — oxlint with `--type-aware` over `packages/ui/src`
542
+ 1. `lint:types` — oxlint with `--type-aware` over `packages/env/src`, `packages/tooling/src` and `packages/ui/src`
497
543
  2. `lint:code` — oxlint over everything, no type information
498
544
  3. `lint:css` — Stylelint over `**/*.css`
499
545
  4. `format:check` — `prettier --check .`
500
546
  - `pnpm lint:fix` — passes 1-3 with `--fix`: the type-aware oxlint invocation over
501
- `packages/ui/src`, the plain one over everything, then Stylelint. **Never** add
547
+ the same three folders, the plain one over everything, then Stylelint. **Never** add
502
548
  `--fix-suggestions`: it rewrites `a[i++]` to `a[i += 1]`, which is a different program.
503
549
  - `pnpm format` — `prettier --write .`
504
550
  - `pnpm typecheck` — `tsc`, and it must pass before you commit.
@@ -513,8 +559,7 @@ including on a fresh clone. Do not merge the two passes.
513
559
  Prettier config sets `proseWrap: "never"`, which would collapse every hand-wrapped
514
560
  paragraph — this file included — into a single line.
515
561
 
516
- **Commit hooks are installed by husky** on your first `pnpm install` (`prepare: "husky"`),
517
- and they need a `.git` directory, which `saasaloy init` creates for you:
562
+ **Commit hooks are installed by husky** on your first `pnpm install`, and they need a `.git` directory, which `saasaloy init` creates for you. The root `prepare` script is `husky && node packages/tooling/src/link-skills.ts`, so the same install also links every folder in `.agents/skills/` into `.claude/skills/`. pnpm skips `prepare` when an install changes nothing, so after you add a skill folder to a checkout that is already installed, run `pnpm skills:link`. The hooks:
518
563
 
519
564
  - `pre-commit` runs **lint-staged** over staged files only — oxlint `--fix`, Stylelint
520
565
  `--fix`, Prettier `--write`. It skips the type-aware pass on purpose: that one needs the
@@ -527,12 +572,32 @@ hook (which is also how you keep hooks out of CI).
527
572
 
528
573
  ## Testing Instructions
529
574
 
575
+ The block below states this project's testing mode, which `saasaloy.json` records under `testing.mode`. Change the mode with `saasaloy testing <off|tests-after|tdd>`, never by hand: the command rewrites the block and the file together. The `saasaloy-testing` skill says what each mode asks and which test each kind of change needs: a unit test, a route test, a seed slice or a Playwright spec. Once `auth` is installed with testing on, `apps/api/src/routes/auth.test.ts` is the route test to copy.
576
+
577
+ <!-- saasaloy:testing -->
578
+ Testing mode: `off`. This project ships no module tests, and `saasaloy add` writes none. Do not add tests unless the owner asks for them.
579
+
580
+ - Turn module tests on with `saasaloy testing tests-after`, or `saasaloy testing tdd` to work test-first.
581
+ <!-- /saasaloy:testing -->
582
+
530
583
  - Run type checking: `pnpm typecheck` (must pass before commits)
531
584
  - Run linting: `pnpm lint` (see above — it reports, `pnpm lint:fix` fixes)
532
585
  - Check formatting: `pnpm format:check`, or `pnpm format` to rewrite
533
586
  - Run the tests: `pnpm test`. It runs `turbo run test` (each workspace's own `test` script), then `vitest run` from the root, whose `vitest.config.ts` treats every workspace under `apps/*` and `packages/*` as a project. Write new tests for Vitest: put a `*.test.ts` file beside the code, and give the workspace a `vitest.config.ts` only when it needs setup of its own. Do not add a per-workspace `test` script that calls Vitest, or the file runs twice. `packages/env` is the exception: its tests run on `node --test` through its own `test` script, and the root config leaves it out.
587
+ - Run the browser suite: `pnpm e2e`, once `saasaloy add e2e` is installed. It is Playwright against the running apps, in `packages/e2e`. Run `pnpm e2e:install` once per machine first to download Chromium. The root `vitest.config.ts` leaves `packages/e2e` out, so `pnpm test` never collects a Playwright spec. The `saasaloy-e2e` skill covers adding a flow and reading a red run.
588
+ - `packages/tooling` tests run on Vitest through the root `vitest.config.ts`, like every other workspace. The workspace has a `typecheck` script and no `test` script, so `pnpm test` runs each file once.
534
589
  - Before you hand over UI work, run `pnpm dev`, load the pages you changed, and read the dev server's terminal output. Fix every error and warning it prints. A clean build does not prove a clean dev server.
535
590
 
591
+ ## Branches and Deploys
592
+
593
+ - **Deploy from `main`.** `pnpm deploy:production` starts only from a branch that `branches` in `packages/tooling/src/deploy.config.ts` allows: `main` and `hotfix-*` by default. Every other branch fails the branch gate.
594
+ - **A fix while `main` holds unreleased work goes on a `hotfix-<slug>` branch** cut from the last deploy tag: `git switch -c hotfix-<slug> "$(git describe --tags --match 'deploy-*' --abbrev=0)"`. Deploy from that branch, then merge it into `main` so the next deploy keeps the fix.
595
+ - **No long-lived production branch.** The newest deploy tag marks the commit that is live, so no branch has to.
596
+ - **Never move or delete a deploy tag.** Each successful deploy pushes an annotated `deploy-<UTC yyyymmdd-hhmm>` tag. `git log <tag>..main` lists what the next deploy ships, and a hotfix branches from the tag.
597
+ - **Release before you deploy.** `pnpm release` bumps the root `package.json` version, writes `CHANGELOG.md`, and pushes an annotated `v<version>` tag and a GitHub Release. The `v*` tag names the release, and the `deploy-*` tag records when it went live. A deploy from a commit that is not a release warns and still runs. Never move or delete a release tag, and never edit `version` by hand.
598
+ - **Merge a hotfix branch into `main`, never rebase it.** A rebase rewrites the commit its release tag names.
599
+ - **An agent deploys only after the owner says so in the same session.** It runs `pnpm deploy:production --dry-run` and reports first. The `saasaloy-deploy` skill is the procedure, and `docs/runbook-deploy.md` holds this project's own deploy steps.
600
+
536
601
  ## Boundaries
537
602
 
538
603
  ### ✅ Always Do
@@ -542,7 +607,9 @@ hook (which is also how you keep hooks out of CI).
542
607
  - Run `pnpm lint` and fix all errors
543
608
  - Give every new app or package a `clean` script backed by `rimraf` (see above)
544
609
  - Use TypeScript strict mode (no `any` without explicit reason)
545
- - Use workspace package names (`@repo/ui`, `@repo/tsconfig`) for imports
610
+ - Use workspace package names (`@repo/ui`, `@repo/config`, `@repo/tsconfig`) for imports
611
+ - Put a value you would otherwise write twice in `@repo/config`, and a per-deployment value in
612
+ `.env`/`.dev.vars` — see above
546
613
 
547
614
  ### ⚠️ Ask First
548
615
 
@@ -10,6 +10,21 @@ pnpm install
10
10
  pnpm dev # astro dev on apps/web
11
11
  ```
12
12
 
13
+ ## Test
14
+
15
+ ```sh
16
+ pnpm test # each workspace's own test script, then Vitest over apps/* and packages/*
17
+ ```
18
+
19
+ `saasaloy add e2e` adds a browser suite on top. It brings Playwright, four flows against the running apps, and two commands:
20
+
21
+ ```sh
22
+ pnpm e2e:install # download Chromium, once per machine
23
+ pnpm e2e # migrate and seed the database, start the apps, run the flows
24
+ ```
25
+
26
+ `pnpm test` never collects a Playwright spec, and `pnpm e2e` never collects a Vitest test.
27
+
13
28
  ## Deploy
14
29
 
15
30
  ```sh
@@ -56,7 +71,7 @@ Components land in `packages/ui/src/components/` as source you own and can edit.
56
71
 
57
72
  `apps/web/src/pages/index.astro` composes thirteen blocks from `packages/ui/src/blocks/`: `navbar`, `hero`, `logo-cloud`, `pain-points`, `how-it-works`, `feature-grid`, `showcase`, `audience`, `testimonials`, `pricing-table`, `faq`, `cta` and `footer`. The page ships describing Saasaloy itself, so it reads as a finished product on day one. You make it yours with two edits and no others:
58
73
 
59
- 1. **Rewrite the words** in `packages/ui/src/content/landing.ts`: every heading, link, price and icon name. The `saasaloy-landing-copy` skill drafts it from your product brief. The brand is `siteName` in `packages/ui/src/index.ts`, which `saasaloy-setup` sets.
74
+ 1. **Rewrite the words** in `packages/ui/src/content/landing.ts`: every heading, link, price and icon name. The `saasaloy-landing-copy` skill drafts it from your product brief. The brand is `app.name` in `packages/config/src/project.ts`, which `saasaloy-setup` sets and `siteName` re-exports.
60
75
  2. **Choose the sections** in `index.astro`. Each section is one import and one line.
61
76
 
62
77
  ### The section recipe
@@ -0,0 +1,131 @@
1
+ ---
2
+ name: saasaloy-config
3
+ description: Work with @repo/config — the values this project checks into its repo and ships identically to every environment. Use when a value needs a single home, when deciding whether something belongs in config or in .env, when adding a section for a capability, when a project override is not taking effect, or when the owner says "where do I change the product name", "where do I put this constant", "config or env".
4
+ ---
5
+
6
+ # saasaloy-config — one home for a checked-in value
7
+
8
+ `@repo/config` is a frozen plain object of values this project checks into its repo. Read it
9
+ with a plain import, from an app, a capability or a React island alike:
10
+
11
+ ```ts
12
+ import { config } from "@repo/config";
13
+
14
+ config.app.name;
15
+ config.app.locale;
16
+ config.auth.adminRole; // once `auth` is installed
17
+ ```
18
+
19
+ There is no factory, no `env` argument, no async and no I/O. The object is built once at
20
+ module load and frozen, so a bundler can inline it.
21
+
22
+ ## The rule: config or `.env`
23
+
24
+ - **`env`** owns a value the platform supplies per deployment, secret or not. A database
25
+ URL, an API origin, a Stripe key, a provider selection.
26
+ - **`config`** owns a value checked into the repo that is the same in every deployment. The
27
+ product name, the locale, a role string.
28
+
29
+ **The test.** Two deployments of *this* project — production and staging. If the value can
30
+ differ between them, it is `env`. If it cannot, it is `config`. A value that differs between
31
+ two *different* projects but not between one project's environments is `config`.
32
+
33
+ `packages/config` imports nothing, `@repo/env` included, so a section cannot read an env
34
+ var. A value derived from both channels is derived where it is used, not in a section file.
35
+
36
+ ## Not the landing copy
37
+
38
+ Everything on the landing page, prices and tier ids included, lives in
39
+ `packages/ui/src/content/landing.ts`, and `saasaloy-landing-copy` owns it. `config` holds
40
+ the facts more than one workspace reads: the product name, the locale, the legal paths, and
41
+ whatever an installed module's section adds.
42
+
43
+ ## The four files
44
+
45
+ | Path | Who owns it |
46
+ |------|-------------|
47
+ | `src/project.ts` | **You.** The only file here you are expected to edit. Nothing overwrites it. |
48
+ | `src/sections.ts` | The registry. `saasaloy add` patches one line into it; do not hand-edit the array. |
49
+ | `src/sections/<key>.ts` | The module that installed it (`app` belongs to the base template). |
50
+ | `src/define.ts` | The base template. The composition core. |
51
+
52
+ ## Changing a value
53
+
54
+ Edit `src/project.ts`. It is typed as a partial of the composed shape, so a key no
55
+ installed section defines is a `typecheck` error rather than a value nothing reads.
56
+
57
+ ```ts
58
+ export const project: ProjectOverride = {
59
+ app: { name: "Ledgerly", locale: "en-GB" },
60
+ };
61
+ ```
62
+
63
+ **The merge goes one level below the section, and no deeper.** `app: { name: "..." }`
64
+ replaces the name and keeps the rest of `app`. A nested record or an array is replaced
65
+ whole, so `app: { legal: { termsPath: "/legal/terms" } }` must also name `privacyPath`.
66
+
67
+ Run `pnpm typecheck` after an edit. That is the only validation there is: the values are
68
+ literals in this repo, so a wrong one is a review problem rather than a runtime one.
69
+
70
+ ## Adding a section
71
+
72
+ A capability contributes one section, keyed by the module name. The module ships one file
73
+ into `packages/config/src/sections/<key>.ts` and registers it with a `plugin-array` patch:
74
+
75
+ ```ts
76
+ // packages/config/src/sections/shop.ts
77
+ import { defineSection } from "@repo/config/define";
78
+
79
+ export function shopConfig() {
80
+ return defineSection("shop", {
81
+ defaultCurrency: "USD",
82
+ maxCartItems: 50,
83
+ });
84
+ }
85
+ ```
86
+
87
+ ```jsonc
88
+ // the module's registry-item.json
89
+ {
90
+ "file": "packages/config/src/sections.ts",
91
+ "kind": "plugin-array",
92
+ "exportName": "sections",
93
+ "arrayProp": "sections",
94
+ "call": "shopConfig",
95
+ "import": { "name": "shopConfig", "from": "./sections/shop" }
96
+ }
97
+ ```
98
+
99
+ Four rules:
100
+
101
+ - **The key is the module name**, flat, and unique. `saasaloy add` refuses two modules
102
+ claiming one key and names both, and the base's own `app` is taken; at runtime a
103
+ duplicate throws at module load. The file name and the key passed to `defineSection`
104
+ must match, and `add` refuses a section file where they differ.
105
+ - **The section file lives in `packages/config`, not in the capability.** `@repo/config` is
106
+ the leaf of the dependency graph — it imports nothing, so everything may import it,
107
+ including the capability whose values these are. A section inside the capability would
108
+ invert that and cycle.
109
+ - **Import the helper by subpath**, `@repo/config/define`, never by relative path.
110
+ - **A section never reads another section.** They are composed side by side. Apply a
111
+ fallback between two sections where the value is used, the way
112
+ `apps/api/src/billing-store.ts` does for `config.billing.appName || config.app.name`.
113
+
114
+ ## When an override does not take effect
115
+
116
+ 1. **The section is not installed.** `config.shop` only exists once `saasaloy add shop`
117
+ has patched `src/sections.ts`. Check the array.
118
+ 2. **You edited a section file, not `project.ts`.** A module-owned section file may be
119
+ rewritten by `saasaloy update`. Move the edit to `project.ts`.
120
+ 3. **You expected a deep merge.** One level below the section is the whole rule; a nested
121
+ record is replaced whole.
122
+ 4. **Something reads the value at build time.** A Node config file (`astro.config.mjs`,
123
+ `vite.config.ts`) is not part of the app graph and keeps its own literals on purpose.
124
+
125
+ ## What is not here
126
+
127
+ - **A runtime override channel.** A value that must change per deployment is an `env` value
128
+ by definition.
129
+ - **Schema validation.** `typecheck` is the gate.
130
+ - **A `<CAP>_PROVIDER` key.** Provider selection stays in `env`.
131
+ - **The dev ports.** 3000/3001/4000 are read by Node config files at build time.