feat(sdk): flows build gates on flows check green (#318)

[kjgbot]

Closes #318. Follow-up to slice A.

What

flows build <flow> runs the same preflight pipeline flows check uses (with deferred cli/command/executor probes, since the build host is not the deployment target). Any refusal-severity diagnostic exits 2 with REFUSED [kind] message on stderr and no artifact directory is created. A previous dist/flows/<name>@sha256:<hex>/ from an earlier successful build is not touched.

How

• New checkBuildableFlow(path) in packages/sdk/src/cli/check.ts — runs the shared preflight pipeline with build-mode deferred probes, filters out probe_failed refusals (probes are deferred to run time), returns a CheckReport in the exact shape flows check --json emits.
• parseBuildArgs accepts --json. On refusal in --json mode, runBuild prints one JSON object matching flows check --json's shape on stdout, then exits 2.
• TS flows delegate to buildFlow's inline preflight (which already refuses on the same threshold) — invoking checkTypeScriptFlow at build time would need @relayflows/surface resolvable from the flow's directory, not a build-time invariant.

Test evidence

New packages/sdk/tests/build-gate.test.ts (3 cases per issue #318):

1. flows build bad.flow.yaml (unresolvable named-agent CLI) → exit 2, stderr cli_unresolved, dist/flows/ never created.
2. flows build --json bad.flow.yaml → exit 2, one CheckReport JSON on stdout, ok: false, refusal in diagnostics, no artifacts.
3. flows build good.yaml (deterministic-only) → exit 0, full bundle buildable@sha256:<hex>/ with spec.canonical.json, preflight.json, manifest.json, identity.json, captured assets.

Full tests/bundle.test.ts regression: 21/21 pass.

---

Note

Medium Risk
Changes when builds succeed or fail and what artifacts CI produces; behavior is intentional but affects the critical build path.

Overview
flows build now runs a preflight gate (same pipeline as flows check) before any bundling. Build-provable refusals exit 2, print REFUSED [kind] on stderr, and never create an output directory or partial bundle; prior successful bundle dirs are left untouched.

The gate is checkBuildableFlow: it uses deferred cli / command / executor probes (host environment is not the deploy target) and drops probe_failed refusals so only spec-level problems block the build. TypeScript flows skip this upfront check and still rely on buildFlow’s inline preflight.

--json on build emits a single CheckReport on stdout on refusal, matching flows check --json. Integration tests cover refusal with no artifacts, JSON output, and a successful deterministic build regression.

^{Reviewed by Cursor Bugbot for commit ea74cd7. Bugbot is set up for automated code reviews on this repo. Configure here.}

[coderabbitai]

Important

• 🔍 Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Advanced

Run ID: 821f71ca-d293-4f27-81d1-593cc935e261

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[cursor]

Cursor Bugbot has reviewed your changes using high effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit ea74cd7. Configure here.}

[cursor]

Named gates refuse under deferred probes

Medium Severity

The build gate drops only probe_failed refusals from deferred probes, but probeNamedGate fail-closes a thrown command probe as gate_command_missing. Any named-gate flow therefore fails checkBuildableFlow even when flows check is green, because the deferred probe always throws.

Additional Locations (1)

• packages/sdk/src/cli/check.ts#L173-L178

 

^{Reviewed by Cursor Bugbot for commit ea74cd7. Configure here.}

[kjgbot]

maintainability lens — FAIL

Looking at the diff with a maintainability lens.

Blockers

checkBuildableFlow silently no-ops for authored TypeScript flows (packages/sdk/src/cli/check.ts:157-171). Returning { ok: true, gates: [], resolutions: [], diagnostics: [] } unconditionally for any path matching /\.(?:[cm]?[jt]s)$/ means the "same shape as flows check" contract the PR advertises does not hold for .ts flows. When a broken .ts flow is built with --json, the gate passes, buildFlow throws, runBuild's outer catch emits REFUSED [bundle_invalid] … as plain-text stderr — no CheckReport on stdout, no structured kind. A CI script consuming flows build --json will parse fine for YAML refusals and crash on TS refusals. The stated goal (#318) — refusals consumable by the same tooling — is only half-delivered, and no test covers it (the .ts branch has zero test coverage). Either route TS through the same emitter or narrow the exported contract explicitly.

Concerns

Preflight is now invoked twice with the same deferred-probes config — once in checkBuildableFlow (check.ts:174-181) and again in buildFlow (build.ts:77-88). Two callsites must stay in sync on what "build-provable" means; a future change to the deferred probe set or the probe_failed filter will land in one place and drift in the other. Extract a buildTimePreflight(authoring, config) helper both call.

--json output is asymmetric. On refusal, one JSON CheckReport on stdout (build.ts:41). On success, the plain bundle path string (build.ts:62). A consumer that does JSON.parse(stdout) works only on failure — the opposite of what --json usually means. Either always emit JSON under --json, or document the asymmetry.

Regex breadth in check.ts:159. /\.(?:[cm]?[jt]s)$/ matches .js/.mjs/.cjs as well, but buildFlow accepts only .yaml/.yml/.ts (build.ts:55, 61, 64). The gate defers .js files to a buildFlow that immediately rejects them. Tighten to \.ts$ or align both.

The invariant "no partial artifacts on refusal" is enforced by ordering, not structure (build.ts:55-64 comment block). A future refactor that reorders runBuild will silently break it. The comment asserts what the code does not enforce — exactly the smell this lens flags.

Notes

• parseBuildArgs: flows build --verify --json path silently drops --json (build.ts:16-19). Minor, but returning undefined would be more honest.
• emitBuildCheckReport prints only refusal diagnostics to stderr; warning diagnostics from preflight are dropped, unlike flows check.
• Missing test: TS-flow gate delegation. The comment's claim about parity is unverified.

REVIEW_FAILED

[kjgbot]

history lens — FAIL

Blocker — H1, criterion 3: the commit overstates --json coverage. Commit ea74cd78 says it adds “--json support emitting the same CheckReport shape flows check --json emits.” The PR body explicitly promises one JSON object on refusal without excluding TypeScript.

However, packages/sdk/src/cli/check.ts:158–169 returns an unconditional successful report for TypeScript inputs. In packages/sdk/src/cli/build.ts:60–65, that skips the only JSON report emitter and proceeds into buildFlow. A subsequent TypeScript preflight refusal reaches the existing catch, which writes stderr and returns 2 without emitting JSON. Thus the advertised refusal contract does not cover a supported input format.

The relevant captured source inspection was:

git show ea74cd78:packages/sdk/src/cli/build.ts | nl -ba | sed -n '30,110p'

Excerpt:

    67	  } catch (error) {
    68	    io.stderr(`REFUSED [bundle_invalid] ${error instanceof Error ? error.message : String(error)}`);
    69	    return 2;
    70	  }

Either route TypeScript refusals through the report emitter or explicitly narrow the commit/PR claims to upfront YAML preflight refusals and document the remaining JSON behavior as a follow-up.

Concerns: packages/sdk/tests/build-gate.test.ts:47–74 covers JSON refusal only for YAML, leaving this distinction untested. I did not execute the tests and make no finding that the reported 21/21 bundle result is false.

Notes: The deferred probes in packages/sdk/src/cli/check.ts:174–192 continue the deliberate build-host/deployment-host distinction established by #316 (3a078ab9). They do not reintroduce DRIVE-LOG’s runtime probe failures. The diff also preserves the model-registry forwarding repaired in that commit. I found no separate blocker involving a newly contradicted settled RFC decision; stale ops/NEXT.md gate references are outside this review’s blocker criteria.

REVIEW_FAILED

[kjgbot]

structure lens — MISSING

[kjgbot]

🎯 review-swarm: FAILED (M:fail H:fail S:missing)

Lens transcripts posted as sibling comments above.