openuispec 0.1.0 → 0.1.2

package/README.md

@@ -17,45 +17,11 @@ The result: each platform feels native, but every app stays consistent because i
 
 ## How it works
 
-```
-┌─────────────────────────┐
-│   OpenUISpec (YAML)     │  ← Single source of truth
-│   Tokens + Contracts    │
-│   Screens + Flows       │
-└────────┬────────────────┘
-         │
-    AI Generation Layer
-         │
-    ┌────┴─────┬──────────┐
-    ▼          ▼          ▼
- SwiftUI   Compose     React
-  (iOS)   (Android)    (Web)
-```
+![How OpenUISpec works](docs/images/how-it-works.jpg)
 
 ## Workflows
 
-OpenUISpec supports two complementary workflows — one for designing new features, another for day-to-day development.
-
-```
-DESIGN MODE (spec-first)              DEVELOPMENT MODE (platform-first)
-For new features & design changes     For iteration, tweaks & bug fixes
-
-  Spec (YAML)                           Xcode / Android Studio
-      │                                        │
-      ▼                                        ▼
-  AI generates native code              Developer edits native code
-      │                                        │
-      ▼                                        ▼
-  Refine per platform               AI syncs changes back to spec
-                                               │
-                                               ▼
-                                    Other platforms see spec diff
-                                    and update their code
-```
-
-**Design mode** is the starting point: you write (or generate) spec YAML, then AI produces native SwiftUI, Compose, or React code. This is how new screens, flows, and design system changes enter the project.
-
-**Development mode** is where most time is spent: a developer works in their IDE with live preview, iterating on layout, interactions, and fixes. When they're done, AI reads the code changes and updates the spec YAML. Other platform teams see the spec diff in version control and propagate the changes to their codebase. The spec acts as a shared sync layer — a UI changelog that keeps all platforms consistent.
+![OpenUISpec workflows](docs/images/workflows.png)
 
 ## Key concepts
 

package/cli/index.ts

@@ -3,26 +3,33 @@
  * OpenUISpec CLI
  *
  * Usage:
- *   openuispec init          # scaffold a new spec project
- *   openuispec drift         # check for spec drift (all targets)
- *   openuispec drift --target ios
- *   openuispec drift --snapshot --target ios
+ *   openuispec init                           Create a new spec project
+ *   openuispec drift [--target <t>]           Check for spec drift
+ *   openuispec drift --snapshot --target <t>  Snapshot current state
+ *   openuispec validate [group...]            Validate spec files against schemas
  */
 
 import { init } from "./init.js";
 
 async function main(): Promise<void> {
-  const [command] = process.argv.slice(2);
+  const [command, ...rest] = process.argv.slice(2);
 
   switch (command) {
     case "init":
       await init();
       break;
 
-    case "drift":
-      console.error("drift command coming soon — use npm run drift for now");
-      process.exit(1);
+    case "drift": {
+      const { runDrift } = await import("../drift/index.js");
+      runDrift(rest);
+      break;
+    }
+
+    case "validate": {
+      const { runValidate } = await import("../schema/validate.js");
+      runValidate(rest);
       break;
+    }
 
     case undefined:
     case "--help":
@@ -34,8 +41,11 @@ Usage:
   openuispec init                           Create a new spec project
   openuispec drift [--target <t>]           Check for spec drift
   openuispec drift --snapshot --target <t>  Snapshot current state
+  openuispec validate [group...]            Validate spec files
+
+Validate groups: manifest, tokens, screens, flows, platform, locales, custom_contracts
 
-Learn more: https://github.com/anthropics/openuispec
+Learn more: https://github.com/rsktash/openuispec
 `);
       break;
 

package/cli/init.ts

@@ -223,6 +223,18 @@ function aiRulesBlock(specDir: string, targets: string[]): string {
 2. Targets in this project: ${targetList}.
 3. Run \`openuispec drift\` to verify no untracked drift remains.
 
+## Screen and flow status
+Screens and flows have a \`status\` field that controls drift tracking:
+- \`stub\` — placeholder, not yet specced. Drift detection skips these.
+- \`draft\` — in progress, actively being specced. Tracked by drift.
+- \`ready\` — fully specified (default if omitted). Tracked by drift.
+
+When adopting OpenUISpec in an existing project:
+1. Create spec files for existing screens as \`status: stub\` initially.
+2. When speccing a screen from existing code, change status to \`draft\`.
+3. Once the spec is complete and reviewed, change to \`ready\` (or remove the field).
+4. Only \`draft\` and \`ready\` screens trigger drift failures in CI.
+
 ## Spec file conventions
 - Tokens (colors, typography, spacing, motion, icons) live in \`${specDir}/tokens/\`.
 - Contracts (UI component definitions) live in \`${specDir}/contracts/\`.

package/drift/index.ts

@@ -4,33 +4,35 @@
  *
  * Tracks spec changes via content hashes so you know what to
  * re-generate or review after editing spec files.
+ * Stub screens/flows are reported separately and don't fail CI.
  *
  * Usage:
- *   npm run drift -- --target ios           # check drift for ios
- *   npm run drift                           # check all targets with snapshots
- *   npm run drift -- --snapshot --target ios # snapshot for ios
- *   npm run drift -- --json --target ios    # machine-readable output
+ *   openuispec drift --target ios           # check drift for ios
+ *   openuispec drift                        # check all targets with snapshots
+ *   openuispec drift --snapshot --target ios # snapshot for ios
+ *   openuispec drift --json --target ios    # machine-readable output
+ *   openuispec drift --target ios --all     # include stubs in drift count
  */
 
-import { readFileSync, writeFileSync, readdirSync, existsSync, mkdirSync } from "node:fs";
+import { readFileSync, writeFileSync, readdirSync, existsSync } from "node:fs";
 import { resolve, join, relative, basename, dirname } from "node:path";
-import { fileURLToPath } from "node:url";
 import { createHash } from "node:crypto";
 import YAML from "yaml";
 
-const __dirname = fileURLToPath(new URL(".", import.meta.url));
-const REPO_ROOT = resolve(__dirname, "..");
-const PROJECT_DIR = resolve(REPO_ROOT, "examples", "taskflow");
-const GENERATED_DIR = resolve(REPO_ROOT, "generated");
 const STATE_FILE = ".openuispec-state.json";
 
 // ── types ─────────────────────────────────────────────────────────────
 
+interface FileEntry {
+  hash: string;
+  status: string;
+}
+
 interface StateFile {
   spec_version: string;
   snapshot_at: string;
   target: string;
-  files: Record<string, string>;
+  files: Record<string, FileEntry>;
 }
 
 interface DriftResult {
@@ -59,6 +61,29 @@ function hashFile(filePath: string): string {
   return `sha256:${hash}`;
 }
 
+/** Read the status field from a screen or flow YAML file. */
+function readStatus(filePath: string): string {
+  try {
+    const doc = YAML.parse(readFileSync(filePath, "utf-8"));
+    if (doc && typeof doc === "object") {
+      const rootKey = Object.keys(doc)[0];
+      const def = doc[rootKey];
+      if (def && typeof def.status === "string") {
+        return def.status;
+      }
+    }
+  } catch {
+    // If we can't parse, treat as ready
+  }
+  return "ready";
+}
+
+/** Returns true if a file is a screen or flow (has status semantics). */
+function hasStatusSemantics(relPath: string): boolean {
+  const dir = dirname(relPath);
+  return dir === "screens" || dir === "flows";
+}
+
 function discoverSpecFiles(projectDir: string): string[] {
   const manifest = join(projectDir, "openuispec.yaml");
   if (!existsSync(manifest)) {
@@ -70,32 +95,21 @@ function discoverSpecFiles(projectDir: string): string[] {
   const includes = doc.includes ?? {};
   const files: string[] = [manifest];
 
-  // Tokens
   if (includes.tokens) {
     files.push(...listFiles(resolve(projectDir, includes.tokens), ".yaml"));
   }
-
-  // Screens
   if (includes.screens) {
     files.push(...listFiles(resolve(projectDir, includes.screens), ".yaml"));
   }
-
-  // Flows
   if (includes.flows) {
     files.push(...listFiles(resolve(projectDir, includes.flows), ".yaml"));
   }
-
-  // Platform
   if (includes.platform) {
     files.push(...listFiles(resolve(projectDir, includes.platform), ".yaml"));
   }
-
-  // Locales
   if (includes.locales) {
     files.push(...listFiles(resolve(projectDir, includes.locales), ".json"));
   }
-
-  // Custom contracts
   if (includes.contracts) {
     files.push(...listFiles(resolve(projectDir, includes.contracts), ".yaml"));
   }
@@ -115,33 +129,78 @@ function categorize(relPath: string): string {
   return "Other";
 }
 
-function resolveOutputDir(target: string): string {
-  return resolve(GENERATED_DIR, target, "TaskFlow");
+// ── project resolution ───────────────────────────────────────────────
+
+/** Find the spec project directory by looking for openuispec.yaml. */
+function findProjectDir(cwd: string): string {
+  const candidates = [
+    join(cwd, "openuispec"),
+    cwd,
+    // Fallback for running from repo root with examples/
+    join(cwd, "examples", "taskflow"),
+  ];
+  for (const dir of candidates) {
+    if (existsSync(join(dir, "openuispec.yaml"))) {
+      return dir;
+    }
+  }
+  console.error(
+    "Error: No openuispec.yaml found.\n" +
+      "Run from a directory containing openuispec.yaml or an openuispec/ subdirectory."
+  );
+  process.exit(1);
 }
 
-function stateFilePath(target: string): string {
-  return join(resolveOutputDir(target), STATE_FILE);
+/** Read the project name from the manifest. */
+function readProjectName(projectDir: string): string {
+  const doc = YAML.parse(
+    readFileSync(join(projectDir, "openuispec.yaml"), "utf-8")
+  );
+  return doc.project?.name ?? basename(projectDir);
 }
 
-/** Discover all targets that have an existing snapshot. */
-function discoverTargets(): string[] {
-  if (!existsSync(GENERATED_DIR)) return [];
+/** Resolve the generated output directory for a target. */
+function resolveOutputDir(cwd: string, projectName: string, target: string): string {
+  return resolve(cwd, "generated", target, projectName);
+}
+
+function stateFilePath(cwd: string, projectName: string, target: string): string {
+  return join(resolveOutputDir(cwd, projectName, target), STATE_FILE);
+}
+
+function discoverTargets(cwd: string, projectName: string): string[] {
+  const generatedDir = resolve(cwd, "generated");
+  if (!existsSync(generatedDir)) return [];
   try {
-    return readdirSync(GENERATED_DIR)
-      .filter((entry) => existsSync(stateFilePath(entry)))
+    return readdirSync(generatedDir)
+      .filter((entry) =>
+        existsSync(stateFilePath(cwd, projectName, entry))
+      )
       .sort();
   } catch {
     return [];
   }
 }
 
+/**
+ * Normalize a state file entry. Handles backward compatibility
+ * with old format where files were stored as plain hash strings.
+ */
+function normalizeEntry(value: string | FileEntry): FileEntry {
+  if (typeof value === "string") {
+    return { hash: value, status: "ready" };
+  }
+  return value;
+}
+
 // ── snapshot ──────────────────────────────────────────────────────────
 
-function snapshot(projectDir: string, target: string): void {
-  const outDir = resolveOutputDir(target);
+function snapshot(cwd: string, projectDir: string, target: string): void {
+  const projectName = readProjectName(projectDir);
+  const outDir = resolveOutputDir(cwd, projectName, target);
   if (!existsSync(outDir)) {
     console.error(
-      `Error: Output directory not found: ${relative(REPO_ROOT, outDir)}\n` +
+      `Error: Output directory not found: ${relative(cwd, outDir)}\n` +
         `Run code generation for "${target}" first.`
     );
     process.exit(1);
@@ -150,89 +209,132 @@ function snapshot(projectDir: string, target: string): void {
   const files = discoverSpecFiles(projectDir);
   const doc = YAML.parse(readFileSync(join(projectDir, "openuispec.yaml"), "utf-8"));
 
-  const hashes: Record<string, string> = {};
+  const entries: Record<string, FileEntry> = {};
+  let stubCount = 0;
+
   for (const f of files) {
     const rel = relative(projectDir, f);
-    hashes[rel] = hashFile(f);
+    const status = hasStatusSemantics(rel) ? readStatus(f) : "ready";
+    entries[rel] = { hash: hashFile(f), status };
+    if (status === "stub") stubCount++;
   }
 
   const state: StateFile = {
     spec_version: doc.spec_version ?? "0.1",
     snapshot_at: new Date().toISOString(),
     target,
-    files: hashes,
+    files: entries,
   };
 
-  const outPath = stateFilePath(target);
+  const outPath = stateFilePath(cwd, projectName, target);
   writeFileSync(outPath, JSON.stringify(state, null, 2) + "\n");
-  console.log(`Snapshot saved: ${relative(REPO_ROOT, outPath)}`);
-  console.log(`  ${Object.keys(hashes).length} files hashed`);
+  console.log(`Snapshot saved: ${relative(cwd, outPath)}`);
+  console.log(`  ${Object.keys(entries).length} files hashed`);
+  if (stubCount > 0) {
+    console.log(`  ${stubCount} stubs (not tracked for drift)`);
+  }
   console.log(`  target: ${target}`);
 }
 
 // ── check ─────────────────────────────────────────────────────────────
 
-function check(projectDir: string, target: string, jsonOutput: boolean): void {
-  const statePath = stateFilePath(target);
-  if (!existsSync(statePath)) {
-    console.error(
-      `No snapshot found for target "${target}".\n` +
-        `Run: npm run drift -- --snapshot --target ${target}`
-    );
-    process.exit(1);
-  }
+interface CheckResult {
+  state: StateFile;
+  drift: DriftResult;
+  stubDrift: DriftResult;
+  statuses: Record<string, string>;
+}
 
-  const state: StateFile = JSON.parse(readFileSync(statePath, "utf-8"));
+function computeDrift(
+  projectDir: string,
+  state: StateFile,
+  includeAll: boolean
+): CheckResult {
   const files = discoverSpecFiles(projectDir);
 
-  const currentHashes: Record<string, string> = {};
+  const current: Record<string, FileEntry> = {};
   for (const f of files) {
-    currentHashes[relative(projectDir, f)] = hashFile(f);
+    const rel = relative(projectDir, f);
+    const status = hasStatusSemantics(rel) ? readStatus(f) : "ready";
+    current[rel] = { hash: hashFile(f), status };
   }
 
-  const result: DriftResult = {
-    changed: [],
-    added: [],
-    removed: [],
-    unchanged: [],
-  };
+  const drift: DriftResult = { changed: [], added: [], removed: [], unchanged: [] };
+  const stubDrift: DriftResult = { changed: [], added: [], removed: [], unchanged: [] };
+  const statuses: Record<string, string> = {};
+
+  for (const [rel, entry] of Object.entries(current)) {
+    const currentStatus = entry.status;
+    statuses[rel] = currentStatus;
+    const bucket = currentStatus === "stub" && !includeAll ? stubDrift : drift;
 
-  // Check current files against snapshot
-  for (const [rel, hash] of Object.entries(currentHashes)) {
-    if (!(rel in state.files)) {
-      result.added.push(rel);
-    } else if (state.files[rel] !== hash) {
-      result.changed.push(rel);
+    const snapshotEntry = state.files[rel]
+      ? normalizeEntry(state.files[rel] as string | FileEntry)
+      : null;
+
+    if (!snapshotEntry) {
+      bucket.added.push(rel);
+    } else if (snapshotEntry.hash !== entry.hash) {
+      bucket.changed.push(rel);
     } else {
-      result.unchanged.push(rel);
+      bucket.unchanged.push(rel);
     }
   }
 
-  // Check for removed files
-  for (const rel of Object.keys(state.files)) {
-    if (!(rel in currentHashes)) {
-      result.removed.push(rel);
+  for (const [rel, raw] of Object.entries(state.files)) {
+    if (!(rel in current)) {
+      const entry = normalizeEntry(raw as string | FileEntry);
+      statuses[rel] = entry.status;
+      const bucket = entry.status === "stub" && !includeAll ? stubDrift : drift;
+      bucket.removed.push(rel);
     }
   }
 
+  return { state, drift, stubDrift, statuses };
+}
+
+function check(
+  cwd: string,
+  projectDir: string,
+  target: string,
+  jsonOutput: boolean,
+  includeAll: boolean
+): void {
+  const projectName = readProjectName(projectDir);
+  const statePath = stateFilePath(cwd, projectName, target);
+  if (!existsSync(statePath)) {
+    console.error(
+      `No snapshot found for target "${target}".\n` +
+        `Run: openuispec drift --snapshot --target ${target}`
+    );
+    process.exit(1);
+  }
+
+  const state: StateFile = JSON.parse(readFileSync(statePath, "utf-8"));
+  const result = computeDrift(projectDir, state, includeAll);
+
   if (jsonOutput) {
-    printJson(state, result);
+    printJson(result);
   } else {
-    printReport(projectDir, state, result);
+    printReport(projectDir, result);
   }
 
-  const hasDrift =
-    result.changed.length > 0 ||
-    result.added.length > 0 ||
-    result.removed.length > 0;
+  const d = result.drift;
+  const hasDrift = d.changed.length > 0 || d.added.length > 0 || d.removed.length > 0;
   process.exit(hasDrift ? 1 : 0);
 }
 
-function checkAll(projectDir: string, jsonOutput: boolean): void {
-  const targets = discoverTargets();
+function checkAll(
+  cwd: string,
+  projectDir: string,
+  jsonOutput: boolean,
+  includeAll: boolean
+): void {
+  const projectName = readProjectName(projectDir);
+  const targets = discoverTargets(cwd, projectName);
   if (targets.length === 0) {
     console.error(
-      "No snapshots found. Run: npm run drift -- --snapshot --target <target>"
+      "No snapshots found. Run: openuispec drift --snapshot --target <target>"
     );
     process.exit(1);
   }
@@ -240,48 +342,18 @@ function checkAll(projectDir: string, jsonOutput: boolean): void {
   let anyDrift = false;
 
   for (const target of targets) {
-    const statePath = stateFilePath(target);
+    const statePath = stateFilePath(cwd, projectName, target);
     const state: StateFile = JSON.parse(readFileSync(statePath, "utf-8"));
-    const files = discoverSpecFiles(projectDir);
-
-    const currentHashes: Record<string, string> = {};
-    for (const f of files) {
-      currentHashes[relative(projectDir, f)] = hashFile(f);
-    }
-
-    const result: DriftResult = {
-      changed: [],
-      added: [],
-      removed: [],
-      unchanged: [],
-    };
-
-    for (const [rel, hash] of Object.entries(currentHashes)) {
-      if (!(rel in state.files)) {
-        result.added.push(rel);
-      } else if (state.files[rel] !== hash) {
-        result.changed.push(rel);
-      } else {
-        result.unchanged.push(rel);
-      }
-    }
-
-    for (const rel of Object.keys(state.files)) {
-      if (!(rel in currentHashes)) {
-        result.removed.push(rel);
-      }
-    }
+    const result = computeDrift(projectDir, state, includeAll);
 
     if (jsonOutput) {
-      printJson(state, result);
+      printJson(result);
     } else {
-      printReport(projectDir, state, result);
+      printReport(projectDir, result);
     }
 
-    const hasDrift =
-      result.changed.length > 0 ||
-      result.added.length > 0 ||
-      result.removed.length > 0;
+    const d = result.drift;
+    const hasDrift = d.changed.length > 0 || d.added.length > 0 || d.removed.length > 0;
     if (hasDrift) anyDrift = true;
 
     if (targets.length > 1 && target !== targets[targets.length - 1]) {
@@ -294,13 +366,20 @@ function checkAll(projectDir: string, jsonOutput: boolean): void {
 
 // ── output ────────────────────────────────────────────────────────────
 
-function printJson(state: StateFile, result: DriftResult): void {
+function printJson(result: CheckResult): void {
+  const stubTotal =
+    result.stubDrift.changed.length +
+    result.stubDrift.added.length +
+    result.stubDrift.removed.length +
+    result.stubDrift.unchanged.length;
+
   console.log(
     JSON.stringify(
       {
-        snapshot_at: state.snapshot_at,
-        target: state.target,
-        ...result,
+        snapshot_at: result.state.snapshot_at,
+        target: result.state.target,
+        ...result.drift,
+        stubs: stubTotal > 0 ? result.stubDrift : undefined,
       },
       null,
       2
@@ -308,32 +387,26 @@ function printJson(state: StateFile, result: DriftResult): void {
   );
 }
 
-function printReport(
-  projectDir: string,
-  state: StateFile,
-  result: DriftResult
-): void {
-  const doc = YAML.parse(
-    readFileSync(join(projectDir, "openuispec.yaml"), "utf-8")
-  );
-  const projectName = doc.project?.name ?? basename(projectDir);
+function printReport(projectDir: string, result: CheckResult): void {
+  const projectName = readProjectName(projectDir);
 
   console.log("OpenUISpec Drift Check");
   console.log("======================");
   console.log(`Project: ${projectName}`);
-  console.log(`Snapshot: ${state.snapshot_at}`);
-  console.log(`Target: ${state.target}`);
-
-  // Group all files by category
-  const allFiles = new Set([
-    ...result.unchanged,
-    ...result.changed,
-    ...result.added,
-    ...result.removed,
+  console.log(`Snapshot: ${result.state.snapshot_at}`);
+  console.log(`Target: ${result.state.target}`);
+
+  const d = result.drift;
+
+  const allTracked = new Set([
+    ...d.unchanged,
+    ...d.changed,
+    ...d.added,
+    ...d.removed,
   ]);
 
   const categories = new Map<string, string[]>();
-  for (const f of allFiles) {
+  for (const f of allTracked) {
     const cat = categorize(f);
     if (!categories.has(cat)) categories.set(cat, []);
     categories.get(cat)!.push(f);
@@ -358,41 +431,76 @@ function printReport(
     console.log(`\n${cat}`);
     for (const f of files) {
       const name = basename(f);
-      if (result.changed.includes(f)) {
-        console.log(`  ✗  ${name} (changed)`);
-      } else if (result.added.includes(f)) {
+      if (d.changed.includes(f)) {
+        console.log(`  \u2717  ${name} (changed)`);
+      } else if (d.added.includes(f)) {
         console.log(`  +  ${name} (added)`);
-      } else if (result.removed.includes(f)) {
+      } else if (d.removed.includes(f)) {
         console.log(`  -  ${name} (removed)`);
       } else {
-        console.log(`  ✓  ${name}`);
+        console.log(`  \u2713  ${name}`);
       }
     }
   }
 
+  const sd = result.stubDrift;
+  const allStubs = [
+    ...sd.unchanged,
+    ...sd.changed,
+    ...sd.added,
+    ...sd.removed,
+  ];
+
+  if (allStubs.length > 0) {
+    console.log("\nStubs (not tracked)");
+    allStubs.sort();
+    for (const f of allStubs) {
+      const name = basename(f);
+      const hasChange =
+        sd.changed.includes(f) || sd.added.includes(f) || sd.removed.includes(f);
+      console.log(`  \u00b7  ${name}${hasChange ? " (changed)" : ""}`);
+    }
+  }
+
+  const stubCount = allStubs.length;
+  const stubSuffix = stubCount > 0 ? ` (${stubCount} stubs skipped)` : "";
   console.log(
-    `\nSummary: ${result.changed.length} changed, ${result.added.length} added, ${result.removed.length} removed`
+    `\nSummary: ${d.changed.length} changed, ${d.added.length} added, ${d.removed.length} removed${stubSuffix}`
   );
 }
 
 // ── main ──────────────────────────────────────────────────────────────
 
-const args = process.argv.slice(2);
-const isSnapshot = args.includes("--snapshot");
-const isJson = args.includes("--json");
+export function runDrift(argv: string[]): void {
+  const isSnapshot = argv.includes("--snapshot");
+  const isJson = argv.includes("--json");
+  const includeAll = argv.includes("--all");
 
-const targetIdx = args.indexOf("--target");
-const target = targetIdx !== -1 && args[targetIdx + 1] ? args[targetIdx + 1] : null;
+  const targetIdx = argv.indexOf("--target");
+  const target = targetIdx !== -1 && argv[targetIdx + 1] ? argv[targetIdx + 1] : null;
 
-if (isSnapshot) {
-  if (!target) {
-    console.error("Error: --target is required for --snapshot");
-    console.error("Usage: npm run drift -- --snapshot --target <target>");
-    process.exit(1);
+  const cwd = process.cwd();
+  const projectDir = findProjectDir(cwd);
+
+  if (isSnapshot) {
+    if (!target) {
+      console.error("Error: --target is required for --snapshot");
+      console.error("Usage: openuispec drift --snapshot --target <target>");
+      process.exit(1);
+    }
+    snapshot(cwd, projectDir, target);
+  } else if (target) {
+    check(cwd, projectDir, target, isJson, includeAll);
+  } else {
+    checkAll(cwd, projectDir, isJson, includeAll);
   }
-  snapshot(PROJECT_DIR, target);
-} else if (target) {
-  check(PROJECT_DIR, target, isJson);
-} else {
-  checkAll(PROJECT_DIR, isJson);
+}
+
+// Direct execution
+const isDirectRun =
+  process.argv[1]?.endsWith("drift/index.ts") ||
+  process.argv[1]?.endsWith("drift/index.js");
+
+if (isDirectRun) {
+  runDrift(process.argv.slice(2));
 }

package/package.json

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

package/schema/validate.ts

@@ -1,14 +1,14 @@
 #!/usr/bin/env tsx
 /**
- * Validate all TaskFlow example files against their OpenUISpec JSON Schemas.
+ * Validate OpenUISpec files against their JSON Schemas.
  *
  * Usage:
- *   npm run validate              # validate everything
- *   npm run validate:tokens       # validate only tokens
- *   npx tsx schema/validate.ts screens flows  # multiple groups
+ *   openuispec validate                    # validate all spec files
+ *   openuispec validate tokens screens     # validate specific groups
+ *   npm run validate                       # from repo (uses examples/taskflow)
  */
 
-import { readFileSync, readdirSync } from "node:fs";
+import { readFileSync, readdirSync, existsSync } from "node:fs";
 import { resolve, join, basename } from "node:path";
 import { fileURLToPath } from "node:url";
 import { createRequire } from "node:module";
@@ -21,7 +21,6 @@ const addFormats = require("ajv-formats") as typeof import("ajv-formats").defaul
 
 const __dirname = fileURLToPath(new URL(".", import.meta.url));
 const SCHEMA_DIR = resolve(__dirname);
-const EXAMPLES_DIR = resolve(SCHEMA_DIR, "..", "examples", "taskflow");
 
 type AjvInstance = InstanceType<typeof Ajv2020>;
 
@@ -119,16 +118,16 @@ const BASE = "https://openuispec.org/schema/";
 
 interface ValidationGroup {
   label: string;
-  run(ajv: AjvInstance): number;
+  run(ajv: AjvInstance, projectDir: string): number;
 }
 
 const GROUPS: Record<string, ValidationGroup> = {
   manifest: {
     label: "Root manifest",
-    run(ajv) {
+    run(ajv, projectDir) {
       return validateFile(
         ajv,
-        join(EXAMPLES_DIR, "openuispec.yaml"),
+        join(projectDir, "openuispec.yaml"),
         `${BASE}openuispec.schema.json`,
       );
     },
@@ -136,7 +135,7 @@ const GROUPS: Record<string, ValidationGroup> = {
 
   tokens: {
     label: "Tokens",
-    run(ajv) {
+    run(ajv, projectDir) {
       let errors = 0;
       const tokenMap: Record<string, string> = {
         "color.yaml": "color.schema.json",
@@ -149,11 +148,10 @@ const GROUPS: Record<string, ValidationGroup> = {
         "icons.yaml": "icons.schema.json",
       };
       for (const [data, schema] of Object.entries(tokenMap)) {
-        errors += validateFile(
-          ajv,
-          join(EXAMPLES_DIR, "tokens", data),
-          `${BASE}tokens/${schema}`,
-        );
+        const filePath = join(projectDir, "tokens", data);
+        if (existsSync(filePath)) {
+          errors += validateFile(ajv, filePath, `${BASE}tokens/${schema}`);
+        }
       }
       return errors;
     },
@@ -161,9 +159,9 @@ const GROUPS: Record<string, ValidationGroup> = {
 
   screens: {
     label: "Screens",
-    run(ajv) {
+    run(ajv, projectDir) {
       let errors = 0;
-      for (const f of listFiles(join(EXAMPLES_DIR, "screens"), ".yaml")) {
+      for (const f of listFiles(join(projectDir, "screens"), ".yaml")) {
         errors += validateFile(ajv, f, `${BASE}screen.schema.json`);
       }
       return errors;
@@ -172,9 +170,9 @@ const GROUPS: Record<string, ValidationGroup> = {
 
   flows: {
     label: "Flows",
-    run(ajv) {
+    run(ajv, projectDir) {
       let errors = 0;
-      for (const f of listFiles(join(EXAMPLES_DIR, "flows"), ".yaml")) {
+      for (const f of listFiles(join(projectDir, "flows"), ".yaml")) {
         errors += validateFile(ajv, f, `${BASE}flow.schema.json`);
       }
       return errors;
@@ -183,9 +181,9 @@ const GROUPS: Record<string, ValidationGroup> = {
 
   platform: {
     label: "Platform",
-    run(ajv) {
+    run(ajv, projectDir) {
       let errors = 0;
-      for (const f of listFiles(join(EXAMPLES_DIR, "platform"), ".yaml")) {
+      for (const f of listFiles(join(projectDir, "platform"), ".yaml")) {
         errors += validateFile(ajv, f, `${BASE}platform.schema.json`);
       }
       return errors;
@@ -194,9 +192,9 @@ const GROUPS: Record<string, ValidationGroup> = {
 
   locales: {
     label: "Locales",
-    run(ajv) {
+    run(ajv, projectDir) {
       let errors = 0;
-      for (const f of listFiles(join(EXAMPLES_DIR, "locales"), ".json")) {
+      for (const f of listFiles(join(projectDir, "locales"), ".json")) {
         errors += validateFile(ajv, f, `${BASE}locale.schema.json`);
       }
       return errors;
@@ -205,9 +203,9 @@ const GROUPS: Record<string, ValidationGroup> = {
 
   custom_contracts: {
     label: "Custom contracts",
-    run(ajv) {
+    run(ajv, projectDir) {
       let errors = 0;
-      for (const f of listFiles(join(EXAMPLES_DIR, "contracts"), ".yaml")) {
+      for (const f of listFiles(join(projectDir, "contracts"), ".yaml")) {
         if (basename(f).startsWith("x_")) {
           errors += validateFile(
             ajv,
@@ -221,13 +219,36 @@ const GROUPS: Record<string, ValidationGroup> = {
   },
 };
 
+// ── project resolution ───────────────────────────────────────────────
+
+function findProjectDir(cwd: string): string {
+  const candidates = [
+    join(cwd, "openuispec"),
+    cwd,
+  ];
+  for (const dir of candidates) {
+    if (existsSync(join(dir, "openuispec.yaml"))) {
+      return dir;
+    }
+  }
+  // Fallback for running from repo root with examples/
+  const examplesDir = join(cwd, "examples", "taskflow");
+  if (existsSync(join(examplesDir, "openuispec.yaml"))) {
+    return examplesDir;
+  }
+  console.error(
+    "Error: No openuispec.yaml found.\n" +
+      "Run from a directory containing openuispec.yaml or an openuispec/ subdirectory."
+  );
+  process.exit(1);
+}
+
 // ── main ─────────────────────────────────────────────────────────────
 
-function main(): void {
-  const args = process.argv.slice(2);
+export function runValidate(argv: string[]): void {
   const selected =
-    args.length > 0
-      ? args.filter((a) => a in GROUPS)
+    argv.length > 0
+      ? argv.filter((a) => a in GROUPS)
       : Object.keys(GROUPS);
 
   if (selected.length === 0) {
@@ -237,13 +258,14 @@ function main(): void {
     process.exit(2);
   }
 
+  const projectDir = findProjectDir(process.cwd());
   const ajv = buildAjv();
   let totalErrors = 0;
 
   for (const key of selected) {
     const group = GROUPS[key];
     console.log(`\n${group.label}:`);
-    totalErrors += group.run(ajv);
+    totalErrors += group.run(ajv, projectDir);
   }
 
   console.log(`\n${"=".repeat(50)}`);
@@ -255,4 +277,11 @@ function main(): void {
   }
 }
 
-main();
+// Direct execution
+const isDirectRun =
+  process.argv[1]?.endsWith("validate.ts") ||
+  process.argv[1]?.endsWith("validate.js");
+
+if (isDirectRun) {
+  runValidate(process.argv.slice(2));
+}