jui-tools-mcp-server 2.12.10 → 2.14.0

package/dist/spec_loader.js

@@ -59,6 +59,10 @@ export class SpecLoader {
     screenIdentity = null;
     commonAttributes = null;
     aliasMap = new Map();
+    /// Lower-cased spelling -> its entry in type_synonyms.json, for the
+    /// spellings that resolve through it (not a section, `_alias_of` or
+    /// metadata alias of their own).
+    typeSynonyms = new Map();
     metadata = {};
     dataSource;
     /** When this process read the files. Data is cached in memory from then
@@ -123,6 +127,13 @@ export class SpecLoader {
         const comp = this.getComponent(name);
         if (!comp)
             return null;
+        // Say which spelling was asked for and why it resolved: the build
+        // accepts `ProgressBar` as a Progress, and an HStack is a View that
+        // also means `orientation: horizontal`.
+        const synonym = this.typeSynonyms.get(name.toLowerCase());
+        if (synonym) {
+            return { ...comp, typeSynonym: synonym, commonAttributes: this.commonAttributes };
+        }
         return { ...comp, commonAttributes: this.commonAttributes };
     }
     getAttribute(name) {
@@ -202,6 +213,15 @@ export class SpecLoader {
                     matches.push(`rule: ${rule}`);
                 }
             }
+            // A spelling the build accepts for this type (type_synonyms.json).
+            for (const synonym of this.typeSynonyms.values()) {
+                if (this.getComponent(synonym.spelling) !== comp)
+                    continue;
+                if (synonym.spelling.toLowerCase().includes(q)) {
+                    score += 8;
+                    matches.push(`type synonym: ${synonym.spelling}`);
+                }
+            }
             if (score > 0)
                 results.push({ component: comp.name, score, matches });
         }
@@ -290,6 +310,7 @@ export class SpecLoader {
             this.dataSource.attributeSemantics,
             this.dataSource.platformSemantics,
             this.dataSource.coverage,
+            this.dataSource.typeSynonyms,
         ].filter((f) => f != null);
         const changed = [];
         for (const file of tracked) {
@@ -458,6 +479,7 @@ export class SpecLoader {
             }
             componentCount++;
         }
+        const typeSynonymsResolution = this.loadTypeSynonyms();
         this.dataSource = {
             attributeDefinitions: attrResolution,
             componentMetadata: metaResolution,
@@ -466,10 +488,59 @@ export class SpecLoader {
             attributeSemantics: attributeSemanticsResolution,
             platformSemantics: platformSemanticsResolution,
             coverage: coverageResolution,
+            typeSynonyms: typeSynonymsResolution,
             componentCount,
             commonAttributeCount: Object.keys(this.commonAttributesRaw).filter((k) => !k.startsWith("_")).length,
         };
     }
+    /**
+     * Type spellings the build accepts for a section they are not
+     * (shared/core/type_synonyms.json, jsonui-cli 1.9.0 — the one table the
+     * tools and the dynamic runtimes read). Until then lookup_component knew
+     * only `_alias_of` sections and metadata aliases, and answered "not found"
+     * for `ProgressBar`, which the build draws as a Progress.
+     *
+     * A section, an `_alias_of` section or a metadata alias of the same
+     * spelling wins: the exact match is found first, as in the tools. An entry
+     * whose canonical is not a section here is skipped.
+     *
+     * Absent (older jsonui-cli): no synonyms. Present but not JSON: the load
+     * throws, so an automatic reload keeps the last content that parsed rather
+     * than swapping in a loader that silently lost every synonym.
+     */
+    loadTypeSynonyms() {
+        this.typeSynonyms = new Map();
+        let resolution;
+        try {
+            resolution = this.resolveFile("shared/core/type_synonyms.json", "data/type_synonyms.json");
+        }
+        catch {
+            return null;
+        }
+        const doc = JSON.parse(readFileSync(resolution.path, "utf-8"));
+        for (const [spelling, entry] of Object.entries(doc.synonyms ?? {})) {
+            if (typeof entry !== "object" || entry === null)
+                continue;
+            const { canonical, render_as: renderAs, ...implies } = entry;
+            if (typeof canonical !== "string" || canonical.length === 0)
+                continue;
+            const key = spelling.toLowerCase();
+            if (this.components.has(key) || this.aliasMap.has(key))
+                continue;
+            const target = this.aliasMap.get(canonical.toLowerCase()) ?? canonical.toLowerCase();
+            if (!this.components.has(target))
+                continue;
+            this.aliasMap.set(key, target);
+            this.typeSynonyms.set(key, {
+                spelling,
+                canonical,
+                ...(typeof renderAs === "string" ? { renderAs } : {}),
+                ...(Object.keys(implies).length > 0 ? { implies } : {}),
+                source: "shared/core/type_synonyms.json",
+            });
+        }
+        return resolution;
+    }
     normalizeMetadata(raw) {
         return {
             description: raw.description ?? "",

package/dist/tools/jui/jui_generate_converter.js

@@ -6,10 +6,17 @@ export function register(server, config) {
         from_spec: z.string().optional().describe("Generate from component spec file path"),
         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."),
+        container: z.boolean().optional().describe("true: a container (it draws its children). false: a leaf (it takes no " +
+            "children, and a layout that gives it some is refused by name) — needs " +
+            "jsonui-cli 1.9.0 or later (earlier `jui` rejects --no-container). " +
+            "Absent: the default form."),
+        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 {
@@ -27,12 +34,20 @@ export function register(server, config) {
             if (params.attributes) {
                 args.push("--attributes", params.attributes);
             }
-            if (params.container) {
+            // `false` asks for a leaf. It used to pass nothing, so the command ran
+            // in the default form and the request was dropped without a word.
+            if (params.container === true) {
                 args.push("--container");
             }
+            if (params.container === false) {
+                args.push("--no-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/dist/tools/jui/jui_generate_project.js

@@ -1,9 +1,18 @@
 import { z } from "zod";
 import { runCli, formatResult } from "../../cli_runner.js";
 export function register(server, config) {
-    server.tool("jui_generate_project", "Generate Layout JSON and ViewModel files from screen specs (all or single spec)", {
+    server.tool("jui_generate_project", "Generate Layout JSON and ViewModel files from screen specs (all or single spec). " +
+        "A Layout JSON it generates — a screen's, or a Collection cell / header / footer's — is " +
+        "written when it is not there, left as it is when it already holds exactly what the spec " +
+        "generates, and otherwise KEPT (the Layout JSON is hand-edited after generation) and named " +
+        "in the output with \"Kept existing … layout: <file> … --force replaces it\". From " +
+        "jsonui-cli 1.9.0; an earlier jui rewrote an existing layout on every run.", {
         spec_file: z.string().optional().describe("Single spec file to process (e.g., 'login.spec.json')"),
-        force: z.boolean().optional().describe("Force overwrite declaration files"),
+        force: z.boolean().optional().describe("Replace the ViewModel declaration files, and each Layout JSON that already exists and " +
+            "differs from what the spec generates (kept and named without it). A layout whose data " +
+            "section holds entries the spec does not declare is not replaced even with force — the " +
+            "output names them. Called from here the command has no terminal, so it never asks: " +
+            "without force an existing layout is kept."),
         skip_layout: z.boolean().optional().describe("Skip Layout JSON generation"),
         dry_run: z.boolean().optional().describe("Show what would be generated without writing"),
         platform: z.enum(["ios", "android", "web"]).optional().describe("Generate for single platform only"),

package/dist/tools/spec/get_data_source.js

@@ -1,7 +1,8 @@
 export function register(server, loader) {
-    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.", {}, async () => {
+    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, 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
@@ -15,6 +16,7 @@ export function register(server, loader) {
             info.attributeSemantics,
             info.platformSemantics,
             info.coverage,
+            info.typeSynonyms,
         ].filter((f) => f != null);
         const stale = files.some((f) => f.freshness === "stale");
         // The data is read once at construction and cached in memory, so a
@@ -35,6 +37,7 @@ export function register(server, loader) {
                         attributeSemantics: info.attributeSemantics,
                         platformSemantics: info.platformSemantics,
                         coverage: info.coverage,
+                        typeSynonyms: info.typeSynonyms,
                         componentCount: info.componentCount,
                         commonAttributeCount: info.commonAttributeCount,
                         loadedAt,

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.10",
+  "version": "2.14.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/scripts/fetch-definitions.js

@@ -44,7 +44,7 @@ const DATA_DIR = join(PROJECT_ROOT, "data");
 //   3. `npm run fetch-definitions` and commit the data/ diff together with
 //      this pin in one commit
 // JSONUI_CLI_RAW_BASE still overrides the whole base URL for manual testing.
-const JSONUI_CLI_TAG = "v1.8.110";
+const JSONUI_CLI_TAG = "v1.9.0";
 const BASE_URL =
   process.env.JSONUI_CLI_RAW_BASE ||
   `https://raw.githubusercontent.com/Tai-Kimura/jsonui-cli/${JSONUI_CLI_TAG}`;

package/scripts/fetch-manifest.js

@@ -59,6 +59,12 @@ export const FILES = [
   // Conformance coverage ledger (declared-but-unimplemented gaps). The loader
   // reads data/coverage.json as its fallback, so it must refresh with the rest
   // — binding_semantics.json already fell into this exact stale-snapshot trap.
+  // Type-spelling synonyms (jsonui-cli 1.9.0): lookup_component and
+  // search_components resolve ProgressBar, HStack, Text … through it.
+  {
+    remote: "shared/core/type_synonyms.json",
+    local: "type_synonyms.json",
+  },
   {
     remote: "conformance/coverage.json",
     local: "coverage.json",

package/src/cli_runner.ts

@@ -14,7 +14,7 @@ export async function runCli(
   const timeout = options.timeout ?? 60_000;
 
   return new Promise((resolve) => {
-    execFile(
+    const child = execFile(
       command,
       args,
       {
@@ -39,6 +39,12 @@ export async function runCli(
         });
       }
     );
+    // Nothing is ever written to the child's stdin: end it now, so a CLI that
+    // reads stdin — an overwrite prompt — sees end-of-file instead of waiting
+    // for a line that never comes. Through 2.13.1 the pipe stayed open, and such
+    // a child waited until the timeout above killed it (`jui g converter` on
+    // an existing component, measured 2026-09-26).
+    child.stdin?.end();
   });
 }
 

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/spec_loader.ts

@@ -90,6 +90,17 @@ export interface ReloadRecord {
   error?: string;
 }
 
+/// A spelling the build accepts for a type it is not, as type_synonyms.json
+/// says: its canonical section, the type it is drawn as when that differs,
+/// and the attributes the spelling itself means.
+export interface TypeSynonym {
+  spelling: string;
+  canonical: string;
+  renderAs?: string;
+  implies?: Record<string, unknown>;
+  source: string;
+}
+
 export interface DataSourceInfo {
   attributeDefinitions: FileInfo;
   componentMetadata: FileInfo;
@@ -111,6 +122,10 @@ export interface DataSourceInfo {
   /// attribute, platform) pairs with their recorded reasons. Optional: absent
   /// on older jsonui-cli checkouts.
   coverage: FileInfo | null;
+  /// shared/core/type_synonyms.json — type spellings the build accepts for a
+  /// section they are not (ProgressBar, HStack, Text …). Optional: absent on
+  /// jsonui-cli before 1.9.0.
+  typeSynonyms: FileInfo | null;
   componentCount: number;
   commonAttributeCount: number;
 }
@@ -157,6 +172,10 @@ export class SpecLoader {
   private screenIdentity: Record<string, any> | null = null;
   private commonAttributes: any = null;
   private aliasMap: Map<string, string> = new Map();
+  /// Lower-cased spelling -> its entry in type_synonyms.json, for the
+  /// spellings that resolve through it (not a section, `_alias_of` or
+  /// metadata alias of their own).
+  private typeSynonyms: Map<string, TypeSynonym> = new Map();
   private metadata: Record<string, ComponentMetadata> = {};
   private dataSource!: DataSourceInfo;
   /** When this process read the files. Data is cached in memory from then
@@ -223,6 +242,13 @@ export class SpecLoader {
   getComponentWithCommon(name: string): any {
     const comp = this.getComponent(name);
     if (!comp) return null;
+    // Say which spelling was asked for and why it resolved: the build
+    // accepts `ProgressBar` as a Progress, and an HStack is a View that
+    // also means `orientation: horizontal`.
+    const synonym = this.typeSynonyms.get(name.toLowerCase());
+    if (synonym) {
+      return { ...comp, typeSynonym: synonym, commonAttributes: this.commonAttributes };
+    }
     return { ...comp, commonAttributes: this.commonAttributes };
   }
 
@@ -312,6 +338,15 @@ export class SpecLoader {
         }
       }
 
+      // A spelling the build accepts for this type (type_synonyms.json).
+      for (const synonym of this.typeSynonyms.values()) {
+        if (this.getComponent(synonym.spelling) !== comp) continue;
+        if (synonym.spelling.toLowerCase().includes(q)) {
+          score += 8;
+          matches.push(`type synonym: ${synonym.spelling}`);
+        }
+      }
+
       if (score > 0) results.push({ component: comp.name, score, matches });
     }
 
@@ -422,6 +457,7 @@ export class SpecLoader {
       this.dataSource.attributeSemantics,
       this.dataSource.platformSemantics,
       this.dataSource.coverage,
+      this.dataSource.typeSynonyms,
     ].filter((f): f is FileInfo => f != null);
 
     const changed: string[] = [];
@@ -635,6 +671,8 @@ export class SpecLoader {
       componentCount++;
     }
 
+    const typeSynonymsResolution = this.loadTypeSynonyms();
+
     this.dataSource = {
       attributeDefinitions: attrResolution,
       componentMetadata: metaResolution,
@@ -643,6 +681,7 @@ export class SpecLoader {
       attributeSemantics: attributeSemanticsResolution,
       platformSemantics: platformSemanticsResolution,
       coverage: coverageResolution,
+      typeSynonyms: typeSynonymsResolution,
       componentCount,
       commonAttributeCount: Object.keys(this.commonAttributesRaw).filter(
         (k) => !k.startsWith("_")
@@ -650,6 +689,52 @@ export class SpecLoader {
     };
   }
 
+  /**
+   * Type spellings the build accepts for a section they are not
+   * (shared/core/type_synonyms.json, jsonui-cli 1.9.0 — the one table the
+   * tools and the dynamic runtimes read). Until then lookup_component knew
+   * only `_alias_of` sections and metadata aliases, and answered "not found"
+   * for `ProgressBar`, which the build draws as a Progress.
+   *
+   * A section, an `_alias_of` section or a metadata alias of the same
+   * spelling wins: the exact match is found first, as in the tools. An entry
+   * whose canonical is not a section here is skipped.
+   *
+   * Absent (older jsonui-cli): no synonyms. Present but not JSON: the load
+   * throws, so an automatic reload keeps the last content that parsed rather
+   * than swapping in a loader that silently lost every synonym.
+   */
+  private loadTypeSynonyms(): FileInfo | null {
+    this.typeSynonyms = new Map();
+    let resolution: FileInfo;
+    try {
+      resolution = this.resolveFile("shared/core/type_synonyms.json", "data/type_synonyms.json");
+    } catch {
+      return null;
+    }
+    const doc = JSON.parse(readFileSync(resolution.path, "utf-8")) as {
+      synonyms?: Record<string, Record<string, unknown>>;
+    };
+    for (const [spelling, entry] of Object.entries(doc.synonyms ?? {})) {
+      if (typeof entry !== "object" || entry === null) continue;
+      const { canonical, render_as: renderAs, ...implies } = entry;
+      if (typeof canonical !== "string" || canonical.length === 0) continue;
+      const key = spelling.toLowerCase();
+      if (this.components.has(key) || this.aliasMap.has(key)) continue;
+      const target = this.aliasMap.get(canonical.toLowerCase()) ?? canonical.toLowerCase();
+      if (!this.components.has(target)) continue;
+      this.aliasMap.set(key, target);
+      this.typeSynonyms.set(key, {
+        spelling,
+        canonical,
+        ...(typeof renderAs === "string" ? { renderAs } : {}),
+        ...(Object.keys(implies).length > 0 ? { implies } : {}),
+        source: "shared/core/type_synonyms.json",
+      });
+    }
+    return resolution;
+  }
+
   private normalizeMetadata(raw: Record<string, any>): ComponentMetadata {
     return {
       description: raw.description ?? "",

package/src/tools/jui/jui_generate_converter.ts

@@ -12,7 +12,12 @@ export function register(server: McpServer, config: ServerConfig) {
       from_spec: z.string().optional().describe("Generate from component spec file path"),
       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"),
+      container: z.boolean().optional().describe(
+        "true: a container (it draws its children). false: a leaf (it takes no " +
+        "children, and a layout that gives it some is refused by name) — needs " +
+        "jsonui-cli 1.9.0 or later (earlier `jui` rejects --no-container). " +
+        "Absent: the default form."
+      ),
       skip_existing: z.boolean().optional().describe(
         "Leave existing converter and scaffold files untouched, without the " +
         "overwrite prompt — for idempotent scaffold runs. Wins over `force` " +
@@ -34,7 +39,10 @@ export function register(server: McpServer, config: ServerConfig) {
         if (params.from_spec) { args.push("--from", params.from_spec); }
         if (params.all) { args.push("--all"); }
         if (params.attributes) { args.push("--attributes", params.attributes); }
-        if (params.container) { args.push("--container"); }
+        // `false` asks for a leaf. It used to pass nothing, so the command ran
+        // in the default form and the request was dropped without a word.
+        if (params.container === true) { args.push("--container"); }
+        if (params.container === false) { args.push("--no-container"); }
         if (params.skip_existing) { args.push("--skip-existing"); }
         if (params.force) { args.push("--force"); }
 

package/src/tools/jui/jui_generate_project.ts

@@ -6,10 +6,21 @@ import { runCli, formatResult } from "../../cli_runner.js";
 export function register(server: McpServer, config: ServerConfig) {
   server.tool(
     "jui_generate_project",
-    "Generate Layout JSON and ViewModel files from screen specs (all or single spec)",
+    "Generate Layout JSON and ViewModel files from screen specs (all or single spec). " +
+      "A Layout JSON it generates — a screen's, or a Collection cell / header / footer's — is " +
+      "written when it is not there, left as it is when it already holds exactly what the spec " +
+      "generates, and otherwise KEPT (the Layout JSON is hand-edited after generation) and named " +
+      "in the output with \"Kept existing … layout: <file> … --force replaces it\". From " +
+      "jsonui-cli 1.9.0; an earlier jui rewrote an existing layout on every run.",
     {
       spec_file: z.string().optional().describe("Single spec file to process (e.g., 'login.spec.json')"),
-      force: z.boolean().optional().describe("Force overwrite declaration files"),
+      force: z.boolean().optional().describe(
+        "Replace the ViewModel declaration files, and each Layout JSON that already exists and " +
+          "differs from what the spec generates (kept and named without it). A layout whose data " +
+          "section holds entries the spec does not declare is not replaced even with force — the " +
+          "output names them. Called from here the command has no terminal, so it never asks: " +
+          "without force an existing layout is kept."
+      ),
       skip_layout: z.boolean().optional().describe("Skip Layout JSON generation"),
       dry_run: z.boolean().optional().describe("Show what would be generated without writing"),
       platform: z.enum(["ios", "android", "web"]).optional().describe("Generate for single platform only"),