saasaloy 0.6.0 → 0.7.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +7 -7
- package/dist/index.js +3952 -1899
- package/dist/index.js.map +1 -1
- package/package.json +2 -1
- package/schemas/manifest.schema.json +32 -1
- package/schemas/registry-item.schema.json +57 -2
- package/schemas/saasaloy-lock.schema.json +9 -0
- package/schemas/saasaloy.schema.json +12 -0
- package/templates/base/AGENTS.md +118 -63
- package/templates/base/README.md +16 -1
- package/templates/base/_agents/skills/saasaloy-config/SKILL.md +131 -0
- package/templates/base/_agents/skills/saasaloy-deploy/SKILL.md +280 -0
- package/templates/base/_agents/skills/saasaloy-design/SKILL.md +21 -11
- package/templates/base/_agents/skills/saasaloy-env/SKILL.md +8 -7
- package/templates/base/_agents/skills/saasaloy-landing-copy/SKILL.md +10 -9
- package/templates/base/_agents/skills/saasaloy-setup/SKILL.md +30 -22
- package/templates/base/_agents/skills/saasaloy-testing/SKILL.md +85 -0
- package/templates/base/_gitignore +4 -0
- package/templates/base/_prettierignore +5 -0
- package/templates/base/_saasaloy-base.json +6 -2
- package/templates/base/apps/web/package.json +1 -0
- package/templates/base/apps/web/src/layouts/Layout.astro +2 -1
- package/templates/base/apps/web/src/pages/privacy.astro +2 -0
- package/templates/base/apps/web/src/pages/terms.astro +2 -0
- package/templates/base/docs/runbook-deploy.md +72 -0
- package/templates/base/oxlint.config.mjs +62 -0
- package/templates/base/package.json +7 -4
- package/templates/base/packages/config/package.json +19 -0
- package/templates/base/packages/config/src/define.test.ts +134 -0
- package/templates/base/packages/config/src/define.ts +135 -0
- package/templates/base/packages/config/src/index.ts +34 -0
- package/templates/base/packages/config/src/project.ts +25 -0
- package/templates/base/packages/config/src/sections/app.ts +27 -0
- package/templates/base/packages/config/src/sections.ts +22 -0
- package/templates/base/packages/config/tsconfig.json +4 -0
- package/templates/base/packages/env/package.json +2 -1
- package/templates/base/packages/env/src/deploy.ts +3 -2
- package/templates/base/packages/env/src/services.test.ts +27 -11
- package/templates/base/packages/tooling/package.json +21 -0
- package/templates/base/packages/tooling/src/deploy-production.test.ts +923 -0
- package/templates/base/packages/tooling/src/deploy-production.ts +1041 -0
- package/templates/base/packages/tooling/src/deploy.config.ts +30 -0
- package/templates/base/packages/tooling/src/link-skills.test.ts +126 -0
- package/templates/base/packages/tooling/src/link-skills.ts +142 -0
- package/templates/base/packages/tooling/src/release.test.ts +205 -0
- package/templates/base/packages/tooling/src/release.ts +228 -0
- package/templates/base/packages/tooling/src/targets.ts +38 -0
- package/templates/base/packages/tooling/src/types.ts +78 -0
- package/templates/base/packages/tooling/tsconfig.json +11 -0
- package/templates/base/packages/ui/package.json +4 -2
- package/templates/base/packages/ui/src/blocks/footer.tsx +5 -3
- package/templates/base/packages/ui/src/containers/README.md +6 -5
- package/templates/base/packages/ui/src/content/landing.ts +2 -4
- package/templates/base/packages/ui/src/index.ts +10 -5
- package/templates/base/saasaloy.json +2 -1
- package/templates/base/turbo.json +1 -5
- package/templates/base/vitest.config.ts +5 -1
|
@@ -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
|
}
|
|
@@ -3,6 +3,7 @@
|
|
|
3
3
|
// import of the web theme, so a page is only ever its own content — no page may
|
|
4
4
|
// duplicate the shell or import a stylesheet again. web.css imports the shared
|
|
5
5
|
// globals.css itself.
|
|
6
|
+
import { config } from "@repo/config";
|
|
6
7
|
import "@repo/ui/styles/web.css";
|
|
7
8
|
import { siteName } from "@repo/ui";
|
|
8
9
|
import { ui } from "@repo/ui/content/landing";
|
|
@@ -23,7 +24,7 @@ const canonical = new URL(Astro.url.pathname, webEnv().PUBLIC_SITE_URL).href;
|
|
|
23
24
|
---
|
|
24
25
|
|
|
25
26
|
<!doctype html>
|
|
26
|
-
<html lang=
|
|
27
|
+
<html lang={config.app.locale}>
|
|
27
28
|
<head>
|
|
28
29
|
<meta charset="utf-8" />
|
|
29
30
|
<meta name="viewport" content="width=device-width, initial-scale=1" />
|
|
@@ -0,0 +1,72 @@
|
|
|
1
|
+
# Runbook: deploy {{PROJECT_NAME}} to production
|
|
2
|
+
|
|
3
|
+
This file belongs to the project. `saasaloy init` wrote it once, and `saasaloy update` never writes it again. Fill in each section marked "Fill in" for this project, and keep it true as production changes.
|
|
4
|
+
|
|
5
|
+
The general flow lives in the `saasaloy-deploy` skill (`.agents/skills/saasaloy-deploy/SKILL.md`): the go-ahead rule for agents, the release, the gates and what clears each one, `--migrate`, `--skip-ci` and `--only`, the hotfix branch and the Worker rollback. This runbook holds what only this project knows.
|
|
6
|
+
|
|
7
|
+
## Commands
|
|
8
|
+
|
|
9
|
+
Each deploy is two steps: `pnpm release`, then `pnpm deploy:production`. The release tags the commit `v<version>` and writes its `CHANGELOG.md` entry. The deploy names that version in its `deploy-*` tag.
|
|
10
|
+
|
|
11
|
+
| Command | What it does |
|
|
12
|
+
| --- | --- |
|
|
13
|
+
| `pnpm release:dry` | Prints the next version and the changelog entry. Changes nothing. |
|
|
14
|
+
| `pnpm release` | Bumps the root `package.json` version, writes `CHANGELOG.md`, commits `chore(release): v<version>`, tags `v<version>`, pushes, and creates a GitHub Release. `pnpm release minor`, `major` or `<version>` picks the bump. |
|
|
15
|
+
| `pnpm deploy:production --dry-run` | Prints the last deploy tag, the commits since it, every gate, the deploy order and the smoke checks, and runs the env check. Builds, uploads, migrates and tags nothing. |
|
|
16
|
+
| `pnpm deploy:production` | The gates, the env check, every Worker in order, the smoke checks, then the deploy tag. |
|
|
17
|
+
| `pnpm deploy:production --migrate` | The same, with the production migration before the first Worker. |
|
|
18
|
+
| `pnpm deploy:production --skip-ci "<reason>"` | Passes the CI gate when GitHub Actions is down. The reason goes into the tag message. |
|
|
19
|
+
| `pnpm deploy:production --only <service>` | One Worker and its smoke checks, after the gates. Writes no tag. |
|
|
20
|
+
| `git describe --tags --match 'deploy-*' --abbrev=0` | Names the last deploy, which is what is live. |
|
|
21
|
+
| `git log <tag>..main` | Lists what the next deploy ships. |
|
|
22
|
+
| `git describe --tags --match 'v*' --abbrev=0` | Names the last release. |
|
|
23
|
+
|
|
24
|
+
With a database module installed, `pnpm db:prod:dump` takes a dump into `~/<project>-backups/` (or `DB_DUMP_DIR`), and `pnpm db:prod:migrate` runs the production migration. `pnpm deploy:production --migrate` calls the second one for you.
|
|
25
|
+
|
|
26
|
+
## Production
|
|
27
|
+
|
|
28
|
+
Fill in: one row per Worker, from `DEPLOY_TARGETS` in `packages/tooling/src/targets.ts`.
|
|
29
|
+
|
|
30
|
+
| Worker | Workspace | Address | What it is |
|
|
31
|
+
| --- | --- | --- | --- |
|
|
32
|
+
| `{{PROJECT_NAME}}-web` | `apps/web` | `https://<host>` | Astro site |
|
|
33
|
+
|
|
34
|
+
A smoke check runs only against a `custom_domain: true` route in the Worker's `wrangler.jsonc`. List each host here once its route is in place.
|
|
35
|
+
|
|
36
|
+
## Hosting
|
|
37
|
+
|
|
38
|
+
Fill in: where each part of production runs and who has access.
|
|
39
|
+
|
|
40
|
+
- The Cloudflare account, and the zone each host sits on.
|
|
41
|
+
- The database, when the project has one: where it runs, its name (`<project>_production` for Postgres), and how a deploy machine reaches it.
|
|
42
|
+
- The value source for production values: `packages/env/.env.prod` on which machine, or the secrets manager. Name where its only copy is kept.
|
|
43
|
+
- Who may deploy, and from which machine.
|
|
44
|
+
|
|
45
|
+
## The first deploy
|
|
46
|
+
|
|
47
|
+
Fill in: the steps this project took for its first deploy, as a record. Every deploy after it follows the `saasaloy-deploy` skill.
|
|
48
|
+
|
|
49
|
+
A starting order:
|
|
50
|
+
|
|
51
|
+
1. Fill `packages/env/.env.prod`, or the production environment of the value source, and run `pnpm deploy:production --dry-run` until the env check passes.
|
|
52
|
+
2. With a database: `pnpm db:prod:dump` on the empty database, to prove the backup path before there is anything to lose.
|
|
53
|
+
3. Add a `custom_domain` route to each Worker that has a production host, so the smoke checks run.
|
|
54
|
+
4. Commit, push, run `pnpm release` (the first release is `v0.1.0`, and its changelog entry covers every commit so far), then `pnpm deploy:production --migrate`. With no deploy tag yet, every migration file counts as new, so the first deploy with a database needs `--migrate`.
|
|
55
|
+
5. Check each production host in a browser, including sign-in when the project has it.
|
|
56
|
+
|
|
57
|
+
## Restore data from a dump
|
|
58
|
+
|
|
59
|
+
Fill in and test this before you rely on it. A code rollback does not undo a migration, and a restore loses every write since the dump was taken. Only the owner decides on a restore.
|
|
60
|
+
|
|
61
|
+
- Postgres: `db:prod:dump` and `db:prod:migrate` write a `pg_dump --format=custom` file named `<project>_production-<UTC time>.dump`. Restore it with `pg_restore --clean --if-exists --single-transaction`, through `pnpm --filter @repo/db exec env-deploy --run api -- <command>` so `DATABASE_URL` is the production value. Write the exact command for this project here.
|
|
62
|
+
- D1: `db:prod:dump` writes a SQL file. Restore it with `wrangler d1 execute <database_name> --remote --file <dump>`, or roll the database back in place with D1 Time Travel (`wrangler d1 time-travel restore`).
|
|
63
|
+
|
|
64
|
+
After a restore, roll the api back to the version that matches that schema.
|
|
65
|
+
|
|
66
|
+
## Hotfix releases
|
|
67
|
+
|
|
68
|
+
A hotfix branch makes its own patch release, such as `v0.3.1`. Merging it back into `main` after `main` has released conflicts in `CHANGELOG.md` and in the root `package.json` `version`: keep both changelog entries and the higher version. The `saasaloy-deploy` skill has the steps. This path has not run on a real project yet, so write down what happened here the first time.
|
|
69
|
+
|
|
70
|
+
## When something fails
|
|
71
|
+
|
|
72
|
+
Fill in: the failures this project has met in production, each with its cause and its fix.
|
|
@@ -42,6 +42,18 @@ function mergePresets(...presets) {
|
|
|
42
42
|
|
|
43
43
|
const ultracite = mergePresets(core, astro, react, vitest);
|
|
44
44
|
|
|
45
|
+
// Every rule the vitest preset turns on, mapped to "off". The preset's file glob is
|
|
46
|
+
// `**/*.{test,spec,…}`, which also matches the Playwright specs `saasaloy add e2e` puts in
|
|
47
|
+
// `packages/e2e/specs/`. Those files call a `test` and an `expect` from `@playwright/test`,
|
|
48
|
+
// so a vitest rule reading them reports on an API that is not there. Derived from the
|
|
49
|
+
// preset rather than listed by hand, so a preset bump cannot reopen the gap. The override
|
|
50
|
+
// that uses it is last, and oxlint lets the last override win.
|
|
51
|
+
const vitestRulesOff = Object.fromEntries(
|
|
52
|
+
(vitest.overrides ?? []).flatMap((override) =>
|
|
53
|
+
Object.keys(override.rules ?? {}).map((rule) => [rule, "off"])
|
|
54
|
+
)
|
|
55
|
+
);
|
|
56
|
+
|
|
45
57
|
// Rules turned off for the whole project, each with its reason. Ultracite enables
|
|
46
58
|
// ~470, including whole families oxlint itself files under `style`, `pedantic` and
|
|
47
59
|
// `restriction`. These are the ones that disagree with how the code Saasaloy ships
|
|
@@ -162,6 +174,40 @@ export default defineConfig({
|
|
|
162
174
|
rules: { "unicorn/filename-case": "off" },
|
|
163
175
|
},
|
|
164
176
|
|
|
177
|
+
// The admin app has its own primitive set in packages/ui/src/components/admin/, which
|
|
178
|
+
// `saasaloy add admin` writes. Its names repeat the base ones (`button`, `card`), so an
|
|
179
|
+
// editor's autocomplete offers both and the wrong one renders with no error, in the
|
|
180
|
+
// web app's styling. Inside the admin app and the admin folders of @repo/ui, a base
|
|
181
|
+
// primitive or a base block with an admin twin is a lint error. A project without the
|
|
182
|
+
// admin app has no file under these globs, so the rule never fires there.
|
|
183
|
+
{
|
|
184
|
+
files: [
|
|
185
|
+
"apps/admin/**",
|
|
186
|
+
"packages/ui/src/blocks/admin/**",
|
|
187
|
+
"packages/ui/src/components/admin/**",
|
|
188
|
+
"packages/ui/src/containers/admin/**",
|
|
189
|
+
],
|
|
190
|
+
rules: {
|
|
191
|
+
"no-restricted-imports": [
|
|
192
|
+
"error",
|
|
193
|
+
{
|
|
194
|
+
patterns: [
|
|
195
|
+
{
|
|
196
|
+
group: [
|
|
197
|
+
"@repo/ui/components/*",
|
|
198
|
+
"!@repo/ui/components/admin/*",
|
|
199
|
+
"@repo/ui/blocks/error-state",
|
|
200
|
+
"@repo/ui/blocks/theme-toggle",
|
|
201
|
+
],
|
|
202
|
+
message:
|
|
203
|
+
"Admin code uses the admin set: import from @repo/ui/components/admin/* and @repo/ui/blocks/admin/*.",
|
|
204
|
+
},
|
|
205
|
+
],
|
|
206
|
+
},
|
|
207
|
+
],
|
|
208
|
+
},
|
|
209
|
+
},
|
|
210
|
+
|
|
165
211
|
// The design system is vendored from shadcn and re-synced with
|
|
166
212
|
// `pnpm --filter @repo/ui exec shadcn add …`. `Label` is a primitive: the control
|
|
167
213
|
// it labels is supplied by the call site, which this rule cannot see.
|
|
@@ -238,5 +284,21 @@ export default defineConfig({
|
|
|
238
284
|
files: ["packages/env/scripts/**", "packages/env/src/deploy.ts"],
|
|
239
285
|
rules: { "no-console": "off", "unicorn/no-process-exit": "off" },
|
|
240
286
|
},
|
|
287
|
+
// The Playwright workspace `saasaloy add e2e` writes. Keep this override last; see
|
|
288
|
+
// `vitestRulesOff` above. `prepare.ts` and `global-teardown.ts` are node scripts that
|
|
289
|
+
// report to stdout, the only place a headless run can say anything, and exit with a
|
|
290
|
+
// status the `e2e` script reads.
|
|
291
|
+
{
|
|
292
|
+
files: ["packages/e2e/**"],
|
|
293
|
+
env: { node: true },
|
|
294
|
+
// `plugins` is not optional here. oxlint only honours a rule turned off in an
|
|
295
|
+
// override when that override also names the rule's plugin.
|
|
296
|
+
plugins: ["vitest"],
|
|
297
|
+
rules: {
|
|
298
|
+
...vitestRulesOff,
|
|
299
|
+
"no-console": "off",
|
|
300
|
+
"unicorn/no-process-exit": "off",
|
|
301
|
+
},
|
|
302
|
+
},
|
|
241
303
|
],
|
|
242
304
|
});
|
|
@@ -9,20 +9,23 @@
|
|
|
9
9
|
"pnpm": ">=11"
|
|
10
10
|
},
|
|
11
11
|
"scripts": {
|
|
12
|
-
"prepare": "husky",
|
|
12
|
+
"prepare": "husky && node packages/tooling/src/link-skills.ts",
|
|
13
13
|
"build": "turbo run build",
|
|
14
14
|
"clean": "turbo run clean && rimraf -g node_modules .turbo \"{apps,packages}/*/node_modules\" \"{apps,packages}/*/.turbo\"",
|
|
15
|
-
"deploy:production": "node packages/
|
|
15
|
+
"deploy:production": "node packages/tooling/src/deploy-production.ts",
|
|
16
|
+
"release": "node packages/tooling/src/release.ts",
|
|
17
|
+
"release:dry": "node packages/tooling/src/release.ts --dry-run",
|
|
16
18
|
"dev": "turbo run dev",
|
|
17
19
|
"env:setup": "node packages/env/scripts/env-setup.ts",
|
|
18
20
|
"test": "turbo run test && vitest run",
|
|
19
21
|
"lint": "pnpm run lint:types && pnpm run lint:code && pnpm run lint:css && pnpm run format:check",
|
|
20
|
-
"lint:types": "oxlint -c oxlint.config.mjs --type-aware --deny-warnings packages/env/src packages/ui/src",
|
|
22
|
+
"lint:types": "oxlint -c oxlint.config.mjs --type-aware --deny-warnings packages/config/src packages/env/src packages/tooling/src packages/ui/src",
|
|
21
23
|
"lint:code": "oxlint -c oxlint.config.mjs --deny-warnings .",
|
|
22
24
|
"lint:css": "stylelint \"**/*.css\" --max-warnings 0",
|
|
23
|
-
"lint:fix": "oxlint -c oxlint.config.mjs --type-aware --fix packages/env/src packages/ui/src && oxlint -c oxlint.config.mjs --fix . && stylelint \"**/*.css\" --fix",
|
|
25
|
+
"lint:fix": "oxlint -c oxlint.config.mjs --type-aware --fix packages/config/src packages/env/src packages/tooling/src packages/ui/src && oxlint -c oxlint.config.mjs --fix . && stylelint \"**/*.css\" --fix",
|
|
24
26
|
"format": "prettier --write .",
|
|
25
27
|
"format:check": "prettier --check .",
|
|
28
|
+
"skills:link": "node packages/tooling/src/link-skills.ts",
|
|
26
29
|
"typecheck": "turbo run typecheck"
|
|
27
30
|
},
|
|
28
31
|
"devDependencies": {
|
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
{
|
|
2
|
+
"name": "@repo/config",
|
|
3
|
+
"version": "0.0.0",
|
|
4
|
+
"private": true,
|
|
5
|
+
"type": "module",
|
|
6
|
+
"exports": {
|
|
7
|
+
".": "./src/index.ts",
|
|
8
|
+
"./define": "./src/define.ts"
|
|
9
|
+
},
|
|
10
|
+
"scripts": {
|
|
11
|
+
"clean": "rimraf -g dist \"*.tsbuildinfo\"",
|
|
12
|
+
"typecheck": "tsc --noEmit -p tsconfig.json"
|
|
13
|
+
},
|
|
14
|
+
"devDependencies": {
|
|
15
|
+
"@repo/tsconfig": "workspace:*",
|
|
16
|
+
"rimraf": "6.1.3",
|
|
17
|
+
"typescript": "7.0.2"
|
|
18
|
+
}
|
|
19
|
+
}
|
|
@@ -0,0 +1,134 @@
|
|
|
1
|
+
import { describe, expect, it } from "vitest";
|
|
2
|
+
import { defineConfig, defineSection, defineSections } from "./define";
|
|
3
|
+
|
|
4
|
+
// The merge rules `@repo/config` has to keep, and the two it has to refuse (#154).
|
|
5
|
+
//
|
|
6
|
+
// It runs on Vitest. In a scaffolded project the root `vitest.config.ts` collects it as the
|
|
7
|
+
// `packages/config` project; in the saasaloy repo `pnpm test:tooling` runs it from the
|
|
8
|
+
// template, and `pnpm test:base` (which is `node --test`) skips this package.
|
|
9
|
+
|
|
10
|
+
const app = () =>
|
|
11
|
+
defineSection("app", {
|
|
12
|
+
name: "Acme",
|
|
13
|
+
locale: "en",
|
|
14
|
+
legal: { termsPath: "/terms", privacyPath: "/privacy" },
|
|
15
|
+
tags: ["one", "two"],
|
|
16
|
+
});
|
|
17
|
+
|
|
18
|
+
const tiers = () => defineSection("tiers", { free: { id: "free" } });
|
|
19
|
+
|
|
20
|
+
describe(defineConfig, () => {
|
|
21
|
+
it("composes one property per section key", () => {
|
|
22
|
+
const config = defineConfig({
|
|
23
|
+
sections: defineSections({ sections: [app(), tiers()] }),
|
|
24
|
+
});
|
|
25
|
+
expect(config.app.name).toBe("Acme");
|
|
26
|
+
expect(config.tiers).toStrictEqual({ free: { id: "free" } });
|
|
27
|
+
});
|
|
28
|
+
|
|
29
|
+
it("an override replaces a leaf and keeps its siblings", () => {
|
|
30
|
+
const config = defineConfig({
|
|
31
|
+
sections: defineSections({ sections: [app()] }),
|
|
32
|
+
overrides: { app: { name: "Ledgerly" } },
|
|
33
|
+
});
|
|
34
|
+
expect(config.app.name).toBe("Ledgerly");
|
|
35
|
+
expect(config.app.locale).toBe("en");
|
|
36
|
+
});
|
|
37
|
+
|
|
38
|
+
it("an override replaces a nested record whole", () => {
|
|
39
|
+
const config = defineConfig({
|
|
40
|
+
sections: defineSections({ sections: [app()] }),
|
|
41
|
+
overrides: {
|
|
42
|
+
app: { legal: { termsPath: "/legal", privacyPath: "/legal/privacy" } },
|
|
43
|
+
},
|
|
44
|
+
});
|
|
45
|
+
expect(config.app.legal).toStrictEqual({
|
|
46
|
+
termsPath: "/legal",
|
|
47
|
+
privacyPath: "/legal/privacy",
|
|
48
|
+
});
|
|
49
|
+
});
|
|
50
|
+
|
|
51
|
+
it("an override replaces an array whole", () => {
|
|
52
|
+
const config = defineConfig({
|
|
53
|
+
sections: defineSections({ sections: [app()] }),
|
|
54
|
+
overrides: { app: { tags: ["three"] } },
|
|
55
|
+
});
|
|
56
|
+
expect(config.app.tags).toStrictEqual(["three"]);
|
|
57
|
+
});
|
|
58
|
+
|
|
59
|
+
it("an explicit undefined keeps the seeded value", () => {
|
|
60
|
+
const config = defineConfig({
|
|
61
|
+
sections: defineSections({ sections: [app()] }),
|
|
62
|
+
overrides: { app: { name: undefined } },
|
|
63
|
+
});
|
|
64
|
+
expect(config.app.name).toBe("Acme");
|
|
65
|
+
});
|
|
66
|
+
|
|
67
|
+
it("the result and every section are frozen", () => {
|
|
68
|
+
const config = defineConfig({
|
|
69
|
+
sections: defineSections({ sections: [app()] }),
|
|
70
|
+
});
|
|
71
|
+
expect(Object.isFrozen(config)).toBeTruthy();
|
|
72
|
+
expect(Object.isFrozen(config.app)).toBeTruthy();
|
|
73
|
+
expect(() => {
|
|
74
|
+
(config.app as { name: string }).name = "nope";
|
|
75
|
+
}).toThrow(TypeError);
|
|
76
|
+
});
|
|
77
|
+
|
|
78
|
+
it("freezes nested records and arrays too", () => {
|
|
79
|
+
const config = defineConfig({
|
|
80
|
+
sections: defineSections({ sections: [app()] }),
|
|
81
|
+
});
|
|
82
|
+
expect(Object.isFrozen(config.app.legal)).toBeTruthy();
|
|
83
|
+
expect(Object.isFrozen(config.app.tags)).toBeTruthy();
|
|
84
|
+
expect(() => {
|
|
85
|
+
(config.app.legal as { termsPath: string }).termsPath = "/nope";
|
|
86
|
+
}).toThrow(TypeError);
|
|
87
|
+
});
|
|
88
|
+
|
|
89
|
+
it("shares no object with the declared section or the overrides", () => {
|
|
90
|
+
const section = app();
|
|
91
|
+
const legal = { termsPath: "/legal", privacyPath: "/legal/privacy" };
|
|
92
|
+
const config = defineConfig({
|
|
93
|
+
sections: defineSections({ sections: [section] }),
|
|
94
|
+
overrides: { app: { legal } },
|
|
95
|
+
});
|
|
96
|
+
expect(config.app.legal).not.toBe(legal);
|
|
97
|
+
expect(config.app.tags).not.toBe(section.values.tags);
|
|
98
|
+
expect(Object.isFrozen(section.values.legal)).toBeFalsy();
|
|
99
|
+
expect(Object.isFrozen(legal)).toBeFalsy();
|
|
100
|
+
legal.termsPath = "/changed";
|
|
101
|
+
expect(config.app.legal.termsPath).toBe("/legal");
|
|
102
|
+
});
|
|
103
|
+
|
|
104
|
+
it("a section never mutates the values it was declared with", () => {
|
|
105
|
+
const section = app();
|
|
106
|
+
defineConfig({
|
|
107
|
+
sections: defineSections({ sections: [section] }),
|
|
108
|
+
overrides: { app: { name: "Ledgerly" } },
|
|
109
|
+
});
|
|
110
|
+
expect(section.values.name).toBe("Acme");
|
|
111
|
+
});
|
|
112
|
+
|
|
113
|
+
it("two sections claiming one key throw, naming the key", () => {
|
|
114
|
+
expect(() =>
|
|
115
|
+
defineConfig({
|
|
116
|
+
sections: defineSections({
|
|
117
|
+
sections: [app(), defineSection("app", { name: "Other" })],
|
|
118
|
+
}),
|
|
119
|
+
})
|
|
120
|
+
).toThrow(/claim the key "app"/);
|
|
121
|
+
});
|
|
122
|
+
|
|
123
|
+
it("an override of a section nothing defines throws", () => {
|
|
124
|
+
expect(() =>
|
|
125
|
+
defineConfig({
|
|
126
|
+
sections: defineSections({ sections: [app()] }),
|
|
127
|
+
// Only reachable by hand-editing: `ProjectOverride` rejects this at typecheck, so
|
|
128
|
+
// the cast is the only way to reach the runtime guard.
|
|
129
|
+
// oxlint-disable-next-line typescript/no-unsafe-type-assertion
|
|
130
|
+
overrides: { billing: { appName: "Acme" } } as never,
|
|
131
|
+
})
|
|
132
|
+
).toThrow(/overrides the section "billing"/);
|
|
133
|
+
});
|
|
134
|
+
});
|