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