@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.
Files changed (85) hide show
  1. package/LICENSE +21 -0
  2. package/bin/create.js +135 -0
  3. package/package.json +22 -5
  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
@@ -0,0 +1,118 @@
1
+ # SSSB app guide
2
+
3
+ The rules for an app built on SSSB (`@sssb/kit`). Paths are relative to the app's own directory, the package that
4
+ depends on `@sssb/kit`. `pnpm exec sssb guide` copies this file into your repository under a hash stamp: edit nothing in
5
+ the copy, rerun the command after an upgrade, and review the diff. Most rules are enforced by the `@sssb/eslint-plugin`
6
+ preset, SSSB's conformance suite or `sssb doctor`; keep the rest by hand.
7
+
8
+ ## The seam
9
+
10
+ - The app extends the framework only through the `@sssb/app-config/*` seam, the modules in `src/app-config/`.
11
+ Register new subjects, jobs, event kinds, tables and migrations there. Never edit or patch a framework base union or
12
+ registry.
13
+ - Import `@sssb/kit` only by a published subpath, a key of its `exports` map. Everything else in the package is
14
+ internal.
15
+
16
+ ## Vendors, environment and parameters
17
+
18
+ - Vendor SDKs (`@clerk/*`, `@aws-sdk/*`, `@anthropic-ai/*`, `@sentry/*`, `posthog-*`, `mailgun.js`, `pg`) are
19
+ imported only in an app's real adapters, `adapters/real/` (and in what runs outside the request path: `next.config.*`
20
+ for the Sentry build plugin, the contract tests in `tests/contract/`, the deployment in `infra/`). Everything else
21
+ codes against a port: `@sssb/kit/ports/*`, or a port the app owns. SSSB's own real adapters
22
+ (`@sssb/kit/adapters/real/*`) load their SDK too, so every module of the app outside `adapters/real/` (which may
23
+ build on one) and the vendor carve-outs above, tests, stories and scripts included, reaches one only with `import()`
24
+ when `!isSimulated`, never by an import declaration (re-exports included; a type-only `import type` or
25
+ `export type`, which loads nothing, is allowed).
26
+ - A vendor SSSB has no port for gets a port the app owns, under `src`: the port module (`ports/<name>.ts`), a registry
27
+ (`adapters/index.ts`) that takes the run mode from SSSB's `isSimulated` (`@sssb/kit/adapters/index`) and loads the
28
+ real adapter only with `import()`, a fake, and the real adapter in `adapters/real/`, the one directory that imports
29
+ the SDK. Nothing imports `adapters/real/` statically, and a fake never imports it at all. Add the SDK to the ban in
30
+ the app's own `package.json`: `"sssb": { "vendors": ["stripe", "stripe/*"] }`.
31
+ - Read `process.env` only in `adapters/real/` (and never the run mode there), in Next's instrumentation hooks, in
32
+ tests and in the app-root tool configs (Playwright, Vite). Every other module imports the resolved value: deployment
33
+ parameters from `config/params.ts`, the run mode from `isSimulated`.
34
+ - Deployment and service parameters exist only in `config/params.ts`. Secret values never enter the repository.
35
+ - `pnpm dev` stays hermetic: no docker, no credentials, no network. Never add `next/font/google`, telemetry, or
36
+ anything that phones home.
37
+ - Anything that needs real credentials, accounts or money is a row in the workspace's cutover checklist, never a
38
+ blocker: the app boots, and is tested, without it.
39
+
40
+ ## Data
41
+
42
+ - Tenant-scoped queries run only inside `db.withTenant()`. `getDb()` is banned in every module under `src`
43
+ (`sssb/no-raw-db-handle`); tests are exempt, except a route's or a screen's. A module that truly needs the raw
44
+ client is a named entry, with its reason, in the app's `lint-exceptions.mjs`: a path relative to the app, one
45
+ existing file per entry, never a glob or a directory.
46
+ - A list that can grow pages through `@sssb/kit/db/keyset`, never a hand-rolled `LIMIT`/`OFFSET`. Parse the cursor
47
+ with `parseDbKeysetCursor` and answer 400 when it is `invalid`; clamp the page size on the server; fix the
48
+ `orderBy` column per route, never from the client.
49
+ - App migrations live in `src/app-config/db/migrations/`, numbered 1001 and up (0001–0999 are the framework's), and
50
+ are listed in `src/app-config/db/migrations/index.ts`. A new tenant table copies the RLS pattern of
51
+ `src/app-config/db/migrations/1001_items.ts`, the generated app's first migration (once you have removed it, read it
52
+ in SSSB's repository at your release), and its isolation proofs go in `src/app-config/db/rls-proofs.ts`.
53
+ - A role is cluster-wide, so a migration that creates one of the app's own creates it only where it does not exist
54
+ yet: a `DO` block that runs `CREATE ROLE reviewer NOLOGIN` only when
55
+ `NOT EXISTS (SELECT FROM pg_roles WHERE rolname = 'reviewer')`. Keep it an ordinary role, before and after every
56
+ migration: NOLOGIN, never CREATEDB, CREATEROLE, SUPERUSER, BYPASSRLS or REPLICATION, granted no privilege on a server
57
+ parameter (`GRANT ... ON PARAMETER`), the owner of no database or tablespace, and a member of no role (at any depth)
58
+ but `app_user` and the app's other named roles (`GRANT reviewer TO app_user` is fine;
59
+ `GRANT pg_read_all_data TO reviewer` is not). Leave the framework's `app_user` ordinary too, since every later owner
60
+ gets ADMIN on it as well: never change its attributes, give it no parameter privilege, database or tablespace, and grant it only
61
+ the app's named roles, never a `pg_*` one. Name your role in `appRoles`, exported beside `appMigrations` from
62
+ `src/app-config/db/migrations/index.ts`: `export const appRoles = ['reviewer'] as const`. The contract tests' owner
63
+ pass grants a later database owner ADMIN on exactly those roles and `app_user`, as Aurora's master user holds on a
64
+ role it created, and refuses a role that is not ordinary; the conformance suite's `app-roles` check fails a role the
65
+ migrations create and `appRoles` does not name, a name they do not create, and a named role or `app_user` they leave
66
+ more than ordinary. Never name `app_user` or a `pg_*` or `rds_*` role.
67
+ - After any migration or database change, run the contract tests on real Postgres (`pnpm test:contract` from the
68
+ workspace root). After renumbering or renaming a migration, wipe
69
+ the local `.data` first.
70
+
71
+ ## Authorization
72
+
73
+ - Every exported mutating route handler (POST, PUT, PATCH, DELETE) in a `route.ts` anywhere under `src/app`, not only
74
+ under `src/app/api`, calls `authorize(...)` from `@sssb/kit/authz/authorize` on its own path, as
75
+ `src/app/api/items/route.ts` does (the generated app's; once you have removed it, read it in SSSB's repository at your
76
+ release). The conformance suite's `authz-mutations` check reads each handler: a string, a
77
+ comment, a dead branch or a helper in another module does not count. Neither does a call whose denial cannot stop
78
+ the handler: in an `async` helper or a callback whose promise the handler neither awaits nor returns, in a callback
79
+ handed to a function the route file defines, or in a `try` whose `catch` does not rethrow. `await` the helper that
80
+ authorizes, and let `withPortErrors` answer the 403.
81
+ - An exemption is an entry in the app's `authz-exemptions.mjs` (`{ files, prefixes }`, keys relative to
82
+ `src/app/api`), with a reason and a `mustMatch` gate. A mutating route outside `src/app/api` can match no
83
+ exemption.
84
+
85
+ ## UI
86
+
87
+ - No hard-coded UI strings: all copy goes through next-intl, accessible names, placeholders, titles and alt text
88
+ included (`sssb/no-jsx-literals`, `sssb/no-literal-a11y-copy`). The app's namespaces live in `messages/en.json` and
89
+ `messages/es.json`; the framework ships its own catalog, and the two are deep-merged wherever messages load. The
90
+ merged catalogs stay key- and placeholder-identical.
91
+ - Screens are router-agnostic: they live in `src/components`, and the files under `src/app` are thin wrappers with no
92
+ logic, so the `file://` static demo still builds.
93
+
94
+ ## Tests
95
+
96
+ - Keep `src/sssb.conformance.test.ts` (SSSB's conformance suite) and `tests/contract/rls-contract.test.ts` (the
97
+ contract runner on real Postgres). Leave a check out only by a named opt-out with its reason,
98
+ `optOut: { '<check id>': '<why>' }`. `sssb doctor` fails when the Vitest config does not run them.
99
+ - A test that needs a scratch directory calls `makeTestTmpDir()` or `makeTestTmpDirAsync()` from
100
+ `@sssb/tools/testing/tmp-dir`, never `mkdtemp` directly. A script that runs Vitest as a gate goes through
101
+ `sssb check-tmpdir-leak`.
102
+ - E2E specs live in `tests/e2e/` and reach the framework only through `@sssb/kit/testing/e2e` (`sssb check-e2e`).
103
+ Playwright's `workers` stays 1: every worker shares one `.data` behind one dev server.
104
+ - Dead code fails `knip`. Never silence a finding with a broad ignore; add the narrowest entry, with its reason.
105
+
106
+ ## The dev loop
107
+
108
+ - Scheduled work runs in dev only when something ticks it: the app's `pnpm tick` calls the running dev server's cron
109
+ route once, and `DEV_TICK_SECONDS=<n> pnpm dev` ticks it every n seconds. The ticker is off by default and stays off
110
+ under e2e. The cron route (`src/app/api/webhooks/cron/route.ts`) stays behind `withWebhookSecret`: never add a
111
+ bypass for the ticker.
112
+ - In a linked git worktree the app's ports are derived per checkout, so parallel sessions never adopt each other's dev
113
+ server; `pnpm exec sssb port`, run from the app, prints its port. An app declares its port slot in its package.json
114
+ (`"sssb": { "port": "starter" }`), and every app of a workspace needs a slot of its own: a second app declares
115
+ `"sssb": { "port": { "name": "ledger", "default": 3700 } }`, which `sssb doctor` checks, and reads its override from
116
+ `LEDGER_PORT`.
117
+ - Before finishing a change, run `pnpm verify` from the workspace root. Format with `pnpm lint:fix`, never by hand.
118
+ Commit messages are conventional commits; the commit-msg hook runs commitlint.