@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,85 @@
1
+ /**
2
+ * Single source of truth for deployment and external-service parameters.
3
+ *
4
+ * Every PLACEHOLDER_ value maps to a row in docs/cutover-checklist.md describing what fills it and
5
+ * when. Fields ending in `Name` are the names of secrets (env var / Secrets Manager entry) — secret
6
+ * VALUES never live in the repo.
7
+ *
8
+ * WHAT IS LINT-ENFORCED (`sssb/no-process-env`, @sssb/eslint-plugin): `process.env` is read ONLY
9
+ * inside SSSB's own adapters (@sssb/kit/adapters) and an app's own real adapters (apps/<app>/src/adapters/real, which
10
+ * may not read the run mode) — every other module imports the resolved value (this file for
11
+ * deployment/service params; `isSimulated`/`isDemoMode` from @sssb/kit/adapters for run mode). Exemptions:
12
+ * instrumentation files (NEXT_PUBLIC needs literal inlining) and the two secret readers
13
+ * (service-auth/{webhook,mailgun}.ts). This file may not read process.env itself (the ban covers config/).
14
+ * An app-owned adapter's non-secret parameters and secret NAMES are recorded here too, with their cutover
15
+ * rows (SSSB's recipe for an app-owned adapter, docs/recipes/app-owned-adapter.md in SSSB's repository).
16
+ * NOT enforced: that a param's literal VALUE appears nowhere else in the repo — that stays a convention,
17
+ * not a scanner.
18
+ */
19
+
20
+ export const params = {
21
+ aws: {
22
+ // cutover: cloud-accounts
23
+ devAccountId: 'PLACEHOLDER_AWS_DEV_ACCOUNT_ID',
24
+ prodAccountId: 'PLACEHOLDER_AWS_PROD_ACCOUNT_ID',
25
+ region: 'PLACEHOLDER_AWS_REGION',
26
+ },
27
+ domains: {
28
+ // cutover: domains-and-certs — first deploys use *.cloudfront.net
29
+ staging: 'PLACEHOLDER_STAGING_DOMAIN',
30
+ production: 'PLACEHOLDER_PRODUCTION_DOMAIN',
31
+ demo: 'PLACEHOLDER_DEMO_DOMAIN',
32
+ certificateArn: 'PLACEHOLDER_ACM_CERTIFICATE_ARN',
33
+ },
34
+ database: {
35
+ // cutover: data-api — how the app reaches Postgres; infra/ (SssbApp) builds the matching network shape
36
+ // and sets DATABASE_TRANSPORT from it.
37
+ // 'pg' (the default): node-postgres from a Lambda inside the database's VPC. 'data-api' (opt-in):
38
+ // the RDS Data API from a Lambda outside any VPC, with no NAT (ADR-0002, addendum 2026-11-16).
39
+ transport: 'pg' as 'pg' | 'data-api',
40
+ },
41
+ ports: {
42
+ // Which of SSSB's optional ports this app uses in a deployment; infra/ (SssbApp) sets LLM_PROVIDER,
43
+ // EMAIL_PROVIDER, INBOUND_EMAIL_PROVIDER and JOBS_RUNNER from it. `none` leaves the port absent: real mode
44
+ // requires none of its settings (and its cutover row does not apply), and a call through it fails naming the
45
+ // switch. Never fill an unused port's settings with placeholder values instead.
46
+ // No model calls: set 'anthropic' when the app adds one (cutover: llm-key)
47
+ llm: 'none' as 'anthropic' | 'none',
48
+ // cutover: email-outbound — invitations, notifications, digests
49
+ email: 'mailgun' as 'mailgun' | 'none',
50
+ // No inbound email route: set 'mailgun' when the app adds /api/webhooks/email (cutover: email-inbound)
51
+ inboundEmail: 'none' as 'mailgun' | 'none',
52
+ // Each job's handler runs in the server, within its time limit, so no CodeBuild project is needed; 'codebuild'
53
+ // (cutover: job-runner) runs each job as a build instead, completed through a jobs webhook route
54
+ jobs: 'in-process' as 'codebuild' | 'in-process' | 'none',
55
+ },
56
+ clerk: {
57
+ // cutover: auth-dev (development instance), auth-prod (production instance)
58
+ publishableKeyName: 'PLACEHOLDER_CLERK_PUBLISHABLE_KEY_NAME',
59
+ secretKeyName: 'PLACEHOLDER_CLERK_SECRET_KEY_NAME',
60
+ },
61
+ mailgun: {
62
+ // cutover: email-outbound
63
+ domain: 'PLACEHOLDER_MAILGUN_DOMAIN',
64
+ apiKeyName: 'PLACEHOLDER_MAILGUN_API_KEY_NAME',
65
+ // cutover: email-inbound — the HMAC signing key Mailgun signs inbound webhooks with
66
+ webhookSigningKeyName: 'PLACEHOLDER_MAILGUN_WEBHOOK_SIGNING_KEY_NAME',
67
+ },
68
+ sentry: {
69
+ // cutover: errors — the Sentry wiring is inert until a DSN is set
70
+ dsn: 'PLACEHOLDER_SENTRY_DSN',
71
+ org: 'PLACEHOLDER_SENTRY_ORG',
72
+ project: 'PLACEHOLDER_SENTRY_PROJECT',
73
+ },
74
+ posthog: {
75
+ // cutover: analytics — real adapter is enabled in staging/prod only
76
+ projectKey: 'PLACEHOLDER_POSTHOG_PROJECT_KEY',
77
+ host: 'PLACEHOLDER_POSTHOG_HOST',
78
+ },
79
+ anthropic: {
80
+ // cutover: llm-key — unlocks `pnpm llm:record`
81
+ apiKeyName: 'PLACEHOLDER_ANTHROPIC_API_KEY_NAME',
82
+ },
83
+ } as const
84
+
85
+ export type Params = typeof params
@@ -0,0 +1,85 @@
1
+ # infra/ — this app's CDK app (DRAFT)
2
+
3
+ This app's deployment, per ADR-0001 and ADR-0014 (D8): one stack holding SSSB's `SssbApp` construct
4
+ (`@sssb/cdk`, `packages/cdk` in SSSB's repository). The construct builds the Next standalone server in one
5
+ Lambda via the AWS Lambda Web Adapter, its Function URL behind CloudFront, static assets from S3, the
6
+ framework's migrator bundled with this app's own migrations, Aurora PostgreSQL Serverless v2 (min-capacity 0
7
+ outside production), alarms and a budget. `app.ts` instantiates it with `..` as the app's directory and the
8
+ app's own `config/params.ts`; `lib/tags.ts` is your organisation's tagging, applied to the whole stack.
9
+
10
+ This is a **draft you are meant to take over**, not a finished deployment. It exists so the hosting
11
+ decision is written down in runnable form rather than as prose, and so `pnpm synth` here proves the shape
12
+ compiles offline before anyone has an AWS account. The stack in `app.ts` is yours: add your own constructs
13
+ beside `SssbApp`. The construct reads only the app's directory and params, so this directory can also move
14
+ into an infrastructure repository or a root `infra/` that composes several apps; give each `SssbApp` an id of
15
+ its own there.
16
+
17
+ ## Status: authored — cutover
18
+
19
+ - `pnpm synth` in this directory is the verification bar: green, offline, zero credentials
20
+ (environment-agnostic stack, no lookups). CI runs it for every app.
21
+ - **Region.** The distribution runs a Lambda@Edge function on each request to the server (it adds the body's hash a
22
+ `POST` needs to reach the Function URL), and Lambda@Edge lives in us-east-1. While the stack is
23
+ environment-agnostic it deploys to us-east-1 only: elsewhere the deploy fails after the database is created, and a
24
+ production stack's retained database and buckets may outlive the rollback. Give the stack an explicit `env` (account
25
+ and region) before deploying anywhere else: the construct then puts that function in a us-east-1 stack of its own,
26
+ with this stack's tags, so bootstrap us-east-1 too and deploy by naming this stack (or with `--all`).
27
+ - **Nothing here deploys until** (see `docs/cutover-checklist.md`): `cloud-accounts` fills
28
+ `../config/params.ts` · `recurring-cost` — Aurora, the NAT gateway (on the `pg` shape), and CloudFront need
29
+ explicit approval. Not a checklist row, but do it first: if your organisation ships its own CDK construct
30
+ library, replace `lib/tags.ts` with it.
31
+
32
+ ## Two network shapes — decide before the first deploy
33
+
34
+ `params.database.transport` in the app's `config/params.ts` picks one (ADR-0001 and ADR-0002, addenda
35
+ 2026-11-16). On an existing stack a switch does not replace anything: it fails on overlapping subnet
36
+ CIDRs and rolls back. Changing shape later means a new stack and a snapshot restore.
37
+
38
+ - **`pg` (default):** both Lambdas inside the VPC, reaching Aurora over a socket. One NAT gateway carries
39
+ their egress.
40
+ - **`data-api` (opt-in):**
41
+ - only the cluster lives in the VPC, in isolated subnets with no NAT gateway;
42
+ - both Lambdas run outside it and reach Aurora through the RDS Data API, authorised by IAM alone;
43
+ - the function configuration holds no database credential.
44
+
45
+ Cutover rows `data-api` (the transport, proven live by SSSB's `docs/runbooks/data-api.md` runbook) and
46
+ `data-api-access` (this shape, deployed) close it.
47
+
48
+ ## What synth asserts
49
+
50
+ `cdk synth` fails unless each of these holds, for the shape the params choose (the construct's header,
51
+ `packages/cdk/src/sssb-app.js` in SSSB's repository, is the full list):
52
+
53
+ - the `@sssb/kit` this app resolves is the construct's own version (SSSB's packages are released in
54
+ lockstep), installed under the project root (the lock file's directory), which also installs esbuild: the
55
+ migrator is bundled locally, never in CDK's Docker fallback;
56
+ - the slug is the `APP_SLUG` in `../config/app.ts`, and a linked `@sssb/app-config` is this app's own
57
+ `src/app-config`;
58
+ - the server's final environment, escape-hatch overrides included, sets `APP_MODE=real` and has neither
59
+ `DEMO_MODE` nor `E2E_BUILD`, so fake adapters cannot serve a deployment; the migrator carries neither either;
60
+ - the migrator deploys the bundle esbuild staged during this synth, and that bundle carries every migration the
61
+ app's registry names under a literal key, names the framework's and the app's migration registries in
62
+ esbuild's path comments (so a minified bundle fails instead of passing unread), and holds no code from a test
63
+ fixture. The construct resolves the migrator from this app's `@sssb/kit` and passes the seam to esbuild
64
+ explicitly (`--alias:@sssb/app-config=<app>/src/app-config`): in SSSB's own repository the nearest tsconfig
65
+ points that alias at SSSB's test fixture, and a migrator bundled with it would ship the fixture's migrations
66
+ instead of the app's.
67
+
68
+ SSSB's own repository also synthesizes both shapes for every app and checks the way in (`packages/cdk`'s
69
+ test): on both, each statement that can grant a Secrets Manager action names the cluster's own secret alone, no
70
+ role attaches an AWS-managed policy beyond the two Lambda execution policies, and every database cluster is
71
+ encrypted at rest; on `data-api`, each statement that can grant an `rds-data` action names the cluster alone and
72
+ the database's security group admits nothing.
73
+
74
+ ## Deploys — checks in CI, deploys in your own pipeline
75
+
76
+ `.github/workflows/checks.yml` runs checks only; there is deliberately no GitHub Actions CD here,
77
+ because the deploy pipeline is the piece most tied to an organisation's accounts and approval gates.
78
+ The shape this stack assumes: a pipeline that uploads the standalone build zip the `Server` function
79
+ expects (the construct's placeholder asset is a `run.sh` that execs `node server.js`) and invokes the
80
+ `Migrator` before shifting traffic. The construct sets the server's `HOSTNAME` to `0.0.0.0`: a `run.sh` that sets
81
+ another value breaks requests through the auth provider's proxy, so leave it out of yours. Cutover row `deploy-pipeline` is where that gets built.
82
+
83
+ Nothing in this directory may depend on app source beyond `config/app.ts` and `config/params.ts`, which is
84
+ what makes moving it mechanical. `pnpm typecheck` covers it, through the app's own `typecheck` (`tsc --noEmit -p infra`,
85
+ with `infra/tsconfig.json`), and `synth` runs it.
@@ -0,0 +1,45 @@
1
+ import path from 'node:path'
2
+ import { SssbApp } from '@sssb/cdk'
3
+ import * as cdk from 'aws-cdk-lib'
4
+ import { APP_SLUG } from '../config/app'
5
+ import { params } from '../config/params'
6
+ import { addTags, TAGS } from './lib/tags'
7
+
8
+ /**
9
+ * This app's deployment (ADR-0014, D8): one stack holding SSSB's `SssbApp` construct, built from this app's
10
+ * own directory and `config/params.ts`. Environment-agnostic until cutover (`cloud-accounts`) fills
11
+ * config/params.ts — no account/region is bound, so `pnpm synth` runs offline with zero credentials.
12
+ *
13
+ * The stack is yours: add your own constructs beside `SssbApp`, or move it into a stack your organisation's
14
+ * infrastructure already has.
15
+ */
16
+ const ENVIRONMENTS = ['Staging', 'Production'] as const
17
+ type Environment = (typeof ENVIRONMENTS)[number]
18
+
19
+ const app = new cdk.App()
20
+
21
+ const environment = app.node.tryGetContext('environment') as Environment | undefined
22
+ if (!environment || !ENVIRONMENTS.includes(environment)) {
23
+ throw new Error(`context "environment" must be one of ${ENVIRONMENTS.join(', ')}`)
24
+ }
25
+
26
+ // Stack id derives from the app slug (capitalized) so two apps in one AWS account never collide.
27
+ const stackId = `${APP_SLUG.charAt(0).toUpperCase()}${APP_SLUG.slice(1)}AppStack`
28
+
29
+ const stack = new cdk.Stack(app, stackId, {
30
+ description: `${APP_SLUG} application stack (Next standalone on Lambda via Web Adapter, ADR-0001)`,
31
+ })
32
+ addTags(stack, { ...TAGS, Environment: environment })
33
+
34
+ // The id `Default` is left out of every logical id under it, so the resources keep the ids they had when
35
+ // they were this stack's own children (before ADR-0014's P9) and a deployed stack updates in place. A second
36
+ // SssbApp in the same stack needs an id of its own.
37
+ new SssbApp(stack, 'Default', {
38
+ appDir: path.join(__dirname, '..'),
39
+ slug: APP_SLUG,
40
+ params,
41
+ environment,
42
+ production: environment === 'Production',
43
+ })
44
+
45
+ app.synth()
@@ -0,0 +1,9 @@
1
+ {
2
+ "app": "pnpm exec tsx app.ts",
3
+ "context": {
4
+ "environment": "Staging"
5
+ },
6
+ "watch": {
7
+ "exclude": ["README.md", "cdk*.json", "**/*.d.ts", "**/*.js", "node_modules"]
8
+ }
9
+ }
@@ -0,0 +1,35 @@
1
+ import * as cdk from 'aws-cdk-lib'
2
+ import type { Construct } from 'constructs'
3
+ import { APP_SLUG } from '../../config/app'
4
+
5
+ /**
6
+ * The mandatory-tag pattern: one map applied to EVERY construct in the stack (`addTags` below), so
7
+ * no resource can be created without answering the questions the organisation asks of it.
8
+ *
9
+ * The first three keys are near-universal — what this is (`Name`, `Application`) and who answers for
10
+ * it (`Owner`); `Environment` is the fourth, added per stack in `../app.ts` because only the stack
11
+ * knows which deployment it is. Keep those.
12
+ *
13
+ * The classification keys below are an EXAMPLE of the other half of the pattern — the governance
14
+ * taxonomy an organisation mandates so its estate can be queried by sensitivity, criticality and
15
+ * blast radius. Every organisation's is different: REPLACE them with your own policy's keys (or drop
16
+ * them if you have none), and if your organisation ships shared CDK constructs for tagging, import
17
+ * those instead of this file. `UPDATE-ME` is a deliberate tripwire — it synths and deploys,
18
+ * and stays obvious in the console until someone fills it in.
19
+ */
20
+ export const TAGS = {
21
+ Name: APP_SLUG,
22
+ Application: APP_SLUG,
23
+ Owner: 'UPDATE-ME',
24
+ // Example governance taxonomy — replace these four keys with your own organisation's.
25
+ AssetClassification: 'UPDATE-ME',
26
+ DataClassification: 'UPDATE-ME',
27
+ MissionCriticality: 'UPDATE-ME',
28
+ AccessLevel: 'UPDATE-ME',
29
+ } as const
30
+
31
+ export function addTags(scope: Construct, tags: Record<string, string>): void {
32
+ for (const [key, value] of Object.entries(tags)) {
33
+ cdk.Tags.of(scope).add(key, value)
34
+ }
35
+ }
@@ -0,0 +1,20 @@
1
+ {
2
+ "name": "starter-infra",
3
+ "version": "0.1.0",
4
+ "private": true,
5
+ "license": "MIT",
6
+ "description": "This app's deployment: SSSB's SssbApp construct in a stack of its own (ADR-0001, ADR-0014 D8). A draft you take over at cutover.",
7
+ "scripts": {
8
+ "synth": "cdk synth --quiet",
9
+ "diff": "cdk diff"
10
+ },
11
+ "dependencies": {
12
+ "@sssb/cdk": "workspace:*",
13
+ "@sssb/tools": "workspace:*",
14
+ "aws-cdk-lib": "^2.274.0",
15
+ "constructs": "^10.8.1"
16
+ },
17
+ "devDependencies": {
18
+ "aws-cdk": "^2.1146.0"
19
+ }
20
+ }
@@ -0,0 +1,13 @@
1
+ {
2
+ // The deployment's own TypeScript program: the app's options (the `extends`, so a compiler option the app sets
3
+ // holds here too), over infra/ only. Not part of the app's program, which `next build` typechecks: the CDK's
4
+ // declarations have no place in the app's build. The app's `typecheck` script runs this one after its own.
5
+ "extends": "../tsconfig.json",
6
+ "compilerOptions": {
7
+ "incremental": false,
8
+ // A CDK app runs in Node (cdk.json runs it with tsx).
9
+ "types": ["node"]
10
+ },
11
+ "include": ["**/*.ts"],
12
+ "exclude": ["node_modules", "cdk.out"]
13
+ }
@@ -0,0 +1,21 @@
1
+ {
2
+ "welcome": {
3
+ "appName": "Starter",
4
+ "title": "Starter",
5
+ "subtitle": "A minimal app to grow from: one entity, one card, and everything else switched off.",
6
+ "dashboardLink": "Go to the dashboard"
7
+ },
8
+ "dashboard": {
9
+ "title": "Dashboard",
10
+ "signedInAs": "Signed in as {name} ({role})."
11
+ },
12
+ "items": {
13
+ "title": "Items",
14
+ "hint": "Items belong to the team you're working in — and never leave your tenant.",
15
+ "empty": "No items in this team yet.",
16
+ "addLabel": "New item",
17
+ "addButton": "Add item",
18
+ "readOnlyHint": "You have read-only access to items in this team.",
19
+ "loadMore": "Show older items"
20
+ }
21
+ }
@@ -0,0 +1,21 @@
1
+ {
2
+ "welcome": {
3
+ "appName": "Starter",
4
+ "title": "Starter",
5
+ "subtitle": "Una aplicación mínima desde la que crecer: una entidad, una tarjeta y todo lo demás apagado.",
6
+ "dashboardLink": "Ir al panel"
7
+ },
8
+ "dashboard": {
9
+ "title": "Panel",
10
+ "signedInAs": "Sesión iniciada como {name} ({role})."
11
+ },
12
+ "items": {
13
+ "title": "Elementos",
14
+ "hint": "Los elementos pertenecen al equipo en el que trabajas y nunca salen de tu organización.",
15
+ "empty": "Aún no hay elementos en este equipo.",
16
+ "addLabel": "Nuevo elemento",
17
+ "addButton": "Añadir elemento",
18
+ "readOnlyHint": "Tienes acceso de solo lectura a los elementos de este equipo.",
19
+ "loadMore": "Ver elementos anteriores"
20
+ }
21
+ }
@@ -0,0 +1,9 @@
1
+ import { withSssb } from '@sssb/tools/next'
2
+
3
+ /**
4
+ * This app's Next config, deliberately shorter than SSSB's reference app's: no Sentry wrapper (that is a cutover row,
5
+ * and the adapter is inert without a DSN), no Panda/PostCSS pipeline (Mantine ships its own reset). What every SSSB
6
+ * app needs (the framework transpiled, next-intl pointed at the framework's request config, the standalone output,
7
+ * a hermetic `next dev`) comes from the preset, @sssb/tools/next.
8
+ */
9
+ export default withSssb({ typedRoutes: true }, { appDir: __dirname })
@@ -0,0 +1,40 @@
1
+ {
2
+ "name": "starter",
3
+ "version": "0.1.0",
4
+ "private": true,
5
+ "license": "MIT",
6
+ "description": "The starter app: the minimum an adopter keeps — one entity, one card, and an otherwise empty seam (ADR-0007, ADR-0012).",
7
+ "scripts": {
8
+ "dev": "NEXT_TELEMETRY_DISABLED=1 APP_MODE=simulated sssb dev-tick -- next dev --port \"$(sssb port)\"",
9
+ "tick": "sssb tick",
10
+ "build": "NEXT_TELEMETRY_DISABLED=1 next build",
11
+ "start": "next start --port \"$(sssb port)\"",
12
+ "typecheck": "next typegen && tsc --noEmit && tsc --noEmit -p infra",
13
+ "sssb:doctor": "sssb doctor",
14
+ "check:e2e": "sssb check-e2e",
15
+ "test:e2e": "NEXT_TELEMETRY_DISABLED=1 playwright test",
16
+ "build:demo-static": "vite build --config vite.demo.config.ts",
17
+ "check:demo-size": "sssb check-demo-size 840000",
18
+ "e2e:demo-static": "playwright test --config playwright.demo.config.ts"
19
+ },
20
+ "dependencies": {
21
+ "@mantine/core": "^9.7.3",
22
+ "@sssb/kit": "workspace:*",
23
+ "kysely": "^0.29.7",
24
+ "next": "^16.4.6",
25
+ "next-intl": "^4.14.9",
26
+ "react": "~19.3.1",
27
+ "react-dom": "~19.3.1"
28
+ },
29
+ "devDependencies": {
30
+ "@playwright/test": "^1.64.1",
31
+ "@sssb/tools": "workspace:*",
32
+ "@vitejs/plugin-react": "^6.1.2",
33
+ "embedded-postgres": "18.4.0-beta.17",
34
+ "vite": "^8.3.5",
35
+ "vite-plugin-singlefile": "^2.3.4"
36
+ },
37
+ "sssb": {
38
+ "port": "starter"
39
+ }
40
+ }
@@ -0,0 +1,50 @@
1
+ import { defineConfig, devices } from '@playwright/test'
2
+ import { originForApp } from '@sssb/tools/ports'
3
+ import { assertNoLiveDevTicker } from '@sssb/tools/ticker-marker'
4
+
5
+ // A dev server started with `DEV_TICK_SECONDS` set would be ADOPTED by `reuseExistingServer` below and tick under the
6
+ // suite; the ticker leaves a marker while it runs, and this refuses to load past it (@sssb/tools/ticker-marker).
7
+ assertNoLiveDevTicker()
8
+
9
+ /**
10
+ * A port of this app's own: two apps in one workspace must be able to run (and be tested) side
11
+ * by side without one silently reusing the other's dev server (or a foreign server squatting :3000,
12
+ * which `reuseExistingServer` would otherwise adopt as this app's).
13
+ *
14
+ * Both numbers now come from @sssb/tools/ports rather than being written here, which extends that same
15
+ * guarantee ACROSS checkouts: a linked worktree gets its own pair, so two agent sessions running e2e
16
+ * at once no longer collide either. `pnpm dev` derives the identical number from the same function.
17
+ */
18
+ const BASE_URL = originForApp(__dirname)
19
+
20
+ export default defineConfig({
21
+ testDir: './tests/e2e',
22
+ fullyParallel: true,
23
+ // This app's whole suite is two short specs, so the first always starts against a cold dev server and pays a
24
+ // full Next compile on every route it touches — sign-in, dashboard, the items route, the Simulator's. The default
25
+ // 30s is marginal for that (it timed out on the first run and passed on retry), and there is no
26
+ // warm-up pass to inherit, so the budget is raised rather than left to flake.
27
+ timeout: 60_000,
28
+ expect: { timeout: 15_000 },
29
+ forbidOnly: !!process.env['CI'],
30
+ retries: process.env['CI'] ? 2 : 1,
31
+ // One worker, on CI too — this app's whole suite is two short specs, so parallelism buys little here,
32
+ // and more workers against one shared world (one `.data` behind one dev server) cost reliability rather than
33
+ // saving time.
34
+ workers: 1,
35
+ reporter: process.env['CI'] ? 'github' : 'list',
36
+ use: {
37
+ baseURL: BASE_URL,
38
+ trace: 'on-first-retry',
39
+ },
40
+ projects: [{ name: 'chromium', use: { ...devices['Desktop Chrome'] } }],
41
+ webServer: {
42
+ command: 'pnpm dev',
43
+ url: BASE_URL,
44
+ // `pnpm dev` ticks the scheduler on a timer when DEV_TICK_SECONDS is set (`sssb dev-tick`). The e2e suite expects a
45
+ // scheduler that does nothing until a test asks, so whatever is in the caller's shell, the server it starts is not ticked.
46
+ env: { DEV_TICK_SECONDS: '' },
47
+ reuseExistingServer: !process.env['CI'],
48
+ timeout: 120_000,
49
+ },
50
+ })
@@ -0,0 +1,10 @@
1
+ import { defineConfig, devices } from '@playwright/test'
2
+
3
+ /** Drives the built static shell straight from file:// — no server involved. */
4
+ export default defineConfig({
5
+ testDir: './tests/demo-static',
6
+ fullyParallel: true,
7
+ expect: { timeout: 10_000 },
8
+ reporter: process.env['CI'] ? 'github' : 'list',
9
+ projects: [{ name: 'chromium', use: { ...devices['Desktop Chrome'] } }],
10
+ })
@@ -0,0 +1,61 @@
1
+ 'use client'
2
+
3
+ import { useEffect, useState } from 'react'
4
+ import { DashboardScreen, type DashboardUser } from '@/components/dashboard-screen'
5
+ import { ItemsCard, type Item } from '@/components/items-card'
6
+
7
+ /** One page of items; no cursor is the first page. Null when the request failed, so a flaky network is a page that does not grow, not an unhandled rejection. */
8
+ async function fetchItemsPage(after: string | null): Promise<{ items: Item[]; nextCursor: string | null } | null> {
9
+ try {
10
+ const response = await fetch(after === null ? '/api/items' : `/api/items?cursor=${encodeURIComponent(after)}`)
11
+ return response.ok ? ((await response.json()) as { items: Item[]; nextCursor: string | null }) : null
12
+ } catch {
13
+ return null
14
+ }
15
+ }
16
+
17
+ export function DashboardGlue({ user, canCreateItem }: { user: DashboardUser; canCreateItem: boolean }) {
18
+ const [items, setItems] = useState<Item[]>([])
19
+ // The cursor for the NEXT page, or null at the end. The glue owns fetching; the card stays a plain list.
20
+ const [cursor, setCursor] = useState<string | null>(null)
21
+
22
+ useEffect(() => {
23
+ // Sets state only once the response lands — the legitimate "sync with an external system"
24
+ // case, so the react-hooks set-state-in-effect rule does not fire here.
25
+ void fetchItemsPage(null).then((page) => {
26
+ if (!page) return
27
+ setItems(page.items)
28
+ setCursor(page.nextCursor)
29
+ })
30
+ }, [])
31
+
32
+ /** "Show older items" APPENDS the next page, so what the reader has scrolled past stays put. */
33
+ async function loadMore() {
34
+ const page = await fetchItemsPage(cursor)
35
+ if (!page) return
36
+ setItems((previous) => [...previous, ...page.items])
37
+ setCursor(page.nextCursor)
38
+ }
39
+
40
+ return (
41
+ <DashboardScreen user={user}>
42
+ <ItemsCard
43
+ items={items}
44
+ canCreate={canCreateItem}
45
+ hasMore={cursor !== null}
46
+ onLoadMore={loadMore}
47
+ onAdd={async (title) => {
48
+ const response = await fetch('/api/items', {
49
+ method: 'POST',
50
+ headers: { 'content-type': 'application/json' },
51
+ body: JSON.stringify({ title }),
52
+ })
53
+ if (response.ok) {
54
+ const { item } = (await response.json()) as { item: Item }
55
+ setItems((prev) => [item, ...prev])
56
+ }
57
+ }}
58
+ />
59
+ </DashboardScreen>
60
+ )
61
+ }
@@ -0,0 +1,21 @@
1
+ import { setRequestLocale } from 'next-intl/server'
2
+ import { redirect } from 'next/navigation'
3
+ import { auth } from '@sssb/kit/adapters/index'
4
+ import { canInActiveOrg } from '@sssb/kit/authz/authorize'
5
+ import { DashboardGlue } from './dashboard-glue'
6
+
7
+ export default async function DashboardPage({ params }: { params: Promise<{ locale: string }> }) {
8
+ const { locale } = await params
9
+ setRequestLocale(locale)
10
+ const user = await auth.getCurrentUser()
11
+ if (!user) redirect(`/${locale}${auth.signInPath()}`)
12
+
13
+ // Reflect the server-side authorization in the UI: restricted members get a read-only card. The
14
+ // POST route re-checks with authorize(), so this is presentation, never enforcement.
15
+ return (
16
+ <DashboardGlue
17
+ user={{ name: user.name, role: user.role }}
18
+ canCreateItem={canInActiveOrg(user, 'create', 'Item')}
19
+ />
20
+ )
21
+ }
@@ -0,0 +1,59 @@
1
+ 'use client'
2
+
3
+ import { useTranslations } from 'next-intl'
4
+ import { AppHeader } from '@sssb/kit/components/app-header'
5
+ import { OrgSwitcher, type SwitcherOrg } from '@sssb/kit/components/auth/org-switcher'
6
+ import { UserMenu, type MenuUser } from '@sssb/kit/components/auth/user-menu'
7
+
8
+ /**
9
+ * The framework header, wired to this app. Deliberately barer than SSSB's reference app's: no notification
10
+ * bell (nothing here produces notifications) and no nav (there is one screen). `appName` is passed
11
+ * because the prop is required: one shared framework catalog cannot name two products, so SSSB's
12
+ * catalog carries no product name and every app supplies its own (see AppHeader).
13
+ */
14
+ export function HeaderGlue({
15
+ user,
16
+ orgs,
17
+ activeSlug,
18
+ tenantName,
19
+ locale,
20
+ }: {
21
+ user: MenuUser
22
+ orgs: SwitcherOrg[]
23
+ activeSlug: string
24
+ tenantName: string
25
+ locale: string
26
+ }) {
27
+ const t = useTranslations('welcome')
28
+ return (
29
+ <AppHeader
30
+ appName={t('appName')}
31
+ tenantName={tenantName}
32
+ controls={
33
+ <>
34
+ <OrgSwitcher
35
+ orgs={orgs}
36
+ activeSlug={activeSlug}
37
+ onSwitch={(orgSlug) => {
38
+ void fetch('/api/auth/org', {
39
+ method: 'POST',
40
+ headers: { 'content-type': 'application/json' },
41
+ body: JSON.stringify({ orgSlug }),
42
+ }).then((response) => {
43
+ if (response.ok) window.location.reload()
44
+ })
45
+ }}
46
+ />
47
+ <UserMenu
48
+ user={user}
49
+ onSignOut={() => {
50
+ void fetch('/api/auth/signout', { method: 'POST' }).then((response) => {
51
+ if (response.ok) window.location.assign(`/${locale}`)
52
+ })
53
+ }}
54
+ />
55
+ </>
56
+ }
57
+ />
58
+ )
59
+ }
@@ -0,0 +1,43 @@
1
+ import { setRequestLocale } from 'next-intl/server'
2
+ import { redirect } from 'next/navigation'
3
+ import type { ReactNode } from 'react'
4
+ import { auth } from '@sssb/kit/adapters/index'
5
+ import { findTenant } from '@/seed'
6
+ import { HeaderGlue } from './header-glue'
7
+
8
+ /**
9
+ * Everything in this group requires a signed-in user; signed-out visitors go to /signin.
10
+ *
11
+ * Deliberately shorter than SSSB's reference app's: no access-gate evaluation, because this app seeds no
12
+ * agreements and registers no gates. The capability is not removed — it is simply unused, and an
13
+ * unused capability needs no scaffolding (ADR-0012).
14
+ */
15
+ export default async function ProtectedLayout({
16
+ children,
17
+ params,
18
+ }: {
19
+ children: ReactNode
20
+ params: Promise<{ locale: string }>
21
+ }) {
22
+ const { locale } = await params
23
+ setRequestLocale(locale)
24
+
25
+ const user = await auth.getCurrentUser()
26
+ if (!user) redirect(`/${locale}${auth.signInPath()}`)
27
+
28
+ const orgs = await auth.listMyOrgs()
29
+ const tenantName = findTenant(user.tenantSlug)?.name ?? user.tenantSlug
30
+
31
+ return (
32
+ <>
33
+ <HeaderGlue
34
+ user={{ name: user.name, email: user.email }}
35
+ orgs={orgs}
36
+ activeSlug={user.orgSlug}
37
+ tenantName={tenantName}
38
+ locale={locale}
39
+ />
40
+ {children}
41
+ </>
42
+ )
43
+ }