jui-tools-mcp-server 2.5.0

package/tests/tools_context.test.ts

@@ -0,0 +1,274 @@
+/**
+ * Group B tools (project context) — exercised against a tmp-dir fixture
+ * project (jui.config.json + specs + layouts). No real project is touched.
+ */
+import { symlinkSync, writeFileSync } from "fs";
+import { join } from "path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+
+import { ServerConfig } from "../src/config.js";
+import { register as registerGetProjectConfig } from "../src/tools/context/get_project_config.js";
+import { register as registerListScreenSpecs } from "../src/tools/context/list_screen_specs.js";
+import { register as registerListComponentSpecs } from "../src/tools/context/list_component_specs.js";
+import { register as registerListLayouts } from "../src/tools/context/list_layouts.js";
+import { register as registerReadSpecFile } from "../src/tools/context/read_spec_file.js";
+import { register as registerReadLayoutFile } from "../src/tools/context/read_layout_file.js";
+import {
+  cleanupTempDirs,
+  createToolHarness,
+  makeFixtureProject,
+  makeTempDir,
+  writeJson,
+  type ToolHarness,
+} from "./helpers.js";
+
+let harness: ToolHarness;
+let projectDir: string;
+
+beforeEach(() => {
+  delete process.env.JUI_PROJECT_DIR;
+  projectDir = makeTempDir("project");
+  makeFixtureProject(projectDir);
+
+  harness = createToolHarness();
+  const config = new ServerConfig();
+  registerGetProjectConfig(harness.server, config);
+  registerListScreenSpecs(harness.server, config);
+  registerListComponentSpecs(harness.server, config);
+  registerListLayouts(harness.server, config);
+  registerReadSpecFile(harness.server, config);
+  registerReadLayoutFile(harness.server, config);
+});
+
+afterEach(() => {
+  delete process.env.JUI_PROJECT_DIR;
+  cleanupTempDirs();
+});
+
+describe("get_project_config", () => {
+  it("returns the resolved project dir and parsed config", async () => {
+    const result = JSON.parse(
+      await harness.call("get_project_config", { project_dir: projectDir })
+    );
+    expect(result.project_dir).toBe(projectDir);
+    expect(result.config.project_name).toBe("ExampleApp");
+    expect(result.config.layouts_directory).toBe("layouts");
+  });
+
+  it("honors JUI_PROJECT_DIR when project_dir is omitted", async () => {
+    process.env.JUI_PROJECT_DIR = projectDir;
+    // ServerConfig captures the env at construction time — build a fresh one.
+    const envHarness = createToolHarness();
+    registerGetProjectConfig(envHarness.server, new ServerConfig());
+    const result = JSON.parse(await envHarness.call("get_project_config"));
+    expect(result.project_dir).toBe(projectDir);
+  });
+
+  it("returns an Error text when no project dir is configured", async () => {
+    const text = await harness.call("get_project_config");
+    expect(text).toMatch(/^Error: No project directory specified/);
+  });
+
+  it("returns an Error text when jui.config.json is missing", async () => {
+    const bare = makeTempDir("bare");
+    const text = await harness.call("get_project_config", { project_dir: bare });
+    expect(text).toMatch(/^Error: jui\.config\.json not found/);
+  });
+
+  it("returns an Error text for a nonexistent project dir", async () => {
+    const text = await harness.call("get_project_config", {
+      project_dir: join(projectDir, "nope"),
+    });
+    expect(text).toMatch(/^Error: Project directory does not exist/);
+  });
+});
+
+describe("list_screen_specs", () => {
+  it("lists *.spec.json with extracted metadata", async () => {
+    const specs = JSON.parse(
+      await harness.call("list_screen_specs", { project_dir: projectDir })
+    );
+    const login = specs.find((s: any) => s.file === "login.spec.json");
+    expect(login).toEqual({
+      file: "login.spec.json",
+      name: "Login",
+      displayName: "Login Screen",
+      type: "screen_spec",
+      layoutFile: "login",
+    });
+  });
+
+  it("degrades gracefully for unparseable spec files", async () => {
+    const specs = JSON.parse(
+      await harness.call("list_screen_specs", { project_dir: projectDir })
+    );
+    const broken = specs.find((s: any) => s.file === "broken.spec.json");
+    expect(broken).toEqual({
+      file: "broken.spec.json",
+      name: "broken",
+      displayName: "",
+      type: "unknown",
+      layoutFile: null,
+    });
+  });
+
+  it("reports a missing spec directory as a plain message", async () => {
+    const proj = makeTempDir("no-specs");
+    writeJson(join(proj, "jui.config.json"), {
+      project_name: "Empty",
+      spec_directory: "missing/specs",
+    });
+    const text = await harness.call("list_screen_specs", { project_dir: proj });
+    expect(text).toContain("Spec directory not found");
+  });
+});
+
+describe("list_component_specs", () => {
+  it("lists *.component.json with name and category", async () => {
+    const specs = JSON.parse(
+      await harness.call("list_component_specs", { project_dir: projectDir })
+    );
+    expect(specs).toEqual([
+      {
+        file: "example_card.component.json",
+        name: "ExampleCard",
+        category: "card",
+      },
+    ]);
+  });
+});
+
+describe("list_layouts", () => {
+  it("lists .json files recursively with relative paths, skipping non-JSON", async () => {
+    const files = JSON.parse(
+      await harness.call("list_layouts", { project_dir: projectDir })
+    );
+    const paths = files
+      .map((f: any) => (typeof f === "string" ? f : f.layout))
+      .sort();
+    expect(paths).toEqual(["Styles/common.json", "login.json"]);
+  });
+
+  it("never classifies a non-layout subtree, however jui resolves", async () => {
+    const files = JSON.parse(
+      await harness.call("list_layouts", { project_dir: projectDir })
+    );
+    const byPath = new Map<string, any>(
+      files.map((f: any) => [typeof f === "string" ? f : f.layout, f])
+    );
+
+    // Holds whether or not `jui screens` is reachable: Styles/ is not a
+    // layout tree (canon: screenId.nonLayoutSubtrees), and a style file
+    // classified as a screen is how phantom screens got markers.
+    expect(byPath.get("Styles/common.json")).toBe("Styles/common.json");
+
+    // Classification comes from shelling out to `jui screens`, which is not
+    // installed everywhere (CI runs without it). When it IS available the
+    // shape is pinned; when it is not, the listing degrades to bare paths
+    // and that is the documented fallback — so assert the branch we are in
+    // rather than requiring the CLI.
+    const login = byPath.get("login.json");
+    if (typeof login === "string") {
+      expect(login).toBe("login.json");
+    } else {
+      expect(login).toMatchObject({
+        layout: "login.json",
+        screen: "login",
+        role: "screen",
+        roleReason: "default",
+      });
+    }
+  });
+});
+
+describe("read_spec_file", () => {
+  it("reads a screen spec from spec_directory", async () => {
+    const text = await harness.call("read_spec_file", {
+      file: "login.spec.json",
+      project_dir: projectDir,
+    });
+    expect(JSON.parse(text).metadata.name).toBe("Login");
+  });
+
+  it("routes *.component.json to component_spec_directory", async () => {
+    const text = await harness.call("read_spec_file", {
+      file: "example_card.component.json",
+      project_dir: projectDir,
+    });
+    expect(JSON.parse(text).metadata.name).toBe("ExampleCard");
+  });
+
+  it("reports missing files with the resolved path", async () => {
+    const text = await harness.call("read_spec_file", {
+      file: "ghost.spec.json",
+      project_dir: projectDir,
+    });
+    expect(text).toContain("File not found");
+    expect(text).toContain("ghost.spec.json");
+  });
+
+  it("blocks ../ traversal out of the project", async () => {
+    // spec_directory is 3 levels deep — 4 ".." segments escape the project.
+    const text = await harness.call("read_spec_file", {
+      file: "../../../../outside-secret.json",
+      project_dir: projectDir,
+    });
+    expect(text).toMatch(/^Error: Path traversal detected/);
+  });
+
+  it("allows ../ segments that stay inside the project", async () => {
+    const text = await harness.call("read_spec_file", {
+      file: "../../components/json/example_card.component.json",
+      project_dir: projectDir,
+    });
+    // Ends in .component.json so it resolves from component_spec_directory,
+    // climbs to docs/, and lands back inside the project.
+    expect(JSON.parse(text).metadata.name).toBe("ExampleCard");
+  });
+});
+
+describe("read_layout_file", () => {
+  it("reads a top-level layout", async () => {
+    const text = await harness.call("read_layout_file", {
+      file: "login.json",
+      project_dir: projectDir,
+    });
+    expect(JSON.parse(text).id).toBe("login_root");
+  });
+
+  it("reads nested layouts via relative paths", async () => {
+    const text = await harness.call("read_layout_file", {
+      file: "Styles/common.json",
+      project_dir: projectDir,
+    });
+    expect(JSON.parse(text).defaultFontColor).toBe("#333333");
+  });
+
+  it("blocks ../ traversal out of the project", async () => {
+    const text = await harness.call("read_layout_file", {
+      file: "../../../../etc/hosts",
+      project_dir: projectDir,
+    });
+    expect(text).toMatch(/^Error: Path traversal detected/);
+  });
+
+  it("reports missing layouts as File not found", async () => {
+    const text = await harness.call("read_layout_file", {
+      file: "ghost.json",
+      project_dir: projectDir,
+    });
+    expect(text).toContain("File not found");
+  });
+
+  it("blocks reading through a symlink that escapes the project", async () => {
+    const outside = makeTempDir("outside");
+    writeFileSync(join(outside, "secret.json"), '{"leaked":true}');
+    symlinkSync(outside, join(projectDir, "layouts", "external"));
+    const text = await harness.call("read_layout_file", {
+      file: "external/secret.json",
+      project_dir: projectDir,
+    });
+    expect(text).toMatch(/^Error: Path traversal detected/);
+    expect(text).not.toContain("leaked");
+  });
+});

package/tests/tools_spec.test.ts

@@ -0,0 +1,225 @@
+/**
+ * Group A tools (component spec lookup) — input schema validation via the
+ * captured Zod shapes plus output contracts against a fixture SpecLoader.
+ */
+import { utimesSync } from "fs";
+import { join } from "path";
+import { ZodError } from "zod";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+
+import { SpecLoader } from "../src/spec_loader.js";
+import { register as registerLookupComponent } from "../src/tools/spec/lookup_component.js";
+import { register as registerLookupAttribute } from "../src/tools/spec/lookup_attribute.js";
+import { register as registerSearchComponents } from "../src/tools/spec/search_components.js";
+import { register as registerGetModifierOrder } from "../src/tools/spec/get_modifier_order.js";
+import { register as registerGetBindingRules } from "../src/tools/spec/get_binding_rules.js";
+import { register as registerGetPlatformMapping } from "../src/tools/spec/get_platform_mapping.js";
+import { register as registerGetDataSource } from "../src/tools/spec/get_data_source.js";
+import {
+  BINDING_RULES,
+  MODIFIER_ORDER,
+  PLATFORM_MAPPING,
+} from "../src/data/derived.js";
+import {
+  cleanupTempDirs,
+  createToolHarness,
+  makeBundledDataset,
+  makeTempDir,
+  type ToolHarness,
+} from "./helpers.js";
+
+const originalCwd = process.cwd();
+
+function buildHarness(loader: SpecLoader): ToolHarness {
+  const harness = createToolHarness();
+  registerLookupComponent(harness.server, loader);
+  registerLookupAttribute(harness.server, loader);
+  registerSearchComponents(harness.server, loader);
+  registerGetModifierOrder(harness.server, loader);
+  registerGetBindingRules(harness.server, loader);
+  registerGetPlatformMapping(harness.server, loader);
+  registerGetDataSource(harness.server, loader);
+  return harness;
+}
+
+function makeFixtureLoader(opts: { staleDays?: number } = {}): SpecLoader {
+  const mcpRoot = makeTempDir("mcp-root");
+  makeBundledDataset(mcpRoot);
+  if (opts.staleDays) {
+    const when = new Date(Date.now() - opts.staleDays * 24 * 60 * 60 * 1000);
+    for (const f of ["attribute_definitions.json", "component_metadata.json"]) {
+      utimesSync(join(mcpRoot, "data", f), when, when);
+    }
+  }
+  return new SpecLoader(mcpRoot);
+}
+
+let harness: ToolHarness;
+
+beforeEach(() => {
+  delete process.env.JSONUI_CLI_PATH;
+  process.chdir(makeTempDir("cwd"));
+  harness = buildHarness(makeFixtureLoader());
+});
+
+afterEach(() => {
+  process.chdir(originalCwd);
+  cleanupTempDirs();
+});
+
+describe("tool registration", () => {
+  it("registers the 7 Group A tools with descriptions", () => {
+    expect([...harness.tools.keys()].sort()).toEqual([
+      "get_binding_rules",
+      "get_data_source",
+      "get_modifier_order",
+      "get_platform_mapping",
+      "lookup_attribute",
+      "lookup_component",
+      "search_components",
+    ]);
+    for (const tool of harness.tools.values()) {
+      expect(tool.description.length).toBeGreaterThan(10);
+    }
+  });
+});
+
+describe("lookup_component", () => {
+  it("returns the full spec plus commonAttributes as JSON", async () => {
+    const text = await harness.call("lookup_component", { name: "TextField" });
+    const spec = JSON.parse(text);
+    expect(spec.name).toBe("TextField");
+    expect(spec.attributes.text.binding_direction).toBe("two-way");
+    expect(spec.bindingBehavior.text.direction).toBe("two-way");
+    expect(spec.commonAttributes.categories.sizing.width).toBeDefined();
+  });
+
+  it("resolves aliases", async () => {
+    const spec = JSON.parse(
+      await harness.call("lookup_component", { name: "Input" })
+    );
+    expect(spec.name).toBe("TextField");
+  });
+
+  it("lists available components when not found", async () => {
+    const text = await harness.call("lookup_component", { name: "Nope" });
+    expect(text).toContain("Component 'Nope' not found");
+    expect(text).toContain("Label");
+    expect(text).toContain("TextField");
+    expect(text).toContain("Button");
+  });
+
+  it("rejects a missing required 'name' param at the schema layer", async () => {
+    await expect(harness.call("lookup_component", {})).rejects.toThrow(ZodError);
+  });
+});
+
+describe("lookup_attribute", () => {
+  it("returns common attribute info as JSON", async () => {
+    const attr = JSON.parse(
+      await harness.call("lookup_attribute", { name: "onClick" })
+    );
+    expect(attr.scope).toBe("common");
+    expect(attr.category).toBe("interaction");
+  });
+
+  it("returns a plain not-found message for unknown attributes", async () => {
+    const text = await harness.call("lookup_attribute", { name: "nope" });
+    expect(text).toBe("Attribute 'nope' not found.");
+  });
+});
+
+describe("search_components", () => {
+  it("returns scored results as JSON, best first", async () => {
+    const results = JSON.parse(
+      await harness.call("search_components", { query: "text" })
+    );
+    expect(results[0].component).toBe("TextField");
+    expect(results[0].score).toBeGreaterThan(0);
+    expect(results[0].matches.length).toBeGreaterThan(0);
+  });
+
+  it("caps output at 20 results", async () => {
+    // Query matching many entries: every fixture component + common attrs
+    // is still < 20, so build a wide loader inline via a broad query and
+    // assert the slice contract holds structurally.
+    const results = JSON.parse(
+      await harness.call("search_components", { query: "t" })
+    );
+    expect(results.length).toBeLessThanOrEqual(20);
+  });
+
+  it("returns a plain message when nothing matches", async () => {
+    const text = await harness.call("search_components", { query: "qqqq" });
+    expect(text).toBe("No results for 'qqqq'.");
+  });
+});
+
+describe("get_modifier_order", () => {
+  it("returns the full table when platform is omitted", async () => {
+    const result = JSON.parse(await harness.call("get_modifier_order"));
+    expect(result).toEqual(JSON.parse(JSON.stringify(MODIFIER_ORDER)));
+  });
+
+  it("returns a single platform section", async () => {
+    const result = JSON.parse(
+      await harness.call("get_modifier_order", { platform: "swift" })
+    );
+    expect(result).toEqual(JSON.parse(JSON.stringify(MODIFIER_ORDER.swift)));
+  });
+
+  it("rejects unknown platforms at the schema layer", async () => {
+    await expect(
+      harness.call("get_modifier_order", { platform: "flutter" })
+    ).rejects.toThrow(ZodError);
+  });
+});
+
+describe("get_binding_rules", () => {
+  it("returns BINDING_RULES verbatim", async () => {
+    const result = JSON.parse(await harness.call("get_binding_rules"));
+    expect(result).toEqual(JSON.parse(JSON.stringify(BINDING_RULES)));
+  });
+});
+
+describe("get_platform_mapping", () => {
+  it("returns the full mapping when category is omitted", async () => {
+    const result = JSON.parse(await harness.call("get_platform_mapping"));
+    expect(result).toEqual(JSON.parse(JSON.stringify(PLATFORM_MAPPING)));
+  });
+
+  it("returns a single category", async () => {
+    const result = JSON.parse(
+      await harness.call("get_platform_mapping", { category: "textAlign" })
+    );
+    expect(result).toEqual(JSON.parse(JSON.stringify(PLATFORM_MAPPING.textAlign)));
+  });
+
+  it("lists available categories for an unknown category", async () => {
+    const text = await harness.call("get_platform_mapping", {
+      category: "bogus",
+    });
+    expect(text).toContain("Category 'bogus' not found");
+    expect(text).toContain("textAlign");
+    expect(text).toContain("fontWeight");
+  });
+});
+
+describe("get_data_source", () => {
+  it("reports per-file layer, freshness, and counts", async () => {
+    const info = JSON.parse(await harness.call("get_data_source"));
+    expect(info.attributeDefinitions.layer).toBe("bundled");
+    expect(info.attributeDefinitions.freshness).toBe("fresh");
+    expect(info.componentMetadata.layer).toBe("bundled");
+    expect(info.componentCount).toBe(3);
+    expect(info.commonAttributeCount).toBe(5);
+    expect(info.hint).toBeUndefined();
+  });
+
+  it("adds a re-fetch hint when any file is stale (> 90 days)", async () => {
+    const staleHarness = buildHarness(makeFixtureLoader({ staleDays: 120 }));
+    const info = JSON.parse(await staleHarness.call("get_data_source"));
+    expect(info.attributeDefinitions.freshness).toBe("stale");
+    expect(info.hint).toContain("90 days");
+  });
+});