jui-tools-mcp-server 2.5.0

package/tests/helpers.ts

@@ -0,0 +1,272 @@
+/**
+ * Shared fixtures and harnesses for the MCP server test suite.
+ *
+ * Everything here is hermetic: fixture datasets are written to fresh temp
+ * directories, and the tool harness invokes tool handlers directly (after
+ * emulating the SDK-side Zod validation) without opening any transport.
+ */
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "fs";
+import { tmpdir } from "os";
+import { dirname, join } from "path";
+import { z, type ZodRawShape } from "zod";
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+
+// ----- temp dirs ----------------------------------------------------------
+
+const createdDirs: string[] = [];
+
+/** Create a throwaway temp directory, tracked for cleanupTempDirs(). */
+export function makeTempDir(label = "fixture"): string {
+  const dir = mkdtempSync(join(tmpdir(), `jui-mcp-test-${label}-`));
+  createdDirs.push(dir);
+  return dir;
+}
+
+/** Remove every directory created via makeTempDir() (call in afterEach/afterAll). */
+export function cleanupTempDirs(): void {
+  while (createdDirs.length > 0) {
+    const dir = createdDirs.pop()!;
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+export function writeJson(filePath: string, data: unknown): void {
+  mkdirSync(dirname(filePath), { recursive: true });
+  writeFileSync(filePath, JSON.stringify(data, null, 2));
+}
+
+// ----- fixture jsonui-cli dataset ----------------------------------------
+
+/**
+ * Minimal but representative attribute_definitions.json:
+ *   - `_comment` top-level key (must be skipped)
+ *   - `common` section with `_meta` (skipped), categorized + uncategorized keys
+ *   - Label: binding attr WITHOUT binding_direction  -> read-only
+ *   - TextField: binding attr WITH binding_direction -> two-way
+ *   - Button: no binding attrs, no metadata entry     -> default metadata
+ */
+export const FIXTURE_ATTRIBUTE_DEFINITIONS = {
+  _comment: "test fixture — not real data",
+  common: {
+    _meta: { version: "0.0.1" },
+    width: { type: ["string", "int"], description: "View width" },
+    padding: { type: "int", description: "Inner padding" },
+    background: { type: "string", description: "Background color" },
+    onClick: { type: "binding", description: "Tap handler binding" },
+    glowIntensity: { type: "float", description: "Uncategorized zebra attribute" },
+  },
+  Label: {
+    _internal: { note: "must be skipped" },
+    text: { type: ["string", "binding"], description: "Text content" },
+    fontSize: { type: "int", description: "Font size in points" },
+  },
+  TextField: {
+    text: {
+      type: ["string", "binding"],
+      description: "Text content (two-way)",
+      binding_direction: "two-way",
+    },
+    hint: { type: "string", description: "Placeholder hint" },
+  },
+  Button: {
+    onclick: { type: "string", description: "Selector-format tap handler" },
+    enabled: { type: ["boolean", "binding"], description: "Enabled state" },
+  },
+  // Component alias in the B1 pointer shape. Deliberately NOT listed in any
+  // metadata `aliases` array (the Toggle -> Switch case): the loader must
+  // resolve it from `_alias_of` alone instead of registering an
+  // empty-attributes component.
+  Flip: {
+    _alias_of: "Button",
+    _comment: "component alias fixture",
+  },
+};
+
+export const FIXTURE_COMPONENT_METADATA = {
+  _description: "test fixture metadata",
+  _schema: { version: 1 },
+  Label: {
+    description: "Text display component",
+    aliases: ["Text"],
+    platforms: { react: false },
+    platformSpecific: { swift: { renderer: "SwiftUI Text" } },
+    rules: ["Prefer fontColor over textColor"],
+  },
+  TextField: {
+    description: "Single-line text input",
+    aliases: ["EditText", "Input"],
+  },
+  // Button intentionally absent -> DEFAULT_METADATA path
+};
+
+export interface CliDatasetOptions {
+  attributeDefinitions?: unknown;
+  componentMetadata?: unknown;
+  /** Skip writing attribute_definitions.json (to test per-file fallback). */
+  omitAttributeDefinitions?: boolean;
+  /** Skip writing component_metadata.json (to test per-file fallback). */
+  omitComponentMetadata?: boolean;
+  /** Optional conformance/coverage.json fixture (implementation-gap ledger). */
+  coverage?: Record<string, unknown>;
+}
+
+/** Coverage-ledger fixture: one gap on Label.fontSize [web] + one on common.onClick [android]. */
+export const FIXTURE_COVERAGE = {
+  schemaVersion: 1,
+  entries: [
+    {
+      component: "Label",
+      attribute: "fontSize",
+      platforms: ["web"],
+      reason: "unimplemented",
+      note: "test gap — web codegen does not read it",
+    },
+    {
+      component: "common",
+      attribute: "onClick",
+      platforms: ["android"],
+      reason: "legacy",
+      note: "test gap — alias normalized before conversion",
+    },
+  ],
+};
+
+/** Write a fixture jsonui-cli checkout layout: <root>/shared/core/*.json */
+export function makeCliDataset(root: string, opts: CliDatasetOptions = {}): void {
+  const core = join(root, "shared", "core");
+  if (!opts.omitAttributeDefinitions) {
+    writeJson(
+      join(core, "attribute_definitions.json"),
+      opts.attributeDefinitions ?? FIXTURE_ATTRIBUTE_DEFINITIONS
+    );
+  }
+  if (!opts.omitComponentMetadata) {
+    writeJson(
+      join(core, "component_metadata.json"),
+      opts.componentMetadata ?? FIXTURE_COMPONENT_METADATA
+    );
+  }
+  if (opts.coverage) {
+    writeJson(join(root, "conformance", "coverage.json"), opts.coverage);
+  }
+}
+
+/** Write a fixture bundled snapshot layout: <mcpRoot>/data/*.json */
+export function makeBundledDataset(root: string, opts: CliDatasetOptions = {}): void {
+  const dataDir = join(root, "data");
+  if (!opts.omitAttributeDefinitions) {
+    writeJson(
+      join(dataDir, "attribute_definitions.json"),
+      opts.attributeDefinitions ?? FIXTURE_ATTRIBUTE_DEFINITIONS
+    );
+  }
+  if (!opts.omitComponentMetadata) {
+    writeJson(
+      join(dataDir, "component_metadata.json"),
+      opts.componentMetadata ?? FIXTURE_COMPONENT_METADATA
+    );
+  }
+}
+
+// ----- fixture JsonUI project ---------------------------------------------
+
+export const FIXTURE_PROJECT_CONFIG = {
+  project_name: "ExampleApp",
+  spec_directory: "docs/screens/json",
+  layouts_directory: "layouts",
+  styles_directory: "layouts/Styles",
+  images_directory: "images",
+  component_spec_directory: "docs/components/json",
+  strings_file: "strings.json",
+  type_map_file: ".jsonui-type-map.json",
+  platforms: { ios: { path: "ios", mode: "swiftui" } },
+};
+
+/**
+ * Create a minimal JsonUI project in `root`:
+ *   jui.config.json, two screen specs (one intentionally corrupt),
+ *   one component spec, nested layout files.
+ */
+export function makeFixtureProject(root: string): void {
+  writeJson(join(root, "jui.config.json"), FIXTURE_PROJECT_CONFIG);
+
+  writeJson(join(root, "docs/screens/json/login.spec.json"), {
+    type: "screen_spec",
+    metadata: {
+      name: "Login",
+      displayName: "Login Screen",
+      layoutFile: "login",
+    },
+  });
+  // Corrupt JSON: list_screen_specs must degrade gracefully, not crash.
+  mkdirSync(join(root, "docs/screens/json"), { recursive: true });
+  writeFileSync(join(root, "docs/screens/json/broken.spec.json"), "{ not json !");
+
+  writeJson(join(root, "docs/components/json/example_card.component.json"), {
+    type: "component_spec",
+    metadata: { name: "ExampleCard", category: "card" },
+  });
+
+  writeJson(join(root, "layouts/login.json"), {
+    type: "View",
+    id: "login_root",
+    child: [{ type: "Label", text: "Welcome" }],
+  });
+  writeJson(join(root, "layouts/Styles/common.json"), {
+    defaultFontColor: "#333333",
+  });
+  // Non-JSON file must not be listed by list_layouts.
+  writeFileSync(join(root, "layouts/README.txt"), "not a layout");
+}
+
+// ----- MCP tool capture harness -------------------------------------------
+
+export interface CapturedTool {
+  description: string;
+  schema: ZodRawShape;
+  handler: (params: Record<string, unknown>) => Promise<{
+    content: Array<{ type: string; text: string }>;
+  }>;
+}
+
+export interface ToolHarness {
+  server: McpServer;
+  tools: Map<string, CapturedTool>;
+  /**
+   * Invoke a registered tool. Params are validated through the captured Zod
+   * raw shape first, mirroring what the MCP SDK does before dispatch.
+   * Returns the text of the first content item.
+   */
+  call(name: string, params?: Record<string, unknown>): Promise<string>;
+}
+
+export function createToolHarness(): ToolHarness {
+  const tools = new Map<string, CapturedTool>();
+  const server = {
+    tool(
+      name: string,
+      description: string,
+      schema: ZodRawShape,
+      handler: CapturedTool["handler"]
+    ) {
+      tools.set(name, { description, schema, handler });
+    },
+  } as unknown as McpServer;
+
+  async function call(
+    name: string,
+    params: Record<string, unknown> = {}
+  ): Promise<string> {
+    const tool = tools.get(name);
+    if (!tool) {
+      throw new Error(
+        `Tool not registered: ${name}. Registered: ${[...tools.keys()].join(", ")}`
+      );
+    }
+    const parsed = z.object(tool.schema).parse(params);
+    const result = await tool.handler(parsed);
+    return result.content[0].text;
+  }
+
+  return { server, tools, call };
+}

package/tests/setup.ts

@@ -0,0 +1,27 @@
+/**
+ * Global test setup — makes every test hermetic by default.
+ *
+ * The server reads three ambient inputs that must never leak in from the
+ * machine running the tests:
+ *
+ *   - `$JSONUI_CLI_PATH`  (layer 1 of the SpecLoader fallback)
+ *   - `$HOME` / `~/.jsonui-cli`  (layer 3 — real installs exist on dev boxes)
+ *   - `$JUI_PROJECT_DIR`  (ServerConfig default project dir)
+ *
+ * We delete the env vars and point HOME at a fresh empty temp directory.
+ * Individual tests that exercise a specific layer re-set these explicitly.
+ *
+ * Note: process.cwd() (layer 2) is handled per-suite via process.chdir()
+ * because it can't be neutralized globally without breaking module paths.
+ */
+import { mkdtempSync } from "fs";
+import { tmpdir } from "os";
+import { join } from "path";
+
+delete process.env.JSONUI_CLI_PATH;
+delete process.env.JUI_PROJECT_DIR;
+
+const isolatedHome = mkdtempSync(join(tmpdir(), "jui-mcp-test-home-"));
+process.env.HOME = isolatedHome;
+// Windows fallback used by os.homedir(); harmless elsewhere.
+process.env.USERPROFILE = isolatedHome;

package/tests/snapshot_completeness.test.ts

@@ -0,0 +1,152 @@
+/**
+ * Snapshot completeness — the structural guard against the "bundled but not
+ * auto-fetched" trap. binding_semantics.json fell into it (diagnosed, fixed,
+ * commented), then coverage.json fell into the very same hole. The root cause
+ * was that nothing enforced the invariant; this suite is that enforcement.
+ *
+ * Three surfaces must agree about the set of jsonui-cli data files:
+ *
+ *   data/ (bundled)  ⊆  fetch-manifest FILES  ⊆  what SpecLoader reads
+ *
+ *   A. Every file bundled in data/ is in the auto-fetch manifest — otherwise
+ *      it only ever refreshes by hand and silently goes stale.
+ *   B. Every manifest entry is actually read AND reported by the SpecLoader —
+ *      otherwise postinstall fetches dead weight nobody serves, or serves a
+ *      file get_data_source cannot account for. Checked on both layers:
+ *      the bundled fallback (data/<local>) and a synthetic jsonui-cli
+ *      checkout laid out from the manifest's <remote> paths, so a drifting
+ *      remote path is caught too.
+ */
+import { copyFileSync, mkdirSync, readdirSync } from "fs";
+import { fileURLToPath } from "url";
+import { basename, dirname, join, resolve } from "path";
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+
+import { SpecLoader, type DataSourceInfo } from "../src/spec_loader.js";
+import { cleanupTempDirs, makeTempDir } from "./helpers.js";
+// Side-effect-free manifest module: importing it must never trigger a fetch.
+import { FILES } from "../scripts/fetch-manifest.js";
+
+interface ManifestEntry {
+  remote: string;
+  local: string;
+  envOverride?: string;
+}
+
+const manifest = FILES as ManifestEntry[];
+const repoRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const originalCwd = process.cwd();
+
+/** Every file the loader read, as reported by get_data_source. */
+function reportedFiles(source: DataSourceInfo) {
+  return [
+    source.attributeDefinitions,
+    source.componentMetadata,
+    source.screenIdentity,
+    source.bindingSemantics,
+    source.attributeSemantics,
+    source.coverage,
+  ].filter((f): f is NonNullable<typeof f> => f != null);
+}
+
+let bundledLoader: SpecLoader;
+let cliLoader: SpecLoader;
+let cliRoot: string;
+
+beforeAll(() => {
+  // Neutralize the env/cwd/home layers, then load once from this repo's
+  // committed data/ snapshot (same harness as bundled_snapshot.test.ts).
+  delete process.env.JSONUI_CLI_PATH;
+  const home = makeTempDir("home");
+  process.env.HOME = home;
+  process.env.USERPROFILE = home;
+  process.chdir(makeTempDir("cwd"));
+  bundledLoader = new SpecLoader(repoRoot);
+
+  // Synthetic jsonui-cli checkout built FROM the manifest: each entry's
+  // bundled snapshot copied to its <remote> path. Loading it through the env
+  // layer (against an empty MCP root, so nothing can fall back) proves the
+  // manifest's remote paths are exactly where the loader looks.
+  cliRoot = makeTempDir("cli-checkout");
+  for (const entry of manifest) {
+    const target = join(cliRoot, entry.remote);
+    mkdirSync(dirname(target), { recursive: true });
+    copyFileSync(join(repoRoot, "data", entry.local), target);
+  }
+  process.env.JSONUI_CLI_PATH = cliRoot;
+  cliLoader = new SpecLoader(makeTempDir("empty-mcp-root"));
+  delete process.env.JSONUI_CLI_PATH;
+});
+
+afterAll(() => {
+  process.chdir(originalCwd);
+  cleanupTempDirs();
+});
+
+describe("fetch manifest sanity", () => {
+  it("has unique local filenames and unique remote paths", () => {
+    const locals = manifest.map((f) => f.local);
+    const remotes = manifest.map((f) => f.remote);
+    expect(new Set(locals).size).toBe(locals.length);
+    expect(new Set(remotes).size).toBe(remotes.length);
+  });
+
+  it("keeps local names in sync with their remote basenames", () => {
+    for (const entry of manifest) {
+      expect(
+        basename(entry.remote),
+        `${entry.local} is fetched from ${entry.remote} — renaming in flight invites confusion`
+      ).toBe(entry.local);
+    }
+  });
+});
+
+describe("data/ ⊆ manifest (everything bundled is auto-fetched)", () => {
+  it("lists every data/ file in the fetch manifest", () => {
+    const fetched = new Set(manifest.map((f) => f.local));
+    const bundled = readdirSync(join(repoRoot, "data")).filter(
+      (name) => !name.startsWith(".") // .DS_Store and friends
+    );
+    expect(bundled.length).toBeGreaterThan(0);
+    for (const file of bundled) {
+      expect(
+        fetched,
+        `data/${file} is not in scripts/fetch-manifest.js FILES — ` +
+          `it will only ever refresh by hand and silently go stale ` +
+          `(the binding_semantics/coverage trap, third edition)`
+      ).toContain(file);
+    }
+  });
+});
+
+describe("manifest ⊆ SpecLoader (everything fetched is read and reported)", () => {
+  it("reads and reports every manifest file from the bundled layer", () => {
+    const reported = reportedFiles(bundledLoader.getDataSource());
+    for (const file of reported) {
+      expect(file.layer).toBe("bundled");
+    }
+    const reportedNames = reported.map((f) => basename(f.path));
+    for (const entry of manifest) {
+      expect(
+        reportedNames,
+        `${entry.local} is fetched into data/ but the SpecLoader never read it ` +
+          `(or does not report it via get_data_source)`
+      ).toContain(entry.local);
+    }
+  });
+
+  it("reads and reports every manifest file from a jsonui-cli checkout at its remote path", () => {
+    const reported = reportedFiles(cliLoader.getDataSource());
+    for (const file of reported) {
+      expect(file.layer).toBe("env");
+    }
+    const reportedPaths = reported.map((f) => f.path);
+    for (const entry of manifest) {
+      expect(
+        reportedPaths,
+        `${entry.remote} is where postinstall fetches ${entry.local} from, but the ` +
+          `SpecLoader resolves a different path inside a jsonui-cli checkout`
+      ).toContain(join(cliRoot, entry.remote));
+    }
+  });
+});