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
@@ -0,0 +1,131 @@
1
+ ---
2
+ name: saasaloy-config
3
+ description: Work with @repo/config — the values this project checks into its repo and ships identically to every environment. Use when a value needs a single home, when deciding whether something belongs in config or in .env, when adding a section for a capability, when a project override is not taking effect, or when the owner says "where do I change the product name", "where do I put this constant", "config or env".
4
+ ---
5
+
6
+ # saasaloy-config — one home for a checked-in value
7
+
8
+ `@repo/config` is a frozen plain object of values this project checks into its repo. Read it
9
+ with a plain import, from an app, a capability or a React island alike:
10
+
11
+ ```ts
12
+ import { config } from "@repo/config";
13
+
14
+ config.app.name;
15
+ config.app.locale;
16
+ config.auth.adminRole; // once `auth` is installed
17
+ ```
18
+
19
+ There is no factory, no `env` argument, no async and no I/O. The object is built once at
20
+ module load and frozen, so a bundler can inline it.
21
+
22
+ ## The rule: config or `.env`
23
+
24
+ - **`env`** owns a value the platform supplies per deployment, secret or not. A database
25
+ URL, an API origin, a Stripe key, a provider selection.
26
+ - **`config`** owns a value checked into the repo that is the same in every deployment. The
27
+ product name, the locale, a role string.
28
+
29
+ **The test.** Two deployments of *this* project — production and staging. If the value can
30
+ differ between them, it is `env`. If it cannot, it is `config`. A value that differs between
31
+ two *different* projects but not between one project's environments is `config`.
32
+
33
+ `packages/config` imports nothing, `@repo/env` included, so a section cannot read an env
34
+ var. A value derived from both channels is derived where it is used, not in a section file.
35
+
36
+ ## Not the landing copy
37
+
38
+ Everything on the landing page, prices and tier ids included, lives in
39
+ `packages/ui/src/content/landing.ts`, and `saasaloy-landing-copy` owns it. `config` holds
40
+ the facts more than one workspace reads: the product name, the locale, the legal paths, and
41
+ whatever an installed module's section adds.
42
+
43
+ ## The four files
44
+
45
+ | Path | Who owns it |
46
+ |------|-------------|
47
+ | `src/project.ts` | **You.** The only file here you are expected to edit. Nothing overwrites it. |
48
+ | `src/sections.ts` | The registry. `saasaloy add` patches one line into it; do not hand-edit the array. |
49
+ | `src/sections/<key>.ts` | The module that installed it (`app` belongs to the base template). |
50
+ | `src/define.ts` | The base template. The composition core. |
51
+
52
+ ## Changing a value
53
+
54
+ Edit `src/project.ts`. It is typed as a partial of the composed shape, so a key no
55
+ installed section defines is a `typecheck` error rather than a value nothing reads.
56
+
57
+ ```ts
58
+ export const project: ProjectOverride = {
59
+ app: { name: "Ledgerly", locale: "en-GB" },
60
+ };
61
+ ```
62
+
63
+ **The merge goes one level below the section, and no deeper.** `app: { name: "..." }`
64
+ replaces the name and keeps the rest of `app`. A nested record or an array is replaced
65
+ whole, so `app: { legal: { termsPath: "/legal/terms" } }` must also name `privacyPath`.
66
+
67
+ Run `pnpm typecheck` after an edit. That is the only validation there is: the values are
68
+ literals in this repo, so a wrong one is a review problem rather than a runtime one.
69
+
70
+ ## Adding a section
71
+
72
+ A capability contributes one section, keyed by the module name. The module ships one file
73
+ into `packages/config/src/sections/<key>.ts` and registers it with a `plugin-array` patch:
74
+
75
+ ```ts
76
+ // packages/config/src/sections/shop.ts
77
+ import { defineSection } from "@repo/config/define";
78
+
79
+ export function shopConfig() {
80
+ return defineSection("shop", {
81
+ defaultCurrency: "USD",
82
+ maxCartItems: 50,
83
+ });
84
+ }
85
+ ```
86
+
87
+ ```jsonc
88
+ // the module's registry-item.json
89
+ {
90
+ "file": "packages/config/src/sections.ts",
91
+ "kind": "plugin-array",
92
+ "exportName": "sections",
93
+ "arrayProp": "sections",
94
+ "call": "shopConfig",
95
+ "import": { "name": "shopConfig", "from": "./sections/shop" }
96
+ }
97
+ ```
98
+
99
+ Four rules:
100
+
101
+ - **The key is the module name**, flat, and unique. `saasaloy add` refuses two modules
102
+ claiming one key and names both, and the base's own `app` is taken; at runtime a
103
+ duplicate throws at module load. The file name and the key passed to `defineSection`
104
+ must match, and `add` refuses a section file where they differ.
105
+ - **The section file lives in `packages/config`, not in the capability.** `@repo/config` is
106
+ the leaf of the dependency graph — it imports nothing, so everything may import it,
107
+ including the capability whose values these are. A section inside the capability would
108
+ invert that and cycle.
109
+ - **Import the helper by subpath**, `@repo/config/define`, never by relative path.
110
+ - **A section never reads another section.** They are composed side by side. Apply a
111
+ fallback between two sections where the value is used, the way
112
+ `apps/api/src/billing-store.ts` does for `config.billing.appName || config.app.name`.
113
+
114
+ ## When an override does not take effect
115
+
116
+ 1. **The section is not installed.** `config.shop` only exists once `saasaloy add shop`
117
+ has patched `src/sections.ts`. Check the array.
118
+ 2. **You edited a section file, not `project.ts`.** A module-owned section file may be
119
+ rewritten by `saasaloy update`. Move the edit to `project.ts`.
120
+ 3. **You expected a deep merge.** One level below the section is the whole rule; a nested
121
+ record is replaced whole.
122
+ 4. **Something reads the value at build time.** A Node config file (`astro.config.mjs`,
123
+ `vite.config.ts`) is not part of the app graph and keeps its own literals on purpose.
124
+
125
+ ## What is not here
126
+
127
+ - **A runtime override channel.** A value that must change per deployment is an `env` value
128
+ by definition.
129
+ - **Schema validation.** `typecheck` is the gate.
130
+ - **A `<CAP>_PROVIDER` key.** Provider selection stays in `env`.
131
+ - **The dev ports.** 3000/3001/4000 are read by Node config files at build time.
@@ -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.
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: saasaloy-design
3
- description: Keep apps/web/DESIGN.md true of the Saasaloy design layer. Use theme to choose and apply a registry style, update after packages/ui changes, or audit the design contract for token drift.
3
+ description: Keep apps/web/DESIGN.md, and apps/admin/DESIGN.md when the admin app is installed, true of the Saasaloy design layer. Use theme to choose and apply a registry style to the web app, update after packages/ui changes, or audit a design contract for token drift.
4
4
  derived-from: "designkit (MIT), narrowed 2026-08-09"
5
5
  ---
6
6
 
@@ -8,9 +8,16 @@ derived-from: "designkit (MIT), narrowed 2026-08-09"
8
8
 
9
9
  This skill records the design system that the project already uses. It writes no components and no pages. Use `uikit` for that work.
10
10
 
11
- The token home is `packages/ui/src/styles/web.css`. The design contract is `apps/web/DESIGN.md`. `web.css` imports `packages/ui/src/styles/globals.css`, which holds the shared Tailwind setup and no token values.
11
+ Each app has its own token home and its own contract:
12
12
 
13
- This skill covers the web app only. Another app's theme file, such as the admin module's `packages/ui/src/styles/admin.css`, is out of scope. Do not read its tokens into this contract, and do not edit it.
13
+ | App | Token home | Contract |
14
+ |-----|------------|----------|
15
+ | web | `packages/ui/src/styles/web.css` | `apps/web/DESIGN.md` |
16
+ | admin, when installed | `packages/ui/src/styles/admin.css` | `apps/admin/DESIGN.md` |
17
+
18
+ Both theme files import `packages/ui/src/styles/globals.css`, which holds the shared Tailwind setup and no token values. Ask which app when the user does not say, and work on one contract at a time. Never read one app's tokens into the other app's contract.
19
+
20
+ The admin contract also covers the admin primitive set in `packages/ui/src/components/admin/`, its blocks in `packages/ui/src/blocks/admin/` and its containers in `packages/ui/src/containers/admin/`. The web contract covers the base `components/`, the other `blocks/` and the web app.
14
21
 
15
22
  The grounding rule controls every mode. Every token value must exist in the project code or in the Tailwind utility that the project uses. Do not choose a nearby value because it looks cleaner.
16
23
 
@@ -26,15 +33,17 @@ If the user does not name a mode, ask which mode to use. Do not choose between a
26
33
 
27
34
  | Mode | Files |
28
35
  |------|-------|
29
- | `theme` | `packages/ui/src/styles/web.css`, `apps/web/DESIGN.md`, and `docs/product-brief.md` only when the brief is absent |
30
- | `update` | `apps/web/DESIGN.md` only |
36
+ | `theme` | web only: `packages/ui/src/styles/web.css`, `apps/web/DESIGN.md`, and `docs/product-brief.md` only when the brief is absent |
37
+ | `update` | the chosen app's `DESIGN.md` only |
31
38
  | `audit` | none |
32
39
 
40
+ `theme` never runs for the admin app. A preset targets `web.css` through `components.json`, and nothing writes to `admin.css` but a person. When the user asks to restyle the admin app, say so, and offer `update` after they edit `admin.css`.
41
+
33
42
  Do not edit `components.json` during a theme change. Do not add a dependency, script, component, page, or Tailwind class.
34
43
 
35
44
  ## Shared rules
36
45
 
37
- Read `apps/web/DESIGN.md`, `packages/ui/src/styles/web.css`, `packages/ui/src/styles/globals.css`, and all files under `packages/ui/src/` before you derive tokens. Read the application files that use `@repo/ui` when you need to confirm usage.
46
+ Read the chosen app's `DESIGN.md` and theme file, `packages/ui/src/styles/globals.css`, and the files under `packages/ui/src/` that the app renders before you derive tokens. Read the application files that use `@repo/ui` when you need to confirm usage.
38
47
 
39
48
  Find the system in this order. Stop at the first match.
40
49
 
@@ -65,11 +74,11 @@ Use only these component token keys: `backgroundColor`, `textColor`, `typography
65
74
 
66
75
  Keep the sections in this order: Overview, Colors, Typography, Layout, Elevation & Depth, Shapes, Components, Do's and Don'ts, Motion, Dark Mode.
67
76
 
68
- The seed is a one-time base file. ADR 0022 means Saasaloy has no update path for it. The fingerprint detects drift, and this skill repairs the contract.
77
+ The web contract is a one-time base seed. ADR 0022 means Saasaloy has no update path for it. The admin contract is an admin module file, so `saasaloy update` lists an edited copy in its merge plan. In both cases the fingerprint detects drift, and this skill repairs the contract.
69
78
 
70
79
  ## Fingerprint
71
80
 
72
- The fingerprint covers only `packages/ui/src/styles/web.css`. It does not cover `globals.css`, components, blocks, or other files.
81
+ The fingerprint covers only the chosen app's theme file: `packages/ui/src/styles/web.css` for the web contract, `packages/ui/src/styles/admin.css` for the admin contract. It does not cover `globals.css`, components, blocks, or other files. The commands and stamps below name `web.css`; substitute `admin.css` for the admin contract.
73
82
 
74
83
  Compute the fingerprint from the file bytes. Use the first 12 lowercase hexadecimal characters of SHA-256.
75
84
 
@@ -93,10 +102,11 @@ Do not change the fingerprint during `audit`.
93
102
 
94
103
  ## Official linter
95
104
 
96
- Run the official linter after each write.
105
+ Run the official linter after each write, on the contract you wrote.
97
106
 
98
107
  ```sh
99
108
  pnpm dlx @google/design.md lint apps/web/DESIGN.md
109
+ pnpm dlx @google/design.md lint apps/admin/DESIGN.md
100
110
  ```
101
111
 
102
112
  The format is alpha. Read the current schema when a lint finding conflicts with this skill.
@@ -179,7 +189,7 @@ Audit is read-only. Do not edit or format any file.
179
189
 
180
190
  ### 1. Check the fingerprint offline
181
191
 
182
- Read the recorded 12-character fingerprint from the final stamp. Compute the current fingerprint from `web.css`.
192
+ Read the recorded 12-character fingerprint from the final stamp. Compute the current fingerprint from the chosen app's theme file, `web.css` or `admin.css`.
183
193
 
184
194
  - `current` means the two fingerprints match.
185
195
  - `stale` means they differ.
@@ -193,7 +203,7 @@ Use `orphaned` for a documented token with no current source. Use `uncovered` fo
193
203
 
194
204
  ### 3. Lint when possible
195
205
 
196
- Run `pnpm dlx @google/design.md lint apps/web/DESIGN.md` when the tool and network are available. If it cannot run, state that the fingerprint check ran offline and structural lint did not run.
206
+ Run `pnpm dlx @google/design.md lint apps/<app>/DESIGN.md` for the chosen app when the tool and network are available. If it cannot run, state that the fingerprint check ran offline and structural lint did not run.
197
207
 
198
208
  ### 4. Report
199
209
 
@@ -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. It runs in two steps:
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` 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. Nothing builds before this passes.
108
- 2. `turbo run deploy` runs each workspace's `deploy` script, which is `env-deploy <service>`. A workspace whose package depends on `@repo/db` waits for `db:migrate:prod` first.
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` sets `passThroughEnv` on `deploy`, because turbo's strict env mode would drop the exported variables otherwise.
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 --filter @repo/api run deploy` deploys one Worker. Pass wrangler flags after `--`: `pnpm --filter @repo/web run deploy -- --dry-run` builds with the production values and uploads nothing.
119
- - `env-deploy --run <service> -- <command> [args...]` runs one command with that service's `prod` values and the credentials. `database-d1`'s `db:migrate:prod` uses it.
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 `siteName` and not the page's `lang` attribute. Those are
28
- project identity, `saasaloy-setup` owns them, and [Step 0](#step-0--before-you-write-anything)
29
- says what to do when they disagree with the brief.
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.** If `siteName` in `packages/ui/src/index.ts` is
49
- still the shipped `"Saasaloy"` or a directory slug, or `lang` in `apps/web/src/layouts/Layout.astro` is
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
- - **`siteName` and `lang` are not yours.** `packages/ui/src/index.ts` and
386
- `apps/web/src/layouts/Layout.astro` belong to `saasaloy-setup`. Report a mismatch; do not
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.