openuispec 0.2.4 → 0.2.6

package/README.md

@@ -332,6 +332,20 @@ Use the commands like this:
 - `openuispec prepare --target <t>` builds the target work bundle for either first-time generation or drift-based updates
 - `openuispec status` shows every target's snapshot state, baseline commit, and whether that target is behind the current spec, still needs a baseline, or has not been generated yet
 
+Spec access commands (also available as MCP tools):
+- `openuispec read-specs [paths...]` reads spec file contents as JSON
+- `openuispec get-screen <name>` gets a single screen spec
+- `openuispec get-contract <name> [--variant v]` gets a contract spec, optionally one variant
+- `openuispec get-tokens <category>` gets tokens for a category (color, typography, spacing, etc.)
+- `openuispec get-locale <locale> [--keys k1,k2]` gets a locale file, optionally filtered keys
+- `openuispec spec-types` lists all available spec types with descriptions
+- `openuispec spec-schema <type>` gets the full JSON schema for a spec type
+
+Screenshot commands (also available as MCP tools):
+- `openuispec screenshot --route /path [--theme dark] [--output-dir dir]` screenshots the web app
+- `openuispec screenshot-android [--project-dir path] [--screen name] [--module name]` screenshots the Android app on an emulator
+- `openuispec screenshot-ios [--project-dir path] [--screen name] [--scheme name]` screenshots the iOS app on a Simulator
+
 In first-time generation mode, `prepare` also carries target-specific generation constraints such as native localization requirements, multi-file output rules, target folder layout expectations, and a requirement to refresh current platform/framework setup knowledge before code generation.
 
 If stack choices were auto-applied via `configure-target --defaults` or `init --defaults`, they remain unconfirmed. `prepare` will block implementation readiness until the user explicitly confirms the target stack, and AI agents should ask the user to confirm or change those choices instead of silently proceeding to code generation.

package/cli/index.ts

@@ -15,11 +15,39 @@
  *   openuispec status                         Show cross-target baseline/drift status
  *   openuispec check --target <t> [--json]    Composite validation + prepare readiness
  *   openuispec validate [group...]            Validate spec files against schemas
+ *   openuispec read-specs [paths...]          Read spec file contents
+ *   openuispec get-screen <name>              Get a single screen spec
+ *   openuispec get-contract <name> [--variant v] Get a contract spec
+ *   openuispec get-tokens <category>          Get tokens for a category
+ *   openuispec get-locale <locale> [--keys k1,k2] Get a locale file
+ *   openuispec spec-types                     List available spec types
+ *   openuispec spec-schema <type>             Get JSON schema for a spec type
+ *   openuispec screenshot [--route /path]     Screenshot the web app
+ *   openuispec screenshot-android [opts]      Screenshot Android app on emulator
+ *   openuispec screenshot-ios [opts]          Screenshot iOS app on simulator
  */
 
 import { init, updateRules, extractRulesVersion, getPackageVersion } from "./init.js";
-import { join } from "node:path";
-import { existsSync, readFileSync } from "node:fs";
+import { join, dirname, relative, resolve } from "node:path";
+import { existsSync, readFileSync, readdirSync, writeFileSync, mkdirSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+
+// ── arg parsing helpers ──────────────────────────────────────────────
+
+function getFlag(argv: string[], name: string): boolean {
+  return argv.includes(name);
+}
+
+function getOption(argv: string[], name: string): string | null {
+  const idx = argv.indexOf(name);
+  return idx !== -1 && argv[idx + 1] ? argv[idx + 1] : null;
+}
+
+function getPositional(argv: string[], startIdx = 0): string[] {
+  return argv.slice(startIdx).filter((a) => !a.startsWith("--"));
+}
+
+// ── rules version check ─────────────────────────────────────────────
 
 function checkRulesVersion(): void {
   const cwd = process.cwd();
@@ -45,8 +73,35 @@ function checkRulesVersion(): void {
   }
 }
 
+// ── spec helpers (shared with MCP server) ────────────────────────────
+
+function resolveSpecDir(projectDir: string, manifest: any, key: string): string {
+  return resolve(projectDir, manifest.includes?.[key] ?? `./${key}/`);
+}
+
+const SCHEMA_CATALOG: Record<string, { file: string; title: string; description: string }> = {
+  manifest:         { file: "openuispec.schema.json",            title: "Root Manifest",    description: "Root manifest (openuispec.yaml)" },
+  screen:           { file: "screen.schema.json",                title: "Screen",           description: "Screen composition: layout, sections, navigation" },
+  flow:             { file: "flow.schema.json",                  title: "Flow",             description: "Navigation flow definitions" },
+  platform:         { file: "platform.schema.json",              title: "Platform",         description: "Platform-specific generation config" },
+  contract:         { file: "contract.schema.json",              title: "Contract",         description: "Built-in UI contract definitions" },
+  "custom-contract":{ file: "custom-contract.schema.json",       title: "Custom Contract",  description: "User-defined UI contract definitions (x_ prefixed)" },
+  locale:           { file: "locale.schema.json",                title: "Locale",           description: "Locale translation files" },
+  "tokens/color":       { file: "tokens/color.schema.json",       title: "Color Tokens",       description: "Color tokens" },
+  "tokens/typography":  { file: "tokens/typography.schema.json",   title: "Typography Tokens",  description: "Typography tokens" },
+  "tokens/spacing":     { file: "tokens/spacing.schema.json",     title: "Spacing Tokens",     description: "Spacing tokens" },
+  "tokens/elevation":   { file: "tokens/elevation.schema.json",   title: "Elevation Tokens",   description: "Elevation tokens" },
+  "tokens/motion":      { file: "tokens/motion.schema.json",      title: "Motion Tokens",      description: "Motion tokens" },
+  "tokens/layout":      { file: "tokens/layout.schema.json",      title: "Layout Tokens",      description: "Layout tokens" },
+  "tokens/themes":      { file: "tokens/themes.schema.json",      title: "Theme Tokens",       description: "Theme definitions" },
+  "tokens/icons":       { file: "tokens/icons.schema.json",       title: "Icon Tokens",        description: "Icon tokens" },
+};
+
+// ── main ─────────────────────────────────────────────────────────────
+
 async function main(): Promise<void> {
   const [command, ...rest] = process.argv.slice(2);
+  const cwd = process.cwd();
 
   switch (command) {
     case "init":
@@ -100,35 +155,252 @@ async function main(): Promise<void> {
       break;
     }
 
+    // ── spec getters ───────────────────────────────────────────────
+
+    case "read-specs": {
+      const { findProjectDir, discoverSpecFiles } = await import("../drift/index.js");
+      const projectDir = findProjectDir(cwd);
+      const allFiles = discoverSpecFiles(projectDir);
+      const paths = getPositional(rest);
+
+      const filesToRead = 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: readFileSync(f, "utf-8"),
+      }));
+      console.log(JSON.stringify(contents, null, 2));
+      break;
+    }
+
+    case "get-screen": {
+      const name = rest[0];
+      if (!name) { console.error("Usage: openuispec get-screen <name>"); process.exit(1); }
+      const { findProjectDir } = await import("../drift/index.js");
+      const YAML = (await import("yaml")).default;
+      const projectDir = findProjectDir(cwd);
+      const manifest = YAML.parse(readFileSync(join(projectDir, "openuispec.yaml"), "utf-8"));
+      const screensDir = resolveSpecDir(projectDir, manifest, "screens");
+      const filePath = join(screensDir, `${name}.yaml`);
+      if (!existsSync(filePath)) { console.error(`Screen "${name}" not found at ${filePath}`); process.exit(1); }
+      console.log(readFileSync(filePath, "utf-8"));
+      break;
+    }
+
+    case "get-contract": {
+      const name = rest[0];
+      if (!name) { console.error("Usage: openuispec get-contract <name> [--variant v]"); process.exit(1); }
+      const variant = getOption(rest, "--variant");
+      const { findProjectDir } = await import("../drift/index.js");
+      const YAML = (await import("yaml")).default;
+      const projectDir = findProjectDir(cwd);
+      const manifest = YAML.parse(readFileSync(join(projectDir, "openuispec.yaml"), "utf-8"));
+      const contractsDir = resolveSpecDir(projectDir, manifest, "contracts");
+
+      if (!existsSync(contractsDir)) { console.error(`Contracts directory not found: ${contractsDir}`); process.exit(1); }
+
+      let found = false;
+      for (const file of readdirSync(contractsDir).filter(f => f.endsWith(".yaml")).sort()) {
+        const filePath = join(contractsDir, file);
+        const raw = readFileSync(filePath, "utf-8");
+        const content = YAML.parse(raw);
+        const contractName = Object.keys(content)[0];
+        if (contractName !== name) continue;
+        found = true;
+
+        if (variant) {
+          const variantDef = content[contractName]?.variants?.[variant];
+          if (!variantDef) {
+            const available = Object.keys(content[contractName]?.variants ?? {}).join(", ");
+            console.error(`Variant "${variant}" not found. Available: ${available}`);
+            process.exit(1);
+          }
+          console.log(JSON.stringify({ name, variant, definition: variantDef }, null, 2));
+        } else {
+          console.log(raw);
+        }
+        break;
+      }
+      if (!found) { console.error(`Contract "${name}" not found in ${contractsDir}`); process.exit(1); }
+      break;
+    }
+
+    case "get-tokens": {
+      const category = rest[0];
+      if (!category) { console.error("Usage: openuispec get-tokens <category>"); process.exit(1); }
+      const { findProjectDir } = await import("../drift/index.js");
+      const YAML = (await import("yaml")).default;
+      const projectDir = findProjectDir(cwd);
+      const manifest = YAML.parse(readFileSync(join(projectDir, "openuispec.yaml"), "utf-8"));
+      const tokensDir = resolveSpecDir(projectDir, manifest, "tokens");
+
+      for (const ext of [".yaml", ".yml"]) {
+        const filePath = join(tokensDir, `${category}${ext}`);
+        if (existsSync(filePath)) { console.log(readFileSync(filePath, "utf-8")); process.exit(0); }
+      }
+
+      const available = readdirSync(tokensDir).filter(f => f.endsWith(".yaml") || f.endsWith(".yml")).map(f => f.replace(/\.ya?ml$/, ""));
+      console.error(`Token category "${category}" not found. Available: ${available.join(", ")}`);
+      process.exit(1);
+      break;
+    }
+
+    case "get-locale": {
+      const locale = rest[0];
+      if (!locale) { console.error("Usage: openuispec get-locale <locale> [--keys k1,k2,k3]"); process.exit(1); }
+      const keysStr = getOption(rest, "--keys");
+      const keys = keysStr ? keysStr.split(",").map(k => k.trim()) : null;
+      const { findProjectDir } = await import("../drift/index.js");
+      const YAML = (await import("yaml")).default;
+      const projectDir = findProjectDir(cwd);
+      const manifest = YAML.parse(readFileSync(join(projectDir, "openuispec.yaml"), "utf-8"));
+      const localesDir = resolveSpecDir(projectDir, manifest, "locales");
+      const filePath = join(localesDir, `${locale}.json`);
+
+      if (!existsSync(filePath)) {
+        const available = existsSync(localesDir)
+          ? readdirSync(localesDir).filter(f => f.endsWith(".json")).map(f => f.replace(".json", ""))
+          : [];
+        console.error(`Locale "${locale}" not found. Available: ${available.join(", ")}`);
+        process.exit(1);
+      }
+
+      const content = JSON.parse(readFileSync(filePath, "utf-8"));
+      if (keys) {
+        const filtered: Record<string, unknown> = {};
+        for (const key of keys) { if (key in content) filtered[key] = content[key]; }
+        console.log(JSON.stringify(filtered, null, 2));
+      } else {
+        console.log(JSON.stringify(content, null, 2));
+      }
+      break;
+    }
+
+    // ── schema reference ───────────────────────────────────────────
+
+    case "spec-types": {
+      const types = Object.entries(SCHEMA_CATALOG).map(([type, info]) => ({
+        type, title: info.title, description: info.description,
+      }));
+      console.log(JSON.stringify(types, null, 2));
+      break;
+    }
+
+    case "spec-schema": {
+      const type = rest[0];
+      if (!type) { console.error("Usage: openuispec spec-schema <type>\nRun `openuispec spec-types` to list types."); process.exit(1); }
+      const entry = SCHEMA_CATALOG[type];
+      if (!entry) { console.error(`Unknown spec type "${type}". Run \`openuispec spec-types\` to list types.`); process.exit(1); }
+      const __dirname = dirname(fileURLToPath(import.meta.url));
+      const schemaPath = join(__dirname, "..", "schema", entry.file);
+      console.log(readFileSync(schemaPath, "utf-8"));
+      break;
+    }
+
+    // ── screenshot tools ───────────────────────────────────────────
+
+    case "screenshot": {
+      const { takeScreenshot } = await import("../mcp-server/screenshot.js");
+      const result = await takeScreenshot(cwd, {
+        route: getOption(rest, "--route") ?? "/",
+        viewport: {
+          width: parseInt(getOption(rest, "--width") ?? "1280"),
+          height: parseInt(getOption(rest, "--height") ?? "800"),
+        },
+        theme: getOption(rest, "--theme") as "light" | "dark" | undefined,
+        wait_for: parseInt(getOption(rest, "--wait-for") ?? "1000"),
+        full_page: getFlag(rest, "--full-page"),
+        selector: getOption(rest, "--selector") ?? undefined,
+        output_dir: getOption(rest, "--output-dir") ?? undefined,
+      });
+      printScreenshotResult(result);
+      break;
+    }
+
+    case "screenshot-android": {
+      const { takeAndroidScreenshot } = await import("../mcp-server/screenshot-android.js");
+      const result = await takeAndroidScreenshot(cwd, {
+        screen: getOption(rest, "--screen") ?? undefined,
+        route: getOption(rest, "--route") ?? undefined,
+        nav: getOption(rest, "--nav")?.split(",") ?? undefined,
+        theme: getOption(rest, "--theme") as "light" | "dark" | undefined,
+        wait_for: parseInt(getOption(rest, "--wait-for") ?? "3000"),
+        output_dir: getOption(rest, "--output-dir") ?? undefined,
+        project_dir: getOption(rest, "--project-dir") ?? undefined,
+        module: getOption(rest, "--module") ?? undefined,
+      });
+      printScreenshotResult(result);
+      break;
+    }
+
+    case "screenshot-ios": {
+      const { takeIOSScreenshot } = await import("../mcp-server/screenshot-ios.js");
+      const result = await takeIOSScreenshot(cwd, {
+        screen: getOption(rest, "--screen") ?? undefined,
+        device: getOption(rest, "--device") ?? undefined,
+        nav: getOption(rest, "--nav")?.split(",") ?? undefined,
+        theme: getOption(rest, "--theme") as "light" | "dark" | undefined,
+        wait_for: parseInt(getOption(rest, "--wait-for") ?? "3000"),
+        output_dir: getOption(rest, "--output-dir") ?? undefined,
+        project_dir: getOption(rest, "--project-dir") ?? undefined,
+        scheme: getOption(rest, "--scheme") ?? undefined,
+        bundle_id: getOption(rest, "--bundle-id") ?? undefined,
+      });
+      printScreenshotResult(result);
+      break;
+    }
+
+    // ── help ────────────────────────────────────────────────────────
+
     case undefined:
     case "--help":
     case "-h":
       console.log(`
-OpenUISpec CLI v0.1
+OpenUISpec CLI v${getPackageVersion()}
 
 Usage:
   openuispec init                           Create a new spec project
   openuispec init --defaults                Scaffold non-interactively with unconfirmed defaults
-  openuispec init --list-options            Print init prompt options as JSON
   openuispec init --no-configure-targets    Skip target stack setup during init
   openuispec update-rules                   Update AI rules to match installed version
-  openuispec configure-target <t> [--defaults] Configure target stack; --defaults stays unconfirmed
-  openuispec configure-target <t> --set k=v    Set specific stack values (confirmed)
-  openuispec configure-target <t> --list-options Print target stack prompt options as JSON
+  openuispec configure-target <t> [--defaults]  Configure target stack
+  openuispec configure-target <t> --set k=v     Set specific stack values (confirmed)
+
+Workflow:
+  openuispec status                         Show cross-target baseline/drift status
   openuispec drift [--target <t>]           Check for spec drift
   openuispec drift --snapshot --target <t>  Snapshot current state + git baseline
   openuispec drift --target <t> --explain   Explain semantic changes since baseline
   openuispec prepare --target <t>           Build the target work bundle
-  openuispec status                         Show cross-target baseline/drift status
   openuispec check --target <t> [--json]    Composite validation + prepare readiness
   openuispec validate [group...] [--json]   Validate spec files
-  openuispec validate semantic --json       Semantic validation as JSON
-  openuispec mcp                           Start MCP server (stdio transport)
 
-Validate groups: manifest, tokens, screens, flows, platform, locales, contracts, semantic
+Spec access:
+  openuispec read-specs [paths...]          Read spec file contents as JSON
+  openuispec get-screen <name>              Get a single screen spec (YAML)
+  openuispec get-contract <name> [--variant v]  Get a contract spec
+  openuispec get-tokens <category>          Get tokens for a category (YAML)
+  openuispec get-locale <locale> [--keys k1,k2] Get a locale file (JSON)
+  openuispec spec-types                     List available spec types
+  openuispec spec-schema <type>             Get full JSON schema for a spec type
 
-Exit codes: 0 = success, 1 = missing config/usage error, 2 = validation failure
+Screenshots:
+  openuispec screenshot [--route /path] [--theme light|dark] [--output-dir dir]
+  openuispec screenshot-android [--screen name] [--project-dir path] [--module name]
+      [--route deeplink] [--nav Step1,Step2] [--theme light|dark] [--output-dir dir]
+  openuispec screenshot-ios [--screen name] [--project-dir path] [--scheme name]
+      [--bundle-id id] [--device name] [--nav Step1,Step2] [--theme light|dark]
+
+Server:
+  openuispec mcp                            Start MCP server (stdio transport)
 
+Validate groups: manifest, tokens, screens, flows, platform, locales, contracts, semantic
+Exit codes: 0 = success, 1 = missing config/usage error, 2 = validation failure
 Docs: https://openuispec.rsteam.uz
 `);
       break;
@@ -140,6 +412,25 @@ Docs: https://openuispec.rsteam.uz
   }
 }
 
+// ── screenshot result printer ────────────────────────────────────────
+
+function printScreenshotResult(result: { content: Array<{ type: string; text?: string; data?: string; mimeType?: string }>; isError?: boolean }): void {
+  if (result.isError) {
+    for (const item of result.content) {
+      if (item.type === "text") console.error(item.text);
+    }
+    process.exit(1);
+  }
+  for (const item of result.content) {
+    if (item.type === "text") console.log(item.text);
+    if (item.type === "image" && item.data) {
+      const outFile = `screenshot-${Date.now()}.png`;
+      writeFileSync(outFile, Buffer.from(item.data, "base64"));
+      console.log(`Screenshot saved: ${outFile}`);
+    }
+  }
+}
+
 main().catch((err) => {
   console.error(err instanceof Error ? err.message : String(err));
   process.exit(1);

package/cli/init.ts

@@ -282,13 +282,14 @@ When the openuispec MCP server is configured, AI assistants should use these too
 | \`openuispec_get_contract\` | Get a single contract spec, optionally filtered to one variant. |
 | \`openuispec_get_tokens\` | Get tokens for a specific category (color, typography, spacing, etc.). |
 | \`openuispec_get_locale\` | Get a single locale file, optionally filtered to specific keys. |
-| \`openuispec_screenshot\` | Take a screenshot of the generated web app at a route (requires \`puppeteer\`). |
-| \`openuispec_screenshot_android\` | Take screenshots of the generated Android app on an emulator (requires running emulator). |
-| \`openuispec_screenshot_ios\` | Take screenshots of the generated iOS app using swift-snapshot-testing (requires Xcode + Simulator). |
+| \`openuispec_screenshot\` | Screenshot the web app at a route via headless browser (requires \`puppeteer\`). |
+| \`openuispec_screenshot_android\` | Screenshot Android app on emulator — works with any project via \`project_dir\`. |
+| \`openuispec_screenshot_ios\` | Screenshot iOS app on Simulator via XCUITest — works with any project via \`project_dir\`. |
 
 ## CLI commands
 
 \`\`\`bash
+# Workflow
 openuispec validate             # Validate spec files against schemas
 openuispec validate semantic    # Run semantic cross-reference linting
 openuispec configure-target ${targets[0]} [--defaults] # Configure target stack; --defaults stays unconfirmed
@@ -296,6 +297,20 @@ openuispec status               # Show cross-target baseline/drift status
 openuispec drift --target ${targets[0]} --explain   # Explain semantic spec drift
 openuispec prepare --target ${targets[0]}          # Build the target work bundle
 openuispec drift --snapshot --target ${targets[0]} # Snapshot current state + git baseline after target output exists
+
+# Spec access
+openuispec read-specs [paths...]          # Read spec file contents as JSON
+openuispec get-screen <name>              # Get a single screen spec
+openuispec get-contract <name> [--variant v] # Get a contract spec
+openuispec get-tokens <category>          # Get tokens for a category
+openuispec get-locale <locale> [--keys k1,k2] # Get a locale file
+openuispec spec-types                     # List available spec types
+openuispec spec-schema <type>             # Get JSON schema for a spec type
+
+# Screenshots
+openuispec screenshot --route /home --theme dark --output-dir screenshots
+openuispec screenshot-android --screen home --project-dir /path/to/android
+openuispec screenshot-ios --screen home --project-dir /path/to/ios --scheme MyApp
 \`\`\`
 
 The target work bundle has two modes:
@@ -376,6 +391,16 @@ If MCP tools are not available, use these CLI commands with \`--json\` flag:
 - \`openuispec status --json\` — cross-target status
 - \`openuispec drift --target <t> --explain --json\` — semantic drift
 - \`openuispec validate [group...] --json\` — schema validation
+- \`openuispec read-specs [paths...]\` — read spec file contents
+- \`openuispec get-screen <name>\` — get a single screen spec
+- \`openuispec get-contract <name> [--variant v]\` — get a contract spec
+- \`openuispec get-tokens <category>\` — get tokens for a category
+- \`openuispec get-locale <locale> [--keys k1,k2]\` — get a locale file
+- \`openuispec spec-types\` — list available spec types
+- \`openuispec spec-schema <type>\` — get JSON schema for a spec type
+- \`openuispec screenshot --route /path\` — screenshot the web app
+- \`openuispec screenshot-android [--project-dir path]\` — screenshot Android app
+- \`openuispec screenshot-ios [--project-dir path]\` — screenshot iOS app
 
 ### Other CLI commands
 - \`openuispec init\` — scaffold a new spec project

package/examples/social-app/AGENTS.md

@@ -1,5 +1,5 @@
 <!-- openuispec-rules-start -->
-<!-- openuispec-rules-version: 0.2.3 -->
+<!-- openuispec-rules-version: 0.2.4 -->
 # OpenUISpec — AI Assistant Rules
 # ================================
 # This project uses OpenUISpec to define UI as a semantic spec.
@@ -60,6 +60,16 @@ If MCP tools are not available, use these CLI commands with `--json` flag:
 - `openuispec status --json` — cross-target status
 - `openuispec drift --target <t> --explain --json` — semantic drift
 - `openuispec validate [group...] --json` — schema validation
+- `openuispec read-specs [paths...]` — read spec file contents
+- `openuispec get-screen <name>` — get a single screen spec
+- `openuispec get-contract <name> [--variant v]` — get a contract spec
+- `openuispec get-tokens <category>` — get tokens for a category
+- `openuispec get-locale <locale> [--keys k1,k2]` — get a locale file
+- `openuispec spec-types` — list available spec types
+- `openuispec spec-schema <type>` — get JSON schema for a spec type
+- `openuispec screenshot --route /path` — screenshot the web app
+- `openuispec screenshot-android [--project-dir path]` — screenshot Android app
+- `openuispec screenshot-ios [--project-dir path]` — screenshot iOS app
 
 ### Other CLI commands
 - `openuispec init` — scaffold a new spec project

package/examples/social-app/CLAUDE.md

@@ -1,5 +1,5 @@
 <!-- openuispec-rules-start -->
-<!-- openuispec-rules-version: 0.2.3 -->
+<!-- openuispec-rules-version: 0.2.4 -->
 # OpenUISpec — AI Assistant Rules
 # ================================
 # This project uses OpenUISpec to define UI as a semantic spec.
@@ -60,6 +60,16 @@ If MCP tools are not available, use these CLI commands with `--json` flag:
 - `openuispec status --json` — cross-target status
 - `openuispec drift --target <t> --explain --json` — semantic drift
 - `openuispec validate [group...] --json` — schema validation
+- `openuispec read-specs [paths...]` — read spec file contents
+- `openuispec get-screen <name>` — get a single screen spec
+- `openuispec get-contract <name> [--variant v]` — get a contract spec
+- `openuispec get-tokens <category>` — get tokens for a category
+- `openuispec get-locale <locale> [--keys k1,k2]` — get a locale file
+- `openuispec spec-types` — list available spec types
+- `openuispec spec-schema <type>` — get JSON schema for a spec type
+- `openuispec screenshot --route /path` — screenshot the web app
+- `openuispec screenshot-android [--project-dir path]` — screenshot Android app
+- `openuispec screenshot-ios [--project-dir path]` — screenshot iOS app
 
 ### Other CLI commands
 - `openuispec init` — scaffold a new spec project

package/examples/social-app/package.json

@@ -4,9 +4,10 @@
   "version": "0.0.0",
   "description": "OpenUISpec test project wired to the local ../openuispec checkout",
   "scripts": {
-    "openuispec": "node --import ./../openuispec/node_modules/tsx/dist/loader.mjs ./../openuispec/cli/index.ts",
-    "validate": "node --import ./../openuispec/node_modules/tsx/dist/loader.mjs ./../openuispec/cli/index.ts validate",
-    "validate:semantic": "node --import ./../openuispec/node_modules/tsx/dist/loader.mjs ./../openuispec/cli/index.ts validate semantic",
-    "status": "node --import ./../openuispec/node_modules/tsx/dist/loader.mjs ./../openuispec/cli/index.ts status"
+    "openuispec": "node --import ./../../node_modules/tsx/dist/loader.mjs ./../../cli/index.ts",
+    "validate": "node --import ./../../node_modules/tsx/dist/loader.mjs ./../../cli/index.ts validate",
+    "validate:semantic": "node --import ./../../node_modules/tsx/dist/loader.mjs ./../../cli/index.ts validate semantic",
+    "status": "node --import ./../../node_modules/tsx/dist/loader.mjs ./../../cli/index.ts status",
+    "screenshots:web": "node --import ./../../node_modules/tsx/dist/loader.mjs ./take-web-screenshots.ts"
   }
 }

package/examples/social-app/take-web-screenshots.ts

@@ -0,0 +1,97 @@
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { Client } from "@modelcontextprotocol/sdk/client";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+
+type ImageContent = {
+  type: "image";
+  data: string;
+  mimeType: string;
+};
+
+type TextContent = {
+  type: "text";
+  text: string;
+};
+
+type WebCapture = {
+  name: string;
+  route: string;
+};
+
+const OUTPUT_DIR = resolve("generated/web/social-app/screenshots");
+const VIEWPORT = { width: 1366, height: 900 };
+const captures: WebCapture[] = [
+  { name: "home", route: "/home" },
+  { name: "discover", route: "/discover" },
+  { name: "notifications", route: "/notifications" },
+  { name: "messages", route: "/messages" },
+  { name: "profile", route: "/profile" },
+  { name: "profile-edit", route: "/profile/edit" },
+  { name: "settings", route: "/settings" },
+  { name: "create", route: "/create" },
+  { name: "search-editorial-ui-posts", route: "/search?query=Editorial%20UI&tab=posts" },
+  { name: "post-post-1", route: "/posts/post-1" },
+  { name: "user-lina", route: "/u/user-lina" },
+  { name: "chat-conversation-1", route: "/chat/conversation-1" },
+];
+
+function getImageData(content: Array<ImageContent | TextContent>): string {
+  const image = content.find((item): item is ImageContent => item.type === "image");
+  if (!image) {
+    throw new Error("Screenshot tool did not return image data.");
+  }
+  return image.data;
+}
+
+function getText(content: Array<ImageContent | TextContent>): string | null {
+  const text = content.find((item): item is TextContent => item.type === "text");
+  return text?.text ?? null;
+}
+
+async function main() {
+  mkdirSync(OUTPUT_DIR, { recursive: true });
+
+  const transport = new StdioClientTransport({
+    command: "npm",
+    args: ["run", "openuispec", "--", "mcp"],
+    cwd: process.cwd(),
+    stderr: "inherit",
+  });
+
+  const client = new Client(
+    { name: "social-app-screenshot-runner", version: "0.1.0" },
+    { capabilities: {} },
+  );
+
+  await client.connect(transport);
+
+  try {
+    for (const capture of captures) {
+      const result = await client.callTool({
+        name: "openuispec_screenshot",
+        arguments: {
+          route: capture.route,
+          viewport: VIEWPORT,
+          wait_for: 1200,
+          full_page: true,
+        },
+      });
+
+      if (result.isError) {
+        throw new Error(`Failed to capture ${capture.route}: ${getText(result.content as Array<ImageContent | TextContent>) ?? "Unknown tool error"}`);
+      }
+
+      const outputPath = join(OUTPUT_DIR, `${capture.name}.png`);
+      writeFileSync(outputPath, Buffer.from(getImageData(result.content as Array<ImageContent | TextContent>), "base64"));
+      console.log(`saved ${outputPath}`);
+    }
+  } finally {
+    await transport.close();
+  }
+}
+
+main().catch((error) => {
+  console.error(error instanceof Error ? error.message : error);
+  process.exitCode = 1;
+});

package/examples/taskflow/.codex/config.toml

@@ -0,0 +1,4 @@
+
+[mcp_servers.openuispec]
+command = "openuispec"
+args = ["mcp"]

package/examples/taskflow/.mcp.json

@@ -0,0 +1,10 @@
+{
+  "mcpServers": {
+    "openuispec": {
+      "command": "openuispec",
+      "args": [
+        "mcp"
+      ]
+    }
+  }
+}