saasaloy 0.6.1 → 0.7.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- 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 +86 -19
- 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-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 +28 -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 +1 -0
- package/templates/base/packages/ui/src/blocks/footer.tsx +5 -3
- 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
|
@@ -0,0 +1,280 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: saasaloy-deploy
|
|
3
|
+
description: Runbook for an AI agent that releases and deploys this project to production with pnpm release and pnpm deploy:production. Use when the owner says "deploy", "ship this", "release", "cut a release", "bump the version", "update the changelog", "put this live", "hotfix production", "roll back production", "what is live", or "what will the next deploy ship", when a release or a deploy stops at a gate, or when editing packages/tooling/src/deploy.config.ts or targets.ts. Covers the go-ahead rule, the release and its changelog, the dry-run report, the gates and what clears each one, --migrate, --skip-ci and --only, smoke checks on a custom domain, the hotfix branch, and the rollback.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# saasaloy-deploy
|
|
7
|
+
|
|
8
|
+
A production deploy is two commands, in this order. `pnpm release` gives the commit a version and a changelog entry (see "The release"). `pnpm deploy:production` then puts it live.
|
|
9
|
+
|
|
10
|
+
`pnpm deploy:production` runs `packages/tooling/src/deploy-production.ts`. It does every mechanical step, in this order, and stops at the first failure:
|
|
11
|
+
|
|
12
|
+
1. **Gates.** The branch, the tree, origin, CI and new migrations. A real run lists every failed gate at once, each with the command that clears it, and builds nothing.
|
|
13
|
+
2. **Env check.** `node packages/env/src/deploy.ts --check` names every blank production key. The `saasaloy-env` skill covers the values.
|
|
14
|
+
3. **Migration**, with `--migrate` only: `pnpm --filter @repo/db run db:prod:migrate`.
|
|
15
|
+
4. **Workers**, one at a time, lowest `order` first from `DEPLOY_TARGETS` in `packages/tooling/src/targets.ts`. Each runs its own `deploy` script, `env-deploy <service>`.
|
|
16
|
+
5. **Smoke checks.** Each `SMOKE_CHECKS` row is requested on every custom domain of its service, three tries, 5 seconds apart.
|
|
17
|
+
6. **Tag.** HEAD gets an annotated `deploy-<UTC yyyymmdd-hhmm>` tag, pushed to origin. Its message names the release, such as `Production deploy of c75d4e1 (v0.1.0): api, admin, web.` A run that fails any step writes no tag.
|
|
18
|
+
|
|
19
|
+
The deploy prints the release on HEAD before the gates. When HEAD is not a release commit, it prints a warning that lists the commits `CHANGELOG.md` does not cover, and it still deploys. That warning is never a gate, so an urgent hotfix goes out first.
|
|
20
|
+
|
|
21
|
+
This skill covers what the command cannot decide: what the owner approves, what to read, and what to do when a step fails. `docs/runbook-deploy.md` holds this project's own steps: the first deploy, the hosting and the data restore.
|
|
22
|
+
|
|
23
|
+
## The rule
|
|
24
|
+
|
|
25
|
+
**Never run `pnpm release` or a real deploy without the owner's go-ahead in this session.** A go-ahead is a message from the owner, after your dry-run report, that tells you to release, to deploy, or both. "Deploy" in the first request is not a go-ahead for a run you have not reported yet. A go-ahead covers the commands your report named, once each. When a run fails and you change anything, report again and wait again.
|
|
26
|
+
|
|
27
|
+
You may run these without asking:
|
|
28
|
+
|
|
29
|
+
- `pnpm release:dry`, any number of times. It prints the next version and the changelog entry, and commits, tags and pushes nothing.
|
|
30
|
+
- `pnpm deploy:production --dry-run`, any number of times. It runs the env check and builds, uploads, migrates and tags nothing.
|
|
31
|
+
- Read-only git: `git describe --tags --match 'deploy-*' --abbrev=0`, `git log <tag>..HEAD`, `git show <tag>`.
|
|
32
|
+
- `pnpm --filter <package> exec env-deploy --run <service> -- wrangler deployments list`, for each deploy target.
|
|
33
|
+
|
|
34
|
+
Only the owner decides these, each in its own message:
|
|
35
|
+
|
|
36
|
+
- `--migrate`. The owner reads the SQL you show and says yes.
|
|
37
|
+
- `--skip-ci "<reason>"`. Use it only when GitHub Actions itself is down, never for a red run. The owner gives the reason.
|
|
38
|
+
- `--only <service>`.
|
|
39
|
+
- `pnpm release major`, or an exact version. Below 1.0 a breaking change bumps the minor, so `1.0.0` is the owner's choice.
|
|
40
|
+
- A deploy with no release first, for an urgent hotfix.
|
|
41
|
+
- `wrangler rollback`, and the restore of a database dump.
|
|
42
|
+
|
|
43
|
+
Never do these:
|
|
44
|
+
|
|
45
|
+
- Move, delete or re-create a deploy tag or a release tag.
|
|
46
|
+
- Edit a released `CHANGELOG.md` entry, or the root `package.json` `version`, by hand. `pnpm release` writes both.
|
|
47
|
+
- Edit `packages/env/.env.prod`, or print a value from it.
|
|
48
|
+
- Commit with `--no-verify`, stash or discard files to pass the tree gate.
|
|
49
|
+
- Deploy a Worker with `pnpm --filter <package> run deploy` or `wrangler deploy`. Both skip the gates, the order and the tag. Use `pnpm deploy:production --only <service>` for one Worker.
|
|
50
|
+
- Push to `main` without the owner's approval.
|
|
51
|
+
|
|
52
|
+
## Procedure
|
|
53
|
+
|
|
54
|
+
1. Bring the checkout up to date:
|
|
55
|
+
```sh
|
|
56
|
+
git switch main && git pull --ff-only
|
|
57
|
+
pnpm install
|
|
58
|
+
```
|
|
59
|
+
2. Check for unpushed commits and uncommitted files:
|
|
60
|
+
```sh
|
|
61
|
+
git status -sb
|
|
62
|
+
```
|
|
63
|
+
`pnpm release` pushes every local commit with the release commit, so a commit from another session would go to origin unreviewed. When the first line shows `ahead`, or any file is listed, stop and ask the owner what to do with them.
|
|
64
|
+
3. Run both dry runs:
|
|
65
|
+
```sh
|
|
66
|
+
pnpm release:dry
|
|
67
|
+
pnpm deploy:production --dry-run
|
|
68
|
+
```
|
|
69
|
+
4. When the deploy dry run lists migration files, print each `.sql` file it names and read it.
|
|
70
|
+
5. Write the report. Use the template below.
|
|
71
|
+
6. Stop. Wait for the owner's go-ahead.
|
|
72
|
+
7. Run the release the owner approved, then wait for CI on the release commit when the config names a workflow:
|
|
73
|
+
```sh
|
|
74
|
+
pnpm release # or pnpm release minor, major, <version>
|
|
75
|
+
gh run watch
|
|
76
|
+
```
|
|
77
|
+
8. Run the deploy the owner approved, with exactly the flags in the report:
|
|
78
|
+
```sh
|
|
79
|
+
pnpm deploy:production # or with --migrate, --skip-ci "<reason>", --only <service>
|
|
80
|
+
```
|
|
81
|
+
9. Check what the smoke checks do not cover, such as a sign-in flow, in a browser. Use `playwright-cli` when `command -v playwright-cli` finds it. Otherwise list the pages for the owner.
|
|
82
|
+
10. Report the result. Use the template below.
|
|
83
|
+
|
|
84
|
+
## The dry-run report
|
|
85
|
+
|
|
86
|
+
```markdown
|
|
87
|
+
**Deploy proposal** for <branch> at <short sha>
|
|
88
|
+
|
|
89
|
+
Last deploy: <tag, or "none, this deploy writes the first tag">
|
|
90
|
+
|
|
91
|
+
Release: <the version and the changelog entry pnpm release:dry printed | "none: an urgent hotfix, released after">
|
|
92
|
+
|
|
93
|
+
Commits this deploy ships:
|
|
94
|
+
- <sha> <subject>
|
|
95
|
+
- ...
|
|
96
|
+
|
|
97
|
+
Migrations: <none | the file names, each with a one-line summary of its SQL, and a note on any statement that drops, renames or rewrites data>
|
|
98
|
+
|
|
99
|
+
Gates: <all pass | each line the dry run printed as fail>
|
|
100
|
+
|
|
101
|
+
Env check: <passed | the blank keys it named>
|
|
102
|
+
|
|
103
|
+
Deploy order: <as the dry run printed it>
|
|
104
|
+
|
|
105
|
+
Smoke checks: <the URLs | the services it skipped for want of a custom domain>
|
|
106
|
+
|
|
107
|
+
Commands I will run: `pnpm release <increment, when one>`, then `pnpm deploy:production <flags>`
|
|
108
|
+
|
|
109
|
+
Risks: <a commit that changes sign-in, payment or an authorization check; a migration that is not additive; "none seen">
|
|
110
|
+
```
|
|
111
|
+
|
|
112
|
+
Leave out a section only when it is empty. Do not claim a commit is safe without reading its diff. Name the files you read.
|
|
113
|
+
|
|
114
|
+
## The release
|
|
115
|
+
|
|
116
|
+
`pnpm release` runs `packages/tooling/src/release.ts`, which runs release-it with options it builds from `deploy.config.ts`. It reads no `.release-it.json`, and it never asks a question. In one run it:
|
|
117
|
+
|
|
118
|
+
1. Reads the Conventional Commits since the last release tag and picks the next version: a `fix` bumps the patch, a `feat` the minor, a breaking change the major. Below 1.0 a breaking change bumps the minor (`preMajor`).
|
|
119
|
+
2. Writes the version into the root `package.json` and a new entry at the top of `CHANGELOG.md`.
|
|
120
|
+
3. Commits both as `chore(release): v<version>`, tags the commit `v<version>`, pushes, and creates a GitHub Release.
|
|
121
|
+
|
|
122
|
+
The changelog shows `feat`, `fix`, `perf` and `revert` commits. A commit of any other type shows only when it is breaking, under its own heading, such as `Miscellaneous Chores` for a breaking `chore!`. The first release covers every commit since the project start, so its entry is long.
|
|
123
|
+
|
|
124
|
+
| Command | What it does |
|
|
125
|
+
| --- | --- |
|
|
126
|
+
| `pnpm release:dry` | Prints the next version and the changelog entry. Changes nothing. |
|
|
127
|
+
| `pnpm release` | The version the commits ask for. |
|
|
128
|
+
| `pnpm release patch`, `minor`, `major` | That bump, whatever the commits ask for. |
|
|
129
|
+
| `pnpm release 1.2.3` | That exact version. |
|
|
130
|
+
|
|
131
|
+
It refuses to start, and changes nothing, when:
|
|
132
|
+
|
|
133
|
+
| The run prints | Clear it with |
|
|
134
|
+
| --- | --- |
|
|
135
|
+
| `Must be on branch ...` | The release takes the deploy's `branches`. `git switch main`, or release from the hotfix branch. |
|
|
136
|
+
| `Working dir must be clean` | Commit or ask the owner. Never turn the check off: release-it commits with `git add . --update`, so a dirty file would go into the release commit. |
|
|
137
|
+
| `No upstream configured for current branch` | `git push -u origin <branch>`. |
|
|
138
|
+
| `There are no commits since the latest tag` | Nothing to release. Deploy without one, or wait for a commit. |
|
|
139
|
+
| `a GitHub Release needs a token and none was found` | `gh auth login`, or set `GITHUB_TOKEN`. The owner may set `release.githubRelease: false` instead. |
|
|
140
|
+
|
|
141
|
+
## The gates and what clears each one
|
|
142
|
+
|
|
143
|
+
The gate values come from `packages/tooling/src/deploy.config.ts`. A key the file leaves out falls back to the default shown.
|
|
144
|
+
|
|
145
|
+
| Gate | It passes when | The run prints | Clear it with |
|
|
146
|
+
| --- | --- | --- | --- |
|
|
147
|
+
| Branch | The branch matches `branches` (default `["main", "hotfix-*"]`; a trailing `*` matches any rest). | `The branch is <x>, and a deploy starts only from ...` | `git switch main`. For a fix while `main` holds unreleased work, see "Hotfix". |
|
|
148
|
+
| Tree | `git status --porcelain` is empty. | `The tree has uncommitted changes (...)` | `git commit`, or `git stash push -u`. An agent asks the owner what to do with the named files. A file the build itself changed is a bug to fix, not to stash. |
|
|
149
|
+
| Origin | HEAD is the same commit as `origin/<branch>`. | `origin has no <branch>`, or `HEAD (...) is not origin/<branch> (...)` | `git push -u origin <branch>`, or `git pull --ff-only`, or `git push`. |
|
|
150
|
+
| CI | `ciWorkflow` names no workflow (the gate is off), or a run of that workflow on HEAD succeeded. | `<workflow> failed on HEAD`, `is still running`, or `has no run on HEAD` | `gh run watch`, then the dry run again. A failed run: read it with `gh run view <id> --log-failed`, fix, push. When GitHub Actions is down: `--skip-ci "<reason>"`. |
|
|
151
|
+
| Migrations | No file matching `migrations` (default `packages/db/migrations/*.sql`) changed since the last deploy tag, or `--migrate` is set. With no tag yet, every migration file counts as new. | `<n> migration file(s) changed since <tag>` | Read the SQL, then `pnpm deploy:production --migrate`. |
|
|
152
|
+
|
|
153
|
+
Two more checks stop the run before the gates, because the deploy order would be a guess:
|
|
154
|
+
|
|
155
|
+
| The run prints | Clear it with |
|
|
156
|
+
| --- | --- |
|
|
157
|
+
| `apps/<service> deploys and has no DEPLOY_TARGETS row` | Add `{ service: "<service>", order: <number> }` to `DEPLOY_TARGETS`. `saasaloy doctor` warns about the same state. |
|
|
158
|
+
| `DEPLOY_TARGETS names <service>, and apps/<service> is not a workspace with a wrangler.jsonc and a deploy script`, a service or smoke `id` listed twice, or a `SMOKE_CHECKS` row for a service that does not deploy | Remove or fix the row in `packages/tooling/src/targets.ts`. |
|
|
159
|
+
| `this repository has no commit yet` | Make the first commit and push it, as the message says. |
|
|
160
|
+
|
|
161
|
+
A failure after the gates:
|
|
162
|
+
|
|
163
|
+
| The run prints | What it means, and what to do |
|
|
164
|
+
| --- | --- |
|
|
165
|
+
| `<service> has no production value for <KEY>`, or another env check line | Nothing built. Report the key names. The owner sets the values. |
|
|
166
|
+
| `Migrate failed. No deploy tag was written.` | No Worker deployed. Read the migration output. The migration output names the dump it took first. |
|
|
167
|
+
| `Deploy <service> failed. No deploy tag was written.` | That Worker did not go live. A Worker before it in the order is live on the new commit, and the run prints its rollback command. |
|
|
168
|
+
| `The Workers are live, and a smoke check failed` | Follow "Roll back" at once: report the failing URL and its status, and propose the rollback the run printed. |
|
|
169
|
+
| `... and the push failed, so the tag is local only` | The Workers are live. Run `git push origin <tag>`. |
|
|
170
|
+
|
|
171
|
+
## The flags
|
|
172
|
+
|
|
173
|
+
- `--dry-run` prints the last deploy tag, the commits since it, the new migration files, every gate, the deploy order and the smoke checks, then runs the env check. It exits 0 and ends with the list of what would stop a real run.
|
|
174
|
+
- `--migrate` runs `pnpm --filter @repo/db run db:prod:migrate` after the env check and before the first Worker, so a new migration lands before the code that reads it. A project with no `@repo/db` workspace refuses the flag. Keep each migration additive (a new table, a nullable or defaulted column), so old code runs on the new schema and a code rollback stays safe.
|
|
175
|
+
- `database-postgres`: `db:prod:migrate` checks that `DATABASE_URL` names `<project>_production` on a server other than the development one in `apps/api/.env`. It then dumps the database with `pg_dump` and applies the migrations with `drizzle-kit migrate`. No migration runs without a good dump.
|
|
176
|
+
- `database-d1`: `db:prod:migrate` runs `wrangler d1 migrations apply DB --remote`, and creates the database first when the account has none by its `database_name`. Before it migrates an existing database, it dumps it with `wrangler d1 export --remote`. No migration runs without a good dump. A database it has just created gets no dump, because it holds nothing.
|
|
177
|
+
- `--skip-ci "<reason>"` passes the CI gate. The reason goes into the tag message. Every other gate still runs.
|
|
178
|
+
- `--only <service>` deploys one Worker after the same gates, and runs only its smoke checks. It writes no tag, because the tag means "this commit is live on every Worker".
|
|
179
|
+
|
|
180
|
+
`pnpm db:prod:dump` takes a dump on its own: `pg_dump --format=custom` for Postgres, `wrangler d1 export --remote` for D1. Dumps land in `~/<project>-backups/` (mode 0700), or in `DB_DUMP_DIR` when it is set, outside the repository. For Postgres, `pg_dump` runs from the `postgres:<major>` image the root `compose.yaml` names, through Docker. Set `PG_DUMP=local` to use the `pg_dump` on `PATH` instead.
|
|
181
|
+
|
|
182
|
+
## Changing the gates, the order and the smoke checks
|
|
183
|
+
|
|
184
|
+
`packages/tooling/src/deploy.config.ts` and `packages/tooling/src/targets.ts` belong to the project. `saasaloy init` writes them once, and `saasaloy update` never writes them again. The engine reads every key with a default, so an older copy keeps working.
|
|
185
|
+
|
|
186
|
+
`deploy.config.ts`:
|
|
187
|
+
|
|
188
|
+
- `branches`: the branches a deploy may start from.
|
|
189
|
+
- `tagPrefix`: the start of every deploy tag. Change it only before the first deploy, or the engine no longer finds the older tags.
|
|
190
|
+
- `ciWorkflow`: the GitHub Actions workflow file that must pass on HEAD, such as `"ci.yml"`. `undefined` turns the CI gate off.
|
|
191
|
+
- `migrations`: the git pathspec for migration files.
|
|
192
|
+
- `release`: what `pnpm release` writes. `tagPrefix` (default `v`; change it only before the first release), `githubRelease` (default `true`), `preMajor` (default `true`), and `changelogSections`, the `conventionalcommits` preset's `types` list. Unset keeps the preset's sections. A key left out falls back to its default.
|
|
193
|
+
|
|
194
|
+
`targets.ts` holds two arrays. Keep each in the shape `export const NAME: Type[] = [...]`, because `saasaloy add` appends its rows there with a `const-array` patch, and `saasaloy remove` takes them out again.
|
|
195
|
+
|
|
196
|
+
- `DEPLOY_TARGETS`: `{ service, order }`. `service` is the directory under `apps/`. The base adds `web` (30), the api module `api` (10) and the admin module `admin` (20). A new Worker needs its own row, or the deploy stops and names it.
|
|
197
|
+
- `SMOKE_CHECKS`: `{ id, service, path, status, body? }`. `body` is text the response body must contain. The `id` stays unique.
|
|
198
|
+
|
|
199
|
+
**A smoke check needs a custom domain.** The engine takes the host from each `routes[]` entry with `custom_domain: true` in `apps/<service>/wrangler.jsonc`. A service with none gets no smoke check, and the run says so. It never guesses a `workers.dev` address. To turn the checks on, add the route and deploy:
|
|
200
|
+
|
|
201
|
+
```jsonc
|
|
202
|
+
// apps/api/wrangler.jsonc
|
|
203
|
+
"routes": [{ "pattern": "api.example.com", "custom_domain": true }]
|
|
204
|
+
```
|
|
205
|
+
|
|
206
|
+
Wrangler creates the domain on the next deploy when the zone is on the same Cloudflare account. The next `pnpm deploy:production --dry-run` lists the smoke URLs for that host.
|
|
207
|
+
|
|
208
|
+
## Hotfix
|
|
209
|
+
|
|
210
|
+
Use this when live code needs a fix and `main` holds commits that must not go live yet. There is no long-lived production branch: the newest deploy tag marks what is live.
|
|
211
|
+
|
|
212
|
+
1. Start the branch from the live commit:
|
|
213
|
+
```sh
|
|
214
|
+
git switch -c hotfix-<slug> "$(git describe --tags --match 'deploy-*' --abbrev=0)"
|
|
215
|
+
```
|
|
216
|
+
2. Make the fix, run `pnpm typecheck`, `pnpm lint` and `pnpm test`, and commit.
|
|
217
|
+
3. Ask the owner to approve the push. Then push it:
|
|
218
|
+
```sh
|
|
219
|
+
git push -u origin hotfix-<slug>
|
|
220
|
+
```
|
|
221
|
+
4. Wait for CI on the branch when the config names a workflow. Then follow "Procedure" from step 2 on this branch. `pnpm release` on the branch makes a patch release such as `v0.3.1`. When the fix cannot wait for the release, the owner may deploy first and release after.
|
|
222
|
+
5. After the deploy, ask the owner to merge the fix into `main`, so the next deploy keeps it. Merge, never rebase: a rebase rewrites the commit the release tag names.
|
|
223
|
+
```sh
|
|
224
|
+
git switch main && git merge hotfix-<slug>
|
|
225
|
+
```
|
|
226
|
+
When `main` has released since the hotfix branched, the merge conflicts in `CHANGELOG.md` and in the root `package.json` `version`. Keep both changelog entries, newest version first, and keep the higher version. Then commit the merge and push:
|
|
227
|
+
```sh
|
|
228
|
+
git push
|
|
229
|
+
git branch -d hotfix-<slug> && git push origin --delete hotfix-<slug>
|
|
230
|
+
```
|
|
231
|
+
|
|
232
|
+
A release from a hotfix branch has not run on a real project yet. Read its `pnpm release:dry` output closely.
|
|
233
|
+
|
|
234
|
+
## Roll back
|
|
235
|
+
|
|
236
|
+
1. Report the failure and propose the rollback. Wait for the owner's go-ahead.
|
|
237
|
+
2. Roll back each broken Worker to its previous version. A failed run prints one line per Worker it deployed, in this form:
|
|
238
|
+
```sh
|
|
239
|
+
pnpm --filter <package> exec env-deploy --run <service> -- wrangler rollback
|
|
240
|
+
```
|
|
241
|
+
`wrangler deployments list` in the same form lists the versions. `wrangler rollback <version-id>` picks an older one.
|
|
242
|
+
3. Request the smoke-check URLs again, and check that each answers as `SMOKE_CHECKS` expects.
|
|
243
|
+
4. Propose a `git revert <sha>` on `main` for the bad commit, so the next deploy does not ship it again. Leave the deploy tags alone. After a rollback, the live code is the previous tag's commit, and the next deploy tags the revert.
|
|
244
|
+
|
|
245
|
+
A code rollback does not undo a migration. A data restore loses every write since the dump. Only the owner decides on it, with the steps in `docs/runbook-deploy.md`.
|
|
246
|
+
|
|
247
|
+
## The result report
|
|
248
|
+
|
|
249
|
+
```markdown
|
|
250
|
+
**Deployed** <short sha> as <tag> (<UTC time>)
|
|
251
|
+
|
|
252
|
+
Release: <v-version, with its GitHub Release link | "none", and why>
|
|
253
|
+
Ran: `pnpm release <increment>`, then `pnpm deploy:production <flags>`
|
|
254
|
+
Migration: <none | the dump file it printed>
|
|
255
|
+
Smoke checks: <pass | skipped for <services>, no custom domain>
|
|
256
|
+
Browser checks: <each page and its result | "for the owner", with the list>
|
|
257
|
+
```
|
|
258
|
+
|
|
259
|
+
When the run failed, report the step that failed, the error lines, what is live now, and your proposed next step.
|
|
260
|
+
|
|
261
|
+
## A project made before the gated deploy
|
|
262
|
+
|
|
263
|
+
`saasaloy update` adds `packages/tooling` and this skill. It lists the root `package.json`, `turbo.json` and `AGENTS.md` in the merge plan when you edited them. Finish by hand:
|
|
264
|
+
|
|
265
|
+
1. Merge the root `package.json` scripts: `deploy:production` is `node packages/tooling/src/deploy-production.ts`, `prepare` is `husky && node packages/tooling/src/link-skills.ts`, `skills:link` is `node packages/tooling/src/link-skills.ts`, and `lint:types` and `lint:fix` include `packages/tooling/src`.
|
|
266
|
+
2. Merge `turbo.json`: remove `^db:migrate:prod` from the `deploy` task's `dependsOn`, and remove the `db:migrate:prod` task.
|
|
267
|
+
3. With `database-d1`, check `packages/db/package.json`. It needs `db:prod:migrate` and `db:prod:dump`, and the old `db:migrate:prod` script goes: rename it to `db:prod:migrate` if the update did not add that one. A D1 deploy no longer migrates on its own. Run `pnpm deploy:production --migrate` when the migration gate asks for it.
|
|
268
|
+
4. Run `saasaloy doctor`. Its Deploy warnings name a `turbo.json` that still has `db:migrate:prod`, and each deploying workspace with no `DEPLOY_TARGETS` row. Each warning prints its fix.
|
|
269
|
+
5. Add a `custom_domain` route to each Worker that has a production host, so its smoke checks run.
|
|
270
|
+
6. Copy `docs/runbook-deploy.md` from a new project if you want the runbook. `saasaloy update` does not create seed files.
|
|
271
|
+
|
|
272
|
+
## A project made before the release step
|
|
273
|
+
|
|
274
|
+
`saasaloy update` adds `packages/tooling/src/release.ts` and the two release-it pins in `packages/tooling/package.json`. Finish by hand:
|
|
275
|
+
|
|
276
|
+
1. Merge the root `package.json` scripts: `release` is `node packages/tooling/src/release.ts`, and `release:dry` is `node packages/tooling/src/release.ts --dry-run`. `saasaloy doctor` warns while they are missing.
|
|
277
|
+
2. Delete an older `.release-it.json`, and any `release-it` or `@release-it/conventional-changelog` in the root `package.json`. `release.ts` reads neither. Move a changelog choice into the `release` block of `deploy.config.ts`.
|
|
278
|
+
3. Keep `CHANGELOG.md` and the `v*` tags. The next release reads the newest tag and adds its entry above the old ones.
|
|
279
|
+
|
|
280
|
+
The root `package.json` `version` belongs to the project. `saasaloy update` compares the file as if it held the template's version and keeps yours when it writes, so a release alone never puts the file in a merge plan.
|
|
@@ -89,7 +89,7 @@ STORAGE_PROXY_URL=
|
|
|
89
89
|
|
|
90
90
|
`pnpm env:setup` reads its values from a source, selected by `ENV_SOURCE`:
|
|
91
91
|
|
|
92
|
-
- **`local`** (the default, always installed) reads the gitignored `packages/env/.env`. `saasaloy env` prompts for each unset key and writes that file, so a project develops with no vendor account and no network.
|
|
92
|
+
- **`local`** (the default, always installed) reads the gitignored `packages/env/.env`. `saasaloy env` prompts for each unset key and writes that file, so a project develops with no vendor account and no network. An agent with no terminal runs `saasaloy env --from-file <path>` instead, which writes the `KEY=VALUE` lines of a dotenv file with no prompt and refuses a key no installed module declares. Prefer it to `--set KEY=VALUE`, which leaves the value in shell history.
|
|
93
93
|
- **`infisical`** arrives with `saasaloy add env-infisical`.
|
|
94
94
|
|
|
95
95
|
A source that does not answer at all — no CLI, no network — is treated as offline: `env:setup` keeps every service file that is already complete and warns, and fails writing nothing when one is incomplete. A refusal the source *answered* with, such as no access, always fails.
|
|
@@ -102,21 +102,22 @@ Each service row declares `dev` or `prod`. `pnpm env:setup --env prod` refuses t
|
|
|
102
102
|
|
|
103
103
|
## Deploying: `pnpm deploy:production` and `env-deploy`
|
|
104
104
|
|
|
105
|
-
`pnpm deploy:production` deploys every Worker in the project with wrangler.
|
|
105
|
+
`pnpm deploy:production` (`packages/tooling/src/deploy-production.ts`) deploys every Worker in the project with wrangler. The `saasaloy-deploy` skill covers its gates, its flags, the go-ahead an agent needs, the hotfix branch and the rollback. This section covers the environment half:
|
|
106
106
|
|
|
107
|
-
1. `node packages/env/src/deploy.ts --check
|
|
108
|
-
2.
|
|
107
|
+
1. Before any build, it runs `node packages/env/src/deploy.ts --check`. That loads every service's `prod` values from the selected source and exits non-zero, naming each blank key, when one is missing. It also stops when `CLOUDFLARE_API_TOKEN` is blank and wrangler holds no `wrangler login` session. `pnpm deploy:production --dry-run` runs the same check and reports its result.
|
|
108
|
+
2. It then runs each deploy target's `deploy` script, one at a time, in the order `packages/tooling/src/targets.ts` gives. That script is `env-deploy <service>`. No Worker deploy runs a migration. A production migration runs only through `pnpm deploy:production --migrate`.
|
|
109
109
|
|
|
110
110
|
`env-deploy <service>` loads that service's `prod` values and the `deploy` credentials, runs `pnpm run build` with them in the environment, and runs `wrangler deploy --secrets-file <file>`. Code and secrets land in one Worker version, so a Worker that throws at module scope on a missing secret deploys cleanly the first time. The secrets file is JSON, mode `0600`, under the OS temp directory, and deleted when the deploy ends, passed or failed. It holds the service's values minus every `CLOUDFLARE_*` key, minus each key the Worker's `wrangler.jsonc` already sets in `vars`, minus empty values. An assets-only Worker, one with no `main`, gets no secrets file.
|
|
111
111
|
|
|
112
|
-
**Where the production values come from.** The `local` source reads the gitignored `packages/env/.env.prod`, never `packages/env/.env`, so a deploy cannot ship a `localhost` URL by accident. Copy the keys from `packages/env/.env.example` into it and set each one. `env-infisical` reads its `prod` environment. A variable the shell already exports wins over both, which is how CI passes values. The base `turbo.json`
|
|
112
|
+
**Where the production values come from.** The `local` source reads the gitignored `packages/env/.env.prod`, never `packages/env/.env`, so a deploy cannot ship a `localhost` URL by accident. Copy the keys from `packages/env/.env.example` into it and set each one. `env-infisical` reads its `prod` environment. A variable the shell already exports wins over both, which is how CI passes values. The base `turbo.json` keeps a `deploy` task with `passThroughEnv` for a project that runs `turbo run deploy` by hand, because turbo's strict env mode would drop the exported variables otherwise. `pnpm deploy:production` does not use turbo for the deploy.
|
|
113
113
|
|
|
114
114
|
**Why the dev `.env` stays out of the build.** Vite gives the environment priority over a `.env` file, but the Cloudflare adapters prerender inside workerd, and wrangler hands workerd the `.env` beside the workspace as its vars. So `env-deploy` builds with `CLOUDFLARE_LOAD_DEV_VARS_FROM_DOT_ENV=false`, and it sets a key the source leaves out to an empty string rather than leaving it unset. `apps/web/.env` keeps its dev values, and nothing writes a production value under `apps/`.
|
|
115
115
|
|
|
116
116
|
Three more forms:
|
|
117
117
|
|
|
118
|
-
- `pnpm --
|
|
119
|
-
- `
|
|
118
|
+
- `pnpm deploy:production --only <service>` deploys one Worker after the same gates, and runs its smoke checks. It writes no deploy tag.
|
|
119
|
+
- `pnpm --filter @repo/web run deploy -- --dry-run` builds one Worker with the production values and uploads nothing. Pass wrangler flags after `--`. Do not deploy with `pnpm --filter <package> run deploy` alone: it skips the gates, the order and the tag.
|
|
120
|
+
- `env-deploy --run <service> -- <command> [args...]` runs one command with that service's `prod` values and the credentials. The `db:prod:migrate` and `db:prod:dump` scripts use it: `--run api` under `database-postgres`, because `DATABASE_URL` is an `api` key, and `--run deploy` under `database-d1`, which needs only the Cloudflare credentials.
|
|
120
121
|
- `env-deploy --check` is step 1 on its own.
|
|
121
122
|
|
|
122
123
|
Two things the flow does not do. `--secrets-file` only adds: a secret you removed from the value source stays on the Worker until you run `wrangler secret delete <KEY>` in its workspace. And a key marked `# Blank on purpose` passes the check even where production needs it, such as `BETTER_AUTH_SECRET`; the Worker's own `createEnv` gate is what refuses it.
|
|
@@ -24,9 +24,10 @@ reviewed.
|
|
|
24
24
|
| `apps/web/src/pages/index.astro` | Only to drop a block, and only behind its own confirmation. |
|
|
25
25
|
| `docs/product-brief.md` | Only to append what you learned filling a gap the brief left, and only its **Known gaps** section otherwise. |
|
|
26
26
|
|
|
27
|
-
Nothing else — in particular not `
|
|
28
|
-
project identity, `saasaloy-setup` owns them, and
|
|
29
|
-
says what to do when they disagree with the
|
|
27
|
+
Nothing else — in particular not `packages/config/src/project.ts`, which holds the product
|
|
28
|
+
name and the locale. Those are project identity, `saasaloy-setup` owns them, and
|
|
29
|
+
[Step 0](#step-0--before-you-write-anything) says what to do when they disagree with the
|
|
30
|
+
brief.
|
|
30
31
|
|
|
31
32
|
## Step 0 — before you write anything
|
|
32
33
|
|
|
@@ -45,9 +46,9 @@ says what to do when they disagree with the brief.
|
|
|
45
46
|
Reading a block is fine; editing one is not. Its keys are the whole vocabulary available
|
|
46
47
|
to `landing.features.items[].icon`, and they are the actual list rather than one copied
|
|
47
48
|
into this file that went stale.
|
|
48
|
-
4. **Check the two facts you do not own
|
|
49
|
-
still the shipped `"Saasaloy"
|
|
50
|
-
`en` while the brief names another language, say so now and carry both into the draft's
|
|
49
|
+
4. **Check the two facts you do not own**, both in `packages/config/src/project.ts`. If
|
|
50
|
+
`app.name` is unset, so `siteName` is still the shipped `"Saasaloy"`, or it is a directory
|
|
51
|
+
slug, or `app.locale` is `en` while the brief names another language, say so now and carry both into the draft's
|
|
51
52
|
**Not mine to fix** list. Writing Bangla copy into a page that declares itself English is
|
|
52
53
|
a real defect, and one attribute long. Do not fix it yourself.
|
|
53
54
|
5. **Look at git, and treat it as advice.** `git status --short` if there is a repo. A dirty
|
|
@@ -382,9 +383,9 @@ Copy on disk plus a brief means this has run before.
|
|
|
382
383
|
`docs/landing-copy-draft.md`, which you write on every run and delete at the end. The
|
|
383
384
|
other two are a consented block removal in `apps/web/src/pages/index.astro` and appended
|
|
384
385
|
gaps in `docs/product-brief.md`.
|
|
385
|
-
-
|
|
386
|
-
|
|
387
|
-
fix it.
|
|
386
|
+
- **The product name and the locale are not yours.** `packages/config/src/project.ts`
|
|
387
|
+
belongs to `saasaloy-setup`, and so does everything else in `packages/config`. Report a
|
|
388
|
+
mismatch; do not fix it.
|
|
388
389
|
- **Never edit a block.** `packages/ui/src/blocks/*.tsx` is off limits: no markup, no
|
|
389
390
|
classes, no structure, no widening the icon registry. Read them freely. If copy will not
|
|
390
391
|
fit a block, say so and let the owner decide.
|
|
@@ -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
|
|
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
|
|
9
|
-
|
|
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:
|
|
14
|
-
and
|
|
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/
|
|
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/
|
|
34
|
-
|
|
35
|
-
|
|
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
|
-
|
|
222
|
-
|
|
223
|
-
|
|
224
|
-
|
|
225
|
-
in
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
|
|
229
|
-
|
|
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
|
|
238
|
+
Then check it still builds, because every page reads that object:
|
|
232
239
|
|
|
233
240
|
```sh
|
|
234
|
-
pnpm
|
|
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
|
|
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.
|
|
@@ -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
|
}
|