@sssb/create 0.0.0 → 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.
- package/LICENSE +21 -0
- package/bin/create.js +135 -0
- package/package.json +22 -5
- package/src/args.js +270 -0
- package/src/files.js +660 -0
- package/src/generate.js +517 -0
- package/src/json.js +60 -0
- package/src/signals.js +72 -0
- package/src/template.js +496 -0
- package/src/yaml.js +17 -0
- package/template/app/DEMO-SIZE.md +55 -0
- package/template/app/config/app.ts +17 -0
- package/template/app/config/params.ts +70 -0
- package/template/app/infra/README.md +78 -0
- package/template/app/infra/app.ts +45 -0
- package/template/app/infra/cdk.json +9 -0
- package/template/app/infra/lib/tags.ts +35 -0
- package/template/app/infra/package.json +20 -0
- package/template/app/infra/tsconfig.json +13 -0
- package/template/app/messages/en.json +20 -0
- package/template/app/messages/es.json +20 -0
- package/template/app/next.config.ts +9 -0
- package/template/app/package.json +40 -0
- package/template/app/playwright.config.ts +50 -0
- package/template/app/playwright.demo.config.ts +10 -0
- package/template/app/src/app/[locale]/(protected)/dashboard/dashboard-glue.tsx +37 -0
- package/template/app/src/app/[locale]/(protected)/dashboard/page.tsx +21 -0
- package/template/app/src/app/[locale]/(protected)/header-glue.tsx +59 -0
- package/template/app/src/app/[locale]/(protected)/layout.tsx +43 -0
- package/template/app/src/app/[locale]/layout.tsx +55 -0
- package/template/app/src/app/[locale]/page.tsx +9 -0
- package/template/app/src/app/[locale]/signin/page.tsx +55 -0
- package/template/app/src/app/[locale]/signin/picker-glue.tsx +21 -0
- package/template/app/src/app/api/auth/dev-signin/route.ts +12 -0
- package/template/app/src/app/api/auth/org/route.ts +10 -0
- package/template/app/src/app/api/auth/signout/route.ts +9 -0
- package/template/app/src/app/api/items/route.ts +52 -0
- package/template/app/src/app/api/respond.ts +13 -0
- package/template/app/src/app/api/webhooks/cron/route.test.ts +59 -0
- package/template/app/src/app/api/webhooks/cron/route.ts +15 -0
- package/template/app/src/app/layout.tsx +7 -0
- package/template/app/src/app-config/abilities.ts +93 -0
- package/template/app/src/app-config/actors.ts +13 -0
- package/template/app/src/app-config/audit.ts +9 -0
- package/template/app/src/app-config/db/migrations/1001_items.ts +37 -0
- package/template/app/src/app-config/db/migrations/index.ts +11 -0
- package/template/app/src/app-config/db/rls-proofs.ts +81 -0
- package/template/app/src/app-config/db/schema.ts +23 -0
- package/template/app/src/app-config/digest.ts +10 -0
- package/template/app/src/app-config/identity.ts +8 -0
- package/template/app/src/app-config/inbound-email.ts +10 -0
- package/template/app/src/app-config/jobs.ts +28 -0
- package/template/app/src/app-config/messages.ts +18 -0
- package/template/app/src/app-config/notifications.ts +31 -0
- package/template/app/src/app-config/preset-operations.ts +9 -0
- package/template/app/src/app-config/presets.ts +18 -0
- package/template/app/src/app-config/seed.ts +7 -0
- package/template/app/src/app-config/simulator.ts +17 -0
- package/template/app/src/app-config/tours.ts +14 -0
- package/template/app/src/app-config/webhooks.ts +13 -0
- package/template/app/src/components/dashboard-screen.tsx +26 -0
- package/template/app/src/components/items-card.tsx +84 -0
- package/template/app/src/components/welcome-screen.tsx +20 -0
- package/template/app/src/demo-static/app.tsx +77 -0
- package/template/app/src/demo-static/index.html +12 -0
- package/template/app/src/demo-static/main.tsx +40 -0
- package/template/app/src/proxy.ts +9 -0
- package/template/app/src/seed/index.ts +93 -0
- package/template/app/src/sssb.conformance.test.ts +7 -0
- package/template/app/src/styles/index.css +1 -0
- package/template/app/tests/catalog.ts +15 -0
- package/template/app/tests/contract/rls-contract.test.ts +14 -0
- package/template/app/tests/demo-static/static-shell.spec.ts +32 -0
- package/template/app/tests/e2e/items.spec.ts +58 -0
- package/template/app/tsconfig.json +29 -0
- package/template/app/vite.demo.config.ts +8 -0
- package/template/guide.md +118 -0
- package/template/meta.json +633 -0
- package/template/root/_dot_editorconfig +12 -0
- package/template/root/_dot_husky/commit-msg +1 -0
- package/template/root/_dot_husky/pre-commit +1 -0
- package/template/root/_dot_nvmrc +1 -0
- package/template/root/_dot_prettierrc.json +5 -0
- package/template/root/commitlint.config.mjs +1 -0
- 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
|
+
}
|