openuispec 0.1.39 → 0.1.41

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 ──────────────────────────────────────────────
 
@@ -68,9 +70,13 @@ 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, and generation constraints you must follow.
-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.
+   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.
+   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.
 
 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.`,
@@ -82,7 +88,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, and generation constraints.",
+    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 }) => {
@@ -149,6 +155,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.39",
+  "version": "0.1.41",
   "license": "MIT",
   "type": "module",
   "description": "A semantic UI specification format for AI-native, platform-native app development",

package/prepare/index.ts

@@ -116,6 +116,12 @@ interface PrepareBootstrapBundle {
   reference_examples: string[];
 }
 
+interface SpecFileContent {
+  path: string;
+  category: string;
+  content: string;
+}
+
 export interface PrepareResult {
   mode: "bootstrap" | "update";
   project: string;
@@ -138,6 +144,7 @@ export interface PrepareResult {
   explanation_note?: string;
   items: PrepareItem[];
   bootstrap?: PrepareBootstrapBundle;
+  spec_contents?: SpecFileContent[];
   next_steps: string[];
 }
 
@@ -842,6 +849,17 @@ function generationWarnings(target: string, platformConfig: PreparePlatformConfi
   return warnings;
 }
 
+function readAllSpecContents(projectDir: string): SpecFileContent[] {
+  return discoverSpecFiles(projectDir).map((filePath) => {
+    const relPath = relative(projectDir, filePath);
+    return {
+      path: relPath,
+      category: categorizeSpecFile(relPath),
+      content: readFileSync(filePath, "utf-8"),
+    };
+  });
+}
+
 function bootstrapSpecFiles(projectDir: string, target: string): BootstrapSpecFile[] {
   return discoverSpecFiles(projectDir)
     .map((filePath) => {
@@ -1039,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);
@@ -1106,6 +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: [],
+    ...(includeContents ? { spec_contents: readAllSpecContents(projectDir) } : {}),
     bootstrap: {
       output_exists: existsSync(outputDir),
       generation_ready: missingDecisions.length === 0 && backendContextReady && !pendingUserConfirmation,
@@ -1131,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);
@@ -1176,19 +1195,20 @@ function buildUpdatePrepareResult(cwd: string, target: string): PrepareResult {
     changes_available: result.explanation?.available ?? false,
     explanation_note: result.explanation?.note,
     items,
+    ...(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 {