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
@@ -1,17 +1,17 @@
1
1
  ---
2
2
  name: saasaloy-setup
3
- description: Interview the project owner about their product once, and write the answers to docs/product-brief.md — the shared context every other Saasaloy skill reads. Use at the start of a freshly scaffolded project, when the owner says "set up this project", "tell you about my product", "what is this project", when siteName is still the scaffold's directory name, when another skill needs product context and no brief exists yet, and when re-running to update the brief after something changed.
3
+ description: Interview the project owner about their product once, and write the answers to docs/product-brief.md — the shared context every other Saasaloy skill reads. Use at the start of a freshly scaffolded project, when the owner says "set up this project", "tell you about my product", "what is this project", when config.app.name is still the shipped "Saasaloy", when another skill needs product context and no brief exists yet, and when re-running to update the brief after something changed.
4
4
  ---
5
5
 
6
6
  # saasaloy-setup — find out what this project is, once
7
7
 
8
- A scaffolded project knows nothing about the product it is going to become. Its name is a
9
- directory name, its language is English because nobody asked, and every skill that follows
8
+ A scaffolded project knows nothing about the product it is going to become. Its name is
9
+ `Saasaloy`, because the shipped landing page describes Saasaloy itself, its language is English because nobody asked, and every skill that follows
10
10
  has to either interview the owner again or guess.
11
11
 
12
12
  So this skill asks once and writes the answers down. The deliverable is
13
- **`docs/product-brief.md`**, plus the two facts that are code rather than prose: `siteName`
14
- and the page's `lang` attribute.
13
+ **`docs/product-brief.md`**, plus the two facts that are code rather than prose: the
14
+ product's name and its locale. Both live in one file, `packages/config/src/project.ts`.
15
15
 
16
16
  It writes no copy. `saasaloy-landing-copy` does that, from the brief this leaves behind.
17
17
 
@@ -20,8 +20,7 @@ It writes no copy. `saasaloy-landing-copy` does that, from the brief this leaves
20
20
  | Path | What you change |
21
21
  |------|-----------------|
22
22
  | `docs/product-brief.md` | The whole file. Create `docs/` if it does not exist. |
23
- | `packages/ui/src/index.ts` | `siteName` — the brand constant, and nothing else in the file. |
24
- | `apps/web/src/layouts/Layout.astro` | The `lang` attribute only, and only when it differs from the brief's language code. |
23
+ | `packages/config/src/project.ts` | `app.name` and `app.locale`, and nothing else in the file. |
25
24
 
26
25
  Nothing else. You are not here to write the landing page, add a dependency, or touch a
27
26
  block.
@@ -30,9 +29,10 @@ block.
30
29
 
31
30
  1. **Read `docs/product-brief.md`.** If it exists, someone has already been through this.
32
31
  Read it fully and jump to [Re-running](#re-running).
33
- 2. **Read `packages/ui/src/index.ts`** for the current `siteName`. `saasaloy init` sets it
34
- to the directory name, so it is usually a slug like `my-saas` rather than a brand. It is
35
- still the best opening guess you have, and it belongs in question 1's samples.
32
+ 2. **Read `packages/config/src/project.ts`** for the current `app.name`. It ships
33
+ commented out, so the name is still the base's `"Saasaloy"` until someone sets it. When
34
+ it is set, it is the best opening guess you have, and it belongs in question 1's
35
+ samples. The project's directory name is the next best guess.
36
36
  3. **Look at git, and treat it as advice.** `git status --short` if there is a repo. A dirty
37
37
  tree or no repo at all is worth one sentence — "your changes aren't committed, so you
38
38
  can't undo this with git; every write here is previewed and confirmed anyway" — and then
@@ -218,20 +218,27 @@ Two rules about this file:
218
218
 
219
219
  ## Step 3 — set the two facts that are code
220
220
 
221
- Show the change and confirm it, one file at a time.
222
-
223
- 1. **`siteName`** in `packages/ui/src/index.ts`. This is the brand as it appears in the
224
- header, the footer and the browser tab. It is not translated, and it is the only thing
225
- in that file you may edit.
226
- 2. **`lang`** in `apps/web/src/layouts/Layout.astro`. Set it to the brief's language code
227
- whenever the attribute differs from it, including back to `en` on a re-run that returns
228
- to English. It ships hardcoded as `en`. Getting this wrong tells screen readers to
229
- pronounce Bangla with English phonetics.
221
+ Both are leaves of the `app` section in `packages/config/src/project.ts`, the one file in
222
+ `packages/config` a project owner edits. Show the change and confirm it.
223
+
224
+ 1. **`app.name`** — the brand as it appears in the header, the footer, the browser tab and
225
+ every email. `siteName` in `@repo/ui` re-exports it, so nothing else needs editing. It
226
+ is not translated. It ships commented out: uncomment the line and set it.
227
+ 2. **`app.locale`** — the brief's language code. `apps/web`'s shared layout reads it as
228
+ `<html lang>`. Set it whenever it differs from the brief, including back to `en` on a
229
+ re-run that returns to English. Getting this wrong tells screen readers to pronounce
230
+ Bangla with English phonetics.
231
+
232
+ ```ts
233
+ export const project: ProjectOverride = {
234
+ app: { name: "Ledgerly", locale: "en-GB" },
235
+ };
236
+ ```
230
237
 
231
- Then check it still builds, because both files are imported by the page:
238
+ Then check it still builds, because every page reads that object:
232
239
 
233
240
  ```sh
234
- pnpm --filter @repo/ui typecheck
241
+ pnpm typecheck
235
242
  pnpm build
236
243
  ```
237
244
 
@@ -252,7 +259,8 @@ A brief on disk means the interview already happened.
252
259
  Say so explicitly when you finish, because the brief on its own changes nothing the owner
253
260
  can see:
254
261
 
255
- > The brief is at `docs/product-brief.md` and `siteName` is set. Run
262
+ > The brief is at `docs/product-brief.md` and the product's name is set in
263
+ > `packages/config/src/project.ts`. Run
256
264
  > `/saasaloy-landing-copy` and it will write the landing page from this, as a markdown
257
265
  > draft you review before anything touches the site.
258
266
 
@@ -0,0 +1,85 @@
1
+ ---
2
+ name: saasaloy-testing
3
+ description: Pick the test a change needs and write it the way this project's testing mode asks. Use when the AGENTS.md testing block says tests-after or tdd, when adding or changing a route, a pure function, a provider, a table or a user-visible flow, when the owner asks "which test do I write", "how do I test this route", "turn TDD on", or when deciding whether a change needs a test at all.
4
+ ---
5
+
6
+ # saasaloy-testing — which test a change needs
7
+
8
+ This project records one testing mode in `saasaloy.json`, under `testing.mode`. Read it before you write code. An absent key reads as `off`.
9
+
10
+ | Mode | What it asks of you |
11
+ | --- | --- |
12
+ | `off` | The project ships no module tests, and `saasaloy add` writes none. Write a test only when the owner asks for one. |
13
+ | `tests-after` | Every change ships with its test, written once the code works. Run `pnpm test` before you hand the change over. It must pass. |
14
+ | `tdd` | Write the test first, one behaviour at a time, in the loop below. Run `pnpm test` before you hand the change over. |
15
+
16
+ The marked block under "Testing Instructions" in the root `AGENTS.md` states the same mode. Change the mode with `saasaloy testing <off|tests-after|tdd>`, never by editing either file. The command rewrites `saasaloy.json` and the block together. `saasaloy testing` with no argument prints the mode.
17
+
18
+ Turning testing on also brings in the tests the installed modules ship, such as `apps/api/src/routes/auth.test.ts`. Turning it off deletes nothing.
19
+
20
+ ## The TDD loop
21
+
22
+ 1. Write one failing test for the next behaviour. The table below says which kind.
23
+ 2. Run that one file, and see it fail for the reason you stated. A test that fails on an import error has not tested anything yet.
24
+ 3. Write the code that makes it pass, and no more.
25
+ 4. Run the file again, and see it pass.
26
+
27
+ Write no code that a failing test did not ask for. Run one file while you work (`pnpm vitest run <path>`), and the whole `pnpm test` once at the end.
28
+
29
+ ## Which test a change needs
30
+
31
+ | The change | Its test | Where it goes |
32
+ | --- | --- | --- |
33
+ | Pure logic: a parser, a price rule, a formatter | A unit test | `<name>.test.ts` beside the file |
34
+ | An api route | A route test with `testDatabase()`, four cases | `apps/api/src/routes/<route>.test.ts` |
35
+ | A provider behind a capability | The capability's contract suite | Not shipped yet, see below |
36
+ | A new table | A seed slice | `packages/db/src/seed/slices/<table>.ts` |
37
+ | A user-visible flow | A Playwright spec | `packages/e2e/specs/<feature>-<journey>.spec.ts`, once `e2e` is installed |
38
+
39
+ Every Vitest file is a `*.test.ts` beside its code. The root `vitest.config.ts` collects it, so a workspace needs no `test` script of its own.
40
+
41
+ ### A unit test
42
+
43
+ Test the function through its inputs and outputs. Import it, call it, assert on what it returns. Mock nothing the function owns. A function that needs a database or a request is a route, not a unit.
44
+
45
+ ### A route test
46
+
47
+ Copy `apps/api/src/routes/auth.test.ts`, which the `auth` module ships. It shows the whole shape:
48
+
49
+ - `const database = testDatabase();` from `@repo/db/testing`, once at the top of the file.
50
+ - `app.request(path, init, database.env)` to call the route, with `app` imported from `../index`.
51
+ - `database.db` to look behind the route at the rows it wrote.
52
+ - A seeded user signed in through `/auth/sign-in/email` for a session cookie. Every seed user signs in with `saasaloy-dev-password`, and `seedId("users", "<slug>")` from `@repo/db/seed/id` gives its id.
53
+
54
+ Each test starts from the seed, and nothing a test writes reaches the next one. Cover four cases for every route:
55
+
56
+ 1. Success: the right caller gets the right answer, and the rows changed as they should.
57
+ 2. `401` with no session cookie.
58
+ 3. `403` for the wrong tenant or the wrong role: a signed-in user who must not see or change this record.
59
+ 4. One `400` for bad input.
60
+
61
+ A public route has no `401` or `403` case. Say so in a comment, and keep the other two.
62
+
63
+ The test database needs the database driver's setup. Read the `saasaloy-database-d1` or `saasaloy-database-postgres` skill, "Route tests", when `testDatabase()` refuses to start.
64
+
65
+ ### A provider
66
+
67
+ Each capability with providers (`email`, `sms`, `queue`, `kv`, `storage`, `payment`, `logger`) is to get a contract suite: one shared set of tests that every provider of that capability must pass. The contract suites are not shipped yet. Until they arrive, test a new provider with unit tests on its own mapping: the vendor error codes it turns into the capability's error codes, and the `retryable` flag on each one.
68
+
69
+ ### A new table
70
+
71
+ A table's test is its seed slice. Add `packages/db/src/seed/slices/<table-in-kebab-case>.ts` in the same change as the table, with one row for each state the UI shows differently, or `rows: {}` for a table that stays empty. `packages/db/src/seed/completeness.test.ts` fails naming every table that has no slice. The `saasaloy-database` skill, "Seed data", has the slice contract.
72
+
73
+ A route test reads the seed, so the slice is also what the route test for the table starts from.
74
+
75
+ ### A user-visible flow
76
+
77
+ A flow a person clicks through gets a Playwright spec in `packages/e2e/specs/`, named `<feature>-<journey>.spec.ts`, and tagged with every module it needs. The `saasaloy-e2e` skill covers the tags, the seeded admin and a red run. `pnpm test` never runs a spec; `pnpm e2e` does.
78
+
79
+ The module that owns the feature owns its spec. A module ships its journey spec only while `e2e` is installed, so `saasaloy add e2e` brings the specs of the modules already present. A journey that crosses three or more features goes in its own spec named for the journey.
80
+
81
+ Without `e2e` installed, write no spec. Tell the owner that `saasaloy add e2e` adds the browser suite.
82
+
83
+ ## What needs no test
84
+
85
+ A change with no behaviour: a type, a copy string in `packages/ui/src/content/landing.ts`, a style, a config value. Say in the hand-over that it has no test and why.
@@ -5,6 +5,10 @@ dist/
5
5
  .wrangler/
6
6
  *.tsbuildinfo
7
7
 
8
+ # Playwright output. `saasaloy add e2e` writes both under packages/e2e/.
9
+ playwright-report/
10
+ test-results/
11
+
8
12
  # Logs
9
13
  *.log
10
14
  npm-debug.log*
@@ -23,6 +23,11 @@ saasaloy-lock.json
23
23
  # patcher does not emit — leaving `pnpm lint` red after every binding a module adds.
24
24
  **/wrangler.jsonc
25
25
 
26
+ # The TanStack Router plugin writes routeTree.gen.ts on every build. Its generator options
27
+ # already match Prettier's style, but the file is generated output, so a format pass must
28
+ # never touch it and a build must never fight a format pass.
29
+ **/routeTree.gen.ts
30
+
26
31
  # Build output and dependencies.
27
32
  **/node_modules
28
33
  **/dist
@@ -4,7 +4,9 @@
4
4
  "README.md",
5
5
  "saasaloy.json",
6
6
  "apps/web/src/pages/index.astro",
7
- "packages/ui/src/content/landing.ts"
7
+ "packages/ui/src/content/landing.ts",
8
+ "docs/runbook-deploy.md",
9
+ "packages/config/src/project.ts"
8
10
  ],
9
11
  "retiredSeedFiles": ["DESIGN.md"],
10
12
  "ownedFiles": [
@@ -21,6 +23,8 @@
21
23
  "packages/ui/src/index.ts",
22
24
  "packages/ui/src/lib/icons.ts",
23
25
  "apps/web/src/layouts/Layout.astro",
24
- "apps/web/public/favicon.*"
26
+ "apps/web/public/favicon.*",
27
+ "packages/tooling/src/deploy.config.ts",
28
+ "packages/tooling/src/targets.ts"
25
29
  ]
26
30
  }
@@ -16,6 +16,7 @@
16
16
  "@astrojs/react": "7.0.0",
17
17
  "react": "19.3.0",
18
18
  "react-dom": "19.3.0",
19
+ "@repo/config": "workspace:*",
19
20
  "@repo/env": "workspace:*",
20
21
  "@repo/ui": "workspace:*"
21
22
  },
@@ -3,6 +3,7 @@
3
3
  // import of the web theme, so a page is only ever its own content — no page may
4
4
  // duplicate the shell or import a stylesheet again. web.css imports the shared
5
5
  // globals.css itself.
6
+ import { config } from "@repo/config";
6
7
  import "@repo/ui/styles/web.css";
7
8
  import { siteName } from "@repo/ui";
8
9
  import { ui } from "@repo/ui/content/landing";
@@ -23,7 +24,7 @@ const canonical = new URL(Astro.url.pathname, webEnv().PUBLIC_SITE_URL).href;
23
24
  ---
24
25
 
25
26
  <!doctype html>
26
- <html lang="en">
27
+ <html lang={config.app.locale}>
27
28
  <head>
28
29
  <meta charset="utf-8" />
29
30
  <meta name="viewport" content="width=device-width, initial-scale=1" />
@@ -1,4 +1,6 @@
1
1
  ---
2
+ // This file's name is the route. `config.app.legal.privacyPath` is what the footer links, so rename
3
+ // this page and that value in the same edit, or the link 404s.
2
4
  import { siteName } from "@repo/ui";
3
5
  import Layout from "../layouts/Layout.astro";
4
6
  ---
@@ -1,4 +1,6 @@
1
1
  ---
2
+ // This file's name is the route. `config.app.legal.termsPath` is what the footer links, so rename
3
+ // this page and that value in the same edit, or the link 404s.
2
4
  import { siteName } from "@repo/ui";
3
5
  import Layout from "../layouts/Layout.astro";
4
6
  ---
@@ -0,0 +1,72 @@
1
+ # Runbook: deploy {{PROJECT_NAME}} to production
2
+
3
+ This file belongs to the project. `saasaloy init` wrote it once, and `saasaloy update` never writes it again. Fill in each section marked "Fill in" for this project, and keep it true as production changes.
4
+
5
+ The general flow lives in the `saasaloy-deploy` skill (`.agents/skills/saasaloy-deploy/SKILL.md`): the go-ahead rule for agents, the release, the gates and what clears each one, `--migrate`, `--skip-ci` and `--only`, the hotfix branch and the Worker rollback. This runbook holds what only this project knows.
6
+
7
+ ## Commands
8
+
9
+ Each deploy is two steps: `pnpm release`, then `pnpm deploy:production`. The release tags the commit `v<version>` and writes its `CHANGELOG.md` entry. The deploy names that version in its `deploy-*` tag.
10
+
11
+ | Command | What it does |
12
+ | --- | --- |
13
+ | `pnpm release:dry` | Prints the next version and the changelog entry. Changes nothing. |
14
+ | `pnpm release` | Bumps the root `package.json` version, writes `CHANGELOG.md`, commits `chore(release): v<version>`, tags `v<version>`, pushes, and creates a GitHub Release. `pnpm release minor`, `major` or `<version>` picks the bump. |
15
+ | `pnpm deploy:production --dry-run` | Prints the last deploy tag, the commits since it, every gate, the deploy order and the smoke checks, and runs the env check. Builds, uploads, migrates and tags nothing. |
16
+ | `pnpm deploy:production` | The gates, the env check, every Worker in order, the smoke checks, then the deploy tag. |
17
+ | `pnpm deploy:production --migrate` | The same, with the production migration before the first Worker. |
18
+ | `pnpm deploy:production --skip-ci "<reason>"` | Passes the CI gate when GitHub Actions is down. The reason goes into the tag message. |
19
+ | `pnpm deploy:production --only <service>` | One Worker and its smoke checks, after the gates. Writes no tag. |
20
+ | `git describe --tags --match 'deploy-*' --abbrev=0` | Names the last deploy, which is what is live. |
21
+ | `git log <tag>..main` | Lists what the next deploy ships. |
22
+ | `git describe --tags --match 'v*' --abbrev=0` | Names the last release. |
23
+
24
+ With a database module installed, `pnpm db:prod:dump` takes a dump into `~/<project>-backups/` (or `DB_DUMP_DIR`), and `pnpm db:prod:migrate` runs the production migration. `pnpm deploy:production --migrate` calls the second one for you.
25
+
26
+ ## Production
27
+
28
+ Fill in: one row per Worker, from `DEPLOY_TARGETS` in `packages/tooling/src/targets.ts`.
29
+
30
+ | Worker | Workspace | Address | What it is |
31
+ | --- | --- | --- | --- |
32
+ | `{{PROJECT_NAME}}-web` | `apps/web` | `https://<host>` | Astro site |
33
+
34
+ A smoke check runs only against a `custom_domain: true` route in the Worker's `wrangler.jsonc`. List each host here once its route is in place.
35
+
36
+ ## Hosting
37
+
38
+ Fill in: where each part of production runs and who has access.
39
+
40
+ - The Cloudflare account, and the zone each host sits on.
41
+ - The database, when the project has one: where it runs, its name (`<project>_production` for Postgres), and how a deploy machine reaches it.
42
+ - The value source for production values: `packages/env/.env.prod` on which machine, or the secrets manager. Name where its only copy is kept.
43
+ - Who may deploy, and from which machine.
44
+
45
+ ## The first deploy
46
+
47
+ Fill in: the steps this project took for its first deploy, as a record. Every deploy after it follows the `saasaloy-deploy` skill.
48
+
49
+ A starting order:
50
+
51
+ 1. Fill `packages/env/.env.prod`, or the production environment of the value source, and run `pnpm deploy:production --dry-run` until the env check passes.
52
+ 2. With a database: `pnpm db:prod:dump` on the empty database, to prove the backup path before there is anything to lose.
53
+ 3. Add a `custom_domain` route to each Worker that has a production host, so the smoke checks run.
54
+ 4. Commit, push, run `pnpm release` (the first release is `v0.1.0`, and its changelog entry covers every commit so far), then `pnpm deploy:production --migrate`. With no deploy tag yet, every migration file counts as new, so the first deploy with a database needs `--migrate`.
55
+ 5. Check each production host in a browser, including sign-in when the project has it.
56
+
57
+ ## Restore data from a dump
58
+
59
+ Fill in and test this before you rely on it. A code rollback does not undo a migration, and a restore loses every write since the dump was taken. Only the owner decides on a restore.
60
+
61
+ - Postgres: `db:prod:dump` and `db:prod:migrate` write a `pg_dump --format=custom` file named `<project>_production-<UTC time>.dump`. Restore it with `pg_restore --clean --if-exists --single-transaction`, through `pnpm --filter @repo/db exec env-deploy --run api -- <command>` so `DATABASE_URL` is the production value. Write the exact command for this project here.
62
+ - D1: `db:prod:dump` writes a SQL file. Restore it with `wrangler d1 execute <database_name> --remote --file <dump>`, or roll the database back in place with D1 Time Travel (`wrangler d1 time-travel restore`).
63
+
64
+ After a restore, roll the api back to the version that matches that schema.
65
+
66
+ ## Hotfix releases
67
+
68
+ A hotfix branch makes its own patch release, such as `v0.3.1`. Merging it back into `main` after `main` has released conflicts in `CHANGELOG.md` and in the root `package.json` `version`: keep both changelog entries and the higher version. The `saasaloy-deploy` skill has the steps. This path has not run on a real project yet, so write down what happened here the first time.
69
+
70
+ ## When something fails
71
+
72
+ Fill in: the failures this project has met in production, each with its cause and its fix.
@@ -42,6 +42,18 @@ function mergePresets(...presets) {
42
42
 
43
43
  const ultracite = mergePresets(core, astro, react, vitest);
44
44
 
45
+ // Every rule the vitest preset turns on, mapped to "off". The preset's file glob is
46
+ // `**/*.{test,spec,…}`, which also matches the Playwright specs `saasaloy add e2e` puts in
47
+ // `packages/e2e/specs/`. Those files call a `test` and an `expect` from `@playwright/test`,
48
+ // so a vitest rule reading them reports on an API that is not there. Derived from the
49
+ // preset rather than listed by hand, so a preset bump cannot reopen the gap. The override
50
+ // that uses it is last, and oxlint lets the last override win.
51
+ const vitestRulesOff = Object.fromEntries(
52
+ (vitest.overrides ?? []).flatMap((override) =>
53
+ Object.keys(override.rules ?? {}).map((rule) => [rule, "off"])
54
+ )
55
+ );
56
+
45
57
  // Rules turned off for the whole project, each with its reason. Ultracite enables
46
58
  // ~470, including whole families oxlint itself files under `style`, `pedantic` and
47
59
  // `restriction`. These are the ones that disagree with how the code Saasaloy ships
@@ -162,6 +174,40 @@ export default defineConfig({
162
174
  rules: { "unicorn/filename-case": "off" },
163
175
  },
164
176
 
177
+ // The admin app has its own primitive set in packages/ui/src/components/admin/, which
178
+ // `saasaloy add admin` writes. Its names repeat the base ones (`button`, `card`), so an
179
+ // editor's autocomplete offers both and the wrong one renders with no error, in the
180
+ // web app's styling. Inside the admin app and the admin folders of @repo/ui, a base
181
+ // primitive or a base block with an admin twin is a lint error. A project without the
182
+ // admin app has no file under these globs, so the rule never fires there.
183
+ {
184
+ files: [
185
+ "apps/admin/**",
186
+ "packages/ui/src/blocks/admin/**",
187
+ "packages/ui/src/components/admin/**",
188
+ "packages/ui/src/containers/admin/**",
189
+ ],
190
+ rules: {
191
+ "no-restricted-imports": [
192
+ "error",
193
+ {
194
+ patterns: [
195
+ {
196
+ group: [
197
+ "@repo/ui/components/*",
198
+ "!@repo/ui/components/admin/*",
199
+ "@repo/ui/blocks/error-state",
200
+ "@repo/ui/blocks/theme-toggle",
201
+ ],
202
+ message:
203
+ "Admin code uses the admin set: import from @repo/ui/components/admin/* and @repo/ui/blocks/admin/*.",
204
+ },
205
+ ],
206
+ },
207
+ ],
208
+ },
209
+ },
210
+
165
211
  // The design system is vendored from shadcn and re-synced with
166
212
  // `pnpm --filter @repo/ui exec shadcn add …`. `Label` is a primitive: the control
167
213
  // it labels is supplied by the call site, which this rule cannot see.
@@ -238,5 +284,21 @@ export default defineConfig({
238
284
  files: ["packages/env/scripts/**", "packages/env/src/deploy.ts"],
239
285
  rules: { "no-console": "off", "unicorn/no-process-exit": "off" },
240
286
  },
287
+ // The Playwright workspace `saasaloy add e2e` writes. Keep this override last; see
288
+ // `vitestRulesOff` above. `prepare.ts` and `global-teardown.ts` are node scripts that
289
+ // report to stdout, the only place a headless run can say anything, and exit with a
290
+ // status the `e2e` script reads.
291
+ {
292
+ files: ["packages/e2e/**"],
293
+ env: { node: true },
294
+ // `plugins` is not optional here. oxlint only honours a rule turned off in an
295
+ // override when that override also names the rule's plugin.
296
+ plugins: ["vitest"],
297
+ rules: {
298
+ ...vitestRulesOff,
299
+ "no-console": "off",
300
+ "unicorn/no-process-exit": "off",
301
+ },
302
+ },
241
303
  ],
242
304
  });
@@ -9,20 +9,23 @@
9
9
  "pnpm": ">=11"
10
10
  },
11
11
  "scripts": {
12
- "prepare": "husky",
12
+ "prepare": "husky && node packages/tooling/src/link-skills.ts",
13
13
  "build": "turbo run build",
14
14
  "clean": "turbo run clean && rimraf -g node_modules .turbo \"{apps,packages}/*/node_modules\" \"{apps,packages}/*/.turbo\"",
15
- "deploy:production": "node packages/env/src/deploy.ts --check && turbo run deploy",
15
+ "deploy:production": "node packages/tooling/src/deploy-production.ts",
16
+ "release": "node packages/tooling/src/release.ts",
17
+ "release:dry": "node packages/tooling/src/release.ts --dry-run",
16
18
  "dev": "turbo run dev",
17
19
  "env:setup": "node packages/env/scripts/env-setup.ts",
18
20
  "test": "turbo run test && vitest run",
19
21
  "lint": "pnpm run lint:types && pnpm run lint:code && pnpm run lint:css && pnpm run format:check",
20
- "lint:types": "oxlint -c oxlint.config.mjs --type-aware --deny-warnings packages/env/src packages/ui/src",
22
+ "lint:types": "oxlint -c oxlint.config.mjs --type-aware --deny-warnings packages/config/src packages/env/src packages/tooling/src packages/ui/src",
21
23
  "lint:code": "oxlint -c oxlint.config.mjs --deny-warnings .",
22
24
  "lint:css": "stylelint \"**/*.css\" --max-warnings 0",
23
- "lint:fix": "oxlint -c oxlint.config.mjs --type-aware --fix packages/env/src packages/ui/src && oxlint -c oxlint.config.mjs --fix . && stylelint \"**/*.css\" --fix",
25
+ "lint:fix": "oxlint -c oxlint.config.mjs --type-aware --fix packages/config/src packages/env/src packages/tooling/src packages/ui/src && oxlint -c oxlint.config.mjs --fix . && stylelint \"**/*.css\" --fix",
24
26
  "format": "prettier --write .",
25
27
  "format:check": "prettier --check .",
28
+ "skills:link": "node packages/tooling/src/link-skills.ts",
26
29
  "typecheck": "turbo run typecheck"
27
30
  },
28
31
  "devDependencies": {
@@ -0,0 +1,19 @@
1
+ {
2
+ "name": "@repo/config",
3
+ "version": "0.0.0",
4
+ "private": true,
5
+ "type": "module",
6
+ "exports": {
7
+ ".": "./src/index.ts",
8
+ "./define": "./src/define.ts"
9
+ },
10
+ "scripts": {
11
+ "clean": "rimraf -g dist \"*.tsbuildinfo\"",
12
+ "typecheck": "tsc --noEmit -p tsconfig.json"
13
+ },
14
+ "devDependencies": {
15
+ "@repo/tsconfig": "workspace:*",
16
+ "rimraf": "6.1.3",
17
+ "typescript": "7.0.2"
18
+ }
19
+ }
@@ -0,0 +1,134 @@
1
+ import { describe, expect, it } from "vitest";
2
+ import { defineConfig, defineSection, defineSections } from "./define";
3
+
4
+ // The merge rules `@repo/config` has to keep, and the two it has to refuse (#154).
5
+ //
6
+ // It runs on Vitest. In a scaffolded project the root `vitest.config.ts` collects it as the
7
+ // `packages/config` project; in the saasaloy repo `pnpm test:tooling` runs it from the
8
+ // template, and `pnpm test:base` (which is `node --test`) skips this package.
9
+
10
+ const app = () =>
11
+ defineSection("app", {
12
+ name: "Acme",
13
+ locale: "en",
14
+ legal: { termsPath: "/terms", privacyPath: "/privacy" },
15
+ tags: ["one", "two"],
16
+ });
17
+
18
+ const tiers = () => defineSection("tiers", { free: { id: "free" } });
19
+
20
+ describe(defineConfig, () => {
21
+ it("composes one property per section key", () => {
22
+ const config = defineConfig({
23
+ sections: defineSections({ sections: [app(), tiers()] }),
24
+ });
25
+ expect(config.app.name).toBe("Acme");
26
+ expect(config.tiers).toStrictEqual({ free: { id: "free" } });
27
+ });
28
+
29
+ it("an override replaces a leaf and keeps its siblings", () => {
30
+ const config = defineConfig({
31
+ sections: defineSections({ sections: [app()] }),
32
+ overrides: { app: { name: "Ledgerly" } },
33
+ });
34
+ expect(config.app.name).toBe("Ledgerly");
35
+ expect(config.app.locale).toBe("en");
36
+ });
37
+
38
+ it("an override replaces a nested record whole", () => {
39
+ const config = defineConfig({
40
+ sections: defineSections({ sections: [app()] }),
41
+ overrides: {
42
+ app: { legal: { termsPath: "/legal", privacyPath: "/legal/privacy" } },
43
+ },
44
+ });
45
+ expect(config.app.legal).toStrictEqual({
46
+ termsPath: "/legal",
47
+ privacyPath: "/legal/privacy",
48
+ });
49
+ });
50
+
51
+ it("an override replaces an array whole", () => {
52
+ const config = defineConfig({
53
+ sections: defineSections({ sections: [app()] }),
54
+ overrides: { app: { tags: ["three"] } },
55
+ });
56
+ expect(config.app.tags).toStrictEqual(["three"]);
57
+ });
58
+
59
+ it("an explicit undefined keeps the seeded value", () => {
60
+ const config = defineConfig({
61
+ sections: defineSections({ sections: [app()] }),
62
+ overrides: { app: { name: undefined } },
63
+ });
64
+ expect(config.app.name).toBe("Acme");
65
+ });
66
+
67
+ it("the result and every section are frozen", () => {
68
+ const config = defineConfig({
69
+ sections: defineSections({ sections: [app()] }),
70
+ });
71
+ expect(Object.isFrozen(config)).toBeTruthy();
72
+ expect(Object.isFrozen(config.app)).toBeTruthy();
73
+ expect(() => {
74
+ (config.app as { name: string }).name = "nope";
75
+ }).toThrow(TypeError);
76
+ });
77
+
78
+ it("freezes nested records and arrays too", () => {
79
+ const config = defineConfig({
80
+ sections: defineSections({ sections: [app()] }),
81
+ });
82
+ expect(Object.isFrozen(config.app.legal)).toBeTruthy();
83
+ expect(Object.isFrozen(config.app.tags)).toBeTruthy();
84
+ expect(() => {
85
+ (config.app.legal as { termsPath: string }).termsPath = "/nope";
86
+ }).toThrow(TypeError);
87
+ });
88
+
89
+ it("shares no object with the declared section or the overrides", () => {
90
+ const section = app();
91
+ const legal = { termsPath: "/legal", privacyPath: "/legal/privacy" };
92
+ const config = defineConfig({
93
+ sections: defineSections({ sections: [section] }),
94
+ overrides: { app: { legal } },
95
+ });
96
+ expect(config.app.legal).not.toBe(legal);
97
+ expect(config.app.tags).not.toBe(section.values.tags);
98
+ expect(Object.isFrozen(section.values.legal)).toBeFalsy();
99
+ expect(Object.isFrozen(legal)).toBeFalsy();
100
+ legal.termsPath = "/changed";
101
+ expect(config.app.legal.termsPath).toBe("/legal");
102
+ });
103
+
104
+ it("a section never mutates the values it was declared with", () => {
105
+ const section = app();
106
+ defineConfig({
107
+ sections: defineSections({ sections: [section] }),
108
+ overrides: { app: { name: "Ledgerly" } },
109
+ });
110
+ expect(section.values.name).toBe("Acme");
111
+ });
112
+
113
+ it("two sections claiming one key throw, naming the key", () => {
114
+ expect(() =>
115
+ defineConfig({
116
+ sections: defineSections({
117
+ sections: [app(), defineSection("app", { name: "Other" })],
118
+ }),
119
+ })
120
+ ).toThrow(/claim the key "app"/);
121
+ });
122
+
123
+ it("an override of a section nothing defines throws", () => {
124
+ expect(() =>
125
+ defineConfig({
126
+ sections: defineSections({ sections: [app()] }),
127
+ // Only reachable by hand-editing: `ProjectOverride` rejects this at typecheck, so
128
+ // the cast is the only way to reach the runtime guard.
129
+ // oxlint-disable-next-line typescript/no-unsafe-type-assertion
130
+ overrides: { billing: { appName: "Acme" } } as never,
131
+ })
132
+ ).toThrow(/overrides the section "billing"/);
133
+ });
134
+ });