feat: adopt the @effected front-end kit in cli, mcp and the silk carrier by spencerbeggs · Pull Request #698 · savvy-web/systems

C. Spencer Beggs (spencerbeggs) · 2026-09-25T03:08:36Z

Summary

@savvy-web/cli, @savvy-web/mcp and silk's carrier shims now run on the @effected front-end kit (@effected/engine 0.1.0, @effected/mcp 0.1.1, @effected/cli 0.8.0), replacing hand-rolled process-boundary code. Three things behave differently for people using the tools:

savvy output. Every log line now goes to stderr without the [12:00:00.000] INFO (#N): prefix. stdout carries only a command's result (✓ ⚠ ✗ • lines, coloured only on a TTY without NO_COLOR), JSON output and hook envelopes. Usage errors exit 64 instead of 1: the help text goes to stdout and the error to stderr, which is core effect/unstable/cli behaviour.
savvy-mcp results (mcp: retire SilkMarkdown and the registerSilkToolkit port (Claude Code only shows structuredContent to the model) #688). The markdown transcript is gone. A success returns the typed result in structuredContent, and content[0].text is the same object as JSON. Claude Code forwards only structuredContent to the model, so the transcript reached no model there. Clients that show content (Cursor, Copilot, MCP Apps hosts) now see JSON.
Version lines. Launched through @savvy-web/silk, savvy --version prints savvy v3.2.8 via @savvy-web/silk 4.2.8, and savvy-mcp's serverInfo.version gets the same suffix. This is guaranteed under pnpm only: npm's flat .bin can link the cli or mcp package's own bin instead of silk's shim.

What changed

mcp

main.ts resolves the project directory with LaunchContext.projectDir, which skips empty values and unsubstituted ${VAR} values, and then runs McpStdio.launch/teardown. The crash guards and dynamic imports stay, since the kit doesn't package them yet (effected#835).
ServerLayer is built on McpStdio.layer. The layer answers a non-JSON stdin line with -32700 and keeps logs off the wire.
Tools register through McpToolkit.layer(SilkToolkit, { strict: "annotated" }). No tool is annotated, so every tool still accepts the extra arguments Claude Code sends.
The registerSilkToolkit port of core's registerToolkit is deleted, along with SilkMarkdown and all per-tool markdown renderers.
Tool errors spread ToolFailure.fields. The barrel drops Remediation, composeRemediatedMessage, truncateEchoed and SilkMarkdown (a minor bump, per the mcp semver-surface convention).

cli

main.ts runs CliRuntime.main with Node as the platform and the kit-default CliLogger, and passes a render that prints a failure's message, or its tag and fields. The kit default would print a bare tag, so a failing savvy clean showed CleanError with no reason.
All 42 process.exitCode = 1 writes became CliExit.set(1).
Output was sorted command group by command group (lint, commit, repos, changeset, clean). The result a person ran the command for goes through a local Output helper on stdout. Progress and failure explanations stay as Effect.log* and go to stderr.
repos status --json now always prints one JSON document, including { "error": …, "clean": false } on a config error or a git failure. The gitmodules-drift monitor runs JSON.parse on it.
savvy check separates its three sections with a blank line.

silk and layering

Both shims pass { distribution: { name: "@savvy-web/silk", version } }.
The layering policy moved to packages/silk/layers.json on the kit's LayerPolicy schema. unconstrained replaces harness and also covers the private root. requiredEdges guards against a check that passes on an empty graph.
WorkspaceLayering.checkWorkspace checks the policy in silk's own tests, and e2e/workspace is deleted.
SourceBoundary tests pin three rules at source:
- silk's half of the non-import invariant (only the two src/bin shims import cli or mcp);
- "only bin/main/version touch process" in mcp;
- "no process.exitCode/process.exit" in cli, plus a ratchet on the files that read process.

Things a reviewer should check

Stdout contract. The machine consumers still get what they expect:
- savvy commit hook * still prints its JSON envelope.
- changeset validate-file still prints file:line:col rule message lines, which the plugin hook greps for CSHnnn after merging stderr into stdout.
- repos status --drift --json is always JSON.
- repos sync is read by exit code only.
Help on usage errors. Help stays on stdout on purpose; @effected/cli has no switch to move it. The bin e2e pins the contract: exit 64, the error only on stderr, only help on stdout.
Bump types. mcp and cli are minor bumps with Breaking Changes sections (exit 64, the stdout split, and the mcp text channel and barrel removals), as the design chose. silk is a patch, plus the automatic re-pin.
Deleted tests. The prompt-injection "inert code span" tests went with the markdown, since there is no markdown left to escape.
Lockfile. pnpm 12.6 rewrote optional: flags in pnpm-lock.yaml alongside the new @effected edges.

Verification

All run on the final tree in the worktree:

pnpm test: 3226/3228 passed, 2 skipped (both pre-existing), and all coverage thresholds met.
pnpm build: green, and API Extractor reports zero errors and zero warnings for cli, mcp and silk.
pnpm typecheck, pnpm lint, pnpm lint:md, pnpm peers check: clean. The two lint warnings are __PACKAGE_VERSION__ notes on silk's shims; it is a build-time define, not a turbo env var.
pnpm test:hooks: 473/473 passed.
okfit validate: 0 errors.
Mutation checks: each new boundary test, the layering test, the --json error path and the lint init stdout test were checked by temporarily breaking the code and watching the test fail.
Manual runs:
- savvy check: stderr empty.
- savvy repos status --drift --json: parses as JSON.
- savvy --version: prints the carrier suffix through silk.
- savvy lint --bogus: exits 64.

Follow-ups

Filed upstream: mcp: package the uncaughtException/unhandledRejection crash guards for stdio servers spencerbeggs/effected#835 (package the crash guards) and plugin: effect-v4-cli skill needs a path for migrating a CLI off Effect.log-as-output spencerbeggs/effected#836 (a migration section for the effect-v4-cli skill).
Deferred minors from review:
- a no-op CliExit.set before a propagated failure in config-gate.ts;
- CurrentDistribution is provided but never read;
- Output.summary is unused;
- the exit-write regex check has no positive control;
- clean prints a ✓ summary after ⚠ failures.
The new "front ends adopt the effected kit" Decision is a draft and needs a human okfit verify pass.
A tooling bug surfaced: in a worktree, the pre-commit okfit sync --staged staged the regenerated conventions and decisions indexes at the repo root instead of under okf/. Commit d1472281 corrects it.

feat: adopt the @effected front-end kit in cli, mcp and the silk carrier

- Run savvy under CliRuntime: every log line on stderr, results through a readable Output helper on stdout, usage errors exit 64
- Launch savvy-mcp over McpStdio and register tools through McpToolkit; results are structuredContent with the same object as JSON text
- Name the carrier in savvy --version and serverInfo.version when launched through @savvy-web/silk
- Move the package-layering guard into silk on WorkspaceLayering and delete e2e/workspace

Closes #695, #688

Signed-off-by: C. Spencer Beggs <spencer@savvyweb.systems>

Closes #695
Closes #688

Signed-off-by: C. Spencer Beggs spencer@savvyweb.systems

- Spread ToolFailure.fields into every tagged tool error and compose messages with ToolFailure.message and truncate - Drop Remediation, composeRemediatedMessage and truncateEchoed from the barrel; the kit owns them now Signed-off-by: C. Spencer Beggs <spencer@savvyweb.systems>

- Build ServerLayer on McpStdio.layer and accept a distribution that is rendered into serverInfo.version - Resolve the project directory with LaunchContext.projectDir and run under McpStdio.launch and teardown - Delete the hand-rolled project-root resolver and the e2e process helper in favour of the kit's testing module Signed-off-by: C. Spencer Beggs <spencer@savvyweb.systems>

- Pass the carrier distribution from the savvy-mcp shim so the server reports its version via @savvy-web/silk - Hold the mcp process boundary with a SourceBoundary scan: only bin, main and version touch process Signed-off-by: C. Spencer Beggs <spencer@savvyweb.systems>

- Hand the program to CliRuntime.main with the Node platform at the edge and CliLogger dropping the timestamp prefix - Exit 64 on a usage error instead of 1 - Name the carrier in savvy --version, and pass it from the silk savvy shim Signed-off-by: C. Spencer Beggs <spencer@savvyweb.systems>

- Replace every process.exitCode write in the repos and changeset commands with CliExit.set - Pin the boundary with SourceBoundary: no exitCode or exit writes in src, and process reads ratcheted to today's files Signed-off-by: C. Spencer Beggs <spencer@savvyweb.systems>