@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.
- package/LICENSE +21 -0
- package/bin/create.js +135 -0
- package/package.json +22 -3
- 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
|
@@ -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.
|