@sssb/create 0.2.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.
@@ -10,18 +10,11 @@ import type { AbilityAction, AbilityActor, AbilitySubject, NonSessionAdministrat
10
10
  export type AppSubjectType = 'Item'
11
11
 
12
12
  /**
13
- * App-specific fields merged into the framework's AbilitySubject (`AbilitySubject extends
14
- * AppSubjectFields`). This app has NONE: every one of its subjects is scoped by the framework's own
15
- * `orgId`, so there is nothing to add.
16
- *
17
- * The empty interface is deliberate and is the one place "an unused capability needs no scaffolding"
18
- * is not quite free: because the framework EXTENDS this type, it must be an interface (a mapped type
19
- * such as `Record<never, never>` cannot be extended), and an empty interface is exactly what
20
- * `@typescript-eslint/no-empty-object-type` exists to flag. The suppression is narrow and local; the
21
- * alternative — inventing a field this app does not have — would be worse.
13
+ * App-specific fields merged into the framework's AbilitySubject (`AbilitySubject = AppSubjectFields & { … }`).
14
+ * This app has NONE: every one of its subjects is scoped by the framework's own `orgId`, so there is nothing
15
+ * to add, and `Record<never, never>` says so. An app with fields declares them here as an interface or a type.
22
16
  */
23
- // eslint-disable-next-line @typescript-eslint/no-empty-object-type
24
- export interface AppSubjectFields {}
17
+ export type AppSubjectFields = Record<never, never>
25
18
 
26
19
  /**
27
20
  * The credential kinds, beyond SSSB's own, by which a PERSON or a MACHINE can reach this app (composed
@@ -0,0 +1,29 @@
1
+ import { Kysely } from 'kysely'
2
+
3
+ /**
4
+ * The index that makes the items list pageable (`@sssb/kit/db/keyset`).
5
+ *
6
+ * A keyset page reads `WHERE tenant_id = … AND org_id = … AND (created_at, id) < ($1, $2)
7
+ * ORDER BY created_at DESC, id DESC LIMIT n`. Without a matching index that is a scan of the team's whole
8
+ * list on EVERY page. The column order mirrors the query: the equality columns first (`tenant_id` is a
9
+ * predicate RLS adds to every statement, so it belongs in the index), then the ordering pair in the
10
+ * direction the walk reads it.
11
+ *
12
+ * A SEPARATE migration rather than an edit to 1001: an applied migration is a record, not a document to
13
+ * revise, and an app that already ran 1001 must be able to take this one. A brand-new table meant to be
14
+ * paged would carry its index in its own create migration instead.
15
+ *
16
+ * Not unique: two rows can share `(tenant_id, org_id, created_at)` (one transaction shares one `now()`),
17
+ * which is why `id` is in the key at all.
18
+ */
19
+ export async function up(db: Kysely<unknown>): Promise<void> {
20
+ await db.schema
21
+ .createIndex('items_keyset_idx')
22
+ .on('items')
23
+ .columns(['tenant_id', 'org_id', 'created_at desc', 'id desc'])
24
+ .execute()
25
+ }
26
+
27
+ export async function down(db: Kysely<unknown>): Promise<void> {
28
+ await db.schema.dropIndex('items_keyset_idx').execute()
29
+ }
@@ -1,5 +1,6 @@
1
1
  import type { Migration } from 'kysely/migration'
2
2
  import * as m1001 from './1001_items'
3
+ import * as m1002 from './1002_items_keyset_index'
3
4
 
4
5
  /**
5
6
  * The APP's migrations (the seam side of @sssb/kit/db/migrations, ADR-0012). Numbering convention: framework
@@ -8,4 +9,5 @@ import * as m1001 from './1001_items'
8
9
  */
9
10
  export const appMigrations: Record<string, Migration> = {
10
11
  '1001_items': m1001,
12
+ '1002_items_keyset_index': m1002,
11
13
  }
@@ -1,6 +1,9 @@
1
1
  import { sql } from 'kysely'
2
+ import { encodeKeysetCursor, parseKeysetCursor } from '@sssb/kit/core/keyset'
3
+ import { parseDbKeysetCursor } from '@sssb/kit/db/keyset'
2
4
  import type { RlsProofSuite } from '@sssb/kit/db/rls-proofs'
3
5
  import { runWithTenant } from '@sssb/kit/db/with-tenant'
6
+ import { listItems } from '@/domain/db/items'
4
7
 
5
8
  /**
6
9
  * The APP's tenant-isolation proofs (the seam side of @sssb/kit/db/rls-proofs.ts, ADR-0004 + ADR-0012) —
@@ -15,6 +18,7 @@ import { runWithTenant } from '@sssb/kit/db/with-tenant'
15
18
  export const appRlsProofs: RlsProofSuite = async ({
16
19
  db,
17
20
  appDb,
21
+ dbPort,
18
22
  expect,
19
23
  alphaTenantId,
20
24
  demoTenantId,
@@ -78,4 +82,105 @@ export const appRlsProofs: RlsProofSuite = async ({
78
82
  deleteRejected = /permission denied/.test(String(error))
79
83
  }
80
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)
81
186
  }
@@ -18,15 +18,22 @@ export function ItemsCard({
18
18
  items,
19
19
  onAdd,
20
20
  canCreate = true,
21
+ hasMore = false,
22
+ onLoadMore,
21
23
  }: {
22
24
  items: Item[]
23
25
  onAdd: (title: string) => Promise<void>
24
26
  /** When false (restricted members), the add affordance is disabled and a read-only hint shows. */
25
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>
26
32
  }) {
27
33
  const t = useTranslations('items')
28
34
  const [draft, setDraft] = useState('')
29
35
  const [busy, setBusy] = useState(false)
36
+ const [loadingMore, setLoadingMore] = useState(false)
30
37
 
31
38
  return (
32
39
  <Card withBorder padding="lg" radius="md" data-testid="items-card">
@@ -50,6 +57,21 @@ export function ItemsCard({
50
57
  ))}
51
58
  </Stack>
52
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}
53
75
  <Group align="end" gap="sm">
54
76
  <TextInput
55
77
  label={t('addLabel')}
@@ -0,0 +1,37 @@
1
+ import type { KeysetPosition } from '@sssb/kit/core/keyset'
2
+ import { keysetPage } from '@sssb/kit/db/keyset'
3
+ import type { DbPort } from '@sssb/kit/ports/db'
4
+
5
+ /** An item as its owning team sees it in the list. */
6
+ interface ItemView {
7
+ id: string
8
+ title: string
9
+ }
10
+
11
+ /** One page of a team's items, plus the token that fetches the next one (null at the end). */
12
+ export interface ItemPage {
13
+ items: ItemView[]
14
+ nextCursor: string | null
15
+ }
16
+
17
+ /**
18
+ * Lists ONE PAGE of a team's items, newest first. Tenant-scoped by RLS AND filtered to the org: the same
19
+ * two boundaries as every list (ADR-0004).
20
+ *
21
+ * A list that can grow pages through the framework primitive (`@sssb/kit/db/keyset`), never a hand-rolled
22
+ * `LIMIT`/`OFFSET`. The callback is THE query, run once per page with the cursor added as one more
23
+ * conjunct, so page 7 is scoped by construction: there is no second code path that could forget the org.
24
+ * The order is fixed here (the primitive's default, `created_at` then `id`, newest first), never taken
25
+ * from a request, because a cursor does not say which column it was minted under.
26
+ */
27
+ export async function listItems(
28
+ db: DbPort,
29
+ tenantId: string,
30
+ orgId: string,
31
+ page: { after: KeysetPosition | null; limit: number },
32
+ ): Promise<ItemPage> {
33
+ const result = await keysetPage(db, { tenantId, after: page.after, limit: page.limit }, (trx) =>
34
+ trx.selectFrom('items').select(['id', 'title']).where('org_id', '=', orgId),
35
+ )
36
+ return { items: result.rows.map(({ id, title }) => ({ id, title })), nextCursor: result.nextCursor }
37
+ }
@@ -0,0 +1,44 @@
1
+ // @vitest-environment node
2
+ import { NextRequest, NextResponse, type NextFetchEvent } from 'next/server'
3
+ import { unstable_doesMiddlewareMatch } from 'next/experimental/testing/server'
4
+ import { describe, expect, it, vi } from 'vitest'
5
+ import proxy, { config } from './proxy'
6
+
7
+ // next-intl's middleware does not load under Vitest (its ESM imports `next/server` without an extension), so a
8
+ // stand-in marks the requests it is handed.
9
+ vi.mock('next-intl/middleware', () => ({
10
+ default: () => (request: NextRequest) =>
11
+ NextResponse.redirect(new URL(`/en${request.nextUrl.pathname}`, request.url)),
12
+ }))
13
+
14
+ // The proxy as Next runs it, in simulated mode (the test's run mode): which paths reach it, and what it does there.
15
+ // In real mode the same proxy runs inside the auth provider's middleware, which must see every page and API route.
16
+ function run(path: string) {
17
+ const request = new NextRequest(`http://localhost:3100${path}`)
18
+ return proxy(request, { waitUntil: () => {} } as unknown as NextFetchEvent)
19
+ }
20
+
21
+ describe('the proxy', () => {
22
+ it.each(['/', '/en/projects', '/es', '/api', '/api/projects', '/api/webhooks/cron', '/api/projects/report.csv'])(
23
+ 'is run on %s',
24
+ (path) => {
25
+ expect(unstable_doesMiddlewareMatch({ config, url: path })).toBe(true)
26
+ },
27
+ )
28
+
29
+ it.each(['/_next/static/chunk.js', '/favicon.ico', '/_vercel/insights', '/apiary'])('is not run on %s', (path) => {
30
+ expect(unstable_doesMiddlewareMatch({ config, url: path })).toBe(false)
31
+ })
32
+
33
+ it('hands a page to the locale routing', async () => {
34
+ const response = await run('/projects')
35
+ expect(response?.headers.get('location')).toBe('http://localhost:3100/en/projects')
36
+ })
37
+
38
+ it('passes an API route through untouched', async () => {
39
+ const response = await run('/api/projects')
40
+ expect(response?.headers.get('x-middleware-next')).toBe('1')
41
+ expect(response?.headers.get('location')).toBeNull()
42
+ expect(response?.headers.get('x-middleware-rewrite')).toBeNull()
43
+ })
44
+ })
@@ -1,9 +1,18 @@
1
1
  import createMiddleware from 'next-intl/middleware'
2
+ import { NextResponse } from 'next/server'
3
+ import { withAuthProxy } from '@sssb/kit/adapters/proxy'
2
4
  import { routing } from '@sssb/kit/i18n/routing'
3
5
 
4
- // Next 16 renamed middleware.ts -> proxy.ts; next-intl's locale negotiation runs here.
5
- export default createMiddleware(routing)
6
+ // Next 16 renamed middleware.ts -> proxy.ts. next-intl negotiates the locale on pages; an API route passes through.
7
+ // withAuthProxy runs this inside the auth provider's middleware in real mode, which SSSB's auth adapter needs.
8
+ const locales = createMiddleware(routing)
9
+
10
+ export default withAuthProxy((request) =>
11
+ request.nextUrl.pathname.startsWith('/api') ? NextResponse.next() : locales(request),
12
+ )
6
13
 
7
14
  export const config = {
8
- matcher: '/((?!api|_next|_vercel|.*\\..*).*)',
15
+ // Pages for the locale routing, and every API route, since the auth provider's middleware must see those too.
16
+ // Outside `/api`, a path with a dot in it (a static file) is left out, as are `/_next` and `/_vercel`.
17
+ matcher: ['/((?!api|_next|_vercel|.*\\..*).*)', '/api/:path*'],
9
18
  }
@@ -1,12 +1,11 @@
1
1
  import { expect, test, type Page } from '@playwright/test'
2
2
 
3
3
  /**
4
- * This app's whole e2e budget, spent on the one claim this app exists to prove: an item written
5
- * in one tenant is invisible from the other, through the entire stack (UI → route → withTenant → RLS
6
- * on pglite).
4
+ * The claim this app exists to prove: an item written in one tenant is invisible from the other, through the
5
+ * entire stack (UI → route → withTenant → RLS on pglite).
7
6
  *
8
- * This app has no Simulator panel, so crossing tenants is done the way a real user would — sign out,
9
- * sign in as somebody whose home tenant differs.
7
+ * Crossing tenants is done the way a real user would, not through the Simulator panel: sign out, sign in
8
+ * as somebody whose home tenant differs.
10
9
  */
11
10
 
12
11
  async function signInAs(page: Page, personId: string) {
@@ -56,3 +55,48 @@ test('an item created in one tenant is invisible from the other', async ({ page
56
55
  await signInAs(page, 'person-owner')
57
56
  await expect(page.getByTestId('items-list')).toContainText(secret)
58
57
  })
58
+
59
+ test('the items list pages, and the endpoint refuses a cursor it cannot read', async ({ page }) => {
60
+ await signInAs(page, 'person-owner')
61
+ await expect(page.getByTestId('items-card')).toBeVisible()
62
+
63
+ // The default page is 20, so 22 more items guarantee the list is longer than one page whatever else this
64
+ // run has already written. Written through the route, the way the card's own add button does.
65
+ const stamp = Date.now()
66
+ for (let index = 0; index < 22; index++) {
67
+ const response = await page.request.post('/api/items', { data: { title: `paged-${stamp}-${index}` } })
68
+ expect(response.ok()).toBe(true)
69
+ }
70
+ await page.reload()
71
+ const rows = page.getByTestId('item-row')
72
+ await expect(rows).toHaveCount(20)
73
+ await expect(page.getByTestId('items-load-more')).toBeVisible()
74
+
75
+ // "Show older items" APPENDS: what is on screen stays, in the same order, and the button goes away at the
76
+ // end of the list. Walked with a guard rather than one click, because this world keeps its rows between
77
+ // runs and the list can be longer than two pages.
78
+ let previous = await rows.allTextContents()
79
+ for (let click = 0; click < 20; click++) {
80
+ if (!(await page.getByTestId('items-load-more').isVisible())) break
81
+ await page.getByTestId('items-load-more').click()
82
+ await expect(rows).not.toHaveCount(previous.length)
83
+ const current = await rows.allTextContents()
84
+ expect(current.slice(0, previous.length)).toEqual(previous)
85
+ previous = current
86
+ }
87
+ await expect(page.getByTestId('items-load-more')).toHaveCount(0)
88
+ expect(previous.length).toBeGreaterThan(20)
89
+ expect(new Set(previous).size).toBe(previous.length)
90
+
91
+ // A malformed cursor is a 400, never a silent first page; the server also caps the page size itself.
92
+ const bad = await page.request.get('/api/items?cursor=not-a-cursor')
93
+ expect(bad.status()).toBe(400)
94
+ expect(await bad.json()).toEqual({ error: 'invalid-cursor' })
95
+ const single = await page.request.get('/api/items?limit=1')
96
+ const onePage = (await single.json()) as { items: unknown[]; nextCursor: string | null }
97
+ expect(onePage.items.length).toBe(1)
98
+ expect(onePage.nextCursor).not.toBeNull()
99
+ const greedy = await page.request.get('/api/items?limit=1000000')
100
+ expect(greedy.status()).toBe(200)
101
+ expect(((await greedy.json()) as { items: unknown[] }).items.length).toBeLessThanOrEqual(100)
102
+ })
@@ -0,0 +1,40 @@
1
+ import { expect, test, type Page } from '@playwright/test'
2
+
3
+ /**
4
+ * The Simulator panel on this app's own server: SSSB's panel, fed through `src/app/api/simulator/[...path]/route.ts`.
5
+ * One walk through the tabs it serves (People, Mail, Jobs), with a GET and a POST on each side of a sign-in.
6
+ */
7
+
8
+ /** The pill renders before React attaches its click handler; the panel stamps `data-hydrated` once it has. */
9
+ async function openPanel(page: Page) {
10
+ const panel = page.getByTestId('simulator-panel')
11
+ await expect(async () => {
12
+ if (await panel.isVisible()) return
13
+ await page.locator('[data-testid="simulator-pill"][data-hydrated]').click({ timeout: 2_000 })
14
+ await expect(panel).toBeVisible({ timeout: 2_000 })
15
+ }).toPass({ timeout: 30_000 })
16
+ }
17
+
18
+ test('the Simulator signs you in as anyone, and serves its mail and jobs tabs', async ({ page }) => {
19
+ // Signed out: the panel is there anyway, and picking a person signs this browser in as them.
20
+ await page.goto('/en/signin')
21
+ await openPanel(page)
22
+ await page.getByTestId('people-person-other-tenant').click()
23
+ await page.waitForURL('**/dashboard')
24
+ await expect(page.getByTestId('active-tenant')).toHaveText('Westgate')
25
+
26
+ // The panel remembers it was open across that reload. It shows the tabs its server serves, and no others.
27
+ await expect(page.getByTestId('simulator-panel')).toBeVisible()
28
+ await expect(page.getByTestId('simulator-tab-mail')).toBeVisible()
29
+ await expect(page.getByTestId('simulator-tab-hooks')).toHaveCount(0)
30
+
31
+ await page.getByTestId('simulator-tab-mail').click()
32
+ await expect(page.getByTestId('simulator-mail')).toBeVisible()
33
+
34
+ // Running what is due answers with a notice inside the panel.
35
+ await page.getByTestId('simulator-tab-jobs').click()
36
+ await expect(page.getByTestId('simulator-clock-now')).toBeVisible()
37
+ await page.getByTestId('simulator-clock-run-due').click()
38
+ // Its notice, not a new-mail one (which names an address) that happened to arrive at the same moment.
39
+ await expect(page.getByTestId('simulator-notice').filter({ hasNotText: '@' })).toBeVisible()
40
+ })
package/template/guide.md CHANGED
@@ -32,10 +32,21 @@ preset, SSSB's conformance suite or `sssb doctor`; keep the rest by hand.
32
32
  tests and in the app-root tool configs (Playwright, Vite). Every other module imports the resolved value: deployment
33
33
  parameters from `config/params.ts`, the run mode from `isSimulated`.
34
34
  - Deployment and service parameters exist only in `config/params.ts`. Secret values never enter the repository.
35
+ - Declare which of SSSB's optional ports the app uses in `config/params.ts`'s `ports` (`llm`, `email`, `inboundEmail`,
36
+ `jobs`). A port the app does not use is `none`, never configured with placeholder values.
37
+ - A job handler never reads the seed (`@sssb/app-config/seed`), which a deployment does not have: it finds people with
38
+ `ctx.auth.listMembers(orgSlug)`, and a person's locale with `ctx.resolveLocale`, where the runner provides one.
35
39
  - `pnpm dev` stays hermetic: no docker, no credentials, no network. Never add `next/font/google`, telemetry, or
36
40
  anything that phones home.
37
41
  - Anything that needs real credentials, accounts or money is a row in the workspace's cutover checklist, never a
38
42
  blocker: the app boots, and is tested, without it.
43
+ - `src/proxy.ts` default-exports the app's proxy wrapped in `withAuthProxy` from `@sssb/kit/adapters/proxy`, and its
44
+ `config.matcher` sends it every page and every `/api` route: in real mode SSSB's auth adapter needs its provider's
45
+ middleware to have seen the request, and `withAuthProxy` runs that middleware around your proxy (loading none of it
46
+ in simulated mode). Never import the provider's middleware yourself. A page path has no dot in it (the generated
47
+ matcher leaves those out, as static files), and Next buffers at most `proxyClientMaxBodySize` (10MB by default) of a
48
+ body the proxy sees, so an upload limit above it raises
49
+ `experimental.proxyClientMaxBodySize` in `next.config.ts` too.
39
50
 
40
51
  ## Data
41
52
 
@@ -109,10 +120,13 @@ preset, SSSB's conformance suite or `sssb doctor`; keep the rest by hand.
109
120
  route once, and `DEV_TICK_SECONDS=<n> pnpm dev` ticks it every n seconds. The ticker is off by default and stays off
110
121
  under e2e. The cron route (`src/app/api/webhooks/cron/route.ts`) stays behind `withWebhookSecret`: never add a
111
122
  bypass for the ticker.
123
+ - The Simulator panel on `pnpm dev` is SSSB's: `src/app/api/simulator/[...path]/route.ts` serves it and the locale
124
+ layout renders it, both in simulated mode only. Each handler in that route file opens with the simulated-mode 404 and
125
+ imports SSSB's handler after it; that first line is what exempts the route from `authorize(...)`.
112
126
  - 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`.
127
+ server; `pnpm exec sssb port`, run from the app, prints its port. An app declares its port slot in its package.json,
128
+ `"sssb": { "port": { "name": "ledger", "default": 3800 } }`, and reads its override from `LEDGER_PORT`; its scripts and
129
+ Playwright config name no slot (`sssb tick`, `sssb dev-tick`, `originForApp(__dirname)`), so they read it. Every app of
130
+ a workspace needs a slot of its own, which `sssb doctor` checks: `pnpm exec sssb add-app <slug>` gives a new app one.
117
131
  - Before finishing a change, run `pnpm verify` from the workspace root. Format with `pnpm lint:fix`, never by hand.
118
132
  Commit messages are conventional commits; the commit-msg hook runs commitlint.
@@ -1,8 +1,8 @@
1
1
  {
2
- "version": "0.2.0",
2
+ "version": "0.3.0",
3
3
  "workflow": {
4
4
  "repository": "safeinsights/sssb",
5
- "ref": "e8b1dbfad8d5f7a59c1a49fd39714d73229320c1"
5
+ "ref": "4fd7633d89d3116b66b28d6c7f9dbb7873874f05"
6
6
  },
7
7
  "packageManager": "pnpm@11.14.0",
8
8
  "engines": {
@@ -29,7 +29,7 @@
29
29
  "prettier": "^3.9.10",
30
30
  "tsx": "^4.23.15",
31
31
  "typescript": "~6.0.3",
32
- "typescript-eslint": "^8.72.0",
32
+ "typescript-eslint": "^8.73.0",
33
33
  "vitest": "^4.1.12"
34
34
  },
35
35
  "allowBuilds": {