@sssb/create 0.0.0 → 0.3.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 (91) hide show
  1. package/LICENSE +21 -0
  2. package/bin/create.js +136 -0
  3. package/package.json +26 -5
  4. package/src/add-app.js +165 -0
  5. package/src/args.js +270 -0
  6. package/src/files.js +677 -0
  7. package/src/generate.js +612 -0
  8. package/src/json.js +60 -0
  9. package/src/signals.js +72 -0
  10. package/src/template.js +496 -0
  11. package/src/yaml.js +17 -0
  12. package/template/app/DEMO-SIZE.md +55 -0
  13. package/template/app/config/app.ts +17 -0
  14. package/template/app/config/params.ts +85 -0
  15. package/template/app/infra/README.md +85 -0
  16. package/template/app/infra/app.ts +45 -0
  17. package/template/app/infra/cdk.json +9 -0
  18. package/template/app/infra/lib/tags.ts +35 -0
  19. package/template/app/infra/package.json +20 -0
  20. package/template/app/infra/tsconfig.json +13 -0
  21. package/template/app/messages/en.json +21 -0
  22. package/template/app/messages/es.json +21 -0
  23. package/template/app/next.config.ts +9 -0
  24. package/template/app/package.json +40 -0
  25. package/template/app/playwright.config.ts +50 -0
  26. package/template/app/playwright.demo.config.ts +10 -0
  27. package/template/app/src/app/[locale]/(protected)/dashboard/dashboard-glue.tsx +61 -0
  28. package/template/app/src/app/[locale]/(protected)/dashboard/page.tsx +21 -0
  29. package/template/app/src/app/[locale]/(protected)/header-glue.tsx +59 -0
  30. package/template/app/src/app/[locale]/(protected)/layout.tsx +43 -0
  31. package/template/app/src/app/[locale]/layout.tsx +63 -0
  32. package/template/app/src/app/[locale]/page.tsx +9 -0
  33. package/template/app/src/app/[locale]/signin/page.tsx +55 -0
  34. package/template/app/src/app/[locale]/signin/picker-glue.tsx +21 -0
  35. package/template/app/src/app/api/auth/dev-signin/route.ts +12 -0
  36. package/template/app/src/app/api/auth/org/route.ts +10 -0
  37. package/template/app/src/app/api/auth/signout/route.ts +9 -0
  38. package/template/app/src/app/api/items/route.ts +59 -0
  39. package/template/app/src/app/api/respond.ts +13 -0
  40. package/template/app/src/app/api/simulator/[...path]/route.ts +23 -0
  41. package/template/app/src/app/api/webhooks/cron/route.test.ts +59 -0
  42. package/template/app/src/app/api/webhooks/cron/route.ts +16 -0
  43. package/template/app/src/app/layout.tsx +7 -0
  44. package/template/app/src/app-config/abilities.ts +86 -0
  45. package/template/app/src/app-config/actors.ts +13 -0
  46. package/template/app/src/app-config/audit.ts +9 -0
  47. package/template/app/src/app-config/db/migrations/1001_items.ts +37 -0
  48. package/template/app/src/app-config/db/migrations/1002_items_keyset_index.ts +29 -0
  49. package/template/app/src/app-config/db/migrations/index.ts +13 -0
  50. package/template/app/src/app-config/db/rls-proofs.ts +186 -0
  51. package/template/app/src/app-config/db/schema.ts +23 -0
  52. package/template/app/src/app-config/digest.ts +10 -0
  53. package/template/app/src/app-config/identity.ts +8 -0
  54. package/template/app/src/app-config/inbound-email.ts +10 -0
  55. package/template/app/src/app-config/jobs.ts +28 -0
  56. package/template/app/src/app-config/messages.ts +18 -0
  57. package/template/app/src/app-config/notifications.ts +31 -0
  58. package/template/app/src/app-config/preset-operations.ts +9 -0
  59. package/template/app/src/app-config/presets.ts +18 -0
  60. package/template/app/src/app-config/seed.ts +7 -0
  61. package/template/app/src/app-config/simulator.ts +17 -0
  62. package/template/app/src/app-config/tours.ts +14 -0
  63. package/template/app/src/app-config/webhooks.ts +13 -0
  64. package/template/app/src/components/dashboard-screen.tsx +26 -0
  65. package/template/app/src/components/items-card.tsx +106 -0
  66. package/template/app/src/components/welcome-screen.tsx +20 -0
  67. package/template/app/src/demo-static/app.tsx +77 -0
  68. package/template/app/src/demo-static/index.html +12 -0
  69. package/template/app/src/demo-static/main.tsx +40 -0
  70. package/template/app/src/domain/db/items.ts +37 -0
  71. package/template/app/src/proxy.test.ts +44 -0
  72. package/template/app/src/proxy.ts +18 -0
  73. package/template/app/src/seed/index.ts +93 -0
  74. package/template/app/src/sssb.conformance.test.ts +7 -0
  75. package/template/app/src/styles/index.css +1 -0
  76. package/template/app/tests/catalog.ts +15 -0
  77. package/template/app/tests/contract/rls-contract.test.ts +14 -0
  78. package/template/app/tests/demo-static/static-shell.spec.ts +32 -0
  79. package/template/app/tests/e2e/items.spec.ts +102 -0
  80. package/template/app/tests/e2e/simulator.spec.ts +40 -0
  81. package/template/app/tsconfig.json +29 -0
  82. package/template/app/vite.demo.config.ts +8 -0
  83. package/template/guide.md +132 -0
  84. package/template/meta.json +633 -0
  85. package/template/root/_dot_editorconfig +12 -0
  86. package/template/root/_dot_husky/commit-msg +1 -0
  87. package/template/root/_dot_husky/pre-commit +1 -0
  88. package/template/root/_dot_nvmrc +1 -0
  89. package/template/root/_dot_prettierrc.json +5 -0
  90. package/template/root/commitlint.config.mjs +1 -0
  91. package/README.md +0 -3
package/src/files.js ADDED
@@ -0,0 +1,677 @@
1
+ // @ts-check
2
+ // The workspace-level files the generator WRITES rather than copies: every one whose copy in SSSB's repository names
3
+ // that repository (its two apps, its framework package, its fixture, its maintainers), so a copy would carry SSSB's
4
+ // identity into the adopter's. Each function returns a file's text, laid out as the workspace's own Prettier would.
5
+ import { PLACEHOLDER_OWNER, PLACEHOLDER_REPO } from './args.js'
6
+ import { formatJson, packageJson } from './json.js'
7
+ import { yamlString } from './yaml.js'
8
+
9
+ /**
10
+ * `pnpm verify`: everything CI runs that can run on a laptop, so a local green is a CI green. SSSB's reusable
11
+ * workflow's jobs (lint, typecheck and the coverage run, each app's fences, doctor and e2e-import check; the contract
12
+ * tests; the e2e suites; the static demo; the synth) and the workspace's own (knip, jscpd). Only the secret scan
13
+ * (gitleaks, a binary CI downloads) is CI's alone. The contract tests run on their own, after the parallel group:
14
+ * embedded Postgres starting under a loaded machine is the one step here that times out.
15
+ */
16
+ const VERIFY =
17
+ "concurrently --kill-others-on-fail --group 'pnpm:typecheck' 'pnpm:lint' 'pnpm:test:coverage' 'pnpm:knip' " +
18
+ "'pnpm:jscpd' 'pnpm:check:fences' 'pnpm:sssb:doctor' 'pnpm:check:e2e' 'pnpm:synth' && pnpm test:contract && " +
19
+ 'pnpm test:e2e && pnpm build:demo-static && pnpm check:demo-size && pnpm e2e:demo-static'
20
+
21
+ /**
22
+ * @typedef {{
23
+ * slug: string,
24
+ * name: string,
25
+ * repo: string | null,
26
+ * owners: string[],
27
+ * meta: import('./template.js').TemplateMeta,
28
+ * sssbSpec: (pkg: string) => string,
29
+ * workflowRef: string,
30
+ * }} Context
31
+ */
32
+
33
+ /** @param {Context} c */
34
+ const app = (c) => `apps/${c.slug}`
35
+
36
+ /** @param {Context} c */
37
+ const repoOrPlaceholder = (c) => c.repo ?? `${PLACEHOLDER_OWNER}/${PLACEHOLDER_REPO}`
38
+
39
+ /** @param {Context} c */
40
+ export function rootPackageJson(c) {
41
+ const filter = `--filter ${c.slug}`
42
+ // A selector that matches no app fails, rather than running nothing and passing.
43
+ const apps = "--filter './apps/*' --fail-if-no-match"
44
+ return packageJson({
45
+ // Not the slug: a root package named like the app makes `pnpm --filter <slug>` match both, and the root's
46
+ // scripts fan out to every app.
47
+ name: `${c.slug}-workspace`,
48
+ version: '0.1.0',
49
+ private: true,
50
+ type: 'module',
51
+ description: `${c.name}: a multi-tenant web application built on SSSB.`,
52
+ packageManager: c.meta.packageManager,
53
+ engines: c.meta.engines,
54
+ scripts: {
55
+ dev: `pnpm ${filter} dev`,
56
+ tick: `pnpm ${filter} tick`,
57
+ build: `pnpm ${apps} --workspace-concurrency=1 build`,
58
+ start: `pnpm ${filter} start`,
59
+ prepare: 'husky && sssb launch-json',
60
+ typecheck: `pnpm ${apps} typecheck && tsc --noEmit`,
61
+ lint: 'eslint . && prettier --check --log-level warn .',
62
+ 'lint:fix': 'eslint --fix . && prettier --write --log-level warn .',
63
+ 'test:unit': 'sssb check-tmpdir-leak vitest run',
64
+ 'test:coverage': 'sssb check-tmpdir-leak vitest run --coverage',
65
+ 'test:contract': 'sssb check-tmpdir-leak vitest run --config vitest.contract.config.ts',
66
+ 'test:e2e': `pnpm ${apps} --workspace-concurrency=1 test:e2e`,
67
+ knip: 'knip',
68
+ jscpd: 'jscpd',
69
+ // One run checks every app of the workspace. The root takes no @sssb/kit, so with no `--app` doctor starts from
70
+ // the workspace's first app (`sssb.apps` below): `pnpm exec sssb doctor` works from here, as the docs say.
71
+ 'sssb:doctor': 'sssb doctor',
72
+ // Each app's lint fences as its own config composes them (SSSB's reusable workflow runs this per app).
73
+ 'check:fences': `pnpm ${apps} exec sssb check-fences`,
74
+ 'check:e2e': `pnpm ${apps} check:e2e`,
75
+ 'build:demo-static': `pnpm ${apps} build:demo-static`,
76
+ 'check:demo-size': `pnpm ${apps} check:demo-size`,
77
+ 'e2e:demo-static': `pnpm ${apps} e2e:demo-static`,
78
+ synth: "pnpm --filter './apps/*/infra' --fail-if-no-match synth",
79
+ verify: VERIFY,
80
+ },
81
+ devDependencies: Object.fromEntries(
82
+ Object.entries({ ...c.meta.ranges, '@sssb/tools': c.sssbSpec('tools') }).sort(([a], [b]) =>
83
+ a.localeCompare(b),
84
+ ),
85
+ ),
86
+ sssb: { apps: [app(c)] },
87
+ })
88
+ }
89
+
90
+ /** @param {Context} c */
91
+ export function pnpmWorkspace(c) {
92
+ const lines = [
93
+ 'packages:',
94
+ ' - apps/*',
95
+ ' - apps/*/infra',
96
+ " # Each app's seam, src/app-config: a workspace package, so `pnpm add <pkg>`, `remove` and `update <pkg>` for",
97
+ ' # the app keep it linked into its @sssb/kit (a `link:` they drop). `pnpm sssb:doctor` checks it.',
98
+ ' - apps/*/src/app-config',
99
+ ' - packages/*',
100
+ '',
101
+ "# pnpm blocks dependencies' install scripts unless they are approved here: these are the ones the app and SSSB's",
102
+ '# packages bring. Every platform embedded-postgres ships is approved, not only the one you work on: the block is',
103
+ '# silent, and on a platform left out `pnpm test:contract` fails with an error that never mentions it.',
104
+ 'allowBuilds:',
105
+ ...Object.entries(c.meta.allowBuilds).map(
106
+ ([pkg, allowed]) => ` ${/^[a-z0-9][a-z0-9._-]*$/.test(pkg) ? pkg : yamlString(pkg)}: ${allowed}`,
107
+ ),
108
+ '',
109
+ '# Each importer of @sssb/kit gets an instance of its own, linked to its own @sssb/app-config, or none (ADR-0014',
110
+ "# part 5). Without it a package that takes the framework and links no seam silently shares an app's; after",
111
+ '# changing it, reinstall from a fresh lockfile. `pnpm exec sssb doctor` checks it.',
112
+ 'dedupePeerDependents: false',
113
+ '',
114
+ "# @sssb/eslint-plugin's preset needs eslint-plugin-react and eslint-plugin-jsx-a11y, whose latest releases still",
115
+ '# declare eslint 9 as their highest peer. The preset runs them under eslint 10 (it is what SSSB lints with), so',
116
+ '# the warning on every first install is noise. These two entries, and only these, allow it; delete them once',
117
+ '# both plugins list eslint 10 (`pnpm peers check` shows what is left).',
118
+ 'peerDependencyRules:',
119
+ ' allowedVersions:',
120
+ " 'eslint-plugin-react>eslint': '10'",
121
+ " 'eslint-plugin-jsx-a11y>eslint': '10'",
122
+ ]
123
+ if (c.meta.minimumReleaseAge !== null) {
124
+ lines.push(
125
+ '',
126
+ "# Supply-chain guard: only install package versions published at least this many minutes ago. SSSB's own",
127
+ "# packages are exempt: SSSB's CI gates their releases, and a fix should not wait out the delay.",
128
+ `minimumReleaseAge: ${c.meta.minimumReleaseAge}`,
129
+ 'minimumReleaseAgeExclude:',
130
+ " - '@sssb/*'",
131
+ )
132
+ }
133
+ return `${lines.join('\n')}\n`
134
+ }
135
+
136
+ export const GITIGNORE = `# dependencies
137
+ node_modules/
138
+
139
+ # builds
140
+ .next/
141
+ out/
142
+ dist/
143
+ build/
144
+
145
+ # Next's generated ambient types, written by \`next typegen\` (each app's typecheck and build run it first) and
146
+ # \`next dev\`, which disagree on its contents
147
+ next-env.d.ts
148
+
149
+ # local data written by the fake adapters (pglite, storage, caught emails)
150
+ .data/
151
+
152
+ # test output
153
+ coverage/
154
+ playwright-report/
155
+ test-results/
156
+
157
+ # env and secrets: secret values never live in the repository
158
+ .env
159
+ .env.*
160
+ !.env.example
161
+
162
+ # tooling caches
163
+ *.tsbuildinfo
164
+ .eslintcache
165
+
166
+ # the static demo's build output
167
+ dist-demo/
168
+
169
+ # cdk synth output
170
+ apps/*/infra/cdk.out/
171
+
172
+ # machine-local Claude Code settings, and the launch configuration \`sssb launch-json\` writes per checkout
173
+ .claude/settings.local.json
174
+ .claude/launch.json
175
+
176
+ # OS
177
+ .DS_Store
178
+ `
179
+
180
+ export const PRETTIERIGNORE = `node_modules/
181
+ .next/
182
+ out/
183
+ dist/
184
+ build/
185
+ coverage/
186
+ playwright-report/
187
+ test-results/
188
+ pnpm-lock.yaml
189
+ .data/
190
+ **/next-env.d.ts
191
+ dist-demo/
192
+ apps/*/infra/cdk.out/
193
+ `
194
+
195
+ export const LINT_STAGED = `export default {
196
+ // Every extension ESLint lints: a staged \`.mts\` is linted like a \`.ts\`.
197
+ '*.{ts,tsx,mts,cts,js,jsx,mjs,cjs}': ['eslint --fix', 'prettier --write'],
198
+ '*.{json,md,yaml,yml,css}': ['prettier --write'],
199
+ }
200
+ `
201
+
202
+ /**
203
+ * The workspace root's own lint config, for what no app's config covers: the root's files and packages/*. Each app's
204
+ * eslint.config.mjs (SSSB's preset) lints that app's files wherever ESLint starts, because ESLint 10 takes each file's
205
+ * nearest config.
206
+ */
207
+ export const ROOT_ESLINT = `import js from '@eslint/js'
208
+ import tseslint from 'typescript-eslint'
209
+
210
+ // The workspace root's lint config: the root's own files and packages/*. Each app's files are linted by the app's own
211
+ // eslint.config.mjs (SSSB's fences, @sssb/eslint-plugin's preset), wherever ESLint is started: ESLint takes each
212
+ // file's nearest config. The raw typescript-eslint configs and an explicit tsconfigRootDir, because
213
+ // typescript-eslint's \`configs\` getter records each config file that reads it and its parser refuses to guess
214
+ // between two.
215
+ export default [
216
+ { ignores: ['**/node_modules/**', '**/.next/**', '**/dist-demo/**', 'coverage/**'] },
217
+ js.configs.recommended,
218
+ ...tseslint.plugin.configs['flat/recommended'],
219
+ {
220
+ languageOptions: {
221
+ parserOptions: { tsconfigRootDir: import.meta.dirname },
222
+ globals: { process: 'readonly', console: 'readonly' },
223
+ },
224
+ },
225
+ ]
226
+ `
227
+
228
+ export const APP_ESLINT = `import sssb from '@sssb/eslint-plugin'
229
+
230
+ // SSSB's lint fences for this app (@sssb/eslint-plugin's preset), with this app's own exceptions read from
231
+ // lint-exceptions.mjs when it has one. Add your own blocks after the preset's; \`pnpm exec sssb check-fences\` fails
232
+ // when one of them switches a fence off.
233
+ export default [...(await sssb.configs.app({ root: import.meta.dirname }))]
234
+ `
235
+
236
+ export const ROOT_TSCONFIG = formatJson({
237
+ extends: '@sssb/tools/tsconfig.base.json',
238
+ compilerOptions: { lib: ['dom', 'dom.iterable', 'esnext'], types: ['node'] },
239
+ include: ['*.ts'],
240
+ })
241
+
242
+ /**
243
+ * The workspace's unit run: a Vitest project per app the root's `sssb.apps` names, from SSSB's preset, so a second app
244
+ * joins it by its entry there (`sssb add-app` writes one).
245
+ */
246
+ export const VITEST_CONFIG = `import { fileURLToPath } from 'node:url'
247
+ import { workspaceAppProjects } from '@sssb/tools/vitest'
248
+ import { defineConfig, type ViteUserConfig } from 'vitest/config'
249
+
250
+ const at = (relative: string) => fileURLToPath(new URL(relative, import.meta.url))
251
+
252
+ /**
253
+ * ONE PROJECT PER APP, from SSSB's preset (@sssb/tools/vitest), for every app the root package.json's \`sssb.apps\`
254
+ * names: the framework reads the app's registrations through the bare specifier \`@sssb/app-config/*\`, which one
255
+ * project can resolve for one app only, so each app's project passes its own seam. Each app's conformance suite
256
+ * (src/sssb.conformance.test.ts) runs in its project like any other test; \`pnpm exec sssb doctor\` fails if this
257
+ * config stops running it.
258
+ */
259
+ export default defineConfig(async (): Promise<ViteUserConfig> => ({
260
+ test: {
261
+ projects: await workspaceAppProjects({ root: at('.') }),
262
+ coverage: {
263
+ provider: 'v8',
264
+ include: ['apps/*/src/**/*.{ts,tsx}', 'packages/*/src/**/*.{ts,tsx}'],
265
+ exclude: ['apps/*/src/demo-static/**', '**/*.stories.tsx', '**/*.test.{ts,tsx}'],
266
+ // json-summary: SSSB's reusable workflow puts the totals on the run's page.
267
+ reporter: ['text-summary', 'json-summary'],
268
+ },
269
+ },
270
+ }))
271
+ `
272
+
273
+ /** The workspace's contract run: the same project per app, narrowed to its tests/contract. */
274
+ export const VITEST_CONTRACT_CONFIG = `import { fileURLToPath } from 'node:url'
275
+ import { workspaceAppProjects } from '@sssb/tools/vitest'
276
+ import { defineConfig, type ViteUserConfig } from 'vitest/config'
277
+
278
+ const at = (relative: string) => fileURLToPath(new URL(relative, import.meta.url))
279
+
280
+ /**
281
+ * The contract tests: each app's tests/contract (SSSB's contract runner, @sssb/kit/testing/contract) against real
282
+ * Postgres, a database of the app's own. The preset's project for every app the root package.json's \`sssb.apps\`
283
+ * names, narrowed to tests/contract, in Node, one file at a time, because every app's embedded Postgres takes the one
284
+ * port (CONTRACT_DATABASE_URL names a server instead; CI passes its service container's). The unit config never
285
+ * reaches tests/contract.
286
+ */
287
+ export default defineConfig(async (): Promise<ViteUserConfig> => ({
288
+ test: {
289
+ fileParallelism: false,
290
+ projects: (await workspaceAppProjects({ root: at('.') })).map((project) => ({
291
+ ...project,
292
+ test: { ...project.test, environment: 'node', include: ['tests/contract/**/*.test.ts'] },
293
+ })),
294
+ },
295
+ }))
296
+ `
297
+
298
+ /** @param {Context} c */
299
+ export function knipJson(c) {
300
+ return formatJson({
301
+ $schema: 'https://unpkg.com/knip@6/schema.json',
302
+ workspaces: {
303
+ '.': {
304
+ // knip's Vitest plugin reads vitest.config.ts only.
305
+ entry: ['vitest.contract.config.ts'],
306
+ // @sssb/cdk bundles the app's migrator with the workspace root's esbuild at synth.
307
+ ignoreDependencies: ['esbuild'],
308
+ },
309
+ [app(c)]: {
310
+ entry: ['src/demo-static/**/*.{ts,tsx}', 'src/seed/*.ts'],
311
+ project: ['src/**'],
312
+ // The seam (@sssb/kit resolves it), and the tools SSSB's presets load from the app's directory
313
+ // (@sssb/tools/vite and /vitest), none of which the app imports.
314
+ ignoreDependencies: ['@sssb/app-config', '@vitejs/plugin-react', 'vite-plugin-singlefile'],
315
+ },
316
+ // The seam, a workspace package of its own: read mostly by SSSB's framework, from node_modules, which knip
317
+ // does not follow.
318
+ [`${app(c)}/src/app-config`]: { entry: ['**/*.ts'] },
319
+ },
320
+ })
321
+ }
322
+
323
+ export const JSCPD = formatJson({
324
+ pattern: '{apps/*/src,packages/*/src}/**/*.{ts,tsx}',
325
+ ignore: ['**/*.test.{ts,tsx}', '**/*.stories.tsx'],
326
+ minTokens: 70,
327
+ minLines: 8,
328
+ threshold: 2,
329
+ reporters: ['consoleFull'],
330
+ gitignore: true,
331
+ })
332
+
333
+ export const GITLEAKS = `# gitleaks' default rules (the secret-scan job in .github/workflows/checks.yml). Add an allowlist entry only with a
334
+ # justification, scoped to one file AND one string (\`condition = "AND"\`), so a real leak elsewhere is still caught.
335
+ [extend]
336
+ useDefault = true
337
+ `
338
+
339
+ /** @param {Context} c */
340
+ export function codeowners(c) {
341
+ if (c.owners.length === 0) {
342
+ return `# Who reviews what. @${PLACEHOLDER_OWNER} is not a real account: replace it with the GitHub user or team who
343
+ # should review changes here before you turn on "require review from Code Owners". With an owner GitHub does not
344
+ # know, that setting makes every pull request unmergeable.
345
+ * @${PLACEHOLDER_OWNER}
346
+ `
347
+ }
348
+ return `# Who reviews what: every change, by default. Narrow it with path entries below as the workspace grows.
349
+ * ${c.owners.join(' ')}
350
+ `
351
+ }
352
+
353
+ /** @param {Context} c */
354
+ export function securityMd(c) {
355
+ return `# Security policy
356
+
357
+ ## Reporting a vulnerability
358
+
359
+ Report privately through **[GitHub Security Advisories](https://github.com/${repoOrPlaceholder(c)}/security/advisories/new)**.
360
+ Please do not open a public issue for a vulnerability.
361
+
362
+ Include what you did, what happened, and what you expected. A failing test or a \`curl\` is worth more than a
363
+ paragraph.
364
+
365
+ ## Built on SSSB
366
+
367
+ This app, ${c.name}, is built on SSSB's packages (\`@sssb/*\`). If the root cause is a shape SSSB gave it (tenant
368
+ isolation, authorization, the fail-closed production guard), please report it to SSSB as well, through the security
369
+ policy of the repository its packages name in their \`package.json\`: every app built on SSSB has the same shape.
370
+ `
371
+ }
372
+
373
+ /** @param {Context} c */
374
+ export function codeOfConduct(c) {
375
+ return `# Code of conduct
376
+
377
+ ## The short version
378
+
379
+ Be decent. Assume good faith. Argue about the code, not the person.
380
+
381
+ ## Our pledge
382
+
383
+ We pledge to make participation in this project a harassment-free experience for everyone, regardless of age, body
384
+ size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of
385
+ experience, education, socio-economic status, nationality, personal appearance, race, religion, or sexual identity
386
+ and orientation.
387
+
388
+ ## Enforcement
389
+
390
+ Report unacceptable behaviour through
391
+ **[GitHub Security Advisories](https://github.com/${repoOrPlaceholder(c)}/security/advisories/new)**, a public
392
+ repository's private inbound channel. All complaints will be reviewed and investigated promptly and fairly, and the
393
+ reporter's privacy will be respected.
394
+
395
+ ## Attribution
396
+
397
+ Adapted from the [Contributor Covenant](https://www.contributor-covenant.org), version 2.1.
398
+ `
399
+ }
400
+
401
+ /** @param {Context} c */
402
+ export function issueConfig(c) {
403
+ return `blank_issues_enabled: true
404
+ contact_links:
405
+ - name: Security vulnerability
406
+ url: https://github.com/${repoOrPlaceholder(c)}/security/advisories/new
407
+ about: Report privately through GitHub Security Advisories, not a public issue. See SECURITY.md.
408
+ `
409
+ }
410
+
411
+ export const BUG_REPORT = `name: Bug report
412
+ description: Something behaves differently than it should
413
+ labels: [bug]
414
+ body:
415
+ - type: textarea
416
+ id: what
417
+ attributes:
418
+ label: What happened
419
+ description: What you did, what happened, what you expected instead.
420
+ validations:
421
+ required: true
422
+ - type: textarea
423
+ id: repro
424
+ attributes:
425
+ label: How to reproduce
426
+ description: Commands or steps. A failing test is worth more than a description.
427
+ validations:
428
+ required: true
429
+ `
430
+
431
+ /** @param {Context} c */
432
+ export function workflow(c) {
433
+ return `# This workspace's checks. SSSB's checks for the app are SSSB's REUSABLE WORKFLOW, called here pinned to a commit
434
+ # of SSSB's repository (a tag can be moved; a commit cannot). Require the check \`sssb / all-checks\` in your branch
435
+ # protection or ruleset: it fails unless every one of SSSB's jobs ran and passed, so a skipped or renamed job cannot
436
+ # slip out of the requirement. Raise the pin when you upgrade the @sssb packages: \`pnpm exec sssb pin\` raises it, and
437
+ # the plugin marketplace's in .claude/settings.json, to the installed @sssb/kit's release commit.
438
+ #
439
+ # The reusable workflow takes no secrets: never pass it \`secrets: inherit\`. If this repository is private and in an
440
+ # organization, the organization must allow public reusable workflows in its Actions settings.
441
+ name: checks
442
+
443
+ on:
444
+ push:
445
+ branches: [main]
446
+ pull_request:
447
+
448
+ # Least privilege: nothing by default, and each job states its own.
449
+ permissions: {}
450
+
451
+ concurrency:
452
+ group: checks-\${{ github.event_name == 'push' && github.sha || github.ref }}
453
+ cancel-in-progress: true
454
+
455
+ jobs:
456
+ # Lint, typecheck and unit tests with SSSB's fence, doctor and e2e-import checks, the contract tests on real
457
+ # Postgres, the e2e shards, the static demo, the CDK synth, and \`all-checks\`. Its checks are named \`sssb / <job>\`.
458
+ sssb:
459
+ uses: ${c.meta.workflow.repository}/.github/workflows/app-checks.yml@${c.workflowRef} # @sssb/create ${c.meta.version}
460
+ permissions:
461
+ contents: read
462
+ with:
463
+ synth: ./${app(c)}/infra
464
+
465
+ # What SSSB's workflow does not run: dead code (knip) and duplication (jscpd).
466
+ workspace-checks:
467
+ runs-on: ubuntu-latest
468
+ permissions:
469
+ contents: read
470
+ steps:
471
+ - uses: ${c.meta.actions['actions/checkout']}
472
+ - uses: ${c.meta.actions['pnpm/action-setup']}
473
+ - uses: ${c.meta.actions['actions/setup-node']}
474
+ with:
475
+ node-version-file: .nvmrc
476
+ cache: pnpm
477
+ - run: pnpm install --frozen-lockfile
478
+ - run: pnpm knip
479
+ - run: pnpm jscpd
480
+
481
+ # Secret scanning over the whole history, with this repository's own .gitleaks.toml.
482
+ secret-scan:
483
+ runs-on: ubuntu-latest
484
+ permissions:
485
+ contents: read
486
+ steps:
487
+ - uses: ${c.meta.actions['actions/checkout']}
488
+ with:
489
+ fetch-depth: 0 # full history: a secret committed then deleted is still leaked
490
+ - name: gitleaks (pinned binary; gitleaks-action requires a license key for organization repositories)
491
+ run: |
492
+ curl -sSfL https://github.com/gitleaks/gitleaks/releases/download/v${c.meta.gitleaksVersion}/gitleaks_${c.meta.gitleaksVersion}_linux_x64.tar.gz | tar -xz gitleaks
493
+ ./gitleaks git --redact --config .gitleaks.toml
494
+ `
495
+ }
496
+
497
+ /** The Claude Code release that first takes a commit SHA as a GitHub marketplace's `ref`. */
498
+ const CLAUDE_CODE_FLOOR = '2.1.324'
499
+
500
+ /**
501
+ * The project's Claude Code settings (ADR-0014 part 9): SSSB's plugin marketplace, pinned to the same commit of SSSB's
502
+ * repository as the reusable workflow (a plugin runs on developers' machines, with more reach than CI), and SSSB's plugin
503
+ * enabled from it. `pnpm exec sssb doctor` reports when the pin differs from the installed @sssb/kit's release commit.
504
+ * @param {Context} c
505
+ */
506
+ export function claudeSettings(c) {
507
+ const { marketplace, name } = c.meta.plugin
508
+ return formatJson({
509
+ extraKnownMarketplaces: {
510
+ [marketplace]: { source: { source: 'github', repo: c.meta.workflow.repository, ref: c.workflowRef } },
511
+ },
512
+ enabledPlugins: { [`${name}@${marketplace}`]: true },
513
+ })
514
+ }
515
+
516
+ /**
517
+ * The workspace's own agent guide, which imports SSSB's app guide (the stamped copy `sssb guide` keeps). Written once:
518
+ * it is the adopter's from then on, and the rules below the import are theirs.
519
+ */
520
+ export const CLAUDE_MD = `# Agent guide
521
+
522
+ SSSB's app guide, the rules every app on SSSB follows, from the copy \`pnpm exec sssb guide\` keeps (after an upgrade,
523
+ \`pnpm exec sssb doctor\` fails until it is refreshed, and \`pnpm exec sssb pin\` raises the CI workflow's and the plugin
524
+ marketplace's pins to the release's commit):
525
+
526
+ @.claude/sssb-guide.md
527
+
528
+ ## This workspace
529
+
530
+ Your own rules go here: what the app is for, its domain's vocabulary, and the conventions your team keeps.
531
+ `
532
+
533
+ /** @param {Context} c */
534
+ export function cutoverChecklist(c) {
535
+ return `# Cutover checklist
536
+
537
+ Everything ${c.name} defers because it needs real credentials, accounts or money. The app boots and is fully testable
538
+ without any of it: nothing here is a blocker, each is a row. Fill in who unlocks each one and the proof it owes (a
539
+ real send through the email port, not "set up email"), and add rows as the app acquires dependencies. A real adapter
540
+ is authored but unverified until its row closes.
541
+
542
+ These are SSSB's rows, the ones every app on SSSB has; \`pnpm exec sssb doctor\` reports one this file stops
543
+ mentioning. \`config/params.ts\` in each app names the row that fills each placeholder.
544
+
545
+ ${c.meta.cutoverRows.map((row) => `- [ ] \`${row.id}\`: ${row.what}`).join('\n')}
546
+ `
547
+ }
548
+
549
+ /** @param {number} budget the app's demo-size budget, in bytes */
550
+ export function demoSizeMd(budget) {
551
+ return `# Demo size budget
552
+
553
+ The static demo (\`pnpm build:demo-static\`) is one HTML file you can hand someone, and \`pnpm check:demo-size\`
554
+ fails if it grows past a byte budget. The number is the argument of \`check:demo-size\` in this app's
555
+ \`package.json\` (${budget} bytes when it was generated), and it is this app's own: the command, \`sssb check-demo-size\`
556
+ (from \`@sssb/tools\`), holds no number, and says what to look at first when the gate goes red.
557
+
558
+ It starts roomy, sized for an app's own screens and not as a pacing gate. If you want a pacing gate, set it to what
559
+ your app measures plus the headroom you want.
560
+
561
+ ## How to change it
562
+
563
+ Re-set the number in \`package.json\` and add an entry under "Changes" below in the same commit: what grew or shrank,
564
+ by how much, and how much headroom you left on purpose. Newest first.
565
+
566
+ ## Changes
567
+
568
+ None yet.
569
+ `
570
+ }
571
+
572
+ /**
573
+ * A link to a file (\`blob\`) or directory (\`tree\`) of SSSB's repository at the commit the workspace pins. Every path a
574
+ * workspace's README links this way is checked to exist in SSSB's repository (tests/tooling/create-generate.test.ts).
575
+ * @param {Context} c
576
+ * @param {'blob' | 'tree'} kind
577
+ * @param {string} file
578
+ */
579
+ const sssbDoc = (c, kind, file) => `https://github.com/${c.meta.workflow.repository}/${kind}/${c.workflowRef}/${file}`
580
+
581
+ /** @param {Context} c */
582
+ export function readme(c) {
583
+ return `# ${c.name}
584
+
585
+ A multi-tenant web application built on SSSB: Next.js, ports and adapters, row-level-security tenancy, and a
586
+ hermetic local world. Generated by \`@sssb/create\` ${c.meta.version}.
587
+
588
+ ## Start
589
+
590
+ \`\`\`sh
591
+ git init
592
+ pnpm install
593
+ pnpm --filter './apps/*' exec playwright install chromium # once, for the app's e2e suites
594
+ pnpm dev # the app, seeded, offline, no credentials
595
+ pnpm verify # what CI runs, but the secret scan
596
+ \`\`\`
597
+
598
+ \`pnpm verify\` runs what this workspace's CI runs, so a green here is a green there: typecheck, lint, the unit tests
599
+ with coverage, knip, jscpd, the lint fences, doctor, the contract tests on real Postgres (an embedded server locally),
600
+ the e2e suites, the static demo and the offline CDK synth. Only the secret scan (gitleaks) is CI's alone.
601
+
602
+ ## Building on SSSB
603
+
604
+ SSSB's guide for an app built on it, at the commit this workspace pins, walks you from here: which generated content
605
+ to replace first, a first entity through the app's seam, cutting over to real accounts, and upgrading:
606
+ [\`docs/adopting.md\`](${sssbDoc(c, 'blob', 'docs/adopting.md')}).
607
+ Its reference says the rest, what is yours and what is SSSB's among it:
608
+ [\`docs/adopting-reference.md\`](${sssbDoc(c, 'blob', 'docs/adopting-reference.md')}).
609
+ The worked example of every capability is SSSB's own reference app:
610
+ [\`apps/showcase\`](${sssbDoc(c, 'tree', 'apps/showcase')}).
611
+
612
+ The app starts with one worked example, an Items list (a tenant-scoped table with row-level security, a paged route, a
613
+ card and its tests). When you have read it, \`pnpm exec sssb remove-items --app ${app(c)} --drop-migrations\` takes it out in one step
614
+ (\`--dry-run\` says what it will do; SSSB's reference, under "To remove the Items slice", says when to leave the flag off).
615
+
616
+ ## Layout
617
+
618
+ - \`${app(c)}/\`: the app. Its \`src/app-config/\` is the seam SSSB's framework (\`@sssb/kit\`) reads the app's
619
+ registrations through, a workspace package of its own (\`${c.slug}-app-config\`) that the app takes as
620
+ \`@sssb/app-config\`; \`config/app.ts\` holds its slug and
621
+ \`config/params.ts\` its deployment parameters. It sits under \`apps/\` so that a second app, or a package of your own
622
+ under \`packages/\`, is a sibling rather than a special case; one app is the usual shape.
623
+ - \`${app(c)}/infra/\`: the app's deployment, a CDK app composing SSSB's \`SssbApp\` construct (\`@sssb/cdk\`). Before
624
+ you deploy, replace the \`UPDATE-ME\` tags in its \`lib/tags.ts\` with your organisation's.
625
+ - \`docs/cutover-checklist.md\`: what the app defers until it has real accounts.
626
+ - \`.claude/sssb-guide.md\`: SSSB's app guide (the rules an app on SSSB follows), a stamped copy of the one
627
+ \`@sssb/kit\` ships, which \`CLAUDE.md\` imports (\`@.claude/sssb-guide.md\`; keep that line when you make the file
628
+ your own). After an upgrade, \`pnpm exec sssb guide\` refreshes it; \`pnpm exec sssb doctor\` fails until you do, so
629
+ the change reaches your diff.
630
+ - \`.claude/settings.json\`: SSSB's Claude Code plugin, enabled (below).
631
+ - The root: the workspace's config on SSSB's presets (\`@sssb/tools\`, \`@sssb/eslint-plugin\`).
632
+
633
+ ## Claude Code
634
+
635
+ \`.claude/settings.json\` declares SSSB's plugin marketplace (\`${c.meta.plugin.marketplace}\`), pinned to the same commit
636
+ of SSSB's repository as the CI workflow, and enables its plugin, \`${c.meta.plugin.name}@${c.meta.plugin.marketplace}\`:
637
+ the commands an app author runs, namespaced as \`/${c.meta.plugin.name}:<command>\` (\`/${c.meta.plugin.name}:new-entity\`,
638
+ \`/${c.meta.plugin.name}:verify\` and the rest), and the \`${c.meta.plugin.name}:doc-steward\` agent.
639
+
640
+ - **Claude Code ${CLAUDE_CODE_FLOOR} or later**: older versions cannot pin a marketplace to a commit
641
+ (\`claude --version\`; \`claude update\`).
642
+ - **Install the plugin once per clone**, after trusting the folder (enabling it does not install it):
643
+ \`claude plugin install ${c.meta.plugin.name}@${c.meta.plugin.marketplace} --scope project\`.
644
+ - **Raise the marketplace's \`ref\` with the workflow's pin** when you upgrade: \`pnpm exec sssb pin\` raises both
645
+ (below).
646
+
647
+ ## CI, and the settings only you can make
648
+
649
+ \`.github/workflows/checks.yml\` calls SSSB's reusable workflow, pinned to a commit of SSSB's repository (its \`sssb\`
650
+ job's \`uses:\` line), beside this workspace's own knip, jscpd and secret-scan jobs. On GitHub:
651
+
652
+ - **Require the check \`sssb / all-checks\`** in a ruleset or branch protection on your default branch. It fails unless
653
+ every one of SSSB's jobs ran and passed. Require \`workspace-checks\` and \`secret-scan\` too.
654
+ - If the repository is private and in an organization, allow public reusable workflows in the organization's Actions
655
+ settings.
656
+ - Turn on private vulnerability reporting, which \`SECURITY.md\` and \`CODE_OF_CONDUCT.md\` point reporters to.
657
+ ${
658
+ c.repo === null || c.owners.length === 0
659
+ ? `- Replace the placeholders the generator left (\`${PLACEHOLDER_OWNER}\`, \`${PLACEHOLDER_REPO}\`) in
660
+ \`CODEOWNERS\`, \`SECURITY.md\`, \`CODE_OF_CONDUCT.md\` and \`.github/ISSUE_TEMPLATE/config.yml\`.\n`
661
+ : ''
662
+ }- Add a \`LICENSE\` of your choice.
663
+ - The workflow runs on pushes to \`main\`; rename the branch there if yours differs.
664
+
665
+ ## Upgrading SSSB
666
+
667
+ The \`@sssb/*\` packages are released together at one version. Each release's notes open with "Upgrading to this
668
+ release", the commands that move them together, refresh \`.claude/sssb-guide.md\` (\`pnpm exec sssb guide\`) and raise
669
+ the workflow's pin and the plugin marketplace's \`ref\` in \`.claude/settings.json\` to the release's commit
670
+ (\`pnpm exec sssb pin\`, which reads it from the installed \`@sssb/kit\`). SSSB's guide lists the steps:
671
+ [\`docs/adopting.md\`, "Upgrading by release"](${sssbDoc(c, 'blob', 'docs/adopting.md')}#upgrading-by-release).
672
+ Its reference says why each is there:
673
+ [\`docs/adopting-reference.md\`, "Upgrading, step by step"](${sssbDoc(c, 'blob', 'docs/adopting-reference.md')}#upgrading-step-by-step).
674
+ \`pnpm exec sssb doctor\` fails when the installed packages are out of step, and reports a pin that is not the release
675
+ commit the installed \`@sssb/kit\` names.
676
+ `
677
+ }