jui-tools-mcp-server 2.12.10 → 2.14.0

package/src/tools/spec/get_data_source.ts

@@ -4,11 +4,12 @@ import { SpecLoader } from "../../spec_loader.js";
 export function register(server: McpServer, loader: SpecLoader) {
   server.tool(
     "get_data_source",
-    "Report where the MCP server loaded EVERY canonical data file from — attribute_definitions.json (raw schema), component_metadata.json (presentation metadata), screen_identity.json and binding_semantics.json. Shows layer (env / cwd / home / bundled), the absolute path actually read, file mtime and freshness per file, plus when this server process loaded them. Use it when the CLI and the MCP seem to disagree about the canon: since 2.12.0 every tool call re-reads a file whose CONTENT changed (sha256, not mtime), so a restart is not needed after a jsonui-cli distribution; `lastReload` says when that last happened and whether it succeeded, and `staleInMemory` is non-empty only when a reload FAILED (a file did not parse) and the server is still serving the previous content.",
+    "Report where the MCP server loaded EVERY canonical data file from — attribute_definitions.json (raw schema), component_metadata.json (presentation metadata), screen_identity.json, binding_semantics.json and the rest, down to type_synonyms.json (the type spellings the build accepts). Shows layer (env / cwd / home / bundled), the absolute path actually read, file mtime and freshness per file, plus when this server process loaded them. Use it when the CLI and the MCP seem to disagree about the canon: since 2.12.0 every tool call re-reads a file whose CONTENT changed (sha256, not mtime), so a restart is not needed after a jsonui-cli distribution; `lastReload` says when that last happened and whether it succeeded, and `staleInMemory` is non-empty only when a reload FAILED (a file did not parse) and the server is still serving the previous content.",
     {},
     async () => {
       const info = loader.getDataSource();
-      // 🚨 THE SAME SEVEN THE STALENESS CHECK WATCHES. This list held five
+      // 🚨 THE SAME FILES THE STALENESS CHECK WATCHES (eight since
+      // type_synonyms.json). This list held five
       // while `getChangedSinceLoad` tracked seven, so `staleInMemory` could
       // name a path that appeared in no per-file entry — and a reader who
       // "checked every file reported" had two outside their view. Reported by
@@ -22,6 +23,7 @@ export function register(server: McpServer, loader: SpecLoader) {
         info.attributeSemantics,
         info.platformSemantics,
         info.coverage,
+        info.typeSynonyms,
       ].filter((f): f is NonNullable<typeof f> => f != null);
       const stale = files.some((f) => f.freshness === "stale");
       // The data is read once at construction and cached in memory, so a
@@ -43,6 +45,7 @@ export function register(server: McpServer, loader: SpecLoader) {
                 attributeSemantics: info.attributeSemantics,
                 platformSemantics: info.platformSemantics,
                 coverage: info.coverage,
+                typeSynonyms: info.typeSynonyms,
                 componentCount: info.componentCount,
                 commonAttributeCount: info.commonAttributeCount,
                 loadedAt,

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/cli_runner.test.ts

@@ -1,5 +1,6 @@
 /**
- * cli_runner — execFile wrapper. child_process is mocked; no real CLI runs.
+ * cli_runner — execFile wrapper. child_process is mocked; no real CLI runs,
+ * except in "the child's stdin", which calls through to the real execFile.
  */
 import { beforeEach, describe, expect, it, vi } from "vitest";
 
@@ -19,10 +20,14 @@ interface RecordedCall {
 
 let recorded: RecordedCall[];
 let nextResponse: { error?: any; stdout?: string; stderr?: string };
+// The mocked child's stdin: execFile returns a ChildProcess, and runCli ends
+// its stdin.
+let stdinEnd: ReturnType<typeof vi.fn>;
 
 beforeEach(() => {
   recorded = [];
   nextResponse = {};
+  stdinEnd = vi.fn();
   execFileMock.mockReset();
   execFileMock.mockImplementation(
     (command: string, args: string[], options: any, callback: ExecCallback) => {
@@ -32,6 +37,7 @@ beforeEach(() => {
         nextResponse.stdout ?? "",
         nextResponse.stderr ?? ""
       );
+      return { stdin: { end: stdinEnd } };
     }
   );
 });
@@ -101,6 +107,37 @@ describe("runCli", () => {
   });
 });
 
+// execFile gives the child a stdin pipe, and through 2.13.1 nothing wrote to it
+// or closed it: a CLI that read stdin — `sjui / kjui / rjui g converter` at
+// its overwrite prompt, reached through `jui` — waited for a line that never
+// came, until this runner's timeout killed it (60 s by default; measured
+// 2026-09-26 on jsonui-cli, ticket
+// generate-commands-overwrite-edited-files-and-ignore-their-flags). The
+// child's stdin is ended at once: a reader sees end-of-file.
+describe("the child's stdin", () => {
+  it("is ended at once: a child that reads stdin to end-of-file finishes", async () => {
+    const actual = await vi.importActual<typeof import("child_process")>("child_process");
+    execFileMock.mockImplementation((...args: any[]) => (actual.execFile as any)(...args));
+    const reader =
+      "let n = 0; process.stdin.on('data', (c) => { n += c.length; });" +
+      " process.stdin.on('end', () => { console.log('eof after ' + n + ' bytes'); });";
+    const started = Date.now();
+    // runCli's own limit is 5 s: a child left waiting on stdin comes back as
+    // "Command timed out after 5s", and this test's limit (10 s) stops the
+    // suite from waiting longer than that.
+    const result = await runCli(process.execPath, ["-e", reader], { cwd: process.cwd(), timeout: 5_000 });
+    const elapsed = Date.now() - started;
+    expect(result.stderr).not.toMatch(/timed out/);
+    expect(result).toMatchObject({ exitCode: 0, stdout: "eof after 0 bytes\n" });
+    expect(elapsed).toBeLessThan(2_500);
+  }, 10_000);
+
+  it("ends the stdin of the process execFile returns", async () => {
+    await runCli("jui", ["build"], { cwd: "/proj" });
+    expect(stdinEnd).toHaveBeenCalledTimes(1);
+  });
+});
+
 describe("formatResult", () => {
   it("marks exitCode 0 as success and omits empty errors", () => {
     const result: CliResult = { exitCode: 0, stdout: "ok", stderr: "" };

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/snapshot_completeness.test.ts

@@ -47,6 +47,7 @@ function reportedFiles(source: DataSourceInfo) {
     source.attributeSemantics,
     source.platformSemantics,
     source.coverage,
+    source.typeSynonyms,
   ].filter((f): f is NonNullable<typeof f> => f != null);
 }
 

package/tests/staleness_is_content_not_mtime.test.ts

@@ -156,7 +156,7 @@ describe("the per-file report covers what the check tracks", () => {
 
     const reported = new Set(
       ["attributeDefinitions", "componentMetadata", "screenIdentity",
-       "bindingSemantics", "attributeSemantics", "platformSemantics", "coverage"]
+       "bindingSemantics", "attributeSemantics", "platformSemantics", "coverage", "typeSynonyms"]
         .map((k) => out[k]?.path)
         .filter(Boolean)
     );

package/tests/tools_cli.test.ts

@@ -218,6 +218,32 @@ describe("jui_generate_project", () => {
     ]);
     expect(recorded[0].options.timeout).toBe(120_000);
   });
+
+  // jsonui-cli 1.9.0: `jui g project` keeps a Layout JSON that exists and
+  // differs from what the spec generates, names it, and replaces it only with
+  // --force (never one whose data section the spec does not declare). From
+  // MCP it has no terminal, so it never asks. The description says the same,
+  // the flag reaches the CLI only when asked, and the CLI's line naming a kept
+  // file reaches the agent.
+  it("says what happens to a layout that is already there, as the CLI does", async () => {
+    const tool = harness.tools.get("jui_generate_project")!;
+    expect(tool.description).toContain("written when it is not there");
+    expect(tool.description).toContain("left as it is when it already holds exactly what the spec generates");
+    expect(tool.description).toContain("KEPT");
+    expect(tool.description).toContain("--force replaces it");
+    const force = tool.schema.force.description!;
+    expect(force).not.toBe("Force overwrite declaration files");
+    expect(force).toContain("not replaced even with force");
+    expect(force).toContain("never asks");
+
+    nextResponse = {
+      stdout: "Processing: home.spec.json (Home)\n  Kept existing layout: docs/screens/layouts/home.json " +
+        "(it differs from what the spec generates; --force replaces it)\n",
+    };
+    const text = await harness.call("jui_generate_project", { project_dir: projectDir });
+    expect(recorded[0].args).toEqual(["generate", "project"]);
+    expect(text).toContain("Kept existing layout: docs/screens/layouts/home.json");
+  });
 });
 
 describe("jui_generate_screen", () => {
@@ -270,6 +296,23 @@ describe("jui_generate_converter", () => {
     ]);
   });
 
+  // `container: false` is a leaf (`jui g converter --no-container`, jsonui-cli
+  // 1.9.0). It passed nothing before, so a leaf request scaffolded the
+  // default form.
+  it("passes --no-container for container: false, and neither flag when it is absent", async () => {
+    await harness.call("jui_generate_converter", {
+      name: "LeafCard",
+      container: false,
+      project_dir: projectDir,
+    });
+    await harness.call("jui_generate_converter", {
+      name: "PlainCard",
+      project_dir: projectDir,
+    });
+    expect(recorded[0].args).toEqual(["generate", "converter", "LeafCard", "--no-container"]);
+    expect(recorded[1].args).toEqual(["generate", "converter", "PlainCard"]);
+  });
+
   it("maps spec-mode params to flags", async () => {
     await harness.call("jui_generate_converter", {
       from_spec: "docs/components/json/example_card.component.json",

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",
@@ -125,11 +128,11 @@ describe("test_generate_branch_tests", () => {
     nextResponse = { stdout: "ok" };
     await harness.call("test_generate_branch_tests", {
       project_dir: projectDir,
-      screen: "bottle_detail",
+      screen: "item_detail",
       platform: "android",
       package: "com.example.app",
       module: "AppModule",
-      spec: "docs/screens/json/bottle_detail.spec.json",
+      spec: "docs/screens/json/item_detail.spec.json",
       out_dir: "app/src/test/java",
       harness_dir: "app/src/test/java",
       mocks_dir: "tests/mocks",
@@ -137,7 +140,7 @@ describe("test_generate_branch_tests", () => {
     expect(recorded[0].args).toEqual([
       "generate",
       "branch-tests",
-      "bottle_detail",
+      "item_detail",
       "--platform",
       "android",
       "--package",
@@ -145,7 +148,7 @@ describe("test_generate_branch_tests", () => {
       "--module",
       "AppModule",
       "--spec",
-      "docs/screens/json/bottle_detail.spec.json",
+      "docs/screens/json/item_detail.spec.json",
       "--out-dir",
       "app/src/test/java",
       "--harness-dir",
@@ -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();
+  });
+});