@fabrika/builder 0.9.0-dev.12 → 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.
- package/BUILD-CONTRACT.md +9 -3
- package/README.md +39 -9
- package/cli/src/bin.ts +14 -1
- package/cli/src/build-review.ts +66 -0
- package/cli/src/build-status.ts +41 -3
- package/cli/src/catalog.ts +34 -2
- package/cli/src/commands/advance.ts +48 -6
- package/cli/src/commands/build.ts +152 -15
- package/cli/src/commands/design.ts +34 -0
- package/cli/src/commands/flows.ts +32 -0
- package/cli/src/commands/induce.ts +2 -2
- package/cli/src/commands/init.ts +7 -1
- package/cli/src/commands/next.ts +9 -2
- package/cli/src/context.ts +2 -1
- package/cli/src/contrast.ts +301 -0
- package/cli/src/daemon-client.ts +29 -3
- package/cli/src/design-review.ts +261 -0
- package/cli/src/flows.ts +162 -0
- package/cli/src/frontmatter.ts +32 -0
- package/cli/src/index.ts +10 -1
- package/cli/src/induce.ts +61 -3
- package/cli/src/issues.ts +15 -29
- package/cli/src/layout.ts +5 -2
- package/cli/src/packet.ts +36 -3
- package/cli/src/phase-state.ts +19 -1
- package/cli/src/verify.ts +50 -0
- package/daemon/src/handlers.ts +32 -6
- package/daemon/src/phases.ts +7 -109
- package/daemon/src/platform-source.ts +8 -0
- package/decisions/README.md +2 -2
- package/decisions/patterns/cf-contract-app.md +57 -0
- package/decisions/technologies/bun.md +2 -1
- package/decisions/technologies/cf-fabrika-contract.md +45 -0
- package/decisions/technologies/cloudflare.md +3 -1
- package/decisions/technologies/oblaka.md +1 -1
- package/decisions/technologies/opice.md +1 -1
- package/decisions/technologies/react.md +1 -1
- package/decisions/technologies/tailwind.md +5 -5
- package/decisions/technologies/zerops-fabrika-auth.md +1 -1
- package/decisions/technologies/zerops-platform.md +1 -1
- package/package.json +11 -8
- package/shared/approvals.ts +65 -0
- package/shared/derive.ts +189 -0
- package/shared/gate.ts +20 -0
- package/shared/index.ts +6 -1
- package/shared/phases.ts +22 -20
- package/skill/SKILL.md +25 -16
- package/skill/agents/build-orchestrator.md +28 -8
- package/skill/agents/flows-author.md +27 -13
- package/skill/agents/implementer.md +3 -1
- package/skill/agents/opice-skeleton-author.md +8 -7
- package/skill/gates/brief.jsx +26 -5
- package/skill/gates/review-grid.jsx +3 -8
- package/skill/gates/tech.jsx +3 -3
- package/stacks/README.md +8 -2
- package/stacks/cf-app.md +60 -0
- package/stacks/cf-fat.md +1 -0
- package/stacks/cf-internal-app.md +2 -2
- package/stacks/cf-lightweight.md +3 -2
- package/stacks/contember-app.md +1 -0
- package/stacks/content-site.md +1 -0
- package/stacks/zerops-app.md +1 -0
- package/types/cli/src/bin.d.ts +1 -1
- package/types/cli/src/build-review.d.ts +13 -0
- package/types/cli/src/build-status.d.ts +16 -1
- package/types/cli/src/catalog.d.ts +9 -0
- package/types/cli/src/commands/design.d.ts +1 -0
- package/types/cli/src/commands/flows.d.ts +1 -0
- package/types/cli/src/contrast.d.ts +59 -0
- package/types/cli/src/daemon-client.d.ts +13 -2
- package/types/cli/src/design-review.d.ts +54 -0
- package/types/cli/src/flows.d.ts +28 -0
- package/types/cli/src/frontmatter.d.ts +8 -0
- package/types/cli/src/index.d.ts +1 -1
- package/types/cli/src/induce.d.ts +3 -0
- package/types/cli/src/issues.d.ts +4 -0
- package/types/cli/src/packet.d.ts +9 -1
- package/types/cli/src/phase-state.d.ts +1 -1
- package/types/cli/src/verify.d.ts +18 -0
- package/types/daemon/src/phases.d.ts +4 -16
- package/types/daemon/src/platform-remote.d.ts +6 -2
- package/types/shared/approvals.d.ts +32 -0
- package/types/shared/derive.d.ts +41 -0
- package/types/shared/gate.d.ts +11 -0
- package/types/shared/index.d.ts +105 -65
- package/types/shared/phases.d.ts +7 -1
- package/ui/dist/assets/client.css +1 -1
- package/ui/dist/assets/client.vn7hykcn.js +120 -0
- package/ui/dist/index.html +1 -1
- package/cli/src/derive.ts +0 -105
- package/skill/gates/build.jsx +0 -20
- package/skill/gates/design.jsx +0 -22
- package/skill/gates/flows.jsx +0 -14
- package/skill/gates/vision.jsx +0 -27
- package/types/cli/src/derive.d.ts +0 -17
- package/ui/dist/assets/client.8aw2edb7.js +0 -214
package/BUILD-CONTRACT.md
CHANGED
|
@@ -16,9 +16,15 @@ The builder CLI and dashboard must not import daemon implementation modules. The
|
|
|
16
16
|
|
|
17
17
|
## Phase model
|
|
18
18
|
|
|
19
|
-
The ordered phases are intake, vision, flows, technology,
|
|
19
|
+
The ordered phases are intake, vision, flows, technology, skeletons, issues, and build. A phase is complete when every required output exists and its review gate, when present, has submitted and consumed feedback. Intake has no gate of its own: the vision gate reviews the brief together with the glossary and the principles, so the intent takes one review, not two in a row.
|
|
20
20
|
|
|
21
|
-
|
|
21
|
+
Design is reviewed inside the build, on the running application: `induce` writes the design checkpoint `ISSUE-004` (`gate: design-checkpoint`, a name the removed design phase never used, so none of its old reviews counts), which depends on the foundation issues and which every feature issue depends on. `build done` on an issue with a `gate` records that gate's latest reviewed revision and its verdict as the issue's evidence, through `POST /api/session/:id/gate/:name/consume`; it refuses while the gate has no submitted feedback.
|
|
22
|
+
|
|
23
|
+
`design.md` may also list two or three theme variants (`variants: [<path>, …]`, each a stylesheet of `--fui-*` overrides). `design review` then shows each one side by side, with swatches, its overrides and its contrast, adds a required `variant` choice, and says which variant the imported stylesheet declares exactly. The preview shows only the imported stylesheet: the agent copies the chosen variant into it after the verdict and generates the view again. The variants are never imported by the application, and `build done` judges only the imported stylesheet.
|
|
24
|
+
|
|
25
|
+
The design checkpoint also carries a deterministic check, beside its advisory verdict. `.fabrika/architecture/design.md` names the theme stylesheet in its front matter (`stylesheet:`, repository-relative). `fabrika builder design review` and `build done` read that stylesheet's top-level `:root` and `:root[data-theme='dark']` custom properties over the `theme.css` of the `@fabrika/ui` that resolves from the stylesheet's directory, cascade them as the browser does (the kit's dark rule outranks an application's `:root`, and `!important` outranks both), and compute the WCAG 2 contrast of the pairs the kit's components draw: 4.5:1 for text, 3:1 for the focus ring. `build done` refuses a pair below that unless `--waive-contrast` is passed, and refuses while `design.md` names no stylesheet inside the repository; the evidence records the summary and any waiver. A pair the kit's own values already leave below AA, which the override does not lower, is shown and does not refuse. A pair is reported unchecked, never passed, when a colour cannot be read (a `var()` inside `color-mix()`, a translucent background) or when one of its tokens is also declared in a rule the check does not cascade (another selector, or inside `@media` or `@layer`). `--waive-contrast` is the driver's flag, like `advance --force`: the skill passes it only when the human accepts the listed pairs, and the evidence names each waived pair. A stylesheet from which `@fabrika/ui` does not resolve is a stack without the kit and is not checked.
|
|
26
|
+
|
|
27
|
+
The phase is always derived from application files, gate state and `.fabrika/approvals.json`. No mutable phase counter is authoritative. On success `advance` records, for a gated phase, the sha256 of every file the phase reads or produces and the gate revision whose review it approved (`approvals.json`, `version: 1`; `--force` marks the approval `waived` instead). The files are hashed when `advance` runs, so an edit made between the review and `advance` is approved with it. Once the file exists, a gated phase is complete only with an approval whose files are unchanged, plus, unless the approval is waived, a reviewed gate whose latest revision is the approved one. A stale phase is approved again only on a newer revision of its own gate. A file that does not parse, or of another version, is refused with a repair hint. The earliest gated phase whose files changed is current again, and its packet lists them on a `Stale:` line. The skeletons' approval covers only what they read, because the build fills in the test bodies. `init` writes an empty file for a new project. A project without the file is judged by its gate reviews alone: the first `next` or `advance` that reads its phase from the daemon writes the file and records the gated phases the daemon judged complete. Without the daemon such a project has no record of any review, so its first gated phase whose files exist stays current and `advance` refuses it until the gate is reviewed with the daemon running (or waived with `--force`, which writes the file with that gate alone).
|
|
22
28
|
|
|
23
29
|
## Application state
|
|
24
30
|
|
|
@@ -42,7 +48,7 @@ The installed console owns human application creation/selection and initial plac
|
|
|
42
48
|
4. `gate wait` observes feedback without consuming it.
|
|
43
49
|
5. `advance` validates outputs and consumes the latest feedback.
|
|
44
50
|
|
|
45
|
-
|
|
51
|
+
`advance` consumes the current phase's own gate (`POST /api/session/:id/gate/:name/consume`), and re-opening a gate over pending feedback consumes that feedback and answers 409 with it. `gate wait` never consumes, so a retried wait sees the same feedback. A gate counts as reviewed once its latest revision's feedback was consumed, but in a project that keeps approvals only `advance` completes its phase; its verdict (the `verdict` answer) is recorded, and `advance` warns, without refusing, on anything but `Approve`.
|
|
46
52
|
|
|
47
53
|
## Release artifact
|
|
48
54
|
|
package/README.md
CHANGED
|
@@ -2,18 +2,40 @@
|
|
|
2
2
|
|
|
3
3
|
`@fabrika/builder` guides a coding agent from an initial application brief to a reviewed acceptance contract and an assisted implementation.
|
|
4
4
|
|
|
5
|
-
The builder runs
|
|
5
|
+
The builder runs seven deterministic phases:
|
|
6
6
|
|
|
7
|
-
1. intake
|
|
8
|
-
2. vision
|
|
7
|
+
1. intake (no gate of its own)
|
|
8
|
+
2. vision, whose gate reviews the brief with the glossary and principles
|
|
9
9
|
3. flows
|
|
10
10
|
4. technology
|
|
11
|
-
5.
|
|
12
|
-
6.
|
|
13
|
-
7.
|
|
14
|
-
8. build
|
|
11
|
+
5. opice test skeletons
|
|
12
|
+
6. implementation issues
|
|
13
|
+
7. build
|
|
15
14
|
|
|
16
|
-
|
|
15
|
+
Design is not a phase of its own. `induce` adds a design checkpoint issue, `ISSUE-004`, after the foundation issues and
|
|
16
|
+
before every feature: the agent themes the running application through the UI kit's `--fui-*` tokens, and the human
|
|
17
|
+
reviews it at the `design-checkpoint` gate in the live preview. `fabrika builder design review` generates that gate's view:
|
|
18
|
+
two or three theme variants side by side with a required choice, each with the WCAG contrast of the kit's text and focus
|
|
19
|
+
pairs under its override. `build done ISSUE-004` records the gate's
|
|
20
|
+
verdict, and refuses a pair below AA unless the reviewer waives it with `--waive-contrast`.
|
|
21
|
+
|
|
22
|
+
The current phase is derived from files in `.fabrika/`; it is not stored as a mutable counter. `advance` records the content of each approved phase's files, so a phase whose files change afterwards is current again. Review gates use a local dashboard with persistent annotations and responses.
|
|
23
|
+
|
|
24
|
+
## Non-goals
|
|
25
|
+
|
|
26
|
+
The builder exists to take one brief for a new web application to a running application on the paved road: one UI kit,
|
|
27
|
+
the contract, the proxy and the checker ([ADR-0052](../../docs/decisions/0052-react-and-an-own-component-kit-for-application-spas.md)).
|
|
28
|
+
It does not grow into a general design tool. These are out of scope:
|
|
29
|
+
|
|
30
|
+
- **A node graph or node editor.** The phases are a fixed sequence, and the current one is derived from files and gate
|
|
31
|
+
state; nobody wires the steps by hand.
|
|
32
|
+
- **Multiplatform code generation** (native mobile or desktop UI) and **device simulators**. The paved road's
|
|
33
|
+
application is a web SPA on `@fabrika/ui`.
|
|
34
|
+
- **Editing controls in the dashboard,** such as token sliders or drag and drop. The dashboard edits nothing: a person
|
|
35
|
+
reviews there, sees the evidence, runs the connect and deploy actions, and asks for changes through the gate. The
|
|
36
|
+
agent makes the requested edits, and a person may still edit a file in their own editor.
|
|
37
|
+
|
|
38
|
+
A proposal for one of these needs a new ADR in `docs/decisions/` first, not a feature request.
|
|
17
39
|
|
|
18
40
|
## Usage
|
|
19
41
|
|
|
@@ -35,6 +57,9 @@ fabrika builder gate wait
|
|
|
35
57
|
fabrika builder advance
|
|
36
58
|
```
|
|
37
59
|
|
|
60
|
+
A phase without a gate (intake, issues) completes as soon as its files exist: run `next` again instead of the gate and
|
|
61
|
+
`advance` steps. The vision gate reviews the brief that intake wrote.
|
|
62
|
+
|
|
38
63
|
All commands:
|
|
39
64
|
|
|
40
65
|
```text
|
|
@@ -51,11 +76,16 @@ fabrika builder advance [--force]
|
|
|
51
76
|
fabrika builder gate open <name> --view <file.jsx>
|
|
52
77
|
fabrika builder gate wait [--gate <revision>] [--timeout <ms>]
|
|
53
78
|
fabrika builder ensure-daemon
|
|
79
|
+
fabrika builder flows review
|
|
54
80
|
fabrika builder induce [--force]
|
|
55
81
|
fabrika builder build [--issue <ID>] [--assisted]
|
|
82
|
+
fabrika builder build done <ID> [--verify "<command>"]
|
|
83
|
+
fabrika builder build block <ID> --reason "<text>"
|
|
84
|
+
fabrika builder build status
|
|
85
|
+
fabrika builder build review
|
|
56
86
|
```
|
|
57
87
|
|
|
58
|
-
|
|
88
|
+
The default profile is `zerops-app`. `--profile cf-app` selects the same paved road on Cloudflare: a contract application in one Durable Object per environment. The builder's `connect` and `deploy` work with a Zerops installation only, so a `cf-app` application is deployed by the installation's own Control. The other presets (`cf-lightweight`, `cf-fat`, `cf-internal-app`, `contember-app`, `content-site`) are kept for reference but are unsupported: they leave the contract, the proxy, the kit and the checker. `init`, the tech packet and the build brief warn when one is selected. `init` never replaces a project's profile; to move a project to a supported preset, change `profile` in `.fabrika/config.json` and revisit `.fabrika/architecture/tech.md`.
|
|
59
89
|
|
|
60
90
|
Connected initialization uses `zerops-app` for a new project. A person approves the application and environment in the installed console; the local daemon receives a thirty-day app-scoped credential. The agent and application stay local. Deployment requires a clean, remotely available Git revision and runs through Control. `disconnect` removes the local key only; revoke server access in the console. See [the connected workflow](../../docs/reference/local-builder.md) for prerequisites, custody and recovery.
|
|
61
91
|
|
package/cli/src/bin.ts
CHANGED
|
@@ -1,8 +1,11 @@
|
|
|
1
1
|
#!/usr/bin/env bun
|
|
2
2
|
|
|
3
|
+
import { InvalidApprovalsError } from '../../shared/approvals'
|
|
3
4
|
import { cmdAdvance } from './commands/advance'
|
|
4
5
|
import { cmdBuild } from './commands/build'
|
|
6
|
+
import { cmdDesign } from './commands/design'
|
|
5
7
|
import { cmdEnsureDaemon } from './commands/ensure-daemon'
|
|
8
|
+
import { cmdFlows } from './commands/flows'
|
|
6
9
|
import { cmdGate } from './commands/gate'
|
|
7
10
|
import { cmdInduce } from './commands/induce'
|
|
8
11
|
import { cmdInit } from './commands/init'
|
|
@@ -32,8 +35,14 @@ Usage:
|
|
|
32
35
|
fabrika builder gate open <name> --view <f.jsx> Push a canvas gate and open the dashboard
|
|
33
36
|
fabrika builder gate wait [--gate <n>] [--timeout] Wait for submitted gate feedback
|
|
34
37
|
fabrika builder ensure-daemon Start the daemon if it is not running
|
|
38
|
+
fabrika builder flows review Write the flows gate view: the route map from the flow files
|
|
39
|
+
fabrika builder design review Write the design checkpoint view: overrides, contrast, routes
|
|
35
40
|
fabrika builder induce [--force] Derive issues from opice skeleton metadata
|
|
36
41
|
fabrika builder build [--issue <ID>] [--assisted] Run the assisted per-issue build driver
|
|
42
|
+
fabrika builder build done <ID> [--verify <cmd>] Run the issue's check; record it as done only when green
|
|
43
|
+
A design checkpoint takes [--waive-contrast] instead
|
|
44
|
+
fabrika builder build block <ID> --reason <text> Record an issue as blocked
|
|
45
|
+
fabrika builder build status | review Print the board | write the build gate view from it
|
|
37
46
|
|
|
38
47
|
Environment:
|
|
39
48
|
FABRIKA_PORT Daemon port (default 19410)
|
|
@@ -46,7 +55,7 @@ export async function runBuilderCli(argv: readonly string[]): Promise<number> {
|
|
|
46
55
|
return await dispatchBuilderCli(argv)
|
|
47
56
|
} catch (error) {
|
|
48
57
|
console.error(
|
|
49
|
-
error instanceof BuilderCliError
|
|
58
|
+
error instanceof BuilderCliError || error instanceof InvalidApprovalsError
|
|
50
59
|
? error.message
|
|
51
60
|
: 'Builder command failed. Check arguments, .fabrika/config.json, and the local dashboard; use --help for usage.',
|
|
52
61
|
)
|
|
@@ -80,6 +89,10 @@ async function dispatchBuilderCli(argv: readonly string[]): Promise<number> {
|
|
|
80
89
|
return cmdGate(rest)
|
|
81
90
|
case 'ensure-daemon':
|
|
82
91
|
return cmdEnsureDaemon(rest)
|
|
92
|
+
case 'flows':
|
|
93
|
+
return cmdFlows(rest)
|
|
94
|
+
case 'design':
|
|
95
|
+
return cmdDesign(rest)
|
|
83
96
|
case 'induce':
|
|
84
97
|
return cmdInduce(rest)
|
|
85
98
|
case 'build':
|
|
@@ -0,0 +1,66 @@
|
|
|
1
|
+
import { GATE_APPROVE, GATE_CHANGES, GATE_VERDICT_ID, type GateVerdict } from '../../shared/gate'
|
|
2
|
+
import type { BuildBoard, BuildEvidence } from './build-status'
|
|
3
|
+
import type { Issue } from './issues'
|
|
4
|
+
|
|
5
|
+
export const BUILD_REVIEW_PATH = '.fabrika/build/review.jsx'
|
|
6
|
+
|
|
7
|
+
/**
|
|
8
|
+
* The build gate's view, generated from the recorded checks so the reviewer sees what ran, not what an agent reported.
|
|
9
|
+
* Every value from the repository reaches the view as a string literal whose characters outside a small safe set are
|
|
10
|
+
* `\uXXXX` escapes: the canvas compiler runs regex passes over the raw source, string contents included.
|
|
11
|
+
*/
|
|
12
|
+
export function renderBuildReview(issues: Issue[], board: BuildBoard, now: Date): string {
|
|
13
|
+
const rows = issues.map((issue) => {
|
|
14
|
+
const rec = board[issue.id]
|
|
15
|
+
const status = rec?.status === 'done' ? 'done' : rec?.status === 'blocked' ? 'blocked' : 'not built'
|
|
16
|
+
return [issue.id, issue.goal, status, rec?.evidence ? describeEvidence(rec.evidence) : 'no recorded check']
|
|
17
|
+
})
|
|
18
|
+
const blocked = issues.flatMap((issue) => {
|
|
19
|
+
const rec = board[issue.id]
|
|
20
|
+
return rec?.status === 'blocked' ? [[issue.id, rec.reason ?? '(no reason given)']] : []
|
|
21
|
+
})
|
|
22
|
+
const done = rows.filter((row) => row[2] === 'done').length
|
|
23
|
+
|
|
24
|
+
const lines = [
|
|
25
|
+
`<Section title={${literal(`Build review — ${done}/${issues.length} issues done`)}}>`,
|
|
26
|
+
`\t<Note>{${literal(note(now))}}</Note>`,
|
|
27
|
+
`\t<Table headers={${literal(['Issue', 'Goal', 'Status', 'Check'])}} rows={${literal(rows)}} />`,
|
|
28
|
+
]
|
|
29
|
+
if (blocked.length > 0) {
|
|
30
|
+
lines.push(`\t<Table headers={${literal(['Blocked issue', 'Reason'])}} rows={${literal(blocked)}} />`)
|
|
31
|
+
}
|
|
32
|
+
lines.push(
|
|
33
|
+
`\t<UserInput id="build-note" label="Notes for the blocked or unchecked issues?" placeholder="write here…" multiline />`,
|
|
34
|
+
`\t<Choice id="${GATE_VERDICT_ID}" label="Verdict" required options={['${GATE_APPROVE}', '${GATE_CHANGES}']} />`,
|
|
35
|
+
'</Section>',
|
|
36
|
+
)
|
|
37
|
+
return lines.join('\n') + '\n'
|
|
38
|
+
}
|
|
39
|
+
|
|
40
|
+
const VERDICT_TEXT: Record<GateVerdict, string> = { approve: 'approved', changes: 'changes requested', none: 'no verdict' }
|
|
41
|
+
|
|
42
|
+
export function describeEvidence(evidence: BuildEvidence): string {
|
|
43
|
+
const commit = `${evidence.commit === null ? 'no commit' : `at ${evidence.commit.slice(0, 7)}`}${evidence.dirty ? ' with uncommitted changes' : ''}`
|
|
44
|
+
const result = evidence.verdict === undefined
|
|
45
|
+
? `exit ${evidence.exitCode} · ${(evidence.durationMs / 1000).toFixed(1)} s`
|
|
46
|
+
: VERDICT_TEXT[evidence.verdict]
|
|
47
|
+
return `${evidence.command} · ${result} · ${commit} · ${evidence.at}`
|
|
48
|
+
}
|
|
49
|
+
|
|
50
|
+
function note(now: Date): string {
|
|
51
|
+
return `Generated by \`fabrika builder build review\` at ${now.toISOString()} from .fabrika/build/status.json. The builder ran each check itself; "uncommitted changes" means the commit alone does not reproduce the run.`
|
|
52
|
+
}
|
|
53
|
+
|
|
54
|
+
type Literal = string | readonly Literal[]
|
|
55
|
+
|
|
56
|
+
const SAFE_CHAR = /^[A-Za-z0-9 .,:_/-]$/
|
|
57
|
+
|
|
58
|
+
export function literal(value: Literal): string {
|
|
59
|
+
if (typeof value !== 'string') return `[${value.map(literal).join(', ')}]`
|
|
60
|
+
let out = '"'
|
|
61
|
+
for (let i = 0; i < value.length; i++) {
|
|
62
|
+
const ch = value.charAt(i)
|
|
63
|
+
out += SAFE_CHAR.test(ch) ? ch : `\\u${value.charCodeAt(i).toString(16).padStart(4, '0')}`
|
|
64
|
+
}
|
|
65
|
+
return out + '"'
|
|
66
|
+
}
|
package/cli/src/build-status.ts
CHANGED
|
@@ -1,21 +1,58 @@
|
|
|
1
1
|
import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs'
|
|
2
2
|
import { dirname, join } from 'path'
|
|
3
3
|
import { z } from 'zod'
|
|
4
|
+
import type { GateVerdict } from '../../shared/gate'
|
|
4
5
|
import type { Issue } from './issues'
|
|
5
6
|
|
|
6
7
|
export type IssueStatus = 'done' | 'blocked'
|
|
7
8
|
|
|
9
|
+
/** The check the builder itself ran before it recorded an issue as done. */
|
|
10
|
+
export interface BuildEvidence {
|
|
11
|
+
command: string
|
|
12
|
+
exitCode: number
|
|
13
|
+
durationMs: number
|
|
14
|
+
at: string
|
|
15
|
+
/** HEAD of the repository when the check ran; null outside git. */
|
|
16
|
+
commit: string | null
|
|
17
|
+
/** Uncommitted changes outside `.fabrika/` were present, so the commit alone does not reproduce the run. */
|
|
18
|
+
dirty: boolean
|
|
19
|
+
/** Set when the check was a review gate (the design checkpoint) rather than a command. */
|
|
20
|
+
verdict?: GateVerdict
|
|
21
|
+
}
|
|
22
|
+
|
|
8
23
|
export interface BuildRecord {
|
|
9
24
|
status: IssueStatus
|
|
10
25
|
reason?: string
|
|
11
26
|
at: string
|
|
27
|
+
evidence?: BuildEvidence
|
|
12
28
|
}
|
|
13
29
|
|
|
14
30
|
export type BuildBoard = Record<string, BuildRecord>
|
|
15
31
|
|
|
32
|
+
const buildEvidenceSchema = z.object({
|
|
33
|
+
command: z.string(),
|
|
34
|
+
exitCode: z.number().int(),
|
|
35
|
+
durationMs: z.number().nonnegative(),
|
|
36
|
+
at: z.string(),
|
|
37
|
+
commit: z.string().nullable(),
|
|
38
|
+
dirty: z.boolean(),
|
|
39
|
+
verdict: z.enum(['approve', 'changes', 'none']).optional().catch(undefined),
|
|
40
|
+
}).transform(({ verdict, ...evidence }) => ({ ...evidence, ...(verdict === undefined ? {} : { verdict }) }))
|
|
41
|
+
|
|
42
|
+
// A record written before evidence existed keeps its status and reads as "no recorded check".
|
|
16
43
|
const buildBoardSchema = z.record(
|
|
17
|
-
z.object({
|
|
18
|
-
|
|
44
|
+
z.object({
|
|
45
|
+
status: z.enum(['done', 'blocked']),
|
|
46
|
+
at: z.string(),
|
|
47
|
+
reason: z.string().optional(),
|
|
48
|
+
evidence: buildEvidenceSchema.optional().catch(undefined),
|
|
49
|
+
})
|
|
50
|
+
.transform(({ status, at, reason, evidence }) => ({
|
|
51
|
+
status,
|
|
52
|
+
at,
|
|
53
|
+
...(reason === undefined ? {} : { reason }),
|
|
54
|
+
...(evidence === undefined ? {} : { evidence }),
|
|
55
|
+
})),
|
|
19
56
|
)
|
|
20
57
|
|
|
21
58
|
function parseBoard(value: unknown): BuildBoard | null {
|
|
@@ -50,9 +87,10 @@ export function record(
|
|
|
50
87
|
status: IssueStatus,
|
|
51
88
|
reason: string | undefined,
|
|
52
89
|
at: string,
|
|
90
|
+
evidence?: BuildEvidence,
|
|
53
91
|
): BuildBoard {
|
|
54
92
|
const board = readBoard(fabrikaDir)
|
|
55
|
-
board[id] = { status, ...(reason ? { reason } : {}), at }
|
|
93
|
+
board[id] = { status, ...(reason ? { reason } : {}), at, ...(evidence ? { evidence } : {}) }
|
|
56
94
|
writeBoard(fabrikaDir, board)
|
|
57
95
|
return board
|
|
58
96
|
}
|
package/cli/src/catalog.ts
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import { existsSync, statSync } from 'fs'
|
|
1
|
+
import { existsSync, readdirSync, readFileSync, statSync } from 'fs'
|
|
2
2
|
import { dirname, join, resolve } from 'path'
|
|
3
3
|
import { fileURLToPath } from 'url'
|
|
4
4
|
|
|
@@ -12,27 +12,59 @@ export function resolveCatalogRoot(): string | null {
|
|
|
12
12
|
return null
|
|
13
13
|
}
|
|
14
14
|
|
|
15
|
+
/** The project profile a new project gets; `zerops-app` is the paved road the builder connects and deploys. */
|
|
16
|
+
export const DEFAULT_PROFILE = 'zerops-app'
|
|
17
|
+
|
|
18
|
+
/** `unsupported`: a preset kept for reference that leaves the paved road (no contract, proxy, kit or checker). */
|
|
19
|
+
export type StackSupport = 'supported' | 'unsupported'
|
|
20
|
+
|
|
15
21
|
export interface StackPointer {
|
|
16
22
|
profile: string
|
|
17
23
|
root: string
|
|
18
24
|
stackFile: string
|
|
19
25
|
stackFileExists: boolean
|
|
20
26
|
decisionsDir: string
|
|
27
|
+
/** Null when the preset file does not exist. */
|
|
28
|
+
support: StackSupport | null
|
|
21
29
|
}
|
|
22
30
|
|
|
23
31
|
export function resolveStackPointer(profile: string): StackPointer | null {
|
|
24
32
|
const root = resolveCatalogRoot()
|
|
25
33
|
if (!root) return null
|
|
26
34
|
const stackFile = join(root, 'stacks', `${profile}.md`)
|
|
35
|
+
const stackFileExists = existsSync(stackFile) && statSync(stackFile).isFile()
|
|
27
36
|
return {
|
|
28
37
|
profile,
|
|
29
38
|
root,
|
|
30
39
|
stackFile,
|
|
31
|
-
stackFileExists
|
|
40
|
+
stackFileExists,
|
|
32
41
|
decisionsDir: join(root, 'decisions'),
|
|
42
|
+
support: stackFileExists ? stackSupport(readFileSync(stackFile, 'utf8')) : null,
|
|
33
43
|
}
|
|
34
44
|
}
|
|
35
45
|
|
|
46
|
+
/** The ids of the presets the builder supports, for pointing away from an unsupported one. */
|
|
47
|
+
export function supportedProfiles(): string[] {
|
|
48
|
+
const root = resolveCatalogRoot()
|
|
49
|
+
if (!root) return []
|
|
50
|
+
return readdirSync(join(root, 'stacks'))
|
|
51
|
+
.filter((name) => name.endsWith('.md') && name !== 'README.md')
|
|
52
|
+
.filter((name) => stackSupport(readFileSync(join(root, 'stacks', name), 'utf8')) === 'supported')
|
|
53
|
+
.map((name) => name.slice(0, -'.md'.length))
|
|
54
|
+
.sort()
|
|
55
|
+
}
|
|
56
|
+
|
|
57
|
+
export function unsupportedProfileNote(profile: string): string {
|
|
58
|
+
return `the "${profile}" preset is unsupported: it leaves the paved road (contract, proxy, @fabrika/ui, @fabrika/db, fabrika-check). `
|
|
59
|
+
+ `Supported presets: ${supportedProfiles().join(', ')}.`
|
|
60
|
+
}
|
|
61
|
+
|
|
62
|
+
// A preset that does not say it is supported is treated as unsupported.
|
|
63
|
+
function stackSupport(source: string): StackSupport {
|
|
64
|
+
const frontmatter = /^---\r?\n([\s\S]*?)\r?\n---/.exec(source)?.[1] ?? ''
|
|
65
|
+
return /^support:\s*(["']?)supported\1\s*$/m.test(frontmatter) ? 'supported' : 'unsupported'
|
|
66
|
+
}
|
|
67
|
+
|
|
36
68
|
function isDir(p: string): boolean {
|
|
37
69
|
try {
|
|
38
70
|
return statSync(p).isDirectory()
|
|
@@ -1,9 +1,12 @@
|
|
|
1
1
|
import { parseArgs } from 'util'
|
|
2
|
-
import {
|
|
2
|
+
import { readApprovals, writeApprovals } from '../../../shared/approvals'
|
|
3
|
+
import { isNonEmptyFile, matchGlob, phaseInputs, producesSatisfied } from '../../../shared/derive'
|
|
4
|
+
import { GATE_CHANGES } from '../../../shared/gate'
|
|
5
|
+
import { PHASE_COUNT, phaseById, type PhaseId, phaseIndex, PHASES } from '../../../shared/phases'
|
|
3
6
|
import { resolveContext } from '../context'
|
|
4
|
-
import {
|
|
7
|
+
import { consumeGate } from '../daemon-client'
|
|
5
8
|
import { isDaemonRunning } from '../daemon-lifecycle'
|
|
6
|
-
import {
|
|
9
|
+
import { skeletonRouteWarnings } from '../flows'
|
|
7
10
|
import { resolvePhaseState } from '../phase-state'
|
|
8
11
|
|
|
9
12
|
export async function cmdAdvance(argv: string[]): Promise<number> {
|
|
@@ -38,6 +41,11 @@ export async function cmdAdvance(argv: string[]): Promise<number> {
|
|
|
38
41
|
}
|
|
39
42
|
}
|
|
40
43
|
|
|
44
|
+
let verdictWarning: string | null = null
|
|
45
|
+
let reviewedRevision: number | undefined
|
|
46
|
+
const reopen = `${phase.gateViewCommand ? `${phase.gateViewCommand} && ` : ''}fabrika builder gate open ${phase.id} --view ${
|
|
47
|
+
phase.gateView ?? phase.id + '.jsx'
|
|
48
|
+
} && fabrika builder gate wait`
|
|
41
49
|
if (phase.gate && !values.force) {
|
|
42
50
|
const daemonUp = await isDaemonRunning()
|
|
43
51
|
if (!daemonUp) {
|
|
@@ -46,22 +54,41 @@ export async function cmdAdvance(argv: string[]): Promise<number> {
|
|
|
46
54
|
+ `Open the gate + submit feedback, or pass --force.`,
|
|
47
55
|
)
|
|
48
56
|
} else {
|
|
49
|
-
const
|
|
50
|
-
|
|
57
|
+
const review = await consumeGate(ctx.sessionId, phase.id)
|
|
58
|
+
const approved = readApprovals(ctx.repoRoot)?.[phase.id]?.revision
|
|
59
|
+
if (review === null) {
|
|
51
60
|
problems.push(
|
|
52
61
|
`gate "${phase.id}" has no submitted feedback to consume. `
|
|
53
|
-
+ `Run:
|
|
62
|
+
+ `Run: ${reopen}`,
|
|
54
63
|
)
|
|
64
|
+
} else if (approved !== undefined && review.revision <= approved) {
|
|
65
|
+
// The phase is current again because its files changed; the review it was approved on predates them.
|
|
66
|
+
problems.push(`gate "${phase.id}" was approved at revision ${review.revision}, before its files changed. Re-open it for a new review: ${reopen}`)
|
|
67
|
+
} else {
|
|
68
|
+
reviewedRevision = review.revision
|
|
69
|
+
if (review.verdict !== 'approve') {
|
|
70
|
+
// Gates are advisory: a person may move on over requested changes, but never silently.
|
|
71
|
+
verdictWarning = review.verdict === 'changes'
|
|
72
|
+
? `gate "${phase.id}" was answered "${GATE_CHANGES}"; advancing anyway (gates are advisory). Address the requested changes or re-open the gate.`
|
|
73
|
+
: `gate "${phase.id}" was submitted without a verdict; advancing anyway (gates are advisory).`
|
|
74
|
+
}
|
|
55
75
|
}
|
|
56
76
|
}
|
|
57
77
|
}
|
|
58
78
|
|
|
79
|
+
if (verdictWarning) console.error(`[fabrika] warning: ${verdictWarning}`)
|
|
80
|
+
if (phaseIndex(phase.id) >= phaseIndex('skeletons')) {
|
|
81
|
+
for (const warning of skeletonRouteWarnings(ctx.repoRoot)) console.error(`[fabrika] warning: ${warning}`)
|
|
82
|
+
}
|
|
83
|
+
|
|
59
84
|
if (problems.length > 0) {
|
|
60
85
|
console.error(`[fabrika] cannot advance from phase ${phase.number}/${PHASE_COUNT} (${phase.id}):`)
|
|
61
86
|
for (const p of problems) console.error(` - ${p}`)
|
|
62
87
|
return 1
|
|
63
88
|
}
|
|
64
89
|
|
|
90
|
+
recordApproval(ctx.repoRoot, phase.id, values.force, reviewedRevision)
|
|
91
|
+
|
|
65
92
|
const idx = phaseIndex(phase.id)
|
|
66
93
|
const next = idx + 1 < PHASES.length ? PHASES[idx + 1] : null
|
|
67
94
|
if (next) {
|
|
@@ -72,3 +99,18 @@ export async function cmdAdvance(argv: string[]): Promise<number> {
|
|
|
72
99
|
}
|
|
73
100
|
return 0
|
|
74
101
|
}
|
|
102
|
+
|
|
103
|
+
/** Approves the gated phase over the inputs it reads now. */
|
|
104
|
+
function recordApproval(repoRoot: string, current: PhaseId, waived: boolean, revision: number | undefined): void {
|
|
105
|
+
const approvals = { ...readApprovals(repoRoot) }
|
|
106
|
+
const phase = phaseById(current)
|
|
107
|
+
if (phase.gate) {
|
|
108
|
+
approvals[current] = {
|
|
109
|
+
at: new Date().toISOString(),
|
|
110
|
+
inputs: phaseInputs(repoRoot, phase),
|
|
111
|
+
...(waived ? { waived: true } : {}),
|
|
112
|
+
...(revision !== undefined ? { revision } : {}),
|
|
113
|
+
}
|
|
114
|
+
}
|
|
115
|
+
writeApprovals(repoRoot, approvals)
|
|
116
|
+
}
|