openuispec 0.1.41 → 0.1.43

package/cli/init.ts

@@ -319,21 +319,28 @@ or any visual/structural change — you MUST use the OpenUISpec tools before wri
 
 Call these MCP tools directly. They return structured JSON with everything you need.
 
-1. **Before ANY UI code generation or modification:**
-   Call \`openuispec_prepare\` with the target platform. This returns the spec context,
-   platform config, generation constraints, and semantic changes. Do not skip this step.
-
-2. **After editing spec files:**
-   Call \`openuispec_check\` to validate schema + semantic lint + prepare readiness.
-
-3. **To understand project state:**
-   Call \`openuispec_status\` for cross-target summary.
-
-4. **To detect what changed:**
-   Call \`openuispec_drift\` with \`explain: true\` to see property-level spec changes.
-
-5. **For schema validation only:**
-   Call \`openuispec_validate\` optionally with specific groups.
+**Pre-generation:**
+1. Call \`openuispec_prepare\` with the target platform — returns spec context, platform config, constraints.
+2. Call \`openuispec_read_specs\` to load spec file contents. Use these as the AUTHORITATIVE source.
+3. If spec changes are needed, update spec files FIRST, then call \`openuispec_check\`.
+4. Generate or update the platform UI code based on the spec contents.
+
+**Post-generation (EVERY TIME after writing UI code):**
+5. Call \`openuispec_check\` to validate spec integrity.
+6. Call \`openuispec_read_specs\` for the screens/contracts you just generated code for.
+7. Audit your generated code against the spec. For each screen, verify:
+   - Every field/action in the spec has a corresponding UI element
+   - Token values (colors, spacing, radii) match exactly — no approximations
+   - Contract \`must_handle\` states are all implemented (loading, error, empty, etc.)
+   - Adaptive breakpoints match the spec's \`size_classes\`
+   - Locale keys match \`$t:\` references
+   - Navigation targets match flow definitions
+8. Report any real gaps found and fix them before finishing.
+
+**Other tools:**
+- \`openuispec_status\` — cross-target summary, good starting point
+- \`openuispec_drift\` with \`explain: true\` — property-level spec changes
+- \`openuispec_validate\` — schema-only validation by group
 
 ### CLI fallback (when MCP is not available)
 

package/mcp-server/index.ts

@@ -22,8 +22,9 @@ import { buildCheckResult } from "../check/index.js";
 import { buildStatusResult } from "../status/index.js";
 import { buildValidateResult } from "../schema/validate.js";
 import { loadTargetDrift } from "../drift/index.js";
-import { readFileSync as fsReadFileSync } from "node:fs";
-import { relative } from "node:path";
+import { readFileSync as fsReadFileSync, existsSync, readdirSync } from "node:fs";
+import { relative, resolve } from "node:path";
+import YAML from "yaml";
 
 // ── resolve project cwd ──────────────────────────────────────────────
 
@@ -69,14 +70,26 @@ const server = new McpServer(
 Spec files (YAML) are the single source of truth for all UI across platforms.
 
 MANDATORY WORKFLOW for any UI-related request (screens, navigation, layout, tokens, flows, localization):
-1. BEFORE writing or modifying any UI code, call openuispec_prepare with the target platform.
-   This returns the spec context, platform config, generation constraints, and the list of spec files.
-2. Then call openuispec_read_specs to load the spec file contents you need for the task.
-   Pass specific paths for targeted work, or omit paths to load everything.
+
+PRE-GENERATION:
+1. Call openuispec_prepare with the target platform.
+2. Call openuispec_read_specs to load the spec file contents you need.
    Use the returned contents as the AUTHORITATIVE source — do NOT paraphrase from memory.
    Cross-reference exact token values, contract must_handle lists, and locale keys from the content.
-3. If the request requires spec changes, update the spec files FIRST, then call openuispec_check to validate.
-4. Only then generate or update the platform UI code based on the spec contents.
+3. If the request requires spec changes, update the spec files FIRST, then call openuispec_check.
+4. Generate or update the platform UI code based on the spec contents.
+
+POST-GENERATION (do this EVERY TIME after writing UI code):
+5. Call openuispec_check to validate spec integrity.
+6. Call openuispec_read_specs for the screens/contracts you just generated code for.
+7. Audit your generated code against the spec contents. For each screen, verify:
+   - Every field/action in the spec has a corresponding UI element
+   - Token values (colors, spacing, radii) match the spec exactly, not approximations
+   - Contract must_handle states are all implemented (loading, error, empty, etc.)
+   - Adaptive breakpoints match the layout size_classes in the spec
+   - Locale keys match $t: references in the spec
+   - Navigation targets match flow definitions
+   Report any real gaps found and fix them before finishing.
 
 Skip these tools ONLY when the request is purely non-UI (API logic, database, infrastructure, etc.)
 or explicitly platform-specific polish that doesn't affect shared UI semantics.`,
@@ -102,15 +115,153 @@ server.registerTool(
 
 // ── tool: openuispec_check ───────────────────────────────────────────
 
+function buildAuditChecklist(projectDir: string, target: string): string {
+  const lines: string[] = [
+    "POST-GENERATION AUDIT — verify your code against these concrete spec requirements:",
+    "",
+    "HOW TO AUDIT: For each item below, READ the generated component/screen file,",
+    "find the code that implements it, and confirm the values match exactly.",
+    "If you cannot find the implementation, it is a REAL GAP — fix it.",
+    "",
+  ];
+
+  // Extract must_handle from contracts
+  const manifest = YAML.parse(fsReadFileSync(join(projectDir, "openuispec.yaml"), "utf-8"));
+  const contractsDir = resolve(projectDir, manifest.includes?.contracts ?? "./contracts/");
+
+  if (existsSync(contractsDir)) {
+    lines.push("## Contract must_handle requirements");
+    for (const file of readdirSync(contractsDir).filter(f => f.endsWith(".yaml")).sort()) {
+      try {
+        const content = YAML.parse(fsReadFileSync(join(contractsDir, file), "utf-8"));
+        const contractName = Object.keys(content)[0];
+        const contract = content[contractName];
+        if (!contract?.variants) continue;
+
+        for (const [variantName, variant] of Object.entries(contract.variants as Record<string, any>)) {
+          const mustHandle = variant?.generation?.must_handle;
+          if (mustHandle?.length) {
+            lines.push(`\n### ${contractName}.${variantName}`);
+            for (const item of mustHandle) {
+              lines.push(`- [ ] ${item}`);
+            }
+          }
+        }
+
+        // Top-level generation.must_handle
+        const topMustHandle = contract?.generation?.must_handle;
+        if (topMustHandle?.length) {
+          lines.push(`\n### ${contractName} (global)`);
+          for (const item of topMustHandle) {
+            lines.push(`- [ ] ${item}`);
+          }
+        }
+      } catch { /* skip unparseable files */ }
+    }
+    lines.push("");
+  }
+
+  // Extract screens and their sections
+  const screensDir = resolve(projectDir, manifest.includes?.screens ?? "./screens/");
+  if (existsSync(screensDir)) {
+    lines.push("## Screens — verify all sections exist in generated code");
+    for (const file of readdirSync(screensDir).filter(f => f.endsWith(".yaml")).sort()) {
+      try {
+        const content = YAML.parse(fsReadFileSync(join(screensDir, file), "utf-8"));
+        const screenName = Object.keys(content)[0];
+        const screen = content[screenName];
+        if (screen?.status === "stub") continue;
+
+        const sections: string[] = [];
+        const collectSections = (node: any, prefix = "") => {
+          if (!node || typeof node !== "object") return;
+          if (node.contract) sections.push(`${prefix}${node.contract}${node.variant ? `.${node.variant}` : ""}`);
+          if (node.sections) {
+            for (const [key, child] of Object.entries(node.sections)) {
+              collectSections(child, `${prefix}${key}/`);
+            }
+          }
+          if (node.children && Array.isArray(node.children)) {
+            for (const child of node.children) {
+              collectSections(child, prefix);
+            }
+          }
+        };
+        collectSections(screen?.layout);
+
+        if (sections.length > 0) {
+          lines.push(`\n### ${screenName} (${file})`);
+          for (const section of sections) {
+            lines.push(`- [ ] ${section}`);
+          }
+        }
+
+        // Adaptive layout
+        if (screen?.layout?.adaptive || screen?.adaptive) {
+          lines.push(`- [ ] Adaptive breakpoints implemented`);
+        }
+      } catch { /* skip */ }
+    }
+    lines.push("");
+  }
+
+  // Locale keys count
+  const localesDir = resolve(projectDir, manifest.includes?.locales ?? "./locales/");
+  if (existsSync(localesDir)) {
+    const localeFiles = readdirSync(localesDir).filter(f => f.endsWith(".json"));
+    if (localeFiles.length > 0) {
+      lines.push("## Locales — verify all locale files are wired");
+      for (const file of localeFiles) {
+        try {
+          const keys = Object.keys(JSON.parse(fsReadFileSync(join(localesDir, file), "utf-8")));
+          lines.push(`- [ ] ${file}: ${keys.length} keys loaded at runtime`);
+        } catch { /* skip */ }
+      }
+      lines.push("");
+    }
+  }
+
+  // Platform-specific checks
+  const platformDir = resolve(projectDir, manifest.includes?.platform ?? "./platform/");
+  const platformPath = join(platformDir, `${target}.yaml`);
+  if (existsSync(platformPath)) {
+    try {
+      const platformDoc = YAML.parse(fsReadFileSync(platformPath, "utf-8"));
+      const platformDef = platformDoc?.[target];
+      if (platformDef?.generation) {
+        lines.push("## Platform generation requirements");
+        const gen = platformDef.generation;
+        if (gen.architecture) lines.push(`- [ ] Architecture: ${gen.architecture}`);
+        if (gen.naming) lines.push(`- [ ] Naming convention: ${gen.naming}`);
+        if (gen.css) lines.push(`- [ ] CSS framework: ${gen.css}`);
+      }
+    } catch { /* skip */ }
+  }
+
+  lines.push("FOR EACH UNCHECKED ITEM: Read the generated file, search for the implementation,");
+  lines.push("and either confirm it matches or fix it. Do not mark items as 'intentionally skipped'");
+  lines.push("unless the user explicitly requested to skip them.");
+
+  return lines.join("\n");
+}
+
 server.registerTool(
   "openuispec_check",
   {
-    description: "Run composite validation: schema validation, semantic linting, and prepare readiness check. Call after spec edits to verify correctness.",
+    description: "Run composite validation + post-generation audit. Returns schema validation results AND a concrete audit checklist derived from your spec files — listing every contract must_handle item, every screen section, and every locale file that must exist in your generated code. Verify each item.",
     inputSchema: { target: targetSchema },
   },
   async ({ target }) => {
     try {
-      return toolResult(buildCheckResult(target, projectCwd));
+      const result = buildCheckResult(target, projectCwd);
+      const projectDir = findProjectDir(projectCwd);
+      const audit = buildAuditChecklist(projectDir, target);
+      return {
+        content: [
+          { type: "text" as const, text: JSON.stringify(result, null, 2) },
+          { type: "text" as const, text: audit },
+        ],
+      };
     } catch (err) {
       return toolError(err);
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openuispec",
-  "version": "0.1.41",
+  "version": "0.1.43",
   "license": "MIT",
   "type": "module",
   "description": "A semantic UI specification format for AI-native, platform-native app development",