feat(responses): Add next-step runtime responses

[cameroncooke]

Add next-step instructions to CLI and MCP runtime responses across structured JSON and text output modes.

The motivation is to make runtime responses more useful for both people and agents without baking transport-specific verbosity policy into the runtime. Runtime now decides whether a response is minimal or normal, while CLI can expose that as an override: CLI defaults to normal, MCP defaults to minimal, and CLI callers can request the MCP-style minimal output when using the CLI from AI agents to save tokens.

This also refactors snapshot fixtures so coverage is explicit across the four supported output surfaces: MCP JSON, MCP text, CLI JSON, and CLI text. That makes future response contract changes easier to review because fixture expectations are grouped by runtime and output mode instead of being inferred from older shared fixture paths.

Reviewers should pay close attention to the structured-output envelope and schema version changes. The intent is to add/compact data inside the structured payload while preserving the standard envelope fields.

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/xcodebuildmcp@420

commit: 48c9078

[cursor]

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

Autofix Details

Bugbot Autofix prepared a fix for the issue found in the latest run.

• ✅ Fixed: Global test filter silently skips device snapshot tests
  • Split the command into two separate vitest runs: one for device.snapshot.test.ts without filter to run all tests, and another for parity files with the filter to run only device workflow tests.

Or push these changes by commenting:

@cursor push 51cb64f1df

Preview (51cb64f1df)

diff --git a/package.json b/package.json
--- a/package.json
+++ b/package.json
@@ -47,7 +47,7 @@
     "test:schema-fixtures": "vitest run --config vitest.snapshot.config.ts src/snapshot-tests/__tests__/json-fixture-schema.test.ts",
     "test:snapshot": "npm run build && node build/cli.js daemon stop 2>/dev/null; vitest run --config vitest.snapshot.config.ts",
     "test:snapshots": "npm run test:snapshot",
-    "test:snapshot:device": "npm run build && node build/cli.js daemon stop 2>/dev/null; vitest run --config vitest.snapshot.config.ts src/snapshot-tests/__tests__/device.snapshot.test.ts src/snapshot-tests/__tests__/cli-json-fixture-parity.snapshot.test.ts src/snapshot-tests/__tests__/mcp-json-fixture-parity.snapshot.test.ts -t 'device workflow'",
+    "test:snapshot:device": "npm run build && node build/cli.js daemon stop 2>/dev/null; vitest run --config vitest.snapshot.config.ts src/snapshot-tests/__tests__/device.snapshot.test.ts && vitest run --config vitest.snapshot.config.ts src/snapshot-tests/__tests__/cli-json-fixture-parity.snapshot.test.ts src/snapshot-tests/__tests__/mcp-json-fixture-parity.snapshot.test.ts -t 'device workflow'",
     "test:snapshot:update": "npm run build && node build/cli.js daemon stop 2>/dev/null; UPDATE_SNAPSHOTS=1 vitest run --config vitest.snapshot.config.ts",
     "test:snapshots:update": "npm run test:snapshot:update",
     "test:smoke": "npm run build && vitest run --config vitest.smoke.config.ts",

_{You can send follow-ups to the cloud agent here.}

[cameroncooke]

Validated the Cursor Bugbot autofix note for the device snapshot test filter. This was already fixed in 34fd3c7 by splitting test:snapshot:device into separate vitest invocations so the -t device workflow filter only applies to parity tests.

[github-actions]

stopAllRunningSwiftPackageProcesses parses normalized fixture text for real process IDs, always getting 99999 (src/snapshot-tests/suites/swift-package-suite.ts:17)

JSON.parse(text) on line 22 operates on formatStructuredEnvelopeFixture output, which replaces every processId with 99999 (see json-normalize.ts line 53). The loop will always try to stop PID 99999, fail silently (no such process), then loop forever since activeProcesses still holds the real PIDs. Use structuredEnvelope.data.processes instead — it carries the unnormalized envelope.

Verification

Traced full call chain: createMcpJsonSnapshotHarness (json-harness.ts) wraps createMcpSnapshotHarness and returns text: formatStructuredEnvelopeFixture(envelope). formatStructuredEnvelopeFixture calls normalizeStructuredEnvelope → normalizeValue → normalizeNumber, which maps any key named processId to the literal number 99999 (json-normalize.ts lines 53-55). The structuredEnvelope field in the same return value is the original unmodified envelope. swift_package_stop (swift_package_stop.ts lines 101-104) does a processManager.getProcess(params.pid) lookup — pid 99999 is never found, returns didError: true without throwing. Because the caller discards isError from the stop invocation, the while-true loop spins indefinitely until the test framework hits its timeout.

_{Identified by Warden find-bugs}

[cursor]

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

^{Bugbot Autofix is ON. A cloud agent has been kicked off to fix the reported issue. You can view the agent here.}

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