jui-tools-mcp-server 2.12.9 → 2.13.0

package/README.md

@@ -46,9 +46,9 @@ bash ~/.jsonui-mcp-server/install.sh
 bash ~/.jsonui-mcp-server/uninstall.sh
 ```
 
-## Available Tools (42)
+## Available Tools (46)
 
-### Group A: コンポーネント仕様参照 (8)
+### Group A: コンポーネント仕様参照 (9)
 
 | Tool | Description |
 |------|-------------|
@@ -60,8 +60,9 @@ bash ~/.jsonui-mcp-server/uninstall.sh
 | `get_platform_mapping` | プラットフォーム間の値変換マッピング |
 | `get_screen_identity` | スクリーン正準定義（screen とは何か・id 導出・表示判定述語） |
 | `get_data_source` | データ由来（layer / path / mtime / 鮮度）の確認 |
+| `get_platform_rules` | Layout の platform 指定の規則（1 platform だけ属性を変える node の `platform` オブジェクト、platform ごとに node を落とす文字列形、root の `platforms`、優先順位、`responsive` との違い） |
 
-### Group B: プロジェクトコンテキスト (6)
+### Group B: プロジェクトコンテキスト (7)
 
 | Tool | Description |
 |------|-------------|
@@ -71,6 +72,7 @@ bash ~/.jsonui-mcp-server/uninstall.sh
 | `list_layouts` | Layout JSON ファイル一覧 |
 | `read_spec_file` | spec ファイルの内容を返す |
 | `read_layout_file` | Layout JSON の内容を返す |
+| `search_specs` | 全 spec（画面・サブディレクトリの sub-spec・コンポーネント）をキーワード検索し、ファイル・JSON path・抜粋を返す |
 
 ### Group C: jui CLI (8)
 
@@ -107,7 +109,7 @@ bash ~/.jsonui-mcp-server/uninstall.sh
 | `list_api_models` | 生成済み DTO/Domain 一覧（orphan 検出付き） | `jui ls api-models --json` |
 | `preview_api_model_sync` | swagger→DTO/Domain 同期の dry-run プレビュー（書き込みなし） | `jui g api --dry-run --json` |
 
-### Group F: jsonui-test CLI (9)
+### Group F: jsonui-test CLI (10)
 
 | Tool | Description | CLI |
 |------|-------------|-----|
@@ -120,6 +122,7 @@ bash ~/.jsonui-mcp-server/uninstall.sh
 | `test_mock_generate` | OpenAPI からモック scaffold（`check=true` で drift レポートのみ・書き込みなし） | `jsonui-test mock generate [--check]` |
 | `test_artifacts_pull` | 最新実行のテスト成果物（スクリーンショット/録画）を iOS xcresult / Android 実機から artifacts ディレクトリへ取り込み | `jsonui-test artifacts pull --json` |
 | `test_artifacts_status` | test-artifacts 設定の解決結果（出力先、iOS xcresult 探索、Android appId）と取り込み済みファイル一覧 | `jsonui-test artifacts status --json` |
+| `test_contracts_coverage` | OpenAPI が宣言する応答 status を、画面・VM method・operation・platform ごとに「行が答える / 理由つきの除外 / 評価できない / 不足」に振り分ける（読み取り専用、まだ門ではない。exit 0 pass・1 不足か宣言の誤り・2 始められない・3 評価できないものがある。jsonui-cli 1.8.116 以上） | `jsonui-test contracts coverage [screen] [--platform …] --json` |
 
 > `jsonui-test mock serve`（常駐 HTTP + run-target 実行）は RCE 面のため **MCP 非公開**（CLI 直叩き限定）。
 

package/dist/index.js

@@ -4,6 +4,7 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { SpecLoader, mcpRootFromImportMetaUrl } from "./spec_loader.js";
 import { installAutoReload } from "./auto_reload.js";
 import { ServerConfig } from "./config.js";
+import { packageVersion } from "./version.js";
 // --- Group A: Component Spec Lookup ---
 import { register as registerLookupComponent } from "./tools/spec/lookup_component.js";
 import { register as registerLookupAttribute } from "./tools/spec/lookup_attribute.js";
@@ -55,13 +56,14 @@ import { register as registerTestReport } from "./tools/test/test_report.js";
 import { register as registerTestMockGenerate } from "./tools/test/test_mock_generate.js";
 import { register as registerTestArtifactsPull } from "./tools/test/test_artifacts_pull.js";
 import { register as registerTestArtifactsStatus } from "./tools/test/test_artifacts_status.js";
+import { register as registerTestContractsCoverage } from "./tools/test/test_contracts_coverage.js";
 function log(message) {
     console.error(`[jui-tools] ${new Date().toISOString()} ${message}`);
 }
 log("Server starting...");
 const server = new McpServer({
     name: "jui-tools",
-    version: "2.0.0",
+    version: packageVersion(),
 });
 // Initialize spec loader for Group A
 // Resolves attribute_definitions.json via 4-layer fallback:
@@ -131,6 +133,7 @@ registerTestReport(server, config);
 registerTestMockGenerate(server, config);
 registerTestArtifactsPull(server, config);
 registerTestArtifactsStatus(server, config);
+registerTestContractsCoverage(server, config);
 log(`Registered 41 tools (7 spec + 6 context + 8 jui + 9 doc + 3 api + 8 test)`);
 async function main() {
     const transport = new StdioServerTransport();

package/dist/tools/jui/jui_generate_converter.js

@@ -7,9 +7,13 @@ export function register(server, config) {
         all: z.boolean().optional().describe("Generate from all component specs"),
         attributes: z.string().optional().describe("Attributes in key:type format (e.g., 'prop1:String,prop2:Int')"),
         container: z.boolean().optional().describe("Mark as container component"),
-        skip_existing: z.boolean().optional().describe("Leave existing converter files untouched (no overwrite prompt). " +
-            "`jui build` enables this automatically; pass it here for idempotent " +
-            "explicit scaffold runs."),
+        skip_existing: z.boolean().optional().describe("Leave existing converter and scaffold files untouched, without the " +
+            "overwrite prompt — for idempotent scaffold runs. Wins over `force` " +
+            "when both are set."),
+        force: z.boolean().optional().describe("Replace existing converter and scaffold files without the overwrite " +
+            "prompt. The scaffolds are the project's own code: edits made in them " +
+            "are lost. Needs jsonui-cli 1.8.113 or later (earlier `jui` rejects " +
+            "--force)."),
         project_dir: z.string().optional().describe("Project directory (overrides JUI_PROJECT_DIR env)"),
     }, async (params) => {
         try {
@@ -33,6 +37,9 @@ export function register(server, config) {
             if (params.skip_existing) {
                 args.push("--skip-existing");
             }
+            if (params.force) {
+                args.push("--force");
+            }
             const result = await runCli("jui", args, { cwd: projectDir });
             return { content: [{ type: "text", text: formatResult(result) }] };
         }

package/dist/tools/test/test_contracts_coverage.d.ts

@@ -0,0 +1,10 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { ServerConfig } from "../../config.js";
+import { CliResult } from "../../cli_runner.js";
+export declare function register(server: McpServer, config: ServerConfig): void;
+/**
+ * The CLI's JSON verbatim when there is one and its `exit` is the process's.
+ * Otherwise an envelope that says which of the two is missing — with `exit`
+ * set only where the CLI's own meaning applies (2: it could not start).
+ */
+export declare function coverageEnvelope(result: CliResult): string;

package/dist/tools/test/test_contracts_coverage.js

@@ -0,0 +1,95 @@
+import { z } from "zod";
+import { runCli } from "../../cli_runner.js";
+// The CLI decides the verdict; this tool only carries it. Its exit is the
+// verdict itself — 0 pass (or empty), 1 uncovered or a declaration error,
+// 2 cannot start, 3 something could not be evaluated — so a failure of the
+// TOOL must never be reported as one of those numbers. A timeout reported as
+// exit 1 would read as "uncovered".
+const MIN_CLI = "1.8.116";
+export function register(server, config) {
+    server.tool("test_contracts_coverage", "For every screen and platform, bucket every response status the OpenAPI " +
+        "declares for an operation the screen's dataFlow names: answered by a " +
+        "branch row, excluded with a reason (unit / unreachable / unexpressible), " +
+        "not evaluated, or uncovered (partial / default-only / unattributed). " +
+        "Endpoints listed only in dataFlow.apiEndpoints are named as unbound. " +
+        "Read-only, and not a gate yet. Returns the CLI's JSON report; its `exit` " +
+        "is the verdict: 0 pass (or empty), 1 uncovered or a declaration error, " +
+        "2 cannot start, 3 something could not be evaluated and nothing is " +
+        `uncovered. Needs jsonui-cli ${MIN_CLI} or later`, {
+        screen: z
+            .string()
+            .optional()
+            .describe("One screen (the spec's snake_case name); every screen when omitted"),
+        platform: z
+            .array(z.enum(["web", "android", "ios"]))
+            .optional()
+            .describe("Platforms to evaluate (default: the platforms jui.config.json declares)"),
+        project_dir: z.string().optional().describe("Project directory (overrides JUI_PROJECT_DIR env)"),
+    }, async (params) => {
+        try {
+            const projectDir = config.resolveProjectDir(params.project_dir);
+            const args = ["contracts", "coverage"];
+            if (params.screen) {
+                args.push(params.screen);
+            }
+            for (const p of params.platform ?? []) {
+                args.push("--platform", p);
+            }
+            args.push("--json");
+            const result = await runCli("jsonui-test", args, { cwd: projectDir, timeout: 180_000 });
+            return { content: [{ type: "text", text: coverageEnvelope(result) }] };
+        }
+        catch (e) {
+            return { content: [{ type: "text", text: `Error: ${e.message}` }] };
+        }
+    });
+}
+/**
+ * The CLI's JSON verbatim when there is one and its `exit` is the process's.
+ * Otherwise an envelope that says which of the two is missing — with `exit`
+ * set only where the CLI's own meaning applies (2: it could not start).
+ */
+export function coverageEnvelope(result) {
+    const text = result.stdout.trim();
+    let report;
+    try {
+        report = JSON.parse(text);
+    }
+    catch {
+        report = undefined;
+    }
+    if (report && typeof report === "object" && typeof report.exit === "number") {
+        if (report.exit === result.exitCode) {
+            return text;
+        }
+        return JSON.stringify({
+            exit: null,
+            verdict: "no_report",
+            error: `the report says exit ${report.exit} but the process exited ${String(result.exitCode)}`,
+            report,
+        }, null, 2);
+    }
+    const errors = result.stderr || undefined;
+    if (result.exitCode === "ENOENT") {
+        return JSON.stringify({
+            exit: 2,
+            verdict: "cannot_start",
+            error: `jsonui-test is not on PATH — install jsonui-cli ${MIN_CLI} or later`,
+        }, null, 2);
+    }
+    if (result.exitCode === 2 && /invalid choice: 'contracts'/.test(result.stderr)) {
+        return JSON.stringify({
+            exit: 2,
+            verdict: "cannot_start",
+            error: `this jsonui-test has no \`contracts coverage\` — it arrived in jsonui-cli ${MIN_CLI}`,
+            errors,
+        }, null, 2);
+    }
+    return JSON.stringify({
+        exit: null,
+        verdict: "no_report",
+        error: `no JSON report (process exit ${String(result.exitCode)})`,
+        output: result.stdout || undefined,
+        errors,
+    }, null, 2);
+}

package/dist/version.d.ts

@@ -0,0 +1,14 @@
+/**
+ * The version this server reports to MCP clients, read from package.json.
+ *
+ * The server used to hand McpServer a literal "2.0.0" — written in the
+ * initial commit and never moved, so every release from 2.0.0 to 2.12.x
+ * told clients it was 2.0.0. A literal beside a version that is bumped
+ * elsewhere drifts silently; reading the one file the release bumps does
+ * not.
+ *
+ * `../package.json` resolves from both places this module runs: src/ under
+ * the test runner and dist/ at runtime (npm package and deploy checkout
+ * alike keep package.json at the root, one level up).
+ */
+export declare function packageVersion(moduleUrl?: string): string;

package/dist/version.js

@@ -0,0 +1,21 @@
+import { readFileSync } from "fs";
+/**
+ * The version this server reports to MCP clients, read from package.json.
+ *
+ * The server used to hand McpServer a literal "2.0.0" — written in the
+ * initial commit and never moved, so every release from 2.0.0 to 2.12.x
+ * told clients it was 2.0.0. A literal beside a version that is bumped
+ * elsewhere drifts silently; reading the one file the release bumps does
+ * not.
+ *
+ * `../package.json` resolves from both places this module runs: src/ under
+ * the test runner and dist/ at runtime (npm package and deploy checkout
+ * alike keep package.json at the root, one level up).
+ */
+export function packageVersion(moduleUrl = import.meta.url) {
+    const pkg = JSON.parse(readFileSync(new URL("../package.json", moduleUrl), "utf8"));
+    if (typeof pkg.version !== "string" || pkg.version === "") {
+        throw new Error("package.json has no version");
+    }
+    return pkg.version;
+}

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "jui-tools-mcp-server",
-  "version": "2.12.9",
+  "version": "2.13.0",
   "description": "MCP server for JsonUI project management - wraps jui and jsonui-doc CLIs plus component spec lookup",
   "main": "dist/index.js",
   "scripts": {
     "build": "tsc",
+    "prepack": "npm run build",
     "start": "node dist/index.js",
     "test": "vitest run",
     "test:watch": "vitest",

package/src/index.ts

@@ -5,6 +5,7 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { SpecLoader, mcpRootFromImportMetaUrl } from "./spec_loader.js";
 import { installAutoReload } from "./auto_reload.js";
 import { ServerConfig } from "./config.js";
+import { packageVersion } from "./version.js";
 
 // --- Group A: Component Spec Lookup ---
 import { register as registerLookupComponent } from "./tools/spec/lookup_component.js";
@@ -62,6 +63,7 @@ import { register as registerTestReport } from "./tools/test/test_report.js";
 import { register as registerTestMockGenerate } from "./tools/test/test_mock_generate.js";
 import { register as registerTestArtifactsPull } from "./tools/test/test_artifacts_pull.js";
 import { register as registerTestArtifactsStatus } from "./tools/test/test_artifacts_status.js";
+import { register as registerTestContractsCoverage } from "./tools/test/test_contracts_coverage.js";
 
 function log(message: string) {
   console.error(`[jui-tools] ${new Date().toISOString()} ${message}`);
@@ -71,7 +73,7 @@ log("Server starting...");
 
 const server = new McpServer({
   name: "jui-tools",
-  version: "2.0.0",
+  version: packageVersion(),
 });
 
 // Initialize spec loader for Group A
@@ -155,6 +157,7 @@ registerTestReport(server, config);
 registerTestMockGenerate(server, config);
 registerTestArtifactsPull(server, config);
 registerTestArtifactsStatus(server, config);
+registerTestContractsCoverage(server, config);
 
 log(`Registered 41 tools (7 spec + 6 context + 8 jui + 9 doc + 3 api + 8 test)`);
 

package/src/tools/jui/jui_generate_converter.ts

@@ -14,9 +14,15 @@ export function register(server: McpServer, config: ServerConfig) {
       attributes: z.string().optional().describe("Attributes in key:type format (e.g., 'prop1:String,prop2:Int')"),
       container: z.boolean().optional().describe("Mark as container component"),
       skip_existing: z.boolean().optional().describe(
-        "Leave existing converter files untouched (no overwrite prompt). " +
-        "`jui build` enables this automatically; pass it here for idempotent " +
-        "explicit scaffold runs."
+        "Leave existing converter and scaffold files untouched, without the " +
+        "overwrite prompt — for idempotent scaffold runs. Wins over `force` " +
+        "when both are set."
+      ),
+      force: z.boolean().optional().describe(
+        "Replace existing converter and scaffold files without the overwrite " +
+        "prompt. The scaffolds are the project's own code: edits made in them " +
+        "are lost. Needs jsonui-cli 1.8.113 or later (earlier `jui` rejects " +
+        "--force)."
       ),
       project_dir: z.string().optional().describe("Project directory (overrides JUI_PROJECT_DIR env)"),
     },
@@ -30,6 +36,7 @@ export function register(server: McpServer, config: ServerConfig) {
         if (params.attributes) { args.push("--attributes", params.attributes); }
         if (params.container) { args.push("--container"); }
         if (params.skip_existing) { args.push("--skip-existing"); }
+        if (params.force) { args.push("--force"); }
 
         const result = await runCli("jui", args, { cwd: projectDir });
         return { content: [{ type: "text", text: formatResult(result) }] };

package/src/tools/test/test_contracts_coverage.ts

@@ -0,0 +1,115 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { ServerConfig } from "../../config.js";
+import { runCli, CliResult } from "../../cli_runner.js";
+
+// The CLI decides the verdict; this tool only carries it. Its exit is the
+// verdict itself — 0 pass (or empty), 1 uncovered or a declaration error,
+// 2 cannot start, 3 something could not be evaluated — so a failure of the
+// TOOL must never be reported as one of those numbers. A timeout reported as
+// exit 1 would read as "uncovered".
+const MIN_CLI = "1.8.116";
+
+export function register(server: McpServer, config: ServerConfig) {
+  server.tool(
+    "test_contracts_coverage",
+    "For every screen and platform, bucket every response status the OpenAPI " +
+      "declares for an operation the screen's dataFlow names: answered by a " +
+      "branch row, excluded with a reason (unit / unreachable / unexpressible), " +
+      "not evaluated, or uncovered (partial / default-only / unattributed). " +
+      "Endpoints listed only in dataFlow.apiEndpoints are named as unbound. " +
+      "Read-only, and not a gate yet. Returns the CLI's JSON report; its `exit` " +
+      "is the verdict: 0 pass (or empty), 1 uncovered or a declaration error, " +
+      "2 cannot start, 3 something could not be evaluated and nothing is " +
+      `uncovered. Needs jsonui-cli ${MIN_CLI} or later`,
+    {
+      screen: z
+        .string()
+        .optional()
+        .describe("One screen (the spec's snake_case name); every screen when omitted"),
+      platform: z
+        .array(z.enum(["web", "android", "ios"]))
+        .optional()
+        .describe("Platforms to evaluate (default: the platforms jui.config.json declares)"),
+      project_dir: z.string().optional().describe("Project directory (overrides JUI_PROJECT_DIR env)"),
+    },
+    async (params) => {
+      try {
+        const projectDir = config.resolveProjectDir(params.project_dir);
+        const args = ["contracts", "coverage"];
+        if (params.screen) { args.push(params.screen); }
+        for (const p of params.platform ?? []) { args.push("--platform", p); }
+        args.push("--json");
+        const result = await runCli("jsonui-test", args, { cwd: projectDir, timeout: 180_000 });
+        return { content: [{ type: "text", text: coverageEnvelope(result) }] };
+      } catch (e: any) {
+        return { content: [{ type: "text", text: `Error: ${e.message}` }] };
+      }
+    }
+  );
+}
+
+/**
+ * The CLI's JSON verbatim when there is one and its `exit` is the process's.
+ * Otherwise an envelope that says which of the two is missing — with `exit`
+ * set only where the CLI's own meaning applies (2: it could not start).
+ */
+export function coverageEnvelope(result: CliResult): string {
+  const text = result.stdout.trim();
+  let report: any;
+  try {
+    report = JSON.parse(text);
+  } catch {
+    report = undefined;
+  }
+  if (report && typeof report === "object" && typeof report.exit === "number") {
+    if (report.exit === result.exitCode) {
+      return text;
+    }
+    return JSON.stringify(
+      {
+        exit: null,
+        verdict: "no_report",
+        error: `the report says exit ${report.exit} but the process exited ${String(result.exitCode)}`,
+        report,
+      },
+      null,
+      2
+    );
+  }
+  const errors = result.stderr || undefined;
+  if (result.exitCode === ("ENOENT" as any)) {
+    return JSON.stringify(
+      {
+        exit: 2,
+        verdict: "cannot_start",
+        error: `jsonui-test is not on PATH — install jsonui-cli ${MIN_CLI} or later`,
+      },
+      null,
+      2
+    );
+  }
+  if (result.exitCode === 2 && /invalid choice: 'contracts'/.test(result.stderr)) {
+    return JSON.stringify(
+      {
+        exit: 2,
+        verdict: "cannot_start",
+        error: `this jsonui-test has no \`contracts coverage\` — it arrived in jsonui-cli ${MIN_CLI}`,
+        errors,
+      },
+      null,
+      2
+    );
+  }
+  return JSON.stringify(
+    {
+      exit: null,
+      verdict: "no_report",
+      error: `no JSON report (process exit ${String(result.exitCode)})`,
+      output: result.stdout || undefined,
+      errors,
+    },
+    null,
+    2
+  );
+}

package/src/version.ts

@@ -0,0 +1,22 @@
+import { readFileSync } from "fs";
+
+/**
+ * The version this server reports to MCP clients, read from package.json.
+ *
+ * The server used to hand McpServer a literal "2.0.0" — written in the
+ * initial commit and never moved, so every release from 2.0.0 to 2.12.x
+ * told clients it was 2.0.0. A literal beside a version that is bumped
+ * elsewhere drifts silently; reading the one file the release bumps does
+ * not.
+ *
+ * `../package.json` resolves from both places this module runs: src/ under
+ * the test runner and dist/ at runtime (npm package and deploy checkout
+ * alike keep package.json at the root, one level up).
+ */
+export function packageVersion(moduleUrl: string = import.meta.url): string {
+  const pkg = JSON.parse(readFileSync(new URL("../package.json", moduleUrl), "utf8"));
+  if (typeof pkg.version !== "string" || pkg.version === "") {
+    throw new Error("package.json has no version");
+  }
+  return pkg.version;
+}

package/tests/server_version.test.ts

@@ -0,0 +1,51 @@
+/**
+ * The server reports package.json's version, not a literal.
+ *
+ * Until 2.13.0 the McpServer was built with version "2.0.0" (a literal from
+ * the initial commit), so every release told MCP clients it was 2.0.0.
+ */
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "fs";
+import { tmpdir } from "os";
+import { join } from "path";
+import { pathToFileURL } from "url";
+import { afterEach, describe, expect, it } from "vitest";
+import { packageVersion } from "../src/version.js";
+
+const repoRoot = join(__dirname, "..");
+const tmpDirs: string[] = [];
+
+function fakeModuleUrl(pkg: unknown): string {
+  // A root with package.json and a src/ one level down, like the real layout.
+  const root = mkdtempSync(join(tmpdir(), "jui-version-"));
+  tmpDirs.push(root);
+  mkdirSync(join(root, "src"));
+  writeFileSync(join(root, "package.json"), JSON.stringify(pkg));
+  return pathToFileURL(join(root, "src", "version.js")).href;
+}
+
+afterEach(() => {
+  while (tmpDirs.length) rmSync(tmpDirs.pop()!, { recursive: true, force: true });
+});
+
+describe("server version", () => {
+  it("is the repository's package.json version", () => {
+    const pkg = JSON.parse(readFileSync(join(repoRoot, "package.json"), "utf8"));
+    expect(packageVersion()).toBe(pkg.version);
+  });
+
+  it("follows whatever package.json says (a literal could not)", () => {
+    expect(packageVersion(fakeModuleUrl({ version: "9.8.7" }))).toBe("9.8.7");
+    expect(packageVersion(fakeModuleUrl({ version: "0.0.1-rc.2" }))).toBe("0.0.1-rc.2");
+  });
+
+  it("refuses a package.json without a version", () => {
+    expect(() => packageVersion(fakeModuleUrl({ name: "x" }))).toThrow(/no version/);
+    expect(() => packageVersion(fakeModuleUrl({ version: "" }))).toThrow(/no version/);
+  });
+
+  it("is what index.ts hands McpServer — no version literal left there", () => {
+    const src = readFileSync(join(repoRoot, "src", "index.ts"), "utf8");
+    expect(src).toMatch(/new McpServer\(\{[^}]*version:\s*packageVersion\(\)/s);
+    expect(src).not.toMatch(/version:\s*["'`]\d+\.\d+\.\d+/);
+  });
+});

package/tests/tools_cli.test.ts

@@ -284,6 +284,28 @@ describe("jui_generate_converter", () => {
       "--all",
     ]);
   });
+
+  // `jui g converter --force` exists from jsonui-cli 1.8.113; the tool had no
+  // way to pass it.
+  it("passes --force only when asked", async () => {
+    await harness.call("jui_generate_converter", {
+      all: true,
+      force: true,
+      project_dir: projectDir,
+    });
+    await harness.call("jui_generate_converter", { all: true, project_dir: projectDir });
+    expect(recorded[0].args).toEqual(["generate", "converter", "--all", "--force"]);
+    expect(recorded[1].args).toEqual(["generate", "converter", "--all"]);
+  });
+
+  // The description said "`jui build` enables this automatically": the build
+  // has not generated converters for a long time (jsonui-cli 1.8.113 removed
+  // the same sentence from its own docstring).
+  it("does not tell the agent that jui build skips existing converters", () => {
+    const schema = harness.tools.get("jui_generate_converter")!.schema;
+    expect(schema.skip_existing.description).not.toContain("jui build");
+    expect(schema.force.description).toContain("1.8.113");
+  });
 });
 
 describe("jui_verify", () => {

package/tests/tools_test.test.ts

@@ -20,6 +20,7 @@ import { register as registerTestReport } from "../src/tools/test/test_report.js
 import { register as registerTestMockGenerate } from "../src/tools/test/test_mock_generate.js";
 import { register as registerTestArtifactsPull } from "../src/tools/test/test_artifacts_pull.js";
 import { register as registerTestArtifactsStatus } from "../src/tools/test/test_artifacts_status.js";
+import { register as registerTestContractsCoverage } from "../src/tools/test/test_contracts_coverage.js";
 
 import {
   cleanupTempDirs,
@@ -72,6 +73,7 @@ beforeEach(() => {
   registerTestMockGenerate(harness.server, config);
   registerTestArtifactsPull(harness.server, config);
   registerTestArtifactsStatus(harness.server, config);
+  registerTestContractsCoverage(harness.server, config);
 });
 
 afterEach(() => {
@@ -88,11 +90,12 @@ function failWithCode(code: number, stdout = "", stderr = ""): void {
 }
 
 describe("Group F registration", () => {
-  it("registers all 9 jsonui-test tools", () => {
+  it("registers all 10 jsonui-test tools", () => {
     expect([...harness.tools.keys()].sort()).toEqual(
       [
         "test_artifacts_pull",
         "test_artifacts_status",
+        "test_contracts_coverage",
         "test_generate_branch_tests",
         "test_generate_description",
         "test_generate_flow",
@@ -347,3 +350,98 @@ describe("test_artifacts_status", () => {
     expect(execFileMock).not.toHaveBeenCalled();
   });
 });
+
+describe("test_contracts_coverage", () => {
+  const report = (exit: number) =>
+    JSON.stringify({ app: { spec_file: null, rules: 0, declaration_errors: [] }, platforms: [], exit }, null, 2);
+
+  it("runs `jsonui-test contracts coverage --json` in the project dir", async () => {
+    nextResponse = { stdout: report(0) };
+    await harness.call("test_contracts_coverage", { project_dir: projectDir });
+    expect(recorded).toEqual([
+      expect.objectContaining({
+        command: "jsonui-test",
+        args: ["contracts", "coverage", "--json"],
+        options: expect.objectContaining({ cwd: projectDir, timeout: 180_000 }),
+      }),
+    ]);
+  });
+
+  it("maps the screen and every platform, in order", async () => {
+    nextResponse = { stdout: report(0) };
+    await harness.call("test_contracts_coverage", {
+      project_dir: projectDir,
+      screen: "detail",
+      platform: ["web", "ios"],
+    });
+    expect(recorded[0].args).toEqual([
+      "contracts", "coverage", "detail", "--platform", "web", "--platform", "ios", "--json",
+    ]);
+  });
+
+  it("resolves jsonui-test the way the other jsonui-test tools do", async () => {
+    // The same bare command name and the same environment as
+    // test_artifacts_status: the installed jsonui-cli on PATH, never a
+    // development tree put in front of it by this tool.
+    nextResponse = { stdout: "{}" };
+    await harness.call("test_artifacts_status", { project_dir: projectDir });
+    nextResponse = { stdout: report(0) };
+    await harness.call("test_contracts_coverage", { project_dir: projectDir });
+    const [sibling, coverage] = recorded;
+    expect(coverage.command).toBe(sibling.command);
+    expect(coverage.options.env).toEqual(sibling.options.env);
+    expect(coverage.options.env.PYTHONPATH).toBe(process.env.PYTHONPATH);
+    expect(coverage.options.env.JSONUI_CLI_PATH).toBeUndefined();
+  });
+
+  // The exit IS the verdict, so each of the four has to arrive as itself —
+  // not flattened into success/failure the way formatResult would.
+  it.each([0, 1, 2, 3])("passes the report through verbatim when it and the process both say exit %i", async (code) => {
+    if (code === 0) {
+      nextResponse = { stdout: report(0) };
+    } else {
+      failWithCode(code, report(code));
+    }
+    const text = await harness.call("test_contracts_coverage", { project_dir: projectDir });
+    expect(text).toBe(report(code));
+    expect(JSON.parse(text).exit).toBe(code);
+  });
+
+  it("says so when the report and the process disagree about the exit", async () => {
+    failWithCode(1, report(0));
+    const parsed = JSON.parse(await harness.call("test_contracts_coverage", { project_dir: projectDir }));
+    expect(parsed.exit).toBeNull();
+    expect(parsed.verdict).toBe("no_report");
+    expect(parsed.error).toContain("exit 0");
+    expect(parsed.report.exit).toBe(0);
+  });
+
+  it("names the version when the installed jsonui-test has no contracts command", async () => {
+    failWithCode(2, "", "jsonui-test: error: argument command: invalid choice: 'contracts'");
+    const parsed = JSON.parse(await harness.call("test_contracts_coverage", { project_dir: projectDir }));
+    expect(parsed).toMatchObject({ exit: 2, verdict: "cannot_start" });
+    expect(parsed.error).toContain("1.8.116");
+  });
+
+  it("says jsonui-test is missing when it is not on PATH", async () => {
+    nextResponse = { error: Object.assign(new Error("spawn jsonui-test ENOENT"), { code: "ENOENT" }) };
+    const parsed = JSON.parse(await harness.call("test_contracts_coverage", { project_dir: projectDir }));
+    expect(parsed).toMatchObject({ exit: 2, verdict: "cannot_start" });
+    expect(parsed.error).toContain("not on PATH");
+  });
+
+  it("does not report a timeout as a coverage verdict", async () => {
+    // runCli turns a timeout into exit 1 — which is "uncovered" here.
+    nextResponse = { error: Object.assign(new Error("killed"), { killed: true, code: null }), stdout: '{"plat' };
+    const parsed = JSON.parse(await harness.call("test_contracts_coverage", { project_dir: projectDir }));
+    expect(parsed.exit).toBeNull();
+    expect(parsed.verdict).toBe("no_report");
+    expect(parsed.errors).toContain("timed out");
+  });
+
+  it("does not spawn anything when no project dir is configured", async () => {
+    const text = await harness.call("test_contracts_coverage");
+    expect(text).toMatch(/^Error: /);
+    expect(execFileMock).not.toHaveBeenCalled();
+  });
+});