openuispec 0.1.40 → 0.1.42

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

@@ -16,12 +16,14 @@ import { z } from "zod";
 import { readFileSync } from "node:fs";
 import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
-import { SUPPORTED_TARGETS } from "../drift/index.js";
+import { SUPPORTED_TARGETS, findProjectDir, discoverSpecFiles } from "../drift/index.js";
 import { buildPrepareResult } from "../prepare/index.js";
 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";
 
 // ── resolve project cwd ──────────────────────────────────────────────
 
@@ -67,13 +69,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 full contents
-   of every spec file (tokens, screens, flows, contracts, locales, platform overrides).
-   Use the spec_contents field as the authoritative source — do NOT paraphrase from memory.
-   Cross-reference exact token values, contract must_handle lists, and locale keys from the inline content.
-2. If the request requires spec changes, update the spec files FIRST, then call openuispec_check to validate.
-3. Only then generate or update the platform UI code based on the prepare output.
+
+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.
+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.`,
@@ -85,7 +100,7 @@ or explicitly platform-specific polish that doesn't affect shared UI semantics.`
 server.registerTool(
   "openuispec_prepare",
   {
-    description: "Build AI-ready work bundle for a target platform. REQUIRED before any UI code generation. Returns spec context, platform config, semantic changes, generation constraints, AND the full contents of every spec file inline. Use spec_contents as the authoritative source for tokens, screens, contracts, and locales — do not paraphrase from memory.",
+    description: "Build AI-ready work bundle for a target platform. REQUIRED before any UI code generation. Returns spec context, platform config, semantic changes, and generation constraints. Call openuispec_read_specs afterward to load the actual spec file contents you need for generation.",
     inputSchema: { target: targetSchema },
   },
   async ({ target }) => {
@@ -152,6 +167,42 @@ server.registerTool(
   }
 );
 
+// ── tool: openuispec_read_specs ───────────────────────────────────────
+
+server.registerTool(
+  "openuispec_read_specs",
+  {
+    description: "Read the full contents of spec files. Call after openuispec_prepare to load the actual YAML/JSON content. Pass specific file paths from the prepare output, or omit to read all spec files. Use these contents as the authoritative source — do NOT paraphrase from memory.",
+    inputSchema: {
+      paths: z
+        .array(z.string())
+        .optional()
+        .describe("Specific spec file paths to read (relative to spec root, e.g. 'screens/home.yaml'). If omitted, reads all spec files."),
+    },
+  },
+  async ({ paths }) => {
+    try {
+      const projectDir = findProjectDir(projectCwd);
+      const allFiles = discoverSpecFiles(projectDir);
+      const filesToRead = paths && paths.length > 0
+        ? allFiles.filter((f) => {
+            const rel = relative(projectDir, f);
+            return paths.some((p) => rel === p || rel.endsWith(p));
+          })
+        : allFiles;
+
+      const contents = filesToRead.map((f) => ({
+        path: relative(projectDir, f),
+        content: fsReadFileSync(f, "utf-8"),
+      }));
+
+      return toolResult(contents);
+    } catch (err) {
+      return toolError(err);
+    }
+  }
+);
+
 // ── tool: openuispec_drift ───────────────────────────────────────────
 
 server.registerTool(

package/package.json

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

package/prepare/index.ts

@@ -144,7 +144,7 @@ export interface PrepareResult {
   explanation_note?: string;
   items: PrepareItem[];
   bootstrap?: PrepareBootstrapBundle;
-  spec_contents: SpecFileContent[];
+  spec_contents?: SpecFileContent[];
   next_steps: string[];
 }
 
@@ -1057,7 +1057,7 @@ function printReport(result: PrepareResult): void {
   }
 }
 
-function buildBootstrapPrepareResult(cwd: string, target: string): PrepareResult {
+function buildBootstrapPrepareResult(cwd: string, target: string, includeContents: boolean = false): PrepareResult {
   const projectDir = findProjectDir(cwd);
   const projectName = readProjectName(projectDir);
   const outputDir = resolveOutputDir(projectDir, projectName, target);
@@ -1124,7 +1124,7 @@ function buildBootstrapPrepareResult(cwd: string, target: string): PrepareResult
     changes_available: false,
     explanation_note: "No snapshot exists yet. This is a first-time generation bundle.",
     items: [],
-    spec_contents: readAllSpecContents(projectDir),
+    ...(includeContents ? { spec_contents: readAllSpecContents(projectDir) } : {}),
     bootstrap: {
       output_exists: existsSync(outputDir),
       generation_ready: missingDecisions.length === 0 && backendContextReady && !pendingUserConfirmation,
@@ -1150,7 +1150,7 @@ function buildBootstrapPrepareResult(cwd: string, target: string): PrepareResult
   };
 }
 
-function buildUpdatePrepareResult(cwd: string, target: string): PrepareResult {
+function buildUpdatePrepareResult(cwd: string, target: string, includeContents: boolean = false): PrepareResult {
   const { projectDir, projectName, result } = loadTargetDrift(cwd, target, false, true);
   const outputDir = resolveOutputDir(projectDir, projectName, target);
   const codeRoots = suggestCodeRoots(target, outputDir);
@@ -1195,20 +1195,20 @@ function buildUpdatePrepareResult(cwd: string, target: string): PrepareResult {
     changes_available: result.explanation?.available ?? false,
     explanation_note: result.explanation?.note,
     items,
-    spec_contents: readAllSpecContents(projectDir),
+    ...(includeContents ? { spec_contents: readAllSpecContents(projectDir) } : {}),
     next_steps: nextSteps,
   };
 }
 
-export function buildPrepareResult(target: string, cwd: string = process.cwd()): PrepareResult {
+export function buildPrepareResult(target: string, cwd: string = process.cwd(), includeContents: boolean = false): PrepareResult {
   const projectDir = findProjectDir(cwd);
   const projectName = readProjectName(projectDir);
   const outputDir = resolveOutputDir(projectDir, projectName, target);
   const statePath = join(outputDir, ".openuispec-state.json");
   if (!existsSync(statePath)) {
-    return buildBootstrapPrepareResult(cwd, target);
+    return buildBootstrapPrepareResult(cwd, target, includeContents);
   }
-  return buildUpdatePrepareResult(cwd, target);
+  return buildUpdatePrepareResult(cwd, target, includeContents);
 }
 
 export function runPrepare(argv: string[]): void {