@sssb/create 0.0.0 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (91) hide show
  1. package/LICENSE +21 -0
  2. package/bin/create.js +136 -0
  3. package/package.json +26 -5
  4. package/src/add-app.js +165 -0
  5. package/src/args.js +270 -0
  6. package/src/files.js +677 -0
  7. package/src/generate.js +612 -0
  8. package/src/json.js +60 -0
  9. package/src/signals.js +72 -0
  10. package/src/template.js +496 -0
  11. package/src/yaml.js +17 -0
  12. package/template/app/DEMO-SIZE.md +55 -0
  13. package/template/app/config/app.ts +17 -0
  14. package/template/app/config/params.ts +85 -0
  15. package/template/app/infra/README.md +85 -0
  16. package/template/app/infra/app.ts +45 -0
  17. package/template/app/infra/cdk.json +9 -0
  18. package/template/app/infra/lib/tags.ts +35 -0
  19. package/template/app/infra/package.json +20 -0
  20. package/template/app/infra/tsconfig.json +13 -0
  21. package/template/app/messages/en.json +21 -0
  22. package/template/app/messages/es.json +21 -0
  23. package/template/app/next.config.ts +9 -0
  24. package/template/app/package.json +40 -0
  25. package/template/app/playwright.config.ts +50 -0
  26. package/template/app/playwright.demo.config.ts +10 -0
  27. package/template/app/src/app/[locale]/(protected)/dashboard/dashboard-glue.tsx +61 -0
  28. package/template/app/src/app/[locale]/(protected)/dashboard/page.tsx +21 -0
  29. package/template/app/src/app/[locale]/(protected)/header-glue.tsx +59 -0
  30. package/template/app/src/app/[locale]/(protected)/layout.tsx +43 -0
  31. package/template/app/src/app/[locale]/layout.tsx +63 -0
  32. package/template/app/src/app/[locale]/page.tsx +9 -0
  33. package/template/app/src/app/[locale]/signin/page.tsx +55 -0
  34. package/template/app/src/app/[locale]/signin/picker-glue.tsx +21 -0
  35. package/template/app/src/app/api/auth/dev-signin/route.ts +12 -0
  36. package/template/app/src/app/api/auth/org/route.ts +10 -0
  37. package/template/app/src/app/api/auth/signout/route.ts +9 -0
  38. package/template/app/src/app/api/items/route.ts +59 -0
  39. package/template/app/src/app/api/respond.ts +13 -0
  40. package/template/app/src/app/api/simulator/[...path]/route.ts +23 -0
  41. package/template/app/src/app/api/webhooks/cron/route.test.ts +59 -0
  42. package/template/app/src/app/api/webhooks/cron/route.ts +16 -0
  43. package/template/app/src/app/layout.tsx +7 -0
  44. package/template/app/src/app-config/abilities.ts +86 -0
  45. package/template/app/src/app-config/actors.ts +13 -0
  46. package/template/app/src/app-config/audit.ts +9 -0
  47. package/template/app/src/app-config/db/migrations/1001_items.ts +37 -0
  48. package/template/app/src/app-config/db/migrations/1002_items_keyset_index.ts +29 -0
  49. package/template/app/src/app-config/db/migrations/index.ts +13 -0
  50. package/template/app/src/app-config/db/rls-proofs.ts +186 -0
  51. package/template/app/src/app-config/db/schema.ts +23 -0
  52. package/template/app/src/app-config/digest.ts +10 -0
  53. package/template/app/src/app-config/identity.ts +8 -0
  54. package/template/app/src/app-config/inbound-email.ts +10 -0
  55. package/template/app/src/app-config/jobs.ts +28 -0
  56. package/template/app/src/app-config/messages.ts +18 -0
  57. package/template/app/src/app-config/notifications.ts +31 -0
  58. package/template/app/src/app-config/preset-operations.ts +9 -0
  59. package/template/app/src/app-config/presets.ts +18 -0
  60. package/template/app/src/app-config/seed.ts +7 -0
  61. package/template/app/src/app-config/simulator.ts +17 -0
  62. package/template/app/src/app-config/tours.ts +14 -0
  63. package/template/app/src/app-config/webhooks.ts +13 -0
  64. package/template/app/src/components/dashboard-screen.tsx +26 -0
  65. package/template/app/src/components/items-card.tsx +106 -0
  66. package/template/app/src/components/welcome-screen.tsx +20 -0
  67. package/template/app/src/demo-static/app.tsx +77 -0
  68. package/template/app/src/demo-static/index.html +12 -0
  69. package/template/app/src/demo-static/main.tsx +40 -0
  70. package/template/app/src/domain/db/items.ts +37 -0
  71. package/template/app/src/proxy.test.ts +44 -0
  72. package/template/app/src/proxy.ts +18 -0
  73. package/template/app/src/seed/index.ts +93 -0
  74. package/template/app/src/sssb.conformance.test.ts +7 -0
  75. package/template/app/src/styles/index.css +1 -0
  76. package/template/app/tests/catalog.ts +15 -0
  77. package/template/app/tests/contract/rls-contract.test.ts +14 -0
  78. package/template/app/tests/demo-static/static-shell.spec.ts +32 -0
  79. package/template/app/tests/e2e/items.spec.ts +102 -0
  80. package/template/app/tests/e2e/simulator.spec.ts +40 -0
  81. package/template/app/tsconfig.json +29 -0
  82. package/template/app/vite.demo.config.ts +8 -0
  83. package/template/guide.md +132 -0
  84. package/template/meta.json +633 -0
  85. package/template/root/_dot_editorconfig +12 -0
  86. package/template/root/_dot_husky/commit-msg +1 -0
  87. package/template/root/_dot_husky/pre-commit +1 -0
  88. package/template/root/_dot_nvmrc +1 -0
  89. package/template/root/_dot_prettierrc.json +5 -0
  90. package/template/root/commitlint.config.mjs +1 -0
  91. package/README.md +0 -3
@@ -0,0 +1,186 @@
1
+ import { sql } from 'kysely'
2
+ import { encodeKeysetCursor, parseKeysetCursor } from '@sssb/kit/core/keyset'
3
+ import { parseDbKeysetCursor } from '@sssb/kit/db/keyset'
4
+ import type { RlsProofSuite } from '@sssb/kit/db/rls-proofs'
5
+ import { runWithTenant } from '@sssb/kit/db/with-tenant'
6
+ import { listItems } from '@/domain/db/items'
7
+
8
+ /**
9
+ * The APP's tenant-isolation proofs (the seam side of @sssb/kit/db/rls-proofs.ts, ADR-0004 + ADR-0012) —
10
+ * one section per app table, asserting exactly what the framework half asserts for its own: read
11
+ * isolation both directions under UNFILTERED selects, WITH CHECK on cross-tenant writes, and the
12
+ * per-table privilege grants.
13
+ *
14
+ * @sssb/kit/db/rls-proof-runner.ts composes this with the framework half and runs the union, so these
15
+ * assertions execute wherever that runner does. An adopter with no tenant tables leaves the body empty
16
+ * (ADR-0012, "unused capability = empty registration"). Kept in lockstep with ./migrations.
17
+ */
18
+ export const appRlsProofs: RlsProofSuite = async ({
19
+ db,
20
+ appDb,
21
+ dbPort,
22
+ expect,
23
+ alphaTenantId,
24
+ demoTenantId,
25
+ alphaOrgId,
26
+ demoOrgId,
27
+ }) => {
28
+ // ---- items: tenant-only RLS (1001), single-org app scoping, SELECT/INSERT/UPDATE (no DELETE) ----
29
+
30
+ await db
31
+ .insertInto('items')
32
+ .values([
33
+ { tenant_id: alphaTenantId, org_id: alphaOrgId, title: 'first item', created_by_user_id: 'proof-user' },
34
+ { tenant_id: alphaTenantId, org_id: alphaOrgId, title: 'second item', created_by_user_id: 'proof-user' },
35
+ {
36
+ tenant_id: demoTenantId,
37
+ org_id: demoOrgId,
38
+ title: 'other tenant item',
39
+ created_by_user_id: 'proof-user',
40
+ },
41
+ ])
42
+ .execute()
43
+
44
+ // read isolation, both directions, via UNFILTERED selects under RLS
45
+ const ours = await runWithTenant(appDb, alphaTenantId, (trx) => trx.selectFrom('items').selectAll().execute())
46
+ expect(ours.filter((r) => r.tenant_id === demoTenantId).length).toBe(0)
47
+ expect(ours.filter((r) => r.tenant_id === alphaTenantId).length).toBe(2)
48
+ const theirs = await runWithTenant(appDb, demoTenantId, (trx) => trx.selectFrom('items').selectAll().execute())
49
+ expect(theirs.filter((r) => r.tenant_id === alphaTenantId).length).toBe(0)
50
+ expect(theirs.filter((r) => r.tenant_id === demoTenantId).length).toBe(1)
51
+
52
+ // write isolation: an INSERT carrying the OTHER tenant's id is rejected by WITH CHECK, even though
53
+ // the org id is a real org — the tenant, not the org, is the RLS boundary.
54
+ let writeRejected = false
55
+ try {
56
+ await runWithTenant(appDb, alphaTenantId, (trx) =>
57
+ trx
58
+ .insertInto('items')
59
+ .values({
60
+ tenant_id: demoTenantId,
61
+ org_id: demoOrgId,
62
+ title: 'smuggled',
63
+ created_by_user_id: 'proof-user',
64
+ })
65
+ .execute(),
66
+ )
67
+ } catch (error) {
68
+ writeRejected = /row-level security/.test(String(error))
69
+ }
70
+ expect(writeRejected).toBe(true)
71
+
72
+ // DELETE is denied at the PRIVILEGE layer — the 1001 grant is SELECT/INSERT/UPDATE only, so an
73
+ // item can never be erased even by a correctly-scoped caller.
74
+ let deleteRejected = false
75
+ try {
76
+ await appDb.transaction().execute(async (trx) => {
77
+ await sql`SET LOCAL ROLE app_user`.execute(trx)
78
+ await sql`SELECT set_config('app.current_tenant', ${alphaTenantId}, true)`.execute(trx)
79
+ await sql`DELETE FROM items`.execute(trx)
80
+ })
81
+ } catch (error) {
82
+ deleteRejected = /permission denied/.test(String(error))
83
+ }
84
+ expect(deleteRejected).toBe(true)
85
+
86
+ // ---- the PAGED items list: neither boundary moves when a cursor is involved ----
87
+ //
88
+ // The tenant boundary is RLS's, and the framework half proves a cursor cannot cross it. This half proves
89
+ // the one the app adds on top, the team (an app-level WHERE, not a policy), because that is the one a
90
+ // hand-rolled pager loses: page one is built from the session, page two from the cursor, and the org
91
+ // filter is on the first query only. There is no such second query here, and these assertions say so.
92
+ //
93
+ // Driven through the PRODUCTION function, `listItems`, the same call GET /api/items makes: a proof of a
94
+ // copy of the read path proves nothing about the read path.
95
+
96
+ const stamp = Date.now()
97
+ const [pageOrgP] = await db
98
+ .insertInto('organizations')
99
+ .values({ tenant_id: alphaTenantId, slug: `page-p-${stamp}`, name: 'Page Org P' })
100
+ .returning('id')
101
+ .execute()
102
+ const [pageOrgQ] = await db
103
+ .insertInto('organizations')
104
+ .values({ tenant_id: alphaTenantId, slug: `page-q-${stamp}`, name: 'Page Org Q' })
105
+ .returning('id')
106
+ .execute()
107
+
108
+ // Six items for team P, three for team Q, three for the OTHER TENANT. Every row in a batch shares ONE
109
+ // created_at, written at MICROSECOND precision: the two properties that break a hand-rolled pager (no
110
+ // defined position inside a batch; a cursor truncated to a JS millisecond that excludes the batch it
111
+ // points into).
112
+ const batch = (tenantId: string, orgId: string, label: string, count: number, at: string) =>
113
+ Array.from({ length: count }, (_, index) => ({
114
+ tenant_id: tenantId,
115
+ org_id: orgId,
116
+ title: `${label}-${stamp}-${index}`,
117
+ created_by_user_id: 'proof-user',
118
+ created_at: at,
119
+ }))
120
+ await db
121
+ .insertInto('items')
122
+ .values([
123
+ ...batch(alphaTenantId, pageOrgP!.id, 'KP', 6, '2020-03-04T05:06:07.123456Z'),
124
+ ...batch(alphaTenantId, pageOrgQ!.id, 'KQ', 3, '2020-03-04T05:06:08.654321Z'),
125
+ ...batch(demoTenantId, demoOrgId, 'KD', 3, '2020-03-04T05:06:09.987654Z'),
126
+ ])
127
+ .execute()
128
+
129
+ /** Walk a team's list to the end through the real read path, and report everything it showed. */
130
+ const walk = async (tenantId: string, orgId: string, limit: number) => {
131
+ const seen: string[] = []
132
+ let cursor: string | null = null
133
+ for (let guard = 0; guard < 50; guard++) {
134
+ const parsed = parseDbKeysetCursor(cursor)
135
+ expect(parsed.kind === 'invalid').toBe(false)
136
+ const page = await listItems(dbPort, tenantId, orgId, { after: parsed.position ?? null, limit })
137
+ seen.push(...page.items.map((item) => item.title))
138
+ if (page.nextCursor === null) return seen
139
+ cursor = page.nextCursor
140
+ }
141
+ throw new Error('keyset proof: the items walk did not terminate')
142
+ }
143
+
144
+ // (a) a full walk at a page size that cuts through the batch shows team P's six, once each, and no
145
+ // sight of team Q's or of the other tenant's.
146
+ const walkedP = await walk(alphaTenantId, pageOrgP!.id, 2)
147
+ expect(walkedP.length).toBe(6)
148
+ expect(new Set(walkedP).size).toBe(6)
149
+ expect(walkedP.every((title) => title.startsWith(`KP-${stamp}-`))).toBe(true)
150
+
151
+ // (b) THE ATTACK on the team boundary: a cursor minted while paging team Q's list, handed to team P's.
152
+ // The two teams share a tenant, so RLS is not what stops this; the org filter is, and it is re-applied
153
+ // because the pager rebuilds the whole query on every page rather than resuming one.
154
+ const teamQPage = await listItems(dbPort, alphaTenantId, pageOrgQ!.id, { after: null, limit: 1 })
155
+ expect(teamQPage.nextCursor !== null).toBe(true)
156
+ const crossTeam = await listItems(dbPort, alphaTenantId, pageOrgP!.id, {
157
+ after: parseDbKeysetCursor(teamQPage.nextCursor).position ?? null,
158
+ limit: 50,
159
+ })
160
+ expect(crossTeam.items.length).toBe(6)
161
+ expect(crossTeam.items.every((item) => item.title.startsWith(`KP-${stamp}-`))).toBe(true)
162
+
163
+ // (c) the same across TENANTS: a cursor minted in the other tenant, replayed against alpha's list. The
164
+ // tenant comes from withTenant, which the pager opens from the caller's session, never from the cursor.
165
+ const demoList = await listItems(dbPort, demoTenantId, demoOrgId, { after: null, limit: 1 })
166
+ expect(demoList.nextCursor !== null).toBe(true)
167
+ const crossTenant = await listItems(dbPort, alphaTenantId, pageOrgP!.id, {
168
+ after: parseDbKeysetCursor(demoList.nextCursor).position ?? null,
169
+ limit: 50,
170
+ })
171
+ expect(crossTenant.items.length).toBe(6)
172
+ expect(crossTenant.items.every((item) => item.title.startsWith(`KP-${stamp}-`))).toBe(true)
173
+
174
+ // (d) a cursor crafted to name a REAL item of the other team, at a timestamp that opens the predicate
175
+ // as wide as it goes. Still exactly team P's six rows.
176
+ const teamQFirst = teamQPage.items[0]
177
+ expect(teamQFirst !== undefined).toBe(true)
178
+ const crafted = await listItems(dbPort, alphaTenantId, pageOrgP!.id, {
179
+ after:
180
+ parseKeysetCursor(encodeKeysetCursor({ at: '2999-01-01T00:00:00.000000Z', id: teamQFirst!.id })).position ??
181
+ null,
182
+ limit: 50,
183
+ })
184
+ expect(crafted.items.length).toBe(6)
185
+ expect(crafted.items.every((item) => item.title.startsWith(`KP-${stamp}-`))).toBe(true)
186
+ }
@@ -0,0 +1,23 @@
1
+ import type { Generated } from 'kysely'
2
+
3
+ /**
4
+ * The APP's tenant-scoped tables (the seam side of @sssb/kit/db/schema.ts, ADR-0012). The framework owns its
5
+ * tables + the `DB` interface, which `extends AppTables` (a type-only seam import). Kept in lockstep
6
+ * with the migrations in ./migrations (numbered ≥1001).
7
+ */
8
+
9
+ interface ItemsTable {
10
+ id: Generated<string>
11
+ tenant_id: string
12
+ /** The team that owns the item. NOT NULL — an app-level filter, not an RLS anchor (1001). */
13
+ org_id: string
14
+ title: string
15
+ /** Opaque user id (no users table) — same convention as the framework's jobs / service_keys. */
16
+ created_by_user_id: string
17
+ created_at: Generated<string>
18
+ }
19
+
20
+ /** The app's tables, merged into the framework `DB` interface (@sssb/kit/db/schema.ts `extends AppTables`). */
21
+ export interface AppTables {
22
+ items: ItemsTable
23
+ }
@@ -0,0 +1,10 @@
1
+ import type { DigestBodySource } from '@sssb/kit/jobs/digest-email'
2
+
3
+ /**
4
+ * The APP's digest source (the seam side of @sssb/kit/jobs/digest-email.ts, ADR-0012).
5
+ *
6
+ * EMPTY REGISTRATION: this app has nothing to digest, so the framework's scheduled digest still
7
+ * composes and sends — with its empty-state copy. Removing the capability would mean deleting a
8
+ * framework job kind; leaving it registered-and-empty costs one line.
9
+ */
10
+ export const digestBodies: DigestBodySource = async () => []
@@ -0,0 +1,8 @@
1
+ /**
2
+ * Host identity — the app half of the seam the framework reads its slug through (ADR-0012).
3
+ *
4
+ * `APP_SLUG` is the ONE value an adopter changes to rename the app's mechanical identity: session and
5
+ * viewpoint cookies, the fake-auth JWT issuer, the service-token audience, outbound webhook header
6
+ * names, and the infra resource names. See `config/app.ts` for the collision-risk doctrine.
7
+ */
8
+ export { APP_SLUG } from '../../config/app'
@@ -0,0 +1,10 @@
1
+ import type { InboundHandler } from '@sssb/kit/inbound-email/handlers'
2
+
3
+ /**
4
+ * The app's inbound-email handler registrations (ADR-0012 seam). The recipient address
5
+ * `<org-slug>+<slug>@domain` names the slug; the framework intake looks it up in the composed registry.
6
+ *
7
+ * EMPTY REGISTRATION: this app accepts no email. Every inbound message therefore files as 'unmatched',
8
+ * which is the framework's own fail-closed behaviour for an unknown slug — no removal surgery needed.
9
+ */
10
+ export const appInboundHandlers: Record<string, InboundHandler> = {}
@@ -0,0 +1,28 @@
1
+ import type { JobHandler } from '@sssb/kit/ports/jobs'
2
+ import { digestEmailHandler } from '@sssb/kit/jobs/digest-email'
3
+
4
+ /**
5
+ * The APP's job registrations (the seam side of @sssb/kit/core/jobs.ts, ADR-0012).
6
+ *
7
+ * EMPTY REGISTRATION: no app job kinds, so `AppJobKind` is `never` and `JobKind` collapses to the
8
+ * framework's own. `jobHandlers` is still the composition root the fake jobs adapter consumes, and it
9
+ * still carries the framework's `digest-email` handler — the framework reaches its OWN handler through
10
+ * this seam because the fence forbids the adapter importing app-side modules directly.
11
+ */
12
+ export const appJobKinds = [] as const
13
+ export type AppJobKind = (typeof appJobKinds)[number]
14
+
15
+ /** One handler per app job kind. Exhaustive over AppJobKind — which is empty. */
16
+ export const appJobHandlers: Record<AppJobKind, JobHandler> = {}
17
+
18
+ /** The composed dispatch map (framework kinds + app kinds) — the jobs adapter's single source. */
19
+ export const jobHandlers: Record<string, JobHandler> = {
20
+ 'digest-email': digestEmailHandler,
21
+ ...appJobHandlers,
22
+ }
23
+
24
+ /**
25
+ * Org slugs whose jobs are served by a dedicated service actor, excluded from the generic pending-build
26
+ * pool. EMPTY: this app registers no actors, so no org is service-managed.
27
+ */
28
+ export const serviceManagedOrgSlugs: readonly string[] = []
@@ -0,0 +1,18 @@
1
+ import type { MessageTree } from '@sssb/kit/i18n/messages'
2
+
3
+ /**
4
+ * The APP's i18n registration (the seam side of @sssb/kit/i18n/namespaces.ts, ADR-0012). The catalogs are
5
+ * physically split: the framework owns FRAMEWORK_NAMESPACES in `@sssb/kit/i18n/messages/*.json`;
6
+ * this app owns APP_NAMESPACES in its own `messages/*.json`. Together they partition the merged catalog
7
+ * (disjoint + exhaustive), enforced by the conformance suite's `i18n-partition` check (@sssb/kit/testing), which
8
+ * this app runs against these registrations from src/sssb.conformance.test.ts.
9
+ */
10
+ export const APP_NAMESPACES = ['welcome', 'dashboard', 'items'] as const
11
+
12
+ /**
13
+ * The app's catalog for one locale. Framework code (the next-intl request config, the parity tests)
14
+ * reaches the app's messages ONLY through this loader — the seam's one message door.
15
+ */
16
+ export async function loadAppMessages(locale: string): Promise<MessageTree> {
17
+ return (await import(`../../messages/${locale}.json`)).default as MessageTree
18
+ }
@@ -0,0 +1,31 @@
1
+ import type { NotificationCopy } from '@sssb/kit/core/notifications'
2
+
3
+ /**
4
+ * The APP's notification kinds (the seam side of @sssb/kit/core/notifications.ts, ADR-0012). The framework
5
+ * owns the channels, the resolver, and its own kinds (org.invited, job.completed).
6
+ *
7
+ * EMPTY REGISTRATION: no app kinds. The bell, the prefs screen, email and SMS fan-out all keep working
8
+ * on the framework's kinds.
9
+ */
10
+ export const appNotificationKinds = [] as const
11
+ export type AppNotificationKind = (typeof appNotificationKinds)[number]
12
+
13
+ /** Per-kind payload shapes for the app kinds. There are none, so this contributes nothing to the
14
+ * intersection the framework builds (`Framework & App`). */
15
+ export type AppNotificationPayloadMap = Record<never, never>
16
+
17
+ /**
18
+ * Copy mapping for the app kinds. Unreachable by construction: the framework's `default:` case
19
+ * delegates here only for a kind outside its own union, and this app registers none — so both
20
+ * parameters are `never`. Returning one is the type-safe way to say "cannot happen"; inventing a
21
+ * placeholder NotificationCopy would be a lie the compiler could not check.
22
+ *
23
+ * Worth naming as a rough edge in the seam: an app that registers zero notification kinds still has
24
+ * to write this function, because the framework calls it unconditionally from the switch's default.
25
+ */
26
+ export function appNotificationCopy(
27
+ kind: AppNotificationKind,
28
+ payload: AppNotificationPayloadMap[AppNotificationKind],
29
+ ): NotificationCopy {
30
+ return payload ?? kind
31
+ }
@@ -0,0 +1,9 @@
1
+ import type { ServerPresetOperationHandler } from '@sssb/kit/server-lib/preset-operations'
2
+
3
+ /**
4
+ * The SERVER halves of the app's demo-preset operation kinds (@sssb/kit/server-lib/demo-presets.ts composes
5
+ * them over SSSB's own) — a server-only seam module (ADR-0012), separate from `./presets.ts` because the
6
+ * static demo bundles that one and must never bundle a server half. EMPTY REGISTRATION: this app adds no
7
+ * kinds, so SSSB's `invite`, `inbound`, `flag` and `actor.hold` are the whole registry.
8
+ */
9
+ export const appPresetOperationHandlers: Record<string, ServerPresetOperationHandler> = {}
@@ -0,0 +1,18 @@
1
+ /**
2
+ * The APP's demo presets (@sssb/kit/core/presets.ts) — the seam side of the Snapshots tab's "Start from a
3
+ * preset" list (ADR-0012). EMPTY REGISTRATION: no presets, so the tab shows no presets section, and a
4
+ * tour can still start from `'reset'`, the one world start every host has. To add one, put it in its own
5
+ * file under `./presets/` and list it here — `/sssb:new-preset` walks through it.
6
+ *
7
+ * No operation kinds of its own either: a preset here can use SSSB's (`invite`, `inbound`, `flag`;
8
+ * `actor.hold` needs an actor, and this app registers none). Add one with `/sssb:new-preset-operation`, which
9
+ * registers its definition below and its server half in `./preset-operations.ts`.
10
+ */
11
+
12
+ import type { DemoPreset, PresetOperationDefinition } from '@sssb/kit/core/presets'
13
+
14
+ export type AppPresetOperation = never
15
+
16
+ export const appPresetOperations: PresetOperationDefinition[] = []
17
+
18
+ export const presets: DemoPreset[] = []
@@ -0,0 +1,7 @@
1
+ /**
2
+ * The seam re-export of the app's seed data (ADR-0012). Framework code that needs the world — the fake
3
+ * auth adapter, the DB seeder, per-tenant theming, the static-demo twin — imports it THROUGH here, so
4
+ * WHERE an app keeps its seed is the app's business. SSSB's reference app keeps its in a workspace
5
+ * package (`@app/seed`); this app keeps its in `src/seed`. Neither can see the other's.
6
+ */
7
+ export * from '../seed'
@@ -0,0 +1,17 @@
1
+ /**
2
+ * The APP's Simulator registrations (the seam side of the panel's tab strip + the Snapshots flag list,
3
+ * ADR-0012). The framework panel owns its subsystem tabs and its own feature flags.
4
+ *
5
+ * EMPTY REGISTRATION on every count: no extra tabs, no app feature flags. The panel still ships every
6
+ * framework tab; `flags` is composed into KNOWN_FLAGS (@sssb/kit/adapters/fake/analytics.ts) and an empty
7
+ * list simply adds nothing. `tabs` is not exported at all — nothing would read it, and an export with
8
+ * no consumer is dead code the gate would (rightly) flag.
9
+ */
10
+
11
+ /** One app-registered Snapshots feature flag. `labelKey` resolves in the `simulator` i18n namespace. */
12
+ interface AppSimulatorFlag {
13
+ id: string
14
+ labelKey: string
15
+ }
16
+
17
+ export const flags: AppSimulatorFlag[] = []
@@ -0,0 +1,14 @@
1
+ import type { TourDefinition } from '@sssb/kit/demo-static/tour/contracts'
2
+
3
+ /**
4
+ * The APP's registered TOURS — scripted walkthroughs the Simulator Tours tab lists and runs
5
+ * (@sssb/kit/demo-static/tour/contracts, ADR-0012).
6
+ *
7
+ * EMPTY REGISTRATION, and it is a real off-switch rather than an empty list: with no tours registered
8
+ * the panel does not render the Tours tab at all and the engine never mounts a ghost cursor. It is not
9
+ * free in BYTES — the shell imports the engine either way, which is ~11KB of this app's single-file
10
+ * demo — because the alternative is making every app wire the engine itself, and the framework's whole
11
+ * bargain here is that an app inherits the simulated world without assembling it. An adopter who wants
12
+ * a walkthrough writes one here (`/sssb:new-tour`); SSSB's reference app's is the worked example.
13
+ */
14
+ export const tours: TourDefinition[] = []
@@ -0,0 +1,13 @@
1
+ /**
2
+ * The APP's outbound-webhook event kinds (the seam side of @sssb/kit/core/webhook-events.ts, ADR-0012). The
3
+ * framework owns the backoff policy, the signed envelope, and its own kind (job.status_changed).
4
+ *
5
+ * EMPTY REGISTRATION: no app events. Endpoints can still be registered and still receive the
6
+ * framework's own event; the subscribe list simply offers one kind instead of three.
7
+ */
8
+ export const appWebhookEventKinds = [] as const
9
+ export type AppWebhookEventKind = (typeof appWebhookEventKinds)[number]
10
+
11
+ /** Per-kind payload shapes for the app kinds. There are none, so this contributes nothing to the
12
+ * intersection the framework builds (`Framework & App`). */
13
+ export type AppWebhookEventPayloadMap = Record<never, never>
@@ -0,0 +1,26 @@
1
+ 'use client'
2
+
3
+ import { Container, Stack, Text, Title } from '@mantine/core'
4
+ import { useTranslations } from 'next-intl'
5
+ import type { ReactNode } from 'react'
6
+
7
+ export interface DashboardUser {
8
+ name: string
9
+ role: string
10
+ }
11
+
12
+ /** Signed-in landing screen. Router-agnostic (ADR-0006); the cards are slotted in as children. */
13
+ export function DashboardScreen({ user, children }: { user: DashboardUser; children: ReactNode }) {
14
+ const t = useTranslations('dashboard')
15
+ return (
16
+ <Container component="main" size="sm" py="xl">
17
+ <Stack gap="lg">
18
+ <Title order={1}>{t('title')}</Title>
19
+ <Text c="gray.7" data-testid="signed-in-as">
20
+ {t('signedInAs', { name: user.name, role: user.role })}
21
+ </Text>
22
+ {children}
23
+ </Stack>
24
+ </Container>
25
+ )
26
+ }
@@ -0,0 +1,106 @@
1
+ 'use client'
2
+
3
+ import { Button, Card, Group, Stack, Text, TextInput, Title } from '@mantine/core'
4
+ import { useTranslations } from 'next-intl'
5
+ import { useState } from 'react'
6
+
7
+ export interface Item {
8
+ id: string
9
+ title: string
10
+ }
11
+
12
+ /**
13
+ * The app's ONE screen component: a list of the active team's items with an add box. Router-agnostic
14
+ * (ADR-0006) so the Next route and the `file://` static twin render the same component; `canCreate`
15
+ * comes from the same pure ability model on both sides.
16
+ */
17
+ export function ItemsCard({
18
+ items,
19
+ onAdd,
20
+ canCreate = true,
21
+ hasMore = false,
22
+ onLoadMore,
23
+ }: {
24
+ items: Item[]
25
+ onAdd: (title: string) => Promise<void>
26
+ /** When false (restricted members), the add affordance is disabled and a read-only hint shows. */
27
+ canCreate?: boolean
28
+ /** True while the server has older items to show. The list is paged (`@sssb/kit/db/keyset`). */
29
+ hasMore?: boolean
30
+ /** Appends the next page to `items`; the card shows "load more" only when both this and `hasMore` are set. */
31
+ onLoadMore?: () => Promise<void>
32
+ }) {
33
+ const t = useTranslations('items')
34
+ const [draft, setDraft] = useState('')
35
+ const [busy, setBusy] = useState(false)
36
+ const [loadingMore, setLoadingMore] = useState(false)
37
+
38
+ return (
39
+ <Card withBorder padding="lg" radius="md" data-testid="items-card">
40
+ <Stack gap="sm">
41
+ <Title order={2} size="h3">
42
+ {t('title')}
43
+ </Title>
44
+ <Text size="sm" c="gray.7">
45
+ {t('hint')}
46
+ </Text>
47
+ {items.length === 0 ? (
48
+ <Text c="gray.7" data-testid="items-empty">
49
+ {t('empty')}
50
+ </Text>
51
+ ) : (
52
+ <Stack gap={4} data-testid="items-list">
53
+ {items.map((item) => (
54
+ <Text key={item.id} data-testid="item-row">
55
+ {item.title}
56
+ </Text>
57
+ ))}
58
+ </Stack>
59
+ )}
60
+ {hasMore && onLoadMore ? (
61
+ <Button
62
+ size="compact-sm"
63
+ variant="default"
64
+ loading={loadingMore}
65
+ data-testid="items-load-more"
66
+ style={{ alignSelf: 'flex-start' }}
67
+ onClick={() => {
68
+ setLoadingMore(true)
69
+ onLoadMore().finally(() => setLoadingMore(false))
70
+ }}
71
+ >
72
+ {t('loadMore')}
73
+ </Button>
74
+ ) : null}
75
+ <Group align="end" gap="sm">
76
+ <TextInput
77
+ label={t('addLabel')}
78
+ flex={1}
79
+ value={draft}
80
+ disabled={!canCreate}
81
+ data-testid="item-input"
82
+ onChange={(event) => setDraft(event.currentTarget.value)}
83
+ />
84
+ <Button
85
+ loading={busy}
86
+ disabled={!canCreate || !draft.trim()}
87
+ data-testid="item-add"
88
+ onClick={() => {
89
+ setBusy(true)
90
+ onAdd(draft.trim())
91
+ .then(() => setDraft(''))
92
+ .finally(() => setBusy(false))
93
+ }}
94
+ >
95
+ {t('addButton')}
96
+ </Button>
97
+ </Group>
98
+ {!canCreate ? (
99
+ <Text size="sm" c="gray.7" data-testid="items-readonly-hint">
100
+ {t('readOnlyHint')}
101
+ </Text>
102
+ ) : null}
103
+ </Stack>
104
+ </Card>
105
+ )
106
+ }
@@ -0,0 +1,20 @@
1
+ 'use client'
2
+
3
+ import { Anchor, Container, Stack, Text, Title } from '@mantine/core'
4
+ import { useTranslations } from 'next-intl'
5
+
6
+ /** Router-agnostic landing screen: no Next imports, so the app route and the static twin share it. */
7
+ export function WelcomeScreen({ dashboardHref }: { dashboardHref: string }) {
8
+ const t = useTranslations('welcome')
9
+ return (
10
+ <Container component="main" size="sm" py="xl">
11
+ <Stack gap="lg">
12
+ <Title order={1}>{t('title')}</Title>
13
+ <Text c="gray.7">{t('subtitle')}</Text>
14
+ <Anchor href={dashboardHref} data-testid="dashboard-link">
15
+ {t('dashboardLink')}
16
+ </Anchor>
17
+ </Stack>
18
+ </Container>
19
+ )
20
+ }
@@ -0,0 +1,77 @@
1
+ import { useState } from 'react'
2
+ import { useTranslations } from 'next-intl'
3
+ import { defineAbilitiesFor } from '@sssb/kit/core/abilities'
4
+ import { isRestricted } from '@sssb/kit/core/roles'
5
+ import type { Locale } from '@sssb/kit/core/locale'
6
+ import { DemoShell } from '@sssb/kit/demo-static/shell'
7
+ import { useDemoWorld } from '@sssb/kit/demo-static/world'
8
+ import type { SeedPerson } from '@/seed'
9
+ import { staffOrgSlug } from '@/app-config/abilities'
10
+ import { DashboardScreen } from '@/components/dashboard-screen'
11
+ import { ItemsCard, type Item } from '@/components/items-card'
12
+ import { WelcomeScreen } from '@/components/welcome-screen'
13
+
14
+ /**
15
+ * The static demo's COMPOSITION ROOT — the `file://` twin of the server-side glue, and the same job:
16
+ * take the framework's simulated world (@sssb/kit/demo-static/world), add THIS app's own rows, hand the
17
+ * shell its screens, and get out of the way (ADR-0006, ADR-0012).
18
+ *
19
+ * This is what the twin costs an app that owns ONE table: a row type, a piece of state, an ability
20
+ * check and a card. Everything else on screen — routing, sign-in, the people, mail, jobs, schedules,
21
+ * webhooks, notifications, agreements, audit and the whole Simulator panel — is the package's.
22
+ */
23
+
24
+ /** In-memory twin of an `items` row — tenant + org scoped, so the static dashboard shows only the
25
+ * active team's items and gates create by the same pure ability model the real server runs. */
26
+ interface DemoItem extends Item {
27
+ tenantSlug: string
28
+ orgSlug: string
29
+ }
30
+
31
+ export function StaticDemoApp({ locale, onLocaleChange }: { locale: Locale; onLocaleChange: (l: Locale) => void }) {
32
+ const t = useTranslations('welcome')
33
+ const [items, setItems] = useState<DemoItem[]>([])
34
+ const world = useDemoWorld({ onReset: () => setItems([]) })
35
+
36
+ function renderDashboard(person: SeedPerson) {
37
+ const { tenant, activeOrgSlug } = world
38
+ // Same pure ability the real server runs — a restricted person gets a read-only card here too.
39
+ const ability = defineAbilitiesFor({
40
+ // The static shell's signed-in person IS a session, and only a stated session wields manage-all.
41
+ credential: { kind: 'session', id: null },
42
+ userId: person.id,
43
+ role: world.roleInOrg(person, activeOrgSlug),
44
+ restricted: isRestricted(person.restricted, world.roleInOrg(person, activeOrgSlug)),
45
+ activeOrgId: activeOrgSlug,
46
+ // Acting AS the operator org activates manage-all, exactly like abilityActorFromUser does
47
+ // server-side — genuine parity, no degrade.
48
+ manageAll: activeOrgSlug === staffOrgSlug,
49
+ })
50
+
51
+ return (
52
+ <DashboardScreen user={{ name: world.name, role: world.roleInOrg(person, activeOrgSlug) }}>
53
+ <ItemsCard
54
+ items={items.filter((i) => i.tenantSlug === tenant.slug && i.orgSlug === activeOrgSlug)}
55
+ canCreate={ability.can('create', { type: 'Item', orgId: activeOrgSlug })}
56
+ onAdd={async (title) => {
57
+ const id = crypto.randomUUID()
58
+ setItems((prev) => [{ id, title, tenantSlug: tenant.slug, orgSlug: activeOrgSlug }, ...prev])
59
+ }}
60
+ />
61
+ </DashboardScreen>
62
+ )
63
+ }
64
+
65
+ return (
66
+ <DemoShell
67
+ world={world}
68
+ locale={locale}
69
+ onLocaleChange={onLocaleChange}
70
+ appName={t('appName')}
71
+ welcome={<WelcomeScreen dashboardHref="#/dashboard" />}
72
+ nav={null}
73
+ dashboard={renderDashboard}
74
+ extraTabs={[]}
75
+ />
76
+ )
77
+ }
@@ -0,0 +1,12 @@
1
+ <!doctype html>
2
+ <html lang="en">
3
+ <head>
4
+ <meta charset="utf-8" />
5
+ <meta name="viewport" content="width=device-width, initial-scale=1" />
6
+ <title>Starter — static demo</title>
7
+ </head>
8
+ <body>
9
+ <div id="root"></div>
10
+ <script type="module" src="./main.tsx"></script>
11
+ </body>
12
+ </html>