saasaloy 0.6.0 → 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 (57) 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 +118 -63
  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-design/SKILL.md +21 -11
  14. package/templates/base/_agents/skills/saasaloy-env/SKILL.md +8 -7
  15. package/templates/base/_agents/skills/saasaloy-landing-copy/SKILL.md +10 -9
  16. package/templates/base/_agents/skills/saasaloy-setup/SKILL.md +30 -22
  17. package/templates/base/_agents/skills/saasaloy-testing/SKILL.md +85 -0
  18. package/templates/base/_gitignore +4 -0
  19. package/templates/base/_prettierignore +5 -0
  20. package/templates/base/_saasaloy-base.json +6 -2
  21. package/templates/base/apps/web/package.json +1 -0
  22. package/templates/base/apps/web/src/layouts/Layout.astro +2 -1
  23. package/templates/base/apps/web/src/pages/privacy.astro +2 -0
  24. package/templates/base/apps/web/src/pages/terms.astro +2 -0
  25. package/templates/base/docs/runbook-deploy.md +72 -0
  26. package/templates/base/oxlint.config.mjs +62 -0
  27. package/templates/base/package.json +7 -4
  28. package/templates/base/packages/config/package.json +19 -0
  29. package/templates/base/packages/config/src/define.test.ts +134 -0
  30. package/templates/base/packages/config/src/define.ts +135 -0
  31. package/templates/base/packages/config/src/index.ts +34 -0
  32. package/templates/base/packages/config/src/project.ts +25 -0
  33. package/templates/base/packages/config/src/sections/app.ts +27 -0
  34. package/templates/base/packages/config/src/sections.ts +22 -0
  35. package/templates/base/packages/config/tsconfig.json +4 -0
  36. package/templates/base/packages/env/package.json +2 -1
  37. package/templates/base/packages/env/src/deploy.ts +3 -2
  38. package/templates/base/packages/env/src/services.test.ts +27 -11
  39. package/templates/base/packages/tooling/package.json +21 -0
  40. package/templates/base/packages/tooling/src/deploy-production.test.ts +923 -0
  41. package/templates/base/packages/tooling/src/deploy-production.ts +1041 -0
  42. package/templates/base/packages/tooling/src/deploy.config.ts +30 -0
  43. package/templates/base/packages/tooling/src/link-skills.test.ts +126 -0
  44. package/templates/base/packages/tooling/src/link-skills.ts +142 -0
  45. package/templates/base/packages/tooling/src/release.test.ts +205 -0
  46. package/templates/base/packages/tooling/src/release.ts +228 -0
  47. package/templates/base/packages/tooling/src/targets.ts +38 -0
  48. package/templates/base/packages/tooling/src/types.ts +78 -0
  49. package/templates/base/packages/tooling/tsconfig.json +11 -0
  50. package/templates/base/packages/ui/package.json +4 -2
  51. package/templates/base/packages/ui/src/blocks/footer.tsx +5 -3
  52. package/templates/base/packages/ui/src/containers/README.md +6 -5
  53. package/templates/base/packages/ui/src/content/landing.ts +2 -4
  54. package/templates/base/packages/ui/src/index.ts +10 -5
  55. package/templates/base/saasaloy.json +2 -1
  56. package/templates/base/turbo.json +1 -5
  57. 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.0",
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,12 +125,46 @@ 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
- `packages/ui` owns the design layer: the Tailwind 4 theme in `src/styles/`, the `cn()`
126
- helper, the vendored [shadcn](https://ui.shadcn.com) primitives in `src/components/`, the
127
- marketing **blocks** in `src/blocks/`, the store-bound **containers** in
128
- `src/containers/`, and the landing page's copy in `src/content/`.
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/`.
129
168
 
130
169
  Those layer folders are the whole top level of `src/`: `assets` (images, SVGs and icons, added when the first one arrives), `blocks`, `components`, `containers`, `content`, `lib` and `styles`. Do not add an app folder such as `src/admin/` or `src/web/` beside them. When one app needs its own files inside a layer, give that layer a child folder (`blocks/admin/`, `components/shared/`).
131
170
 
@@ -153,36 +192,42 @@ that carries its own theme file gets its own `apps/<app>/DESIGN.md`, which finge
153
192
  that file. There is no `DESIGN.md` at the repository root. Read the document for the app
154
193
  you are changing before you add or change UI.
155
194
 
195
+ With the admin app installed, `apps/admin/DESIGN.md` records the admin tokens in `packages/ui/src/styles/admin.css` and fingerprints that file. A preset never targets `admin.css`; the admin theme changes by hand.
196
+
156
197
  Primitives, blocks and containers are reached by subpath — none is re-exported from the
157
198
  package root, so importing one never drags in the rest. The root export is project-wide
158
- constants only (`siteName`):
199
+ constants only (`siteName`, which re-exports `config.app.name`):
159
200
 
160
201
  ```ts
161
202
  import { siteName } from "@repo/ui";
162
203
  import { Button } from "@repo/ui/components/button";
163
204
  import { PricingTable } from "@repo/ui/blocks/pricing-table";
164
- import { CartSummary } from "@repo/ui/containers/cart-summary";
165
205
  import { landing, ui } from "@repo/ui/content/landing";
166
206
  import { cn } from "@repo/ui/lib/utils";
167
207
  ```
168
208
 
169
- **Three layers, split by state scope — not by "has state".**
209
+ **The admin app has its own primitive set.** `saasaloy add admin` writes it into `src/components/admin/`, with its blocks in `src/blocks/admin/` and its shell and layouts in `src/containers/admin/`. Admin code imports only those, and a lint rule makes a base primitive under `apps/admin/**` an error, because both sets have a `button` and the wrong one renders with no complaint:
210
+
211
+ ```ts
212
+ import { Button } from "@repo/ui/components/admin/button";
213
+ import { DataTable } from "@repo/ui/blocks/admin/data-table";
214
+ import { PageHeader } from "@repo/ui/blocks/admin/page-header";
215
+ import { PageLayout } from "@repo/ui/containers/admin/page-layout";
216
+ ```
217
+
218
+ The `saasaloy-admin` skill lists the whole set and how a page composes it.
170
219
 
171
- 1. **`src/components/`** — vendored shadcn primitives. No stores, no copy.
172
- 2. **`src/blocks/`** — compositions of primitives plus copy from the content module. Local
173
- state is allowed (an open accordion, a ticking clock). Importing a shared store is
174
- forbidden: a block takes its data as props and reports changes through callbacks, so
175
- every app — the Astro site, a React SPA's panels — can drive the same block from its own
176
- data source.
177
- 3. **`src/containers/`** — compositions that bind a shared store or cross-island state. A
178
- container subscribes, then wires data and callbacks into pure blocks. Containers are
179
- thin, app-flavored wiring; the visual weight stays in the blocks.
220
+ **Seven top-level folders, and no app folder at the root of `src/`.** A folder may hold `admin/`, `web/` or `shared/` children where one app owns the files, for example `src/blocks/admin/` or `src/containers/admin/`, which `saasaloy add admin` writes. A project without that app carries none of them.
180
221
 
181
- **One rule covers the whole package: no IO in `@repo/ui`.** No fetch, no persistence, no
182
- auth, in any of the three layers. Client-state stores (nanostores) live in `src/lib/` and
183
- are bound **only** in containers; the app that owns the data hydrates the store. When a
184
- store-shaped need shows up in a block, move the binding up to a container instead of
185
- importing the store in place.
222
+ 1. **`src/assets/`** holds images, SVGs and icons. The base ships no asset, so the folder does not exist until the first one lands, together with an `assets.d.ts` that types its imports.
223
+ 2. **`src/components/`** holds the vendored shadcn primitives, official and custom. No stores, no copy.
224
+ 3. **`src/blocks/`** holds compositions of primitives plus copy from the content module. Local state is allowed (an open accordion, a ticking clock). Importing a shared store is forbidden: a block takes its data as props and reports changes through callbacks, so every app can drive the same block from its own data source.
225
+ 4. **`src/containers/`** holds the shells and layouts that hold blocks and components on a page: an app shell, a page layout, a page frame. A container takes its data, its links and its callbacks as props. It imports no router and no session, so the app that owns them passes them in.
226
+ 5. **`src/content/`** holds copy, in one place for later translation.
227
+ 6. **`src/lib/`** holds utilities and the client-state stores.
228
+ 7. **`src/styles/`** holds the CSS files with the token variables.
229
+
230
+ **One rule covers the whole package: no IO in `@repo/ui`.** No fetch, no persistence, no auth, no router, in any layer. Client-state stores (nanostores) live in `src/lib/`; the app that owns the data hydrates the store and passes what a block needs as props. When a store-shaped need shows up in a block, move the binding up into the app instead of importing the store in place.
186
231
 
187
232
  **Adding a primitive the base doesn't vendor.** `shadcn` is already an exact-pinned
188
233
  dependency of `@repo/ui`, so reach it with `--filter … exec` — that runs in the package
@@ -375,8 +420,7 @@ The rules below are not stylistic — each one prevents a real failure:
375
420
  directly.
376
421
  - **A link that leaves the site opens a new tab.** Spread `externalLinkProps(href)` from `@repo/ui/lib/external-link` onto the anchor and render `newTabHint(href)` inside it. The href decides: an absolute URL gets `target="_blank"`, `rel="noopener noreferrer"` and a screen-reader hint, and a path or a same-page anchor stays in the tab. Do not write `target="_blank"` by hand.
377
422
  - **A value that waits on a request shows a skeleton.** Render the `Skeleton` primitive at the size the value will take until the response arrives, never a blank gap or a spinner. Add it with `pnpm --filter @repo/ui exec shadcn add skeleton` the first time a block needs it.
378
- - **A block never imports a store either.** Local state is fine; shared state is not. See
379
- the containers section below.
423
+ - **A block never imports a store either.** Local state is fine; shared state is not. The app-side island reads the store and passes the values and the handlers down, the same pattern it uses for `onSubmit`.
380
424
  - **A module's UI arrives here too, and you wire it up by hand.** `saasaloy add <module>`
381
425
  writes a UI-bearing module's block into `src/blocks/` exactly like the base blocks, adds
382
426
  the app-side island that feeds it, and then stops: nothing globs a folder, and no command
@@ -387,33 +431,22 @@ The rules below are not stylistic — each one prevents a real failure:
387
431
 
388
432
  Blocks, like primitives, are source you own — they are meant to be edited, not wrapped.
389
433
 
390
- **Containers — the store bindings.** `src/containers/` holds the compositions that read
391
- shared state. The base ships none; the folder carries a note until you add your first.
392
-
393
- - **A container subscribes, a block renders.** The container reads the store, passes the
394
- values down as props, and passes handlers that write back to the store. It adds no markup
395
- a block could hold. If a container grows layout and copy, that part belongs in a block.
396
- - **The store lives in `src/lib/`, and only a container imports it.** A block that imports
397
- a store is a block a second app cannot reuse, because the store now decides where its data
398
- comes from. Move the binding up.
399
- - **Still no IO.** A container reads client state; it does not fetch, persist, or
400
- authenticate. The app hydrates the store — the same app-side island pattern the blocks use
401
- for `onSubmit`.
402
- - **Same file rules as blocks:** one container, one file, one component export, semantic
403
- kebab-case filename, no barrel. Astro gives every `client:*` component its own React root,
404
- so a container that a page hydrates must hold the whole composition.
405
- - **A container almost always needs a client directive.** It subscribes at runtime, so it
406
- ships JavaScript by definition. Pick the cheapest one that works (`client:idle` above the
407
- fold, `client:visible` below it), and keep the blocks it renders static in every page that
408
- does not need the store.
434
+ **Containers — the shells and the layouts.** `src/containers/` holds the compositions that place blocks and components on a page: an app shell, a page layout, a page frame. The base ships none; `saasaloy add admin` writes the admin app's into `src/containers/admin/`.
435
+
436
+ - **A container places, a block renders.** It decides where the panels, the header and the detail view go, and it adds no copy a block could hold.
437
+ - **No router, no session.** A container takes the nav data, the current area, a link component and the account as props. The app reads its router and its session and passes them in, so a container never depends on one app's routes.
438
+ - **Still no IO.** A container does not fetch, persist, or authenticate.
439
+ - **Same file rules as blocks:** one container per file, semantic kebab-case filename, no barrel.
409
440
 
410
441
  **The content module — where the words live.** `packages/ui/src/content/landing.ts` holds
411
442
  every user-visible string on the landing page, in two namespaces:
412
443
 
413
444
  - **`landing.*`** — marketing copy. What the product is, who it is for, what it costs.
414
- This is the whole surface a copy rewrite touches. The brand itself is not here: `siteName`
415
- lives in `packages/ui/src/index.ts`, is not translated, and is set once by
416
- `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.
417
450
  - **`ui.*`** — chrome and accessibility labels (`Monthly`, `Most popular`, `Close menu`,
418
451
  `Billing period`). Nothing here says anything about the product, so a copy pass never
419
452
  rewrites it. It does get translated, key for key, when `landing.*` is written in some
@@ -462,27 +495,29 @@ the theme toggle's labels deliberately stay in `packages/ui/src/lib/theme.ts`: t
462
495
  inlined verbatim into a pre-paint `<script>` and is import-free on purpose.
463
496
 
464
497
  **The default copy is Saasaloy's own.** A fresh project's page describes Saasaloy, and
465
- `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
466
499
  words agree until you replace both. The two skills below replace them in one pass.
467
500
 
468
- **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
469
502
  `.claude/skills/`, real files in `.agents/skills/`). The first two run in order:
470
503
 
471
504
  1. **`saasaloy-setup`** asks ten questions about the product — starting with its name — and
472
505
  writes the answers to `docs/product-brief.md`. Every question carries sample answers you
473
- 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
474
507
  reads your product knowledge out of your head, so run it first; other skills read the
475
508
  brief rather than interviewing you again.
476
509
  2. **`saasaloy-landing-copy`** turns that brief into the landing page's words. It drafts
477
510
  into `docs/landing-copy-draft.md` for you to review and edit, then writes
478
511
  `packages/ui/src/content/landing.ts` once you approve, then deletes the draft.
479
512
 
480
- 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:
481
514
 
482
- 3. **`saasaloy-design`** keeps `apps/web/DESIGN.md` true. Its `theme` flow swaps the
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
483
516
  preset and re-derives the contract; `update` re-derives after you change `web.css` or
484
517
  add components; `audit` reports where the code and the contract disagree. It reads the
485
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.
486
521
 
487
522
  Invoke them rather than editing thirteen blocks by hand — and if you do edit by hand, keep the
488
523
  strings in the content module so the next pass finds them.
@@ -504,12 +539,12 @@ owning formatting. All four run from `oxlint.config.mjs`, `prettier.config.js` a
504
539
  cannot consume one (`extends` takes file paths, JSON only).
505
540
 
506
541
  - `pnpm lint` — the gate. Four passes, in order:
507
- 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`
508
543
  2. `lint:code` — oxlint over everything, no type information
509
544
  3. `lint:css` — Stylelint over `**/*.css`
510
545
  4. `format:check` — `prettier --check .`
511
546
  - `pnpm lint:fix` — passes 1-3 with `--fix`: the type-aware oxlint invocation over
512
- `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
513
548
  `--fix-suggestions`: it rewrites `a[i++]` to `a[i += 1]`, which is a different program.
514
549
  - `pnpm format` — `prettier --write .`
515
550
  - `pnpm typecheck` — `tsc`, and it must pass before you commit.
@@ -524,8 +559,7 @@ including on a fresh clone. Do not merge the two passes.
524
559
  Prettier config sets `proseWrap: "never"`, which would collapse every hand-wrapped
525
560
  paragraph — this file included — into a single line.
526
561
 
527
- **Commit hooks are installed by husky** on your first `pnpm install` (`prepare: "husky"`),
528
- 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:
529
563
 
530
564
  - `pre-commit` runs **lint-staged** over staged files only — oxlint `--fix`, Stylelint
531
565
  `--fix`, Prettier `--write`. It skips the type-aware pass on purpose: that one needs the
@@ -538,23 +572,44 @@ hook (which is also how you keep hooks out of CI).
538
572
 
539
573
  ## Testing Instructions
540
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
+
541
583
  - Run type checking: `pnpm typecheck` (must pass before commits)
542
584
  - Run linting: `pnpm lint` (see above — it reports, `pnpm lint:fix` fixes)
543
585
  - Check formatting: `pnpm format:check`, or `pnpm format` to rewrite
544
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.
545
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.
546
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
+
547
601
  ## Boundaries
548
602
 
549
603
  ### ✅ Always Do
550
604
 
551
- - Read the app's `DESIGN.md` (`apps/web/DESIGN.md` for the web app) before writing or
552
- changing UI
605
+ - Read the app's `DESIGN.md` (`apps/web/DESIGN.md` for the web app, `apps/admin/DESIGN.md` for the admin app) before writing or changing UI
553
606
  - Run `pnpm typecheck` before committing code changes
554
607
  - Run `pnpm lint` and fix all errors
555
608
  - Give every new app or package a `clean` script backed by `rimraf` (see above)
556
609
  - Use TypeScript strict mode (no `any` without explicit reason)
557
- - 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
558
613
 
559
614
  ### ⚠️ Ask First
560
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