[Upd4ting]

⚠ sensitive: it stacks #858 and #857, so its diff shows both until they land.

Why

Iterating on a visual must be much faster as a mockup than through the builder. #858 adds the mockup engine: mockups/<name>/spec.json, drawn live on /mockup, with annotations a person leaves on it. An agent in Safe mode, the default in the dashboard chat, cannot write files. These four MCP tools let it write and patch a spec and read and resolve those annotations through the core MCP server. Task: ANT-2041. The dms-mockup skills (ANT-2042) use these names.

Stack

Base: feat/builder-engine-mcp-core (#857, the MCP server). The branch also merges feat/mockup-engine (#858), because the tools call its compiler and annotation store. Until #858 lands, this diff shows #858's files too.

Review only these commits:

• 4a0eb9be feat(mcp): apply RFC 6902 JSON Patch operations to a JSON document
• bb571aa1 feat(mcp): add the mockup tools
• 0b2a6f60, 14ebda55 refactor(mcp): import the engine through its entry, and declare the tools as constants tested through MCP_TOOLS
• a67986f2, 9c28b558 test(mcp): the engine's depth and duplicate-id checks through mockup_write_spec, and tests on a unique mockup under the working directory
• In the merge commits, .dependency-cruiser/backend.cjs adds "mockup" to the tier under ["mcp"], so mcp may import mockup.

Once #857 and #858 merge, rebase this branch onto main. It then shrinks to those commits.

Tools

Tool	Effect	Arguments	Answer
mockup_annotations	read	{ mockup, status?: "open" | "resolved", page? }	{ annotations }, filtered
mockup_resolve_annotation	builder	{ mockup, id }	The resolved annotation; writes only annotations.json
mockup_write_spec	builder	{ mockup, spec }	{ ok, errors: [{ path, message }] }
mockup_patch_spec	builder	{ mockup, patch: RFC 6902 operations }	Same as mockup_write_spec

• mockup_write_spec validates exactly as the watcher does (parseSpec, then compileSpec against ListBlockTypes()). It writes mockups/<mockup>/spec.json atomically, pretty-printed, only when errors is empty, so a refused spec leaves the file untouched. Each path is a JSON pointer into the spec.
• mockup_patch_spec applies the patch to the current spec on a copy, then validates and writes like mockup_write_spec. A failed test operation or a bad pointer is an error naming the operation index.
• A refused spec is a normal ok: false answer. A bad name, a failed patch operation or a missing mockup or annotation is an isError result.
• Every tool parses mockup with parseMockupName, so no tool reaches a path outside mockups/<name>/. Safe mode serves all four, because none is project.

flowchart LR
  agent[Agent in Safe mode] -->|mockup_write_spec / mockup_patch_spec| tool[MCP tool]
  tool --> parse[parseSpec + compileSpec]
  parse -->|errors| answer[ok: false, errors]
  parse -->|no errors| write[atomic write of spec.json]
  write --> watcher[mockup store watcher]
  watcher -->|SSE state| viewer["/mockup viewer"]
  person[Person on /mockup] -->|annotate| ann[annotations.json]
  agent -->|mockup_annotations| ann
  agent -->|mockup_resolve_annotation| ann

Loading

Proof

All run on the committed head after a clean pnpm --dir packages/dms run build:

• pnpm run checks: Checks: 11 passed, 0 failed.
• pnpm --dir packages/dms typecheck: passes.
• MCP mockup tool and mockup engine tests (dist/test/unit/mcp/mockup-*.test.js, dist/test/unit/mockup/*.test.js): 67 passing.
• pnpm --dir packages/dms test:unit at b2c15792: 2634 passing (15m). The later merge of feat(mockup): live JSON mockups rendered by the real block preview #858's final fixes (0f4b2d60) touches only the sketch check, a frontend type and their tests; the mockup and MCP tests above ran on it.

The tests each name the wrong implementation they catch, among them:

• a write-then-report, where an invalid spec changes the file: the test checks that it stays byte-identical
• a path join without parseMockupName: eight traversal names are refused by all four tools and nothing outside mockups/<name>/ is created
• a tool declared project: Safe mode's tools/list must list all four
• a patch that half-applies: the file stays unchanged after a failing test operation