jui-tools-mcp-server 2.5.0

package/tests/bundled_snapshot.test.ts

@@ -0,0 +1,155 @@
+/**
+ * Bundled snapshot validity — loads the SpecLoader against the REAL committed
+ * data/ snapshot (attribute_definitions.json + component_metadata.json) by
+ * forcing the 4th fallback layer. Guards against a broken snapshot refresh:
+ * if `data/` ever ships in a state the server can't load or that breaks core
+ * lookups, these tests fail.
+ *
+ * The env/cwd/home layers are neutralized so the test only ever reads the
+ * files committed in this repo.
+ */
+import { fileURLToPath } from "url";
+import { dirname, join, resolve } from "path";
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+
+import { SpecLoader } from "../src/spec_loader.js";
+import { cleanupTempDirs, makeTempDir } from "./helpers.js";
+
+const repoRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const originalCwd = process.cwd();
+let loader: SpecLoader;
+
+beforeAll(() => {
+  delete process.env.JSONUI_CLI_PATH;
+  const home = makeTempDir("home");
+  process.env.HOME = home;
+  process.env.USERPROFILE = home;
+  process.chdir(makeTempDir("cwd"));
+  loader = new SpecLoader(repoRoot);
+});
+
+afterAll(() => {
+  process.chdir(originalCwd);
+  cleanupTempDirs();
+});
+
+describe("bundled data/ snapshot", () => {
+  it("loads via the bundled layer from this repo's data/ directory", () => {
+    const source = loader.getDataSource();
+    expect(source.attributeDefinitions.layer).toBe("bundled");
+    expect(source.attributeDefinitions.path).toBe(
+      join(repoRoot, "data", "attribute_definitions.json")
+    );
+    expect(source.componentMetadata.layer).toBe("bundled");
+  });
+
+  it("contains a sane component and common-attribute population", () => {
+    const source = loader.getDataSource();
+    expect(source.componentCount).toBeGreaterThanOrEqual(25);
+    expect(source.commonAttributeCount).toBeGreaterThanOrEqual(100);
+  });
+
+  it("includes every core component", () => {
+    const components = loader.listComponents();
+    for (const name of [
+      "View",
+      "Label",
+      "TextField",
+      "Button",
+      "Image",
+      "NetworkImage",
+      "ScrollView",
+      "Collection",
+      "SelectBox",
+      "Switch",
+      // Toggle is a component alias of Switch (`_alias_of`) — resolved,
+      // not listed; see "resolves the canonical component aliases" below.
+      "Segment",
+      "Slider",
+      "Progress",
+      "Radio",
+      "CheckBox",
+      "Indicator",
+      "SafeAreaView",
+      "TabView",
+      "Web",
+      "Embed",
+    ]) {
+      expect(components, `missing component: ${name}`).toContain(name);
+    }
+  });
+
+  it("serves the $jui meta-attribute from the common section", () => {
+    const attr = loader.getAttribute("$jui");
+    expect(attr).not.toBeNull();
+    expect(attr.scope).toBe("common");
+    expect(attr.definition.type).toBe("object");
+    expect(attr.definition.description).toContain("normalize");
+  });
+
+  it("resolves the canonical component aliases", () => {
+    expect(loader.getComponent("Text")?.name).toBe("Label");
+    expect(loader.getComponent("EditText")?.name).toBe("TextField");
+    expect(loader.getComponent("Input")?.name).toBe("TextField");
+    expect(loader.getComponent("Check")?.name).toBe("CheckBox");
+    // Not in any metadata `aliases` array — resolved from the section's
+    // `_alias_of` pointer alone (B1).
+    expect(loader.getComponent("Toggle")?.name).toBe("Switch");
+  });
+
+  it("derives two-way binding for TextField.text and read-only for Label.text", () => {
+    expect(loader.getComponent("TextField")!.bindingBehavior.text).toEqual({
+      direction: "two-way",
+    });
+    expect(loader.getComponent("Label")!.bindingBehavior.text).toEqual({
+      direction: "read-only",
+    });
+  });
+
+  it("gives every component a well-formed platform matrix and description", () => {
+    for (const name of loader.listComponents()) {
+      const comp = loader.getComponent(name)!;
+      expect(Object.keys(comp.platforms).sort()).toEqual([
+        "kotlin_dynamic",
+        "kotlin_generated",
+        "react",
+        "swift_dynamic",
+        "swift_generated",
+      ]);
+      for (const value of Object.values(comp.platforms)) {
+        expect(typeof value).toBe("boolean");
+      }
+      expect(comp.description.length).toBeGreaterThan(0);
+      expect(Array.isArray(comp.aliases)).toBe(true);
+      expect(Array.isArray(comp.rules)).toBe(true);
+    }
+  });
+
+  it("only emits valid binding directions", () => {
+    for (const name of loader.listComponents()) {
+      const comp = loader.getComponent(name)!;
+      for (const behavior of Object.values(comp.bindingBehavior)) {
+        expect(["two-way", "read-only"]).toContain(
+          (behavior as { direction: string }).direction
+        );
+      }
+    }
+  });
+
+  it("categorizes common attributes without losing any", () => {
+    const withCommon = loader.getComponentWithCommon("View");
+    const categories = withCommon.commonAttributes.categories;
+    let total = 0;
+    for (const attrs of Object.values(categories)) {
+      total += Object.keys(attrs as Record<string, unknown>).length;
+    }
+    expect(total).toBe(loader.getDataSource().commonAttributeCount);
+  });
+
+  it("answers core attribute lookups", () => {
+    expect(loader.getAttribute("width")).not.toBeNull();
+    expect(loader.getAttribute("background")).not.toBeNull();
+    expect(loader.getAttribute("onclick")).not.toBeNull();
+    expect(loader.searchComponents("binding").length).toBeGreaterThan(0);
+  });
+});

package/tests/cli_runner.test.ts

@@ -0,0 +1,120 @@
+/**
+ * cli_runner — execFile wrapper. child_process is mocked; no real CLI runs.
+ */
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const execFileMock = vi.hoisted(() => vi.fn());
+vi.mock("child_process", () => ({ execFile: execFileMock }));
+vi.mock("node:child_process", () => ({ execFile: execFileMock }));
+
+import { runCli, formatResult, type CliResult } from "../src/cli_runner.js";
+
+type ExecCallback = (error: any, stdout: string, stderr: string) => void;
+
+interface RecordedCall {
+  command: string;
+  args: string[];
+  options: Record<string, any>;
+}
+
+let recorded: RecordedCall[];
+let nextResponse: { error?: any; stdout?: string; stderr?: string };
+
+beforeEach(() => {
+  recorded = [];
+  nextResponse = {};
+  execFileMock.mockReset();
+  execFileMock.mockImplementation(
+    (command: string, args: string[], options: any, callback: ExecCallback) => {
+      recorded.push({ command, args, options });
+      callback(
+        nextResponse.error ?? null,
+        nextResponse.stdout ?? "",
+        nextResponse.stderr ?? ""
+      );
+    }
+  );
+});
+
+describe("runCli", () => {
+  it("returns exitCode 0 with stdout/stderr on success", async () => {
+    nextResponse = { stdout: "done\n", stderr: "" };
+    const result = await runCli("jui", ["build"], { cwd: "/proj" });
+    expect(result).toEqual({ exitCode: 0, stdout: "done\n", stderr: "" });
+  });
+
+  it("propagates the process exit code from the error object", async () => {
+    nextResponse = {
+      error: Object.assign(new Error("exit 3"), { code: 3 }),
+      stdout: "partial",
+      stderr: "boom",
+    };
+    const result = await runCli("jui", ["verify"], { cwd: "/proj" });
+    expect(result).toEqual({ exitCode: 3, stdout: "partial", stderr: "boom" });
+  });
+
+  it("defaults to exitCode 1 when the error has no code", async () => {
+    nextResponse = { error: new Error("spawn failure") };
+    const result = await runCli("jui", ["build"], { cwd: "/proj" });
+    expect(result.exitCode).toBe(1);
+  });
+
+  it("maps a killed process to a timeout message using the default 60s", async () => {
+    nextResponse = {
+      error: Object.assign(new Error("killed"), { killed: true }),
+      stdout: "partial output",
+    };
+    const result = await runCli("jui", ["build"], { cwd: "/proj" });
+    expect(result).toEqual({
+      exitCode: 1,
+      stdout: "partial output",
+      stderr: "Command timed out after 60s",
+    });
+  });
+
+  it("reports custom timeouts in the timeout message", async () => {
+    nextResponse = {
+      error: Object.assign(new Error("killed"), { killed: true }),
+    };
+    const result = await runCli("jui", ["build"], { cwd: "/proj", timeout: 5_000 });
+    expect(result.stderr).toBe("Command timed out after 5s");
+  });
+
+  it("forwards cwd / timeout / maxBuffer / UTF-8 env to execFile", async () => {
+    await runCli("jsonui-doc", ["validate", "spec", "x.json"], {
+      cwd: "/some/project",
+      timeout: 12_345,
+    });
+    expect(recorded).toHaveLength(1);
+    const { command, args, options } = recorded[0];
+    expect(command).toBe("jsonui-doc");
+    expect(args).toEqual(["validate", "spec", "x.json"]);
+    expect(options.cwd).toBe("/some/project");
+    expect(options.timeout).toBe(12_345);
+    expect(options.maxBuffer).toBe(10 * 1024 * 1024);
+    expect(options.env.PYTHONIOENCODING).toBe("utf-8");
+  });
+
+  it("uses a 60s timeout when none is given", async () => {
+    await runCli("jui", ["build"], { cwd: "/proj" });
+    expect(recorded[0].options.timeout).toBe(60_000);
+  });
+});
+
+describe("formatResult", () => {
+  it("marks exitCode 0 as success and omits empty errors", () => {
+    const result: CliResult = { exitCode: 0, stdout: "ok", stderr: "" };
+    const parsed = JSON.parse(formatResult(result));
+    expect(parsed).toEqual({ success: true, output: "ok" });
+    expect("errors" in parsed).toBe(false);
+  });
+
+  it("marks non-zero exit as failure and includes stderr", () => {
+    const result: CliResult = { exitCode: 2, stdout: "log", stderr: "bad" };
+    expect(JSON.parse(formatResult(result))).toEqual({
+      success: false,
+      output: "log",
+      errors: "bad",
+    });
+  });
+});

package/tests/config.test.ts

@@ -0,0 +1,212 @@
+/**
+ * ServerConfig — project dir resolution, jui.config.json reading,
+ * directory field resolution, and path-traversal defense.
+ */
+import { mkdirSync, symlinkSync, writeFileSync } from "fs";
+import { join, resolve } from "path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+
+import { ServerConfig, type ProjectConfig } from "../src/config.js";
+import {
+  cleanupTempDirs,
+  makeFixtureProject,
+  makeTempDir,
+  FIXTURE_PROJECT_CONFIG,
+} from "./helpers.js";
+
+beforeEach(() => {
+  delete process.env.JUI_PROJECT_DIR;
+});
+
+afterEach(() => {
+  delete process.env.JUI_PROJECT_DIR;
+  cleanupTempDirs();
+});
+
+describe("resolveProjectDir", () => {
+  it("uses the explicit override when given", () => {
+    const dir = makeTempDir("proj");
+    const config = new ServerConfig();
+    expect(config.resolveProjectDir(dir)).toBe(resolve(dir));
+  });
+
+  it("falls back to JUI_PROJECT_DIR captured at construction time", () => {
+    const dir = makeTempDir("proj");
+    process.env.JUI_PROJECT_DIR = dir;
+    const config = new ServerConfig();
+    expect(config.resolveProjectDir()).toBe(resolve(dir));
+  });
+
+  it("prefers the override over JUI_PROJECT_DIR", () => {
+    const envDir = makeTempDir("env-proj");
+    const overrideDir = makeTempDir("override-proj");
+    process.env.JUI_PROJECT_DIR = envDir;
+    const config = new ServerConfig();
+    expect(config.resolveProjectDir(overrideDir)).toBe(resolve(overrideDir));
+  });
+
+  it("throws a setup hint when neither override nor env is present", () => {
+    const config = new ServerConfig();
+    expect(() => config.resolveProjectDir()).toThrowError(
+      /No project directory specified.*JUI_PROJECT_DIR/s
+    );
+  });
+
+  it("throws when the directory does not exist", () => {
+    const config = new ServerConfig();
+    const missing = join(makeTempDir("base"), "does-not-exist");
+    expect(() => config.resolveProjectDir(missing)).toThrowError(
+      /Project directory does not exist/
+    );
+  });
+});
+
+describe("readProjectConfig", () => {
+  it("parses jui.config.json from the project root", () => {
+    const dir = makeTempDir("proj");
+    makeFixtureProject(dir);
+    const config = new ServerConfig();
+    const project = config.readProjectConfig(dir);
+    expect(project.project_name).toBe("ExampleApp");
+    expect(project.spec_directory).toBe("docs/screens/json");
+    expect(project.platforms.ios.mode).toBe("swiftui");
+  });
+
+  it("throws with a jui_init hint when jui.config.json is missing", () => {
+    const dir = makeTempDir("empty-proj");
+    const config = new ServerConfig();
+    expect(() => config.readProjectConfig(dir)).toThrowError(
+      /jui\.config\.json not found.*jui_init/s
+    );
+  });
+});
+
+describe("resolveDir", () => {
+  const config = new ServerConfig();
+  const projectConfig = FIXTURE_PROJECT_CONFIG as unknown as ProjectConfig;
+
+  it("joins relative directory fields onto the project dir", () => {
+    expect(resolveDirFor("layouts_directory")).toBe(join("/proj", "layouts"));
+    expect(resolveDirFor("spec_directory")).toBe(
+      join("/proj", "docs/screens/json")
+    );
+  });
+
+  it("passes absolute directory fields through unchanged", () => {
+    const absConfig = {
+      ...projectConfig,
+      layouts_directory: "/abs/layouts",
+    } as ProjectConfig;
+    expect(config.resolveDir(absConfig, "layouts_directory", "/proj")).toBe(
+      "/abs/layouts"
+    );
+  });
+
+  it("falls back to the project dir for non-string fields", () => {
+    expect(config.resolveDir(projectConfig, "platforms", "/proj")).toBe("/proj");
+  });
+
+  function resolveDirFor(field: keyof ProjectConfig): string {
+    return config.resolveDir(projectConfig, field, "/proj");
+  }
+});
+
+describe("validatePathInProject", () => {
+  const config = new ServerConfig();
+
+  // Note: return values are asserted via suffix, not full equality — the
+  // absolute prefix may be symlink-normalized (macOS /var -> /private/var).
+  it("accepts a relative path inside the project", () => {
+    const dir = makeTempDir("proj");
+    const validated = config.validatePathInProject("layouts/login.json", dir);
+    expect(validated.endsWith(join("layouts", "login.json"))).toBe(true);
+  });
+
+  it("accepts an absolute path inside the project", () => {
+    const dir = makeTempDir("proj");
+    const inside = join(dir, "docs", "spec.json");
+    const validated = config.validatePathInProject(inside, dir);
+    expect(validated.endsWith(join("docs", "spec.json"))).toBe(true);
+  });
+
+  it("rejects ../ traversal out of the project", () => {
+    const dir = makeTempDir("proj");
+    expect(() =>
+      config.validatePathInProject("../../etc/passwd", dir)
+    ).toThrowError(/Path traversal detected/);
+  });
+
+  it("rejects ../ traversal hidden in the middle of a path", () => {
+    const dir = makeTempDir("proj");
+    expect(() =>
+      config.validatePathInProject("layouts/../../outside.json", dir)
+    ).toThrowError(/Path traversal detected/);
+  });
+
+  it("rejects absolute paths outside the project", () => {
+    const dir = makeTempDir("proj");
+    const other = makeTempDir("other");
+    expect(() =>
+      config.validatePathInProject(join(other, "secret.json"), dir)
+    ).toThrowError(/Path traversal detected/);
+  });
+
+  it("rejects sibling directories that share the project dir as a name prefix", () => {
+    // "/base/proj-evil/…".startsWith("/base/proj") is true — a naive prefix
+    // check lets siblings through. Must compare on path-segment boundaries.
+    const base = makeTempDir("base");
+    const dir = join(base, "proj");
+    const evil = join(base, "proj-evil");
+    mkdirSync(dir);
+    mkdirSync(evil);
+    writeFileSync(join(evil, "secret.json"), "{}");
+    expect(() =>
+      config.validatePathInProject(join(evil, "secret.json"), dir)
+    ).toThrowError(/Path traversal detected/);
+  });
+
+  it("rejects a symlink inside the project that points outside", () => {
+    const base = makeTempDir("base");
+    const dir = join(base, "proj");
+    const outside = join(base, "outside");
+    mkdirSync(dir);
+    mkdirSync(outside);
+    writeFileSync(join(outside, "secret.json"), "SECRET");
+    symlinkSync(outside, join(dir, "link"));
+    expect(() =>
+      config.validatePathInProject("link/secret.json", dir)
+    ).toThrowError(/Path traversal detected/);
+  });
+
+  it("rejects a non-existent leaf under an outward-pointing symlink", () => {
+    const base = makeTempDir("base");
+    const dir = join(base, "proj");
+    const outside = join(base, "outside");
+    mkdirSync(dir);
+    mkdirSync(outside);
+    symlinkSync(outside, join(dir, "link"));
+    expect(() =>
+      config.validatePathInProject("link/ghost.json", dir)
+    ).toThrowError(/Path traversal detected/);
+  });
+
+  it("accepts a symlink that stays inside the project", () => {
+    const base = makeTempDir("base");
+    const dir = join(base, "proj");
+    mkdirSync(join(dir, "real"), { recursive: true });
+    writeFileSync(join(dir, "real", "file.json"), "{}");
+    symlinkSync(join(dir, "real"), join(dir, "alias"));
+    const validated = config.validatePathInProject("alias/file.json", dir);
+    expect(validated.endsWith(join("real", "file.json"))).toBe(true);
+  });
+
+  it("allows a path that stays inside after .. segments resolve", () => {
+    const dir = makeTempDir("proj");
+    const validated = config.validatePathInProject(
+      "layouts/../docs/spec.json",
+      dir
+    );
+    expect(validated.endsWith(join("docs", "spec.json"))).toBe(true);
+    expect(validated).not.toContain("..");
+  });
+});

package/tests/derived.test.ts

@@ -0,0 +1,114 @@
+/**
+ * Derived static content served by the MCP: common-attribute categorizer and
+ * the platform convention constants. The constants are pinned via file
+ * snapshots — any edit to MODIFIER_ORDER / BINDING_RULES / PLATFORM_MAPPING
+ * must be intentional and reviewed via the snapshot diff.
+ */
+import { describe, expect, it } from "vitest";
+
+import {
+  BINDING_RULES,
+  MODIFIER_ORDER,
+  PLATFORM_MAPPING,
+  categorizeCommonAttributes,
+} from "../src/data/derived.js";
+
+describe("categorizeCommonAttributes", () => {
+  it("places known keys into their category", () => {
+    const result = categorizeCommonAttributes({
+      width: { type: "int" },
+      padding: { type: "int" },
+      background: { type: "string" },
+      hidden: { type: "boolean" },
+      onClick: { type: "binding" },
+      alignTop: { type: "boolean" },
+      onAppear: { type: "binding" },
+      testId: { type: "string" },
+      binding_group: { type: "string" },
+    });
+    expect(result.categories.sizing.width).toBeDefined();
+    expect(result.categories.spacing.padding).toBeDefined();
+    expect(result.categories.visual.background).toBeDefined();
+    expect(result.categories.visibility.hidden).toBeDefined();
+    expect(result.categories.interaction.onClick).toBeDefined();
+    expect(result.categories.layout.alignTop).toBeDefined();
+    expect(result.categories.lifecycle.onAppear).toBeDefined();
+    expect(result.categories.accessibility.testId).toBeDefined();
+    expect(result.categories.binding.binding_group).toBeDefined();
+  });
+
+  it("routes unknown keys to 'other'", () => {
+    const result = categorizeCommonAttributes({ mysteryKnob: { type: "int" } });
+    expect(result.categories.other.mysteryKnob).toBeDefined();
+  });
+
+  it("skips _-prefixed keys", () => {
+    const result = categorizeCommonAttributes({
+      _meta: { version: 1 },
+      width: { type: "int" },
+    });
+    expect(result.categories.other).toBeUndefined();
+    expect(Object.keys(result.categories)).toEqual(["sizing"]);
+  });
+
+  it("drops empty categories entirely", () => {
+    const result = categorizeCommonAttributes({ width: { type: "int" } });
+    expect(Object.keys(result.categories)).toEqual(["sizing"]);
+  });
+
+  it("returns the wrapper description and source", () => {
+    const result = categorizeCommonAttributes({});
+    expect(result.description).toContain("Common attributes");
+    expect(result.source).toContain("attribute_definitions.json");
+    expect(result.categories).toEqual({});
+  });
+
+  it("preserves attribute definitions verbatim", () => {
+    const def = { type: ["string", "binding"], description: "w" };
+    const result = categorizeCommonAttributes({ width: def });
+    expect(result.categories.sizing.width).toBe(def);
+  });
+});
+
+describe("derived constants (pinned)", () => {
+  it("MODIFIER_ORDER covers exactly swift/kotlin/react", () => {
+    expect(Object.keys(MODIFIER_ORDER).sort()).toEqual([
+      "description",
+      "kotlin",
+      "react",
+      "swift",
+    ]);
+    expect(MODIFIER_ORDER.swift.order.length).toBeGreaterThan(0);
+    expect(MODIFIER_ORDER.swift.criticalRules.length).toBeGreaterThan(0);
+    expect(MODIFIER_ORDER.kotlin.order.length).toBeGreaterThan(0);
+  });
+
+  it("BINDING_RULES defines both directions and the @{} syntax", () => {
+    expect(BINDING_RULES.format.bindingExpression).toBe("@{propertyName}");
+    expect(Object.keys(BINDING_RULES.directions).sort()).toEqual([
+      "read-only",
+      "two-way",
+    ]);
+  });
+
+  it("PLATFORM_MAPPING has all three platforms for every plain value mapping", () => {
+    for (const mapping of Object.values(PLATFORM_MAPPING.values)) {
+      expect(Object.keys(mapping).sort()).toEqual(["kotlin", "react", "swift"]);
+    }
+    for (const mapping of Object.values(PLATFORM_MAPPING.textAlign)) {
+      expect(Object.keys(mapping).sort()).toEqual(["kotlin", "react", "swift"]);
+    }
+  });
+
+  it("MODIFIER_ORDER snapshot", () => {
+    expect(MODIFIER_ORDER).toMatchSnapshot();
+  });
+
+  it("BINDING_RULES snapshot", () => {
+    expect(BINDING_RULES).toMatchSnapshot();
+  });
+
+  it("PLATFORM_MAPPING snapshot", () => {
+    expect(PLATFORM_MAPPING).toMatchSnapshot();
+  });
+});