@fabrika/builder 0.9.0-dev.13 → 0.9.0-dev.14

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 (96) hide show
  1. package/BUILD-CONTRACT.md +9 -3
  2. package/README.md +39 -9
  3. package/cli/src/bin.ts +14 -1
  4. package/cli/src/build-review.ts +66 -0
  5. package/cli/src/build-status.ts +41 -3
  6. package/cli/src/catalog.ts +34 -2
  7. package/cli/src/commands/advance.ts +48 -6
  8. package/cli/src/commands/build.ts +152 -15
  9. package/cli/src/commands/design.ts +34 -0
  10. package/cli/src/commands/flows.ts +32 -0
  11. package/cli/src/commands/induce.ts +2 -2
  12. package/cli/src/commands/init.ts +7 -1
  13. package/cli/src/commands/next.ts +9 -2
  14. package/cli/src/context.ts +2 -1
  15. package/cli/src/contrast.ts +301 -0
  16. package/cli/src/daemon-client.ts +29 -3
  17. package/cli/src/design-review.ts +261 -0
  18. package/cli/src/flows.ts +162 -0
  19. package/cli/src/frontmatter.ts +32 -0
  20. package/cli/src/index.ts +10 -1
  21. package/cli/src/induce.ts +61 -3
  22. package/cli/src/issues.ts +15 -29
  23. package/cli/src/layout.ts +5 -2
  24. package/cli/src/packet.ts +36 -3
  25. package/cli/src/phase-state.ts +19 -1
  26. package/cli/src/verify.ts +50 -0
  27. package/daemon/src/handlers.ts +32 -6
  28. package/daemon/src/phases.ts +7 -109
  29. package/daemon/src/platform-source.ts +8 -0
  30. package/decisions/README.md +2 -2
  31. package/decisions/patterns/cf-contract-app.md +57 -0
  32. package/decisions/technologies/bun.md +2 -1
  33. package/decisions/technologies/cf-fabrika-contract.md +45 -0
  34. package/decisions/technologies/cloudflare.md +3 -1
  35. package/decisions/technologies/oblaka.md +1 -1
  36. package/decisions/technologies/opice.md +1 -1
  37. package/decisions/technologies/react.md +1 -1
  38. package/decisions/technologies/tailwind.md +5 -5
  39. package/decisions/technologies/zerops-fabrika-auth.md +1 -1
  40. package/decisions/technologies/zerops-platform.md +1 -1
  41. package/package.json +11 -8
  42. package/shared/approvals.ts +65 -0
  43. package/shared/derive.ts +189 -0
  44. package/shared/gate.ts +20 -0
  45. package/shared/index.ts +6 -1
  46. package/shared/phases.ts +22 -20
  47. package/skill/SKILL.md +25 -16
  48. package/skill/agents/build-orchestrator.md +28 -8
  49. package/skill/agents/flows-author.md +27 -13
  50. package/skill/agents/implementer.md +3 -1
  51. package/skill/agents/opice-skeleton-author.md +8 -7
  52. package/skill/gates/brief.jsx +26 -5
  53. package/skill/gates/review-grid.jsx +3 -8
  54. package/skill/gates/tech.jsx +3 -3
  55. package/stacks/README.md +8 -2
  56. package/stacks/cf-app.md +60 -0
  57. package/stacks/cf-fat.md +1 -0
  58. package/stacks/cf-internal-app.md +2 -2
  59. package/stacks/cf-lightweight.md +3 -2
  60. package/stacks/contember-app.md +1 -0
  61. package/stacks/content-site.md +1 -0
  62. package/stacks/zerops-app.md +1 -0
  63. package/types/cli/src/bin.d.ts +1 -1
  64. package/types/cli/src/build-review.d.ts +13 -0
  65. package/types/cli/src/build-status.d.ts +16 -1
  66. package/types/cli/src/catalog.d.ts +9 -0
  67. package/types/cli/src/commands/design.d.ts +1 -0
  68. package/types/cli/src/commands/flows.d.ts +1 -0
  69. package/types/cli/src/contrast.d.ts +59 -0
  70. package/types/cli/src/daemon-client.d.ts +13 -2
  71. package/types/cli/src/design-review.d.ts +54 -0
  72. package/types/cli/src/flows.d.ts +28 -0
  73. package/types/cli/src/frontmatter.d.ts +8 -0
  74. package/types/cli/src/index.d.ts +1 -1
  75. package/types/cli/src/induce.d.ts +3 -0
  76. package/types/cli/src/issues.d.ts +4 -0
  77. package/types/cli/src/packet.d.ts +9 -1
  78. package/types/cli/src/phase-state.d.ts +1 -1
  79. package/types/cli/src/verify.d.ts +18 -0
  80. package/types/daemon/src/phases.d.ts +4 -16
  81. package/types/daemon/src/platform-remote.d.ts +6 -2
  82. package/types/shared/approvals.d.ts +32 -0
  83. package/types/shared/derive.d.ts +41 -0
  84. package/types/shared/gate.d.ts +11 -0
  85. package/types/shared/index.d.ts +105 -65
  86. package/types/shared/phases.d.ts +7 -1
  87. package/ui/dist/assets/client.css +1 -1
  88. package/ui/dist/assets/client.vn7hykcn.js +120 -0
  89. package/ui/dist/index.html +1 -1
  90. package/cli/src/derive.ts +0 -105
  91. package/skill/gates/build.jsx +0 -20
  92. package/skill/gates/design.jsx +0 -22
  93. package/skill/gates/flows.jsx +0 -14
  94. package/skill/gates/vision.jsx +0 -27
  95. package/types/cli/src/derive.d.ts +0 -17
  96. package/ui/dist/assets/client.cemdw2n8.js +0 -214
@@ -4,6 +4,7 @@ import { existsSync, readdirSync, readFileSync, statSync } from 'fs'
4
4
  import { basename, dirname, extname, join } from 'path'
5
5
  import type { z } from 'zod'
6
6
  import { builderDaemonUrl, buildEventSchema, planInputSchema } from '../../shared'
7
+ import { gateVerdict } from '../../shared/gate'
7
8
  import type { BuildEvent, BuildStream } from './build-stream'
8
9
  import { COMPILE_TEMP_DIR } from './paths'
9
10
  import { derivePhaseState, type GateOracle } from './phases'
@@ -33,15 +34,22 @@ export interface HandlerContext {
33
34
 
34
35
  function gateOracleFor(sm: SessionManager): GateOracle {
35
36
  return {
36
- getLatestUnconsumedFeedback: (id) => sm.getLatestUnconsumedFeedback(id),
37
- hasGateRevision: (id, gateName) => {
37
+ gateReview: (id, gateName) => {
38
38
  const session = sm.get(id)
39
- if (!session) return false
39
+ if (!session) return { reviewed: false, verdict: 'none', revision: null }
40
40
  for (let i = session.revisions.length - 1; i >= 0; i--) {
41
41
  const r = session.revisions[i]!
42
- if (r.label === gateName) return r.hasFeedback
42
+ if (r.label !== gateName) continue
43
+ // `advance` consumes feedback, and so does re-opening a gate over pending feedback (the 409 below). In a project
44
+ // that keeps approvals only `advance` completes the phase, by recording this revision; a legacy project counts
45
+ // either as reviewed.
46
+ return {
47
+ reviewed: r.hasFeedback && r.feedbackConsumed,
48
+ verdict: r.hasFeedback ? gateVerdict(sm.getSubmittedResponses(id, r.revision)) : 'none',
49
+ revision: r.revision,
50
+ }
43
51
  }
44
- return false
52
+ return { reviewed: false, verdict: 'none', revision: null }
45
53
  },
46
54
  }
47
55
  }
@@ -350,13 +358,30 @@ export function createHandlers(ctx: HandlerContext): Route[] {
350
358
  return jsonResponse({ feedback })
351
359
  }
352
360
 
361
+ /** Consumes a named gate's latest submission: how a gate inside the build (the design checkpoint) is reviewed. */
362
+ function handleGateConsume(_req: Request, _url: URL, match: URLPatternResult): Response {
363
+ const sessionId = routeParam(match, 'id')
364
+ const gateName = routeParam(match, 'name')
365
+ const revisions = sessionManager.get(sessionId)?.revisions ?? []
366
+ let revision: (typeof revisions)[number] | undefined
367
+ for (let i = revisions.length - 1; i >= 0 && !revision; i--) if (revisions[i]!.label === gateName) revision = revisions[i]
368
+ if (!revision?.hasFeedback) return jsonResponse({ found: false })
369
+ if (!revision.feedbackConsumed) {
370
+ sessionManager.consumeFeedback(sessionId, revision.revision)
371
+ broadcastRevisionUpdate(sessionId)
372
+ }
373
+ const verdict = gateVerdict(sessionManager.getSubmittedResponses(sessionId, revision.revision))
374
+ return jsonResponse({ found: true, revision: revision.revision, verdict })
375
+ }
376
+
353
377
  function handleFeedbackConsume(_req: Request, _url: URL, match: URLPatternResult): Response {
354
378
  const sessionId = routeParam(match, 'id')
355
379
  const result = sessionManager.getLatestUnconsumedFeedback(sessionId)
356
380
  if (!result) return jsonResponse({ found: false })
357
381
  sessionManager.consumeFeedback(sessionId, result.revision)
358
382
  broadcastRevisionUpdate(sessionId)
359
- return jsonResponse({ found: true, revision: result.revision, feedback: result.feedback })
383
+ const verdict = gateVerdict(sessionManager.getSubmittedResponses(sessionId, result.revision))
384
+ return jsonResponse({ found: true, revision: result.revision, feedback: result.feedback, verdict })
360
385
  }
361
386
 
362
387
  function handleResponsesGet(_req: Request, _url: URL, match: URLPatternResult): Response {
@@ -450,6 +475,7 @@ export function createHandlers(ctx: HandlerContext): Route[] {
450
475
  { method: 'GET', pattern: new URLPattern({ pathname: '/api/session/:id/skeletons' }), handler: handleSkeletons },
451
476
  { method: 'GET', pattern: new URLPattern({ pathname: '/api/session/:id/revision/:rev/feedback' }), handler: handleFeedbackGet },
452
477
  { method: 'POST', pattern: new URLPattern({ pathname: '/api/session/:id/feedback/consume' }), handler: handleFeedbackConsume },
478
+ { method: 'POST', pattern: new URLPattern({ pathname: '/api/session/:id/gate/:name/consume' }), handler: handleGateConsume },
453
479
  { method: 'POST', pattern: new URLPattern({ pathname: '/api/session/:id/reset' }), handler: handleSessionReset },
454
480
  { method: 'GET', pattern: new URLPattern({ pathname: '/api/session/:id/revision/:rev/responses' }), handler: handleResponsesGet },
455
481
  { method: 'PUT', pattern: new URLPattern({ pathname: '/api/session/:id/revision/:rev/responses' }), handler: handleResponsesPut },
@@ -1,90 +1,13 @@
1
- import { existsSync, readdirSync, statSync } from 'fs'
2
- import { basename, dirname, join } from 'path'
3
- import { isPhaseHint, type Phase, phaseById, type PhaseId, PHASES } from '../../shared/phases'
1
+ import { dirname } from 'path'
2
+ import { derivePhase, type GateReview, offlineGateProbe, type PhaseState as SharedPhaseState } from '../../shared/derive'
3
+ import type { PhaseId } from '../../shared/phases'
4
4
 
5
- export interface PhaseState {
6
- current: PhaseId
7
- index: number
8
- completed: PhaseId[]
9
- reads: string[]
10
- produces: string[]
11
- gate: boolean
5
+ export interface PhaseState extends SharedPhaseState {
12
6
  gateName?: string
13
- satisfied: boolean
14
7
  }
15
8
 
16
9
  export interface GateOracle {
17
- getLatestUnconsumedFeedback(sessionId: string): { revision: number; feedback: string } | null
18
- hasGateRevision?(sessionId: string, gateName: string): boolean
19
- }
20
-
21
- function expandGlob(repoRoot: string, glob: string): string[] {
22
- const abs = join(repoRoot, glob)
23
- if (!abs.includes('*')) {
24
- return existsSync(abs) ? [abs] : []
25
- }
26
- const dir = dirname(abs)
27
- const pattern = basename(abs) // e.g. "*.flow.md", "ISSUE-*.md", "*"
28
- if (!existsSync(dir)) return []
29
-
30
- const re = globToRegExp(pattern)
31
- const out: string[] = []
32
- for (const name of readdirSync(dir)) {
33
- if (re.test(name)) out.push(join(dir, name))
34
- }
35
- return out
36
- }
37
-
38
- function globToRegExp(pattern: string): RegExp {
39
- const escaped = pattern
40
- .replace(/[.+^${}()|[\]\\]/g, '\\$&')
41
- .replace(/\*/g, '.*')
42
- return new RegExp(`^${escaped}$`)
43
- }
44
-
45
- function isNonEmptyFile(p: string): boolean {
46
- try {
47
- const s = statSync(p)
48
- return s.isFile() && s.size > 0
49
- } catch {
50
- return false
51
- }
52
- }
53
-
54
- export function producesSatisfied(phase: Phase, repoRoot: string): boolean {
55
- for (const glob of phase.produces) {
56
- if (isPhaseHint(glob)) return false
57
- const matches = expandGlob(repoRoot, glob).filter(isNonEmptyFile)
58
- if (matches.length === 0) return false
59
- }
60
- return true
61
- }
62
-
63
- export function gateSatisfied(
64
- phase: Phase,
65
- sessionId: string,
66
- oracle?: GateOracle,
67
- ): boolean {
68
- if (!phase.gate) return true
69
- if (!oracle) return true
70
- if (oracle.getLatestUnconsumedFeedback(sessionId) !== null) return false
71
- return oracle.hasGateRevision?.(sessionId, phase.id) ?? true
72
- }
73
-
74
- function resolveReads(phase: Phase, repoRoot: string): string[] {
75
- const out: string[] = []
76
- for (const glob of phase.reads.filter((read) => !isPhaseHint(read))) {
77
- out.push(
78
- ...expandGlob(repoRoot, glob).filter(p => {
79
- try {
80
- return statSync(p).size > 0 || statSync(p).isDirectory()
81
- } catch {
82
- return false
83
- }
84
- }),
85
- )
86
- }
87
- return out
10
+ gateReview(sessionId: string, gateName: PhaseId): GateReview
88
11
  }
89
12
 
90
13
  export function derivePhaseState(
@@ -92,31 +15,6 @@ export function derivePhaseState(
92
15
  sessionId = '',
93
16
  oracle?: GateOracle,
94
17
  ): PhaseState {
95
- const repoRoot = dirname(fabrikaDir)
96
- const completed: PhaseId[] = []
97
-
98
- for (const phase of PHASES) {
99
- const satisfied = producesSatisfied(phase, repoRoot)
100
- if (satisfied && gateSatisfied(phase, sessionId, oracle)) {
101
- completed.push(phase.id)
102
- continue
103
- }
104
- return toState(phase, repoRoot, completed, satisfied)
105
- }
106
-
107
- const build = phaseById('build')
108
- return toState(build, repoRoot, completed.filter(id => id !== build.id), false)
109
- }
110
-
111
- function toState(phase: Phase, repoRoot: string, completed: PhaseId[], satisfied: boolean): PhaseState {
112
- return {
113
- current: phase.id,
114
- index: phase.number,
115
- completed,
116
- reads: resolveReads(phase, repoRoot),
117
- produces: phase.produces,
118
- gate: phase.gate,
119
- ...(phase.gate ? { gateName: phase.id } : {}),
120
- satisfied,
121
- }
18
+ const state = derivePhase(dirname(fabrikaDir), oracle ? (phase) => oracle.gateReview(sessionId, phase.id) : offlineGateProbe)
19
+ return state.gate ? { ...state, gateName: state.current } : state
122
20
  }
@@ -1,6 +1,7 @@
1
1
  import type { AppDto } from '@fabrika/control-contract'
2
2
  import {
3
3
  type FabrikaManifest,
4
+ lockfileBuildBaseRefusal,
4
5
  normalizeZeropsSourceRepository,
5
6
  parseFabrikaManifest,
6
7
  verifyZeropsArtifactSourceDescriptor,
@@ -138,6 +139,13 @@ export async function compileProject(root: string, env: string, appId: string, t
138
139
  if (manifest.target.sourceDescriptor.contents !== readFileSync(join(root, 'zerops.yaml'), 'utf8')) {
139
140
  throw new PlatformError('Compiled descriptor differs from the source')
140
141
  }
142
+ // Here, not in the child: its output is discarded, and this refusal is the hint the person needs.
143
+ const lockfile = join(root, 'bun.lock')
144
+ noSymlinks(lockfile)
145
+ if (lstatSync(lockfile, { throwIfNoEntry: false })?.isFile() === true) {
146
+ const refusal = lockfileBuildBaseRefusal(manifest, readFileSync(lockfile, 'utf8'))
147
+ if (refusal !== null) throw new PlatformError(refusal)
148
+ }
141
149
  return manifest
142
150
  } catch (error) {
143
151
  throw error instanceof PlatformError ? error : new PlatformError('Application compilation returned an invalid manifest')
@@ -115,7 +115,7 @@ See `../stacks/README.md`.
115
115
  | error tracking (`error-tracking`) | `sentry` |
116
116
  | testing | `opice` |
117
117
 
118
- The platform-managed Zerops path adds [`zerops-platform`](technologies/zerops-platform.md) and [`zerops-fabrika-auth`](technologies/zerops-fabrika-auth.md).
118
+ The platform-managed Zerops path adds [`zerops-platform`](technologies/zerops-platform.md) and [`zerops-fabrika-auth`](technologies/zerops-fabrika-auth.md). The Cloudflare contract path adds [`cf-fabrika-contract`](technologies/cf-fabrika-contract.md).
119
119
 
120
120
  ### Patterns (`patterns/`)
121
121
 
@@ -130,7 +130,7 @@ Applied _over_ the technologies they `require` (no package; `kind: pattern`).
130
130
  | CI / CD | `app-deploy` (direct), `fabrika-app-deploy` (control plane), `lib-publish` |
131
131
  | observability | `structured-logging`, `observability` |
132
132
 
133
- Zerops composition uses [`zerops-local-app`](patterns/zerops-local-app.md), [`zerops-control-deploy`](patterns/zerops-control-deploy.md), and [`zerops-postgres-seeds`](patterns/zerops-postgres-seeds.md).
133
+ Zerops composition uses [`zerops-local-app`](patterns/zerops-local-app.md), [`zerops-control-deploy`](patterns/zerops-control-deploy.md), and [`zerops-postgres-seeds`](patterns/zerops-postgres-seeds.md). The Cloudflare contract composition uses [`cf-contract-app`](patterns/cf-contract-app.md).
134
134
 
135
135
  ### Tooling (`tooling/`)
136
136
 
@@ -0,0 +1,57 @@
1
+ ---
2
+ id: cf-contract-app
3
+ kind: pattern
4
+ title: A contract application in one Durable Object per environment, previewed locally with `fabrika app dev`
5
+ slot: app-delivery-shape
6
+ provides: [spa, worker-api, local-development, seed-strategy]
7
+ requires: [cloudflare, cf-fabrika-contract, bun, react, buzola]
8
+ recommends: [opice]
9
+ conflicts: [single-worker-spa, zerops-local-app, named-seeds, zerops-postgres-seeds]
10
+ status: wip
11
+ sources:
12
+ - where: "examples/app/README.md + src/app.ts + src/db/tables.ts + db/migrations/ + build-web.ts in fabrika-platform"
13
+ read: "`serve` over the scoped data layer, the SQLite migrations and the SPA build."
14
+ - where: "docs/decisions/0065-an-application-on-cloudflare-runs-in-one-durable-object-per-environment.md in fabrika-platform"
15
+ read: "Why the application runs in one Durable Object per environment, and what that object owns."
16
+ - where: "docs/reference/cloudflare-platform.md (A Durable Object's SQLite) in fabrika-platform"
17
+ read: "Transactions, savepoints and what blocks the object while one is open."
18
+ - where: "packages/app/skill/references/dev.md in fabrika-platform"
19
+ read: "`fabrika app dev`: the in-memory SQLite on Cloudflare, the stand-in IAM, `dev/seed.ts` and the persona picker."
20
+ - where: "packages/app/skill/references/spa.md + app-setup.md in fabrika-platform"
21
+ read: "The SPA on `@fabrika/ui` and `@fabrika/app/react`, theming through `--fui-*` tokens, and which generated files are ignored."
22
+ ---
23
+
24
+ # A contract application on Cloudflare
25
+
26
+ Apply this to a client-rendered React/Buzola application and its API on
27
+ Cloudflare Workers, in the layout of `examples/app`. It replaces the
28
+ `durable-objects`, `d1`, `kv`, `lopata`, `oblaka` and `wrangler` decisions for
29
+ this shape; do not add them.
30
+
31
+ - **One Durable Object per environment** holds the application's SQLite
32
+ (ADR-0065). The deployer declares and binds it; the application declares no
33
+ object, database or migration of its own. Migrations are `db/migrations/*.sql`
34
+ (STRICT tables, timestamps as UTC ISO text), applied by the object.
35
+ `src/db/tables.ts` declares the table policies over the schema
36
+ `fabrika db codegen` writes, and `src/app.ts` is
37
+ `serve(contract, { database: scoped(tables) })`.
38
+ - **The Worker entrypoint is generated** by `fabrika app build --provider=cloudflare`
39
+ (`fabrika/entry.generated.ts`, `fabrika/migrations.generated.ts`). Never edit
40
+ either. Which generated files are committed and which are ignored is the app
41
+ skill's list (`app-setup.md`, "Ignored files").
42
+ - **The SPA** is built with Bun (`build-web.ts`) into the directory its `c.spa`
43
+ mount names, and the config's `pipeline.build` runs that build. Build it on the
44
+ paved-road kit, `@fabrika/ui` and `@fabrika/app/react`, themed through `--fui-*`
45
+ overrides in its own stylesheet. The example's page is deliberately bare and
46
+ uses neither.
47
+ - **Locally**, `bun run build:web && bunx fabrika app dev` serves the application
48
+ through the proxy decision and a stand-in IAM, on an in-memory SQLite. Pick the
49
+ caller at `/__fabrika/dev`. The example's lopata run (`oblaka.ts`,
50
+ `lopata.config.ts`) does not serve yet, and it reads this repository's packages;
51
+ do not copy it.
52
+ - **Seeds** are `dev/seed.ts`, a `DevSeed` that writes through the application's
53
+ endpoints and names the personas a scenario signs in as. A skeleton's
54
+ `seeds: ['x']` names data that seed creates; there are no `seeds/*.sql` files.
55
+ - **After a contract or table change**, run `fabrika db codegen`,
56
+ `fabrika db test-scaffold` and `fabrika app build`. Run `fabrika-check .`
57
+ yourself: the Cloudflare build does not run it yet.
@@ -21,7 +21,8 @@ sources:
21
21
  > **Team preference.** We prefer **Bun + lopata + a non-vite stack**. Pick Bun as the
22
22
  > runtime/toolchain and Bun-native bundling (e.g. `@buzola/bun-plugin`, pletivo's
23
23
  > Bun build) wherever a decision offers it; reach for `vite` only when a chosen lib
24
- > still mandates it (e.g. React Router v7).
24
+ > still mandates it (e.g. React Router v7). A contract application runs locally with
25
+ > `fabrika app dev`, not lopata (`cf-contract-app`).
25
26
 
26
27
  ## What it is
27
28
 
@@ -0,0 +1,45 @@
1
+ ---
2
+ id: cf-fabrika-contract
3
+ kind: technology
4
+ title: Fabrika IAM with contract enforcement at the proxy Worker on Cloudflare
5
+ slot: authz
6
+ provides: [authentication, authorization, proxy-enforcement]
7
+ requires: [cloudflare]
8
+ recommends: []
9
+ conflicts: [fabrika-iam, cloudflare-access, auth-password-kv, zerops-fabrika-auth]
10
+ npm: ["@fabrika/app@0.9.0-dev.14", "@fabrika/db@0.9.0-dev.14", "@fabrika/ui@0.9.0-dev.14", "@fabrika/provider-cloudflare@0.9.0-dev.14", "@fabrika/check@0.9.0-dev.14", "@fabrika/cli@0.9.0-dev.14", "zod@^3.25.76"]
11
+ status: wip
12
+ sources:
13
+ - where: "packages/app/skill/SKILL.md in fabrika-platform (the `fabrika-app` skill)"
14
+ read: "The application rules: contract first, access forms, table policies, what the checker refuses, what is not built."
15
+ - where: "examples/app/README.md + fabrika.contract.ts + fabrika.config.ts + src/access/endpoints.ts in fabrika-platform"
16
+ read: "A worked Cloudflare contract application: the mounts, the access forms, and the deploy surface `defineApp` owns."
17
+ - where: "docs/decisions/0022-the-proxy-is-the-only-enforcement-point.md + 0048-bind-cloudflare-delivery-to-the-recorded-commit.md in fabrika-platform"
18
+ read: "One evaluator at the proxy; the deployer builds the proxy Worker from the contract of the recorded commit."
19
+ ---
20
+
21
+ # Fabrika IAM with contract enforcement at the proxy Worker
22
+
23
+ The application declares its whole access surface in `fabrika.contract.ts`, as on
24
+ Zerops: a vocabulary, procedures under mounts (`c.rpc`), each with its callers and
25
+ access form, the SPA (`c.spa`) and `c.health`. There are no other routes,
26
+ middleware or custom server.
27
+
28
+ `fabrika.config.ts` is `defineApp({ id, pipeline })` from
29
+ `@fabrika/provider-cloudflare`, with at most the `worker` settings the app skill
30
+ allows (`app-setup.md`); it declares no resources, schema or platform bindings. The deployer reads the contract
31
+ from the checkout with the static reader Control uses, builds the proxy Worker
32
+ from `contractProxyTable(artifact)`, binds the application Worker to it, and
33
+ writes the framework variables, the proxy secret, the object binding and the
34
+ files bucket itself. Declaring any of them in the config is refused. Control
35
+ writes the IAM schema from the approved contract; the config declares none.
36
+
37
+ The proxy Worker alone selects the endpoint, handles login and injects
38
+ `X-Fabrika-Token` and `X-Fabrika-Endpoint`. The application Worker has no route
39
+ and no public URL. Never implement a second enforcement decision in the app or
40
+ the SPA. Per-object authorization is the access form (`on`, `over`, `in`), and
41
+ handlers reach rows only through the stores of `src/db/tables.ts`.
42
+
43
+ Choose this over `fabrika-iam`, the older native-login decision, for a new
44
+ application: `fabrika-iam` has the application hold D1 tables and call IAM
45
+ itself, which the contract replaces.
@@ -41,8 +41,10 @@ Workers with first-party bindings to storage and messaging primitives
41
41
  - App is a Worker: code runs in a V8 isolate (web APIs, `nodejs_compat` flag for selected Node built-ins) — **not** full Node.
42
42
  - Bindings are defined in an oblaka resource graph, directly in `oblaka.ts` or
43
43
  through `fabrika.config.ts` for a Fabrika-managed app; never hand-edit the generated
44
- `wrangler.jsonc`.
44
+ `wrangler.jsonc`. A contract application (`cf-contract-app`) declares no bindings of
45
+ its own: the deployer declares and binds its Durable Object.
45
46
  - Local dev emulates D1/KV/R2/Queue/Cron (`lopata` or `wrangler dev`/workerd). **`analytics-engine` has no local runtime** (see `count-store`).
47
+ A contract application runs locally with `fabrika app dev` instead (`cf-contract-app`).
46
48
 
47
49
  ## Recommendations — why
48
50
 
@@ -7,7 +7,7 @@ provides: [iac, binding-definitions, wrangler-generation]
7
7
  requires: [cloudflare]
8
8
  recommends: []
9
9
  conflicts: []
10
- npm: ["oblaka-iac@^0.0.18"]
10
+ npm: ["oblaka-iac@^0.0.22"]
11
11
  status: wip
12
12
  sources:
13
13
  - where: "oblaka (repo) + `oblaka-iac` on npm (installed types)"
@@ -31,7 +31,7 @@ from**.
31
31
 
32
32
  ## Impacts & gotchas
33
33
 
34
- - **Skeleton metadata is a contract**: `url` → a route must exist; `seeds: ['x']` → `seeds/x.sql` must exist; `roles` → an auth foundation. fabrika `induce` unions these.
34
+ - **Skeleton metadata is a contract**: `url` → a route must exist; `seeds: ['x']` → the named data the preset's seed strategy provides (`seeds/x.sql` with `named-seeds` or `zerops-postgres-seeds`; created by `dev/seed.ts` with `cf-contract-app`); `roles` → an auth foundation. fabrika `induce` unions these.
35
35
  - Selector priority: **byRole → byLabel → getByText → el(testid)**. The app must be accessibility-first (every interactive element named, every section a heading) or opice-author has no stable selector.
36
36
  - Runs against the **running** dev server (`APP_URL`); `bunx opice test <file>` for one, `bun test tests/browser` for all. WIP — read installed types.
37
37
 
@@ -24,7 +24,7 @@ the Worker can serve as static assets.
24
24
 
25
25
  ## When & why to use
26
26
 
27
- - Default UI layer — the routers, opice selector conventions, and design-token mockups all assume React.
27
+ - Default UI layer — the routers, the opice selector conventions and `@fabrika/ui` all assume React.
28
28
 
29
29
  ## Impacts & gotchas
30
30
 
@@ -12,7 +12,7 @@ status: stable
12
12
  sources:
13
13
  - where: "tailwindcss.com/docs (v4) + @tailwindcss/vite"
14
14
  read: "v4 setup, the CSS-first config, and how design tokens map to utilities/CSS vars."
15
- - where: ".fabrika/architecture/design.md (fabrika design phase) + nua/@nuasite/components"
15
+ - where: ".fabrika/architecture/design.md (fabrika design checkpoint, ISSUE-004) + nua/@nuasite/components"
16
16
  read: "How fabrika's semantic design tokens compile to Tailwind/CSS vars, and a real component set."
17
17
  ---
18
18
 
@@ -20,15 +20,15 @@ sources:
20
20
 
21
21
  ## What it is
22
22
 
23
- The utility-first styling layer. fabrika's **design phase** defines _semantic_ tokens
24
- (`--surface`, `--accent`, …) that map to Tailwind/CSS vars, so mockups and the built
25
- app share one token system. v4 is CSS-first (config in CSS, `@tailwindcss/vite` or
23
+ The utility-first styling layer. fabrika's **design checkpoint** (`ISSUE-004`, reviewed on
24
+ the running app) records _semantic_ tokens (`--surface`, `--accent`, …) that map to
25
+ Tailwind/CSS vars, so the whole app shares one token system. v4 is CSS-first (config in CSS, `@tailwindcss/vite` or
26
26
  the CLI).
27
27
 
28
28
  ## When & why to use
29
29
 
30
30
  - Default styling for app UIs — semantic tokens → utilities, no separate CSS-in-JS runtime.
31
- - Pairs with the design-tokens phase (`design.md`) and with accessible semantic markup (good for opice selectors).
31
+ - Pairs with the design checkpoint's token record (`design.md`) and with accessible semantic markup (good for opice selectors).
32
32
 
33
33
  ## When NOT to use
34
34
 
@@ -7,7 +7,7 @@ provides: [authentication, authorization, proxy-enforcement]
7
7
  requires: [zerops-platform]
8
8
  recommends: []
9
9
  conflicts: [fabrika-iam, cloudflare-access, auth-password-kv]
10
- npm: ["@fabrika/app@0.9.0-dev.13", "@fabrika/db@0.9.0-dev.13", "zod@^3.25.76"]
10
+ npm: ["@fabrika/app@0.9.0-dev.14", "@fabrika/db@0.9.0-dev.14", "zod@^3.25.76"]
11
11
  status: wip
12
12
  sources:
13
13
  - where: "packages/app/skill/SKILL.md in fabrika-platform (the `fabrika-app` skill)"
@@ -7,7 +7,7 @@ provides: [platform, private-services, managed-deploy]
7
7
  requires: [bun, postgres]
8
8
  recommends: []
9
9
  conflicts: [cloudflare]
10
- npm: ["@fabrika/provider-zerops@0.9.0-dev.13", "@fabrika/app@0.9.0-dev.13", "@fabrika/cli@0.9.0-dev.13"]
10
+ npm: ["@fabrika/provider-zerops@0.9.0-dev.14", "@fabrika/app@0.9.0-dev.14", "@fabrika/cli@0.9.0-dev.14"]
11
11
  status: wip
12
12
  sources:
13
13
  - where: "examples/zerops-app/fabrika.config.ts + zerops.yaml in fabrika-platform"
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@fabrika/builder",
3
- "version": "0.9.0-dev.13",
3
+ "version": "0.9.0-dev.14",
4
4
  "type": "module",
5
5
  "description": "Local-first guided application design and agent-assisted implementation.",
6
6
  "license": "MIT",
@@ -16,6 +16,9 @@
16
16
  "index.ts",
17
17
  "cli/src",
18
18
  "daemon/src",
19
+ "shared/approvals.ts",
20
+ "shared/derive.ts",
21
+ "shared/gate.ts",
19
22
  "shared/index.ts",
20
23
  "shared/phases.ts",
21
24
  "shared/urls.ts",
@@ -48,13 +51,13 @@
48
51
  },
49
52
  "dependencies": {
50
53
  "zod": "^3.25.76",
51
- "@fabrika/annotations": "0.9.0-dev.13",
52
- "@fabrika/app": "0.9.0-dev.13",
53
- "@fabrika/auth-core": "0.9.0-dev.13",
54
- "@fabrika/canvas-kernel": "0.9.0-dev.13",
55
- "@fabrika/control-contract": "0.9.0-dev.13",
56
- "@fabrika/daemon-kit": "0.9.0-dev.13",
57
- "@fabrika/provider-zerops": "0.9.0-dev.13",
54
+ "@fabrika/annotations": "0.9.0-dev.14",
55
+ "@fabrika/app": "0.9.0-dev.14",
56
+ "@fabrika/auth-core": "0.9.0-dev.14",
57
+ "@fabrika/canvas-kernel": "0.9.0-dev.14",
58
+ "@fabrika/control-contract": "0.9.0-dev.14",
59
+ "@fabrika/daemon-kit": "0.9.0-dev.14",
60
+ "@fabrika/provider-zerops": "0.9.0-dev.14",
58
61
  "preact": "^10.25.0"
59
62
  }
60
63
  }
@@ -0,0 +1,65 @@
1
+ // What `advance` approved: per phase, the content of every input it read at that moment. Shared by the CLI and the daemon.
2
+ import { existsSync, readFileSync, renameSync, writeFileSync } from 'fs'
3
+ import { join } from 'path'
4
+ import { z } from 'zod'
5
+ import { PHASE_IDS, type PhaseId } from './phases'
6
+
7
+ export const APPROVALS_FILE = 'approvals.json'
8
+
9
+ const approvalSchema = z.object({
10
+ at: z.string(),
11
+ /** Repository-relative path → sha256 of its content, for every file the phase reads or produces (`phaseInputs`). */
12
+ inputs: z.record(z.string(), z.string()),
13
+ /** `advance --force`: the gate was waived, not reviewed. */
14
+ waived: z.boolean().optional(),
15
+ /** The gate revision whose review `advance` approved; absent when waived or recorded before revisions were kept. */
16
+ revision: z.number().int().positive().optional(),
17
+ })
18
+ export type PhaseApproval = z.infer<typeof approvalSchema>
19
+
20
+ const approvalsSchema = z.object({
21
+ version: z.literal(1),
22
+ phases: z.record(z.string(), z.unknown()),
23
+ }).transform(({ phases }) => {
24
+ const out: Partial<Record<PhaseId, PhaseApproval>> = {}
25
+ for (const id of PHASE_IDS) {
26
+ // A record that does not parse reads as missing: its phase is approved again rather than trusted.
27
+ const parsed = approvalSchema.safeParse(phases[id])
28
+ if (parsed.success) out[id] = parsed.data
29
+ }
30
+ return out
31
+ })
32
+ export type Approvals = Partial<Record<PhaseId, PhaseApproval>>
33
+
34
+ /** A file that does not parse is refused, never read as empty: that would re-open every phase, and the next write would drop its records. */
35
+ export class InvalidApprovalsError extends Error {
36
+ constructor() {
37
+ super(`Invalid .fabrika/${APPROVALS_FILE}; repair it, or delete it to judge the gates by their reviews alone, before continuing.`)
38
+ }
39
+ }
40
+
41
+ /** Null for a project initialized before approvals existed: its gates are judged by the daemon's reviews alone, and refused without it, until the CLI writes the file. */
42
+ export function readApprovals(repoRoot: string): Approvals | null {
43
+ const path = approvalsPath(repoRoot)
44
+ if (!existsSync(path)) return null
45
+ let raw: unknown
46
+ try {
47
+ raw = JSON.parse(readFileSync(path, 'utf8'))
48
+ } catch {
49
+ throw new InvalidApprovalsError()
50
+ }
51
+ const parsed = approvalsSchema.safeParse(raw)
52
+ if (!parsed.success) throw new InvalidApprovalsError()
53
+ return parsed.data
54
+ }
55
+
56
+ export function writeApprovals(repoRoot: string, approvals: Approvals): void {
57
+ const path = approvalsPath(repoRoot)
58
+ const tmp = `${path}.${process.pid}.tmp`
59
+ writeFileSync(tmp, JSON.stringify({ version: 1, phases: approvals }, null, 2) + '\n')
60
+ renameSync(tmp, path)
61
+ }
62
+
63
+ function approvalsPath(repoRoot: string): string {
64
+ return join(repoRoot, '.fabrika', APPROVALS_FILE)
65
+ }