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,135 @@
1
+ // The composition core of `@repo/config` (ADR 0052). Three functions and two type
2
+ // helpers, no runtime dependency and no I/O: a section is a plain object, the registry is
3
+ // an array literal, and the composed config is frozen at module load.
4
+ //
5
+ // `config` is the channel for values a project checks into its repo and ships identically
6
+ // to every environment. `env` is the channel for values the platform supplies per
7
+ // deployment. The test a value takes is two deployments of the *same* project: if the
8
+ // value can differ between them it belongs in `env`, secret or not.
9
+
10
+ /** One capability's contribution: a key the config is read under, and its values. */
11
+ export interface ConfigSection<K extends string, V extends object> {
12
+ readonly key: K;
13
+ readonly values: V;
14
+ }
15
+
16
+ /** A section with any key and any values — what the registry array holds. */
17
+ export type AnySection = ConfigSection<string, object>;
18
+
19
+ /**
20
+ * Declare a section. Called by `src/sections/<module>.ts`, which a capability module
21
+ * ships and appends to the registry with its `plugin-array` patch.
22
+ *
23
+ * The key is inferred as a literal so the composed type carries it; the values are
24
+ * inferred *widened* on purpose, so `name: "Acme"` types as `string` and a project may
25
+ * override it with any string rather than only with the seeded one.
26
+ */
27
+ export function defineSection<const K extends string, V extends object>(
28
+ key: K,
29
+ values: V
30
+ ): ConfigSection<K, V> {
31
+ return { key, values };
32
+ }
33
+
34
+ /**
35
+ * The registry. Identity at runtime; it exists so `sections.ts` reads as
36
+ * `export const sections = defineSections({ sections: [...] })` — the exact shape the
37
+ * `plugin-array` codemod (packages/cli/src/lib/patch/ts-module.ts) pushes a section call
38
+ * into. Never omit the `sections` property, even while it is empty.
39
+ */
40
+ export function defineSections<const S extends readonly AnySection[]>(input: {
41
+ sections: S;
42
+ }): S {
43
+ return input.sections;
44
+ }
45
+
46
+ /** The composed shape: one property per section key, holding that section's values. */
47
+ export type Composed<S extends readonly AnySection[]> = {
48
+ readonly [E in S[number] as E["key"]]: E["values"];
49
+ };
50
+
51
+ /**
52
+ * What `src/project.ts` may say. Partial at the section level and partial one level
53
+ * below it, which is exactly how deep the merge goes — so a typo in an override is a
54
+ * `typecheck` failure rather than a value nothing reads.
55
+ */
56
+ export type ConfigOverride<C> = {
57
+ [K in keyof C]?: { [P in keyof C[K]]?: C[K][P] };
58
+ };
59
+
60
+ /**
61
+ * Compose the registered sections, apply the project's overrides, and freeze the result.
62
+ *
63
+ * The merge is one level below the section, and no deeper. `project.ts` replaces a leaf
64
+ * value; a nested record or an array is replaced whole. That keeps the rule explainable
65
+ * in one sentence, which matters more here than saving an owner a few keystrokes.
66
+ *
67
+ * The result is frozen all the way down, and it shares no object with a declared section or
68
+ * with `project.ts`: every record and array is copied before it is frozen, so neither a
69
+ * reader of `config` nor a later edit of the declaration can change the other.
70
+ *
71
+ * Two sections claiming one key throw at module load. `saasaloy add` refuses that pair
72
+ * before it writes, so reaching this throw means the files were edited by hand.
73
+ */
74
+ export function defineConfig<const S extends readonly AnySection[]>(args: {
75
+ sections: S;
76
+ overrides?: ConfigOverride<Composed<S>>;
77
+ }): Composed<S> {
78
+ const composed: Record<string, Record<string, unknown>> = {};
79
+
80
+ for (const section of args.sections) {
81
+ if (section.key in composed) {
82
+ throw new Error(
83
+ `Two config sections claim the key "${section.key}". A section key is the module name, and it has to be unique — rename one of them in packages/config/src/sections/.`
84
+ );
85
+ }
86
+ composed[section.key] = { ...section.values };
87
+ }
88
+
89
+ const overrides = (args.overrides ?? {}) as Record<
90
+ string,
91
+ Record<string, unknown> | undefined
92
+ >;
93
+ for (const [key, patch] of Object.entries(overrides)) {
94
+ const values = composed[key];
95
+ if (patch === undefined) {
96
+ continue;
97
+ }
98
+ if (values === undefined) {
99
+ throw new Error(
100
+ `packages/config/src/project.ts overrides the section "${key}", which no installed module defines.`
101
+ );
102
+ }
103
+ for (const [prop, value] of Object.entries(patch)) {
104
+ // An explicit `undefined` is the owner deleting a line they half-wrote, not a
105
+ // request to unset a seeded value. Skipping it keeps the default.
106
+ if (value !== undefined) {
107
+ values[prop] = value;
108
+ }
109
+ }
110
+ }
111
+
112
+ // The loop above builds exactly the shape `Composed<S>` describes, one property per
113
+ // section key, and no narrower type can be proved from a `Record` the compiler watched
114
+ // being filled. The assertion is the seam between the two, and it is the only one.
115
+ // oxlint-disable-next-line typescript/no-unsafe-type-assertion
116
+ return frozenCopy(composed) as Composed<S>;
117
+ }
118
+
119
+ /**
120
+ * A deep copy of a config value, frozen at every level. Arrays and plain records are
121
+ * copied; anything else (a string, a number, a boolean) is a value already.
122
+ */
123
+ function frozenCopy(value: unknown): unknown {
124
+ if (Array.isArray(value)) {
125
+ return Object.freeze(value.map(frozenCopy));
126
+ }
127
+ if (typeof value === "object" && value !== null) {
128
+ const copy: Record<string, unknown> = {};
129
+ for (const [key, entry] of Object.entries(value)) {
130
+ copy[key] = frozenCopy(entry);
131
+ }
132
+ return Object.freeze(copy);
133
+ }
134
+ return value;
135
+ }
@@ -0,0 +1,34 @@
1
+ import { defineConfig } from "./define";
2
+ import { project } from "./project";
3
+ import { sections } from "./sections";
4
+
5
+ // `@repo/config` — the values this project checks into its repo and ships identically to
6
+ // every environment (ADR 0052).
7
+ //
8
+ // Read it with a plain import, from an app, a capability or a React island alike:
9
+ //
10
+ // ```ts
11
+ // import { config } from "@repo/config";
12
+ // config.app.name;
13
+ // ```
14
+ //
15
+ // There is no factory over `env` and no async: the values are literals in the repo, so the
16
+ // object is built once at module load and frozen. A bundler can inline it.
17
+ //
18
+ // This package has zero runtime dependencies and imports nothing, `@repo/env` included. A
19
+ // value derived from both channels is derived at the call site.
20
+
21
+ /** The composed, frozen config: the base's sections plus every installed module's. */
22
+ export const config = defineConfig({ sections, overrides: project });
23
+
24
+ /** The shape of `config`, inferred from the registered sections. */
25
+ export type Config = typeof config;
26
+
27
+ export { defineConfig, defineSection, defineSections } from "./define";
28
+ export type {
29
+ AnySection,
30
+ Composed,
31
+ ConfigOverride,
32
+ ConfigSection,
33
+ } from "./define";
34
+ export type { ProjectOverride } from "./sections";
@@ -0,0 +1,25 @@
1
+ import type { ProjectOverride } from "./sections";
2
+
3
+ // This is the file you edit.
4
+ //
5
+ // Every other file in `packages/config` is owned by the base template or by a module, and
6
+ // `saasaloy update` may rewrite them. This one is yours: nothing overwrites it, so an
7
+ // override written here survives every update.
8
+ //
9
+ // What belongs here: a value your project checks into its repo and ships identically to
10
+ // every environment — the product name, the locale, a role string.
11
+ //
12
+ // What does not: anything that differs between two deployments of this same project. An
13
+ // API origin, a database url, a Stripe key, a provider selection. Those are `.env` values,
14
+ // secret or not, and `config` deliberately cannot read one.
15
+ //
16
+ // The merge goes one level below the section. `app: { name: "..." }` replaces the name and
17
+ // keeps the rest of `app`; `app: { legal: { termsPath: "/legal/terms" } }` replaces the
18
+ // whole `legal` record, so name every path in it. A key that no installed section defines
19
+ // is a `typecheck` error, which is the whole reason this file is typed.
20
+ export const project: ProjectOverride = {
21
+ app: {
22
+ // name: "Ledgerly",
23
+ // locale: "en-GB",
24
+ },
25
+ };
@@ -0,0 +1,27 @@
1
+ import { defineSection } from "../define";
2
+
3
+ // The one section the base owns. Everything here is a project-level fact that is the same
4
+ // in dev, in staging and in production: the product's name, the locale its HTML declares,
5
+ // and where its legal pages live.
6
+ //
7
+ // Words do not belong here. A sentence a reader sees lives in `packages/ui/src/content/`.
8
+
9
+ /** The base's `app` section. Override any leaf of it in `../project.ts`. */
10
+ export function app() {
11
+ return defineSection("app", {
12
+ /**
13
+ * The product name. `siteName` in `@repo/ui` re-exports it, and emails read it. It
14
+ * ships as "Saasaloy" because the default landing page describes Saasaloy itself, so
15
+ * the name and the copy agree on a fresh project. Set yours in `../project.ts`.
16
+ */
17
+ name: "Saasaloy",
18
+ /** The BCP 47 tag `<html lang>` declares. One string; translation is a separate job. */
19
+ locale: "en",
20
+ /**
21
+ * Where the legal pages live. `apps/web` ships both, and the footer links them.
22
+ * A nested record is replaced whole by an override, so name both paths when you
23
+ * change one.
24
+ */
25
+ legal: { termsPath: "/terms", privacyPath: "/privacy" },
26
+ });
27
+ }
@@ -0,0 +1,22 @@
1
+ import type { Composed, ConfigOverride } from "./define";
2
+ import { defineSections } from "./define";
3
+ import { app } from "./sections/app";
4
+
5
+ // The section registry, and the one patch point in this package. `saasaloy add auth` adds
6
+ // an import of `./sections/auth` and appends `authConfig()` to the array below; `remove`
7
+ // takes both back out. The install is idempotent, so re-running it changes nothing.
8
+ //
9
+ // Keep this line in exactly this shape: `export const sections = defineSections({
10
+ // sections: [...] })` with a real array literal. The codemod behind the `plugin-array`
11
+ // patch kind (packages/cli/src/lib/patch/ts-module.ts) has nothing to push into
12
+ // otherwise, and the install fails silently. Never omit `sections`, even while it is
13
+ // empty.
14
+ //
15
+ // A module's section file lands here, under `src/sections/`, rather than inside the
16
+ // capability's own package. `@repo/config` is the leaf of the dependency graph: it imports
17
+ // nothing, so that every app and every capability can import it — including the ones it
18
+ // would otherwise have to import back.
19
+ export const sections = defineSections({ sections: [app()] });
20
+
21
+ /** What `./project.ts` may override: any leaf of any registered section. */
22
+ export type ProjectOverride = ConfigOverride<Composed<typeof sections>>;
@@ -0,0 +1,4 @@
1
+ {
2
+ "extends": "@repo/tsconfig/base.json",
3
+ "include": ["src"]
4
+ }
@@ -16,7 +16,8 @@
16
16
  "./services": "./src/services.ts",
17
17
  "./zod": "./src/zod.ts",
18
18
  "./sources": "./src/sources.ts",
19
- "./setup": "./src/setup.ts"
19
+ "./setup": "./src/setup.ts",
20
+ "./deploy": "./src/deploy.ts"
20
21
  },
21
22
  "scripts": {
22
23
  "clean": "rimraf -g dist \"*.tsbuildinfo\"",
@@ -173,8 +173,9 @@ function loginProblem(
173
173
 
174
174
  /**
175
175
  * Every service's production values, before anything builds. An empty result means a
176
- * deploy can start. `pnpm deploy:production` runs this ahead of `turbo run deploy`, so a
177
- * blank key stops the run before the first Worker uploads.
176
+ * deploy can start. `pnpm deploy:production` (the engine in `packages/tooling`) runs this
177
+ * through `deploy.ts --check` after its gates and before the first Worker deploys, so a
178
+ * blank key stops the run before anything uploads.
178
179
  */
179
180
  export async function checkProduction(options: {
180
181
  root: string;
@@ -37,14 +37,21 @@ addService({
37
37
  omit: ["DATABASE_URL"],
38
38
  });
39
39
 
40
+ // A module appends its own row (`saasaloy add admin` adds `admin`), so these tests never
41
+ // pin the whole table. They check the rows the base seeds and the two added above, and
42
+ // derive anything else from the table itself.
40
43
  describe("the service table", () => {
41
44
  it("seeds web and deploy, and takes the rows a const-array patch appends", () => {
42
- assert.deepEqual(serviceNames().toSorted(), [
43
- "api",
44
- "deploy",
45
- "ops",
46
- "web",
47
- ]);
45
+ const names = serviceNames();
46
+ for (const name of ["web", "deploy", "api", "ops"]) {
47
+ assert.ok(names.includes(name), `${name} is in the table`);
48
+ }
49
+ assert.equal(
50
+ new Set(names).size,
51
+ names.length,
52
+ "no service is listed twice"
53
+ );
54
+ assert.equal(findService("web")?.file, "apps/web/.env");
48
55
  assert.equal(findService("ops")?.file, "ops/.env");
49
56
  assert.equal(findService("deploy")?.file, undefined);
50
57
  assert.equal(findService("nope"), undefined);
@@ -53,11 +60,20 @@ describe("the service table", () => {
53
60
 
54
61
  describe("selectServices", () => {
55
62
  it("writes every dev service when nothing is named", () => {
56
- assert.deepEqual(
57
- selectServices("dev")
58
- .map((service) => service.name)
59
- .toSorted(),
60
- ["api", "web"]
63
+ const selected = selectServices("dev").map((service) => service.name);
64
+ const expected = SERVICES.filter(
65
+ (service) => service.environment === "dev" && service.file !== undefined
66
+ ).map((service) => service.name);
67
+ assert.deepEqual(selected.toSorted(), expected.toSorted());
68
+ assert.ok(selected.includes("web"));
69
+ assert.ok(selected.includes("api"));
70
+ assert.ok(
71
+ !selected.includes("ops"),
72
+ "a prod service is never a dev default"
73
+ );
74
+ assert.ok(
75
+ !selected.includes("deploy"),
76
+ "a row with no file is never written"
61
77
  );
62
78
  });
63
79
 
@@ -0,0 +1,21 @@
1
+ {
2
+ "name": "@repo/tooling",
3
+ "version": "0.0.0",
4
+ "private": true,
5
+ "type": "module",
6
+ "scripts": {
7
+ "clean": "rimraf -g dist \"*.tsbuildinfo\"",
8
+ "typecheck": "tsc --noEmit"
9
+ },
10
+ "dependencies": {
11
+ "@release-it/conventional-changelog": "12.0.0",
12
+ "@repo/env": "workspace:*",
13
+ "release-it": "21.0.2"
14
+ },
15
+ "devDependencies": {
16
+ "@repo/tsconfig": "workspace:*",
17
+ "@types/node": "26.4.1",
18
+ "rimraf": "6.1.3",
19
+ "typescript": "7.0.2"
20
+ }
21
+ }