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.
- package/README.md +7 -7
- package/dist/index.js +3952 -1899
- package/dist/index.js.map +1 -1
- package/package.json +2 -1
- package/schemas/manifest.schema.json +32 -1
- package/schemas/registry-item.schema.json +57 -2
- package/schemas/saasaloy-lock.schema.json +9 -0
- package/schemas/saasaloy.schema.json +12 -0
- package/templates/base/AGENTS.md +118 -63
- package/templates/base/README.md +16 -1
- package/templates/base/_agents/skills/saasaloy-config/SKILL.md +131 -0
- package/templates/base/_agents/skills/saasaloy-deploy/SKILL.md +280 -0
- package/templates/base/_agents/skills/saasaloy-design/SKILL.md +21 -11
- package/templates/base/_agents/skills/saasaloy-env/SKILL.md +8 -7
- package/templates/base/_agents/skills/saasaloy-landing-copy/SKILL.md +10 -9
- package/templates/base/_agents/skills/saasaloy-setup/SKILL.md +30 -22
- package/templates/base/_agents/skills/saasaloy-testing/SKILL.md +85 -0
- package/templates/base/_gitignore +4 -0
- package/templates/base/_prettierignore +5 -0
- package/templates/base/_saasaloy-base.json +6 -2
- package/templates/base/apps/web/package.json +1 -0
- package/templates/base/apps/web/src/layouts/Layout.astro +2 -1
- package/templates/base/apps/web/src/pages/privacy.astro +2 -0
- package/templates/base/apps/web/src/pages/terms.astro +2 -0
- package/templates/base/docs/runbook-deploy.md +72 -0
- package/templates/base/oxlint.config.mjs +62 -0
- package/templates/base/package.json +7 -4
- package/templates/base/packages/config/package.json +19 -0
- package/templates/base/packages/config/src/define.test.ts +134 -0
- package/templates/base/packages/config/src/define.ts +135 -0
- package/templates/base/packages/config/src/index.ts +34 -0
- package/templates/base/packages/config/src/project.ts +25 -0
- package/templates/base/packages/config/src/sections/app.ts +27 -0
- package/templates/base/packages/config/src/sections.ts +22 -0
- package/templates/base/packages/config/tsconfig.json +4 -0
- package/templates/base/packages/env/package.json +2 -1
- package/templates/base/packages/env/src/deploy.ts +3 -2
- package/templates/base/packages/env/src/services.test.ts +27 -11
- package/templates/base/packages/tooling/package.json +21 -0
- package/templates/base/packages/tooling/src/deploy-production.test.ts +923 -0
- package/templates/base/packages/tooling/src/deploy-production.ts +1041 -0
- package/templates/base/packages/tooling/src/deploy.config.ts +30 -0
- package/templates/base/packages/tooling/src/link-skills.test.ts +126 -0
- package/templates/base/packages/tooling/src/link-skills.ts +142 -0
- package/templates/base/packages/tooling/src/release.test.ts +205 -0
- package/templates/base/packages/tooling/src/release.ts +228 -0
- package/templates/base/packages/tooling/src/targets.ts +38 -0
- package/templates/base/packages/tooling/src/types.ts +78 -0
- package/templates/base/packages/tooling/tsconfig.json +11 -0
- package/templates/base/packages/ui/package.json +4 -2
- package/templates/base/packages/ui/src/blocks/footer.tsx +5 -3
- package/templates/base/packages/ui/src/containers/README.md +6 -5
- package/templates/base/packages/ui/src/content/landing.ts +2 -4
- package/templates/base/packages/ui/src/index.ts +10 -5
- package/templates/base/saasaloy.json +2 -1
- package/templates/base/turbo.json +1 -5
- 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.
|
|
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.",
|
package/templates/base/AGENTS.md
CHANGED
|
@@ -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
|
|
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
|
-
**
|
|
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
|
-
|
|
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
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
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.
|
|
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
|
|
391
|
-
|
|
392
|
-
|
|
393
|
-
- **A container
|
|
394
|
-
|
|
395
|
-
|
|
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:
|
|
415
|
-
|
|
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
|
-
`
|
|
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.**
|
|
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 `
|
|
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
|
|
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
|
-
|
|
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`
|
|
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
|
|
package/templates/base/README.md
CHANGED
|
@@ -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 `
|
|
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
|