openuispec 0.1.27 → 0.1.28

package/examples/taskflow/generated/web/TaskFlow/src/utils.ts

@@ -0,0 +1,78 @@
+import type { Filter, Project, Task } from "./types";
+
+export function matchesFilter(task: Task, filter: Filter) {
+  const due = task.dueDate ? new Date(task.dueDate) : null;
+  const today = new Date();
+  today.setHours(0, 0, 0, 0);
+  if (filter === "all") return true;
+  if (filter === "done") return task.status === "done";
+  if (filter === "today") return Boolean(due && due.toDateString() === today.toDateString() && task.status !== "done");
+  return Boolean(due && due > today && task.status !== "done");
+}
+
+export function matchesQuery(task: Task, projects: Project[], query: string) {
+  if (!query.trim()) return true;
+  const projectName = projects.find((project) => project.id === task.projectId)?.name ?? "";
+  return [task.title, task.description ?? "", projectName, task.tags.join(" ")]
+    .join(" ")
+    .toLowerCase()
+    .includes(query.toLowerCase());
+}
+
+export function buildCounts(tasks: Task[]) {
+  return {
+    all: tasks.length,
+    today: tasks.filter((task) => matchesFilter(task, "today")).length,
+    upcoming: tasks.filter((task) => matchesFilter(task, "upcoming")).length,
+    done: tasks.filter((task) => task.status === "done").length
+  };
+}
+
+export function parseTags(value: string) {
+  return value
+    .split(",")
+    .map((item) => item.trim())
+    .filter(Boolean);
+}
+
+export function initials(name: string) {
+  return name
+    .split(" ")
+    .slice(0, 2)
+    .map((part) => part[0]?.toUpperCase() ?? "")
+    .join("");
+}
+
+export function relativeDate(value: string) {
+  const date = new Date(value);
+  const today = new Date();
+  today.setHours(0, 0, 0, 0);
+  const target = new Date(date);
+  target.setHours(0, 0, 0, 0);
+  const diff = Math.round((target.getTime() - today.getTime()) / 86400000);
+  if (diff === 0) return "Today";
+  if (diff === 1) return "Tomorrow";
+  if (diff === -1) return "Yesterday";
+  if (diff > 1) return `in ${diff} days`;
+  return `${Math.abs(diff)} days ago`;
+}
+
+export function formatDate(value: string) {
+  return new Date(value).toLocaleDateString("en-US", {
+    month: "short",
+    day: "numeric",
+    year: "numeric"
+  });
+}
+
+export function addDays(days: number) {
+  const next = new Date();
+  next.setDate(next.getDate() + days);
+  return next.toISOString();
+}
+
+export function daysAgo(days: number) {
+  const previous = new Date();
+  previous.setDate(previous.getDate() - days);
+  return previous.toISOString();
+}

package/examples/taskflow/generated/web/TaskFlow/tsconfig.json

@@ -0,0 +1,21 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "useDefineForClassFields": true,
+    "lib": ["ES2020", "DOM", "DOM.Iterable"],
+    "allowJs": false,
+    "skipLibCheck": true,
+    "esModuleInterop": true,
+    "allowSyntheticDefaultImports": true,
+    "strict": true,
+    "forceConsistentCasingInFileNames": true,
+    "module": "ESNext",
+    "moduleResolution": "Node",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "noEmit": true,
+    "jsx": "react-jsx"
+  },
+  "include": ["src"],
+  "references": []
+}

package/examples/taskflow/generated/web/TaskFlow/vite.config.ts

@@ -0,0 +1,6 @@
+import { defineConfig } from "vite";
+import react from "@vitejs/plugin-react";
+
+export default defineConfig({
+  plugins: [react()]
+});

package/examples/taskflow/openuispec/README.md

@@ -0,0 +1,49 @@
+# TaskFlow — OpenUISpec
+
+This directory contains the **OpenUISpec** semantic UI specification for **TaskFlow**.
+
+**Start here:** read `openuispec.yaml` — it defines the project structure, data model, API endpoints, and generation targets (**ios, android, web**).
+
+## Directory structure
+
+| Directory | Contents |
+|-----------|----------|
+| `tokens/` | Design tokens — colors, typography, spacing, elevation, motion, icons, themes |
+| `screens/` | Screen definitions — one YAML file per screen |
+| `flows/` | Navigation flows — multi-step user journeys |
+| `contracts/` | Component contracts — standard extensions and custom (`x_` prefixed) |
+| `platform/` | Platform overrides — per-target (iOS, Android, Web) behaviors |
+| `locales/` | Localization — i18n strings (JSON, ICU MessageFormat) |
+
+## IMPORTANT — Read the specification before working with spec files
+
+The spec format, file schemas, and generation rules are defined in the installed `openuispec` package.
+You MUST read these reference files before creating, editing, or generating from any spec file.
+Do NOT guess the file format — skipping this step will produce invalid YAML that fails validation.
+
+**Find the package in this order:**
+1. `node_modules/openuispec/` (project dependency)
+2. Run `npm root -g` → `<prefix>/openuispec/` (global install)
+3. Online: `https://openuispec.rsteam.uz/llms-full.txt` (if not installed)
+
+**Reference files inside the package (read in this order):**
+1. `README.md` — schema tables, file format reference, root keys
+2. `spec/openuispec-v0.1.md` — full specification (contracts, layout, expressions, etc.)
+3. `examples/taskflow/openuispec/` — complete working example with all file types
+4. `schema/` — JSON Schemas for validation
+
+## CLI commands
+
+```bash
+openuispec validate             # Validate spec files against schemas
+openuispec validate semantic    # Check semantic cross-references
+openuispec validate screens     # Validate only screens
+openuispec status               # Show which targets are behind
+openuispec drift --target ios --explain   # Explain semantic spec drift since ios baseline
+openuispec prepare --target ios           # Build an AI-ready ios update bundle
+openuispec drift --snapshot --target ios  # Snapshot current state + git baseline after ios output exists
+```
+
+## Learn more
+
+Docs: https://openuispec.rsteam.uz

package/examples/todo-orbit/AGENTS.md

@@ -1,5 +1,5 @@
 <!-- openuispec-rules-start -->
-<!-- openuispec-rules-version: 0.1.23 -->
+<!-- openuispec-rules-version: 0.1.28 -->
 # OpenUISpec — AI Assistant Rules
 # ================================
 # This project uses OpenUISpec to define UI as a semantic spec.
@@ -20,7 +20,7 @@ Do NOT guess the file format — skipping this step will produce invalid YAML th
 **Reference files inside the package (read in this order):**
 1. `README.md` — schema tables, file format reference, root wrapper keys
 2. `spec/openuispec-v0.1.md` — full specification (contracts, layout, expressions, adaptive, etc.)
-3. `examples/taskflow/` — complete working example with all file types
+3. `examples/taskflow/openuispec/` — complete working example with all file types
 4. `schema/` — JSON Schemas for every file type
 
 These files are updated with each package version. Always read from the installed package,
@@ -57,22 +57,46 @@ This means the project has existing UI code but hasn't been specced yet. Your jo
 4. **Extract tokens** — scan for colors, fonts, spacing and create files in `openuispec/tokens/`.
 5. **Update the manifest** — fill in `data_model` and `api.endpoints` in `openuispec/openuispec.yaml`.
 
-## Making UI changes
-1. Read the relevant spec files before modifying any UI code.
-2. If the change requires a spec update, modify the spec FIRST, then update code.
-3. Never modify generated code without updating the spec.
-4. When adding a new screen, create the corresponding spec file.
-5. When removing a screen, remove the spec file and update flow references.
-
-## After modifying spec files
-1. Run `openuispec validate` to check specs against the schema.
-2. Run `openuispec validate semantic`.
-3. Run `openuispec drift --target <target> --explain` to inspect semantic changes since that target's baseline.
-4. Run `openuispec prepare --target <target>` to build the target update bundle.
-5. **Update the generated code** for each affected platform to match the new spec.
-6. Run `openuispec drift --snapshot --target <target>` to baseline the updated state.
-7. Run `openuispec drift --target <target> --explain` again to confirm no spec changes remain for that target.
-8. Run `openuispec status` to see which other targets are still behind.
+## OpenUISpec Source Of Truth
+
+OpenUISpec spec files are the primary source of truth for UI behavior across platforms.
+
+### Start from spec when:
+- the request changes screen structure
+- the request changes navigation
+- the request changes fields, actions, validation, or data binding
+- the request changes tokens, variants, contracts, flows, or localization
+- the request affects more than one platform
+- the request is phrased in product/UI terms rather than platform-code terms
+
+Spec-first workflow:
+1. Read `openuispec/openuispec.yaml` and the relevant spec files first.
+2. Update the spec first.
+3. Update the affected generated/native UI code to match the spec.
+4. Run `openuispec validate`.
+5. Run `openuispec validate semantic`.
+6. Run `openuispec drift --target <target> --explain` to inspect semantic changes since that target's baseline.
+7. Run `openuispec prepare --target <target>` to build the AI/developer work bundle for that target.
+8. Verify the affected UI targets build/run if possible.
+9. Only then run `openuispec drift --snapshot --target <target>` for affected targets, after that target output directory exists.
+10. Run `openuispec drift --target <target> --explain` again to confirm no spec changes remain for that target.
+11. Use `openuispec status` to see which other targets are still behind the updated spec.
+
+### Start from platform code when:
+- the change is platform-specific polish
+- the change is a local bug fix that does not alter shared semantic behavior
+- the request explicitly asks for an iOS-only, Android-only, or web-only adjustment
+
+Platform-first workflow:
+1. Update native/platform code.
+2. If the change affects shared semantics, sync the spec afterward.
+3. If the change is intentionally platform-specific, document it in `platform/*.yaml` when appropriate.
+
+### Never do this:
+- Do not snapshot drift immediately after changing spec unless the UI code has also been updated.
+- Do not treat `openuispec drift` as proof that generated UI matches the spec.
+- Do not skip `--explain` / `prepare` when another platform needs to catch up with shared spec changes.
+- Do not modify generated UI without checking whether the spec must change first.
 
 ## CLI commands
 - `openuispec init` — scaffold a new spec project
@@ -80,8 +104,9 @@ This means the project has existing UI code but hasn't been specced yet. Your jo
 - `openuispec validate semantic` — run semantic cross-reference linting
 - `openuispec drift --target <t>` — check for spec drift
 - `openuispec drift --target <t> --explain` — explain semantic spec drift since the target baseline
-- `openuispec drift --snapshot --target <t>` — snapshot current state
+- `openuispec drift --snapshot --target <t>` — snapshot current state after the target output exists
 - `openuispec prepare --target <t>` — build an AI-ready target update bundle
+- `openuispec status` — show cross-target baseline/drift status
 - `openuispec update-rules` — update AI rules to match installed package version
 - `openuispec drift --all` — include stubs in drift check
 <!-- openuispec-rules-end -->

package/examples/todo-orbit/CLAUDE.md

@@ -1,5 +1,5 @@
 <!-- openuispec-rules-start -->
-<!-- openuispec-rules-version: 0.1.23 -->
+<!-- openuispec-rules-version: 0.1.28 -->
 # OpenUISpec — AI Assistant Rules
 # ================================
 # This project uses OpenUISpec to define UI as a semantic spec.
@@ -20,7 +20,7 @@ Do NOT guess the file format — skipping this step will produce invalid YAML th
 **Reference files inside the package (read in this order):**
 1. `README.md` — schema tables, file format reference, root wrapper keys
 2. `spec/openuispec-v0.1.md` — full specification (contracts, layout, expressions, adaptive, etc.)
-3. `examples/taskflow/` — complete working example with all file types
+3. `examples/taskflow/openuispec/` — complete working example with all file types
 4. `schema/` — JSON Schemas for every file type
 
 These files are updated with each package version. Always read from the installed package,
@@ -57,22 +57,46 @@ This means the project has existing UI code but hasn't been specced yet. Your jo
 4. **Extract tokens** — scan for colors, fonts, spacing and create files in `openuispec/tokens/`.
 5. **Update the manifest** — fill in `data_model` and `api.endpoints` in `openuispec/openuispec.yaml`.
 
-## Making UI changes
-1. Read the relevant spec files before modifying any UI code.
-2. If the change requires a spec update, modify the spec FIRST, then update code.
-3. Never modify generated code without updating the spec.
-4. When adding a new screen, create the corresponding spec file.
-5. When removing a screen, remove the spec file and update flow references.
-
-## After modifying spec files
-1. Run `openuispec validate` to check specs against the schema.
-2. Run `openuispec validate semantic`.
-3. Run `openuispec drift --target <target> --explain` to inspect semantic changes since that target's baseline.
-4. Run `openuispec prepare --target <target>` to build the target update bundle.
-5. **Update the generated code** for each affected platform to match the new spec.
-6. Run `openuispec drift --snapshot --target <target>` to baseline the updated state.
-7. Run `openuispec drift --target <target> --explain` again to confirm no spec changes remain for that target.
-8. Run `openuispec status` to see which other targets are still behind.
+## OpenUISpec Source Of Truth
+
+OpenUISpec spec files are the primary source of truth for UI behavior across platforms.
+
+### Start from spec when:
+- the request changes screen structure
+- the request changes navigation
+- the request changes fields, actions, validation, or data binding
+- the request changes tokens, variants, contracts, flows, or localization
+- the request affects more than one platform
+- the request is phrased in product/UI terms rather than platform-code terms
+
+Spec-first workflow:
+1. Read `openuispec/openuispec.yaml` and the relevant spec files first.
+2. Update the spec first.
+3. Update the affected generated/native UI code to match the spec.
+4. Run `openuispec validate`.
+5. Run `openuispec validate semantic`.
+6. Run `openuispec drift --target <target> --explain` to inspect semantic changes since that target's baseline.
+7. Run `openuispec prepare --target <target>` to build the AI/developer work bundle for that target.
+8. Verify the affected UI targets build/run if possible.
+9. Only then run `openuispec drift --snapshot --target <target>` for affected targets, after that target output directory exists.
+10. Run `openuispec drift --target <target> --explain` again to confirm no spec changes remain for that target.
+11. Use `openuispec status` to see which other targets are still behind the updated spec.
+
+### Start from platform code when:
+- the change is platform-specific polish
+- the change is a local bug fix that does not alter shared semantic behavior
+- the request explicitly asks for an iOS-only, Android-only, or web-only adjustment
+
+Platform-first workflow:
+1. Update native/platform code.
+2. If the change affects shared semantics, sync the spec afterward.
+3. If the change is intentionally platform-specific, document it in `platform/*.yaml` when appropriate.
+
+### Never do this:
+- Do not snapshot drift immediately after changing spec unless the UI code has also been updated.
+- Do not treat `openuispec drift` as proof that generated UI matches the spec.
+- Do not skip `--explain` / `prepare` when another platform needs to catch up with shared spec changes.
+- Do not modify generated UI without checking whether the spec must change first.
 
 ## CLI commands
 - `openuispec init` — scaffold a new spec project
@@ -80,8 +104,9 @@ This means the project has existing UI code but hasn't been specced yet. Your jo
 - `openuispec validate semantic` — run semantic cross-reference linting
 - `openuispec drift --target <t>` — check for spec drift
 - `openuispec drift --target <t> --explain` — explain semantic spec drift since the target baseline
-- `openuispec drift --snapshot --target <t>` — snapshot current state
+- `openuispec drift --snapshot --target <t>` — snapshot current state after the target output exists
 - `openuispec prepare --target <t>` — build an AI-ready target update bundle
+- `openuispec status` — show cross-target baseline/drift status
 - `openuispec update-rules` — update AI rules to match installed package version
 - `openuispec drift --all` — include stubs in drift check
 <!-- openuispec-rules-end -->

package/examples/todo-orbit/openuispec/README.md

@@ -29,7 +29,7 @@ Do NOT guess the file format — skipping this step will produce invalid YAML th
 **Reference files inside the package (read in this order):**
 1. `README.md` — schema tables, file format reference, root keys
 2. `spec/openuispec-v0.1.md` — full specification (contracts, layout, expressions, etc.)
-3. `examples/taskflow/` — complete working example with all file types
+3. `examples/taskflow/openuispec/` — complete working example with all file types
 4. `schema/` — JSON Schemas for validation
 
 ## CLI commands
@@ -41,7 +41,7 @@ openuispec validate screens     # Validate only screens
 openuispec status               # Show which targets are behind
 openuispec drift --target ios --explain   # Explain semantic spec drift since ios baseline
 openuispec prepare --target ios           # Build an AI-ready ios update bundle
-openuispec drift --snapshot --target ios  # Snapshot current state + git baseline
+openuispec drift --snapshot --target ios  # Snapshot current state + git baseline after ios output exists
 ```
 
 If a target snapshot was created before baseline metadata was added, `--explain` and `status` will ask you to re-run `openuispec drift --snapshot --target <target>` for that target.

package/package.json

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

package/schema/validate.ts

@@ -5,7 +5,7 @@
  * Usage:
  *   openuispec validate                    # validate all spec files
  *   openuispec validate tokens screens     # validate specific groups
- *   npm run validate                       # from repo (uses examples/taskflow)
+ *   npm run validate                       # from repo (uses examples/taskflow/openuispec)
  */
 
 import { readFileSync, readdirSync, existsSync } from "node:fs";
@@ -572,9 +572,14 @@ function findProjectDir(cwd: string): string {
     }
   }
   // Fallback for running from repo root with examples/
-  const examplesDir = join(cwd, "examples", "taskflow");
-  if (existsSync(join(examplesDir, "openuispec.yaml"))) {
-    return examplesDir;
+  const exampleCandidates = [
+    join(cwd, "examples", "taskflow", "openuispec"),
+    join(cwd, "examples", "taskflow"),
+  ];
+  for (const dir of exampleCandidates) {
+    if (existsSync(join(dir, "openuispec.yaml"))) {
+      return dir;
+    }
   }
   console.error(
     "Error: No openuispec.yaml found.\n" +

package/status/index.ts

@@ -26,6 +26,7 @@ import { readFileSync } from "node:fs";
 interface TargetStatus {
   target: string;
   output_dir: string;
+  output_exists: boolean;
   snapshot: boolean;
   snapshot_at: string | null;
   baseline: {
@@ -74,12 +75,14 @@ function readState(statePath: string): StateFile {
 
 function buildTargetStatus(cwd: string, projectDir: string, projectName: string, target: string): TargetStatus {
   const outputDir = resolveOutputDir(projectDir, projectName, target);
+  const outputExists = existsSync(outputDir);
   const path = stateFilePath(projectDir, projectName, target);
 
   if (!existsSync(path)) {
     return {
       target,
       output_dir: outputDir,
+      output_exists: outputExists,
       snapshot: false,
       snapshot_at: null,
       baseline: {
@@ -93,7 +96,9 @@ function buildTargetStatus(cwd: string, projectDir: string, projectName: string,
       removed: 0,
       behind: false,
       explain_available: false,
-      note: "No snapshot found for this target.",
+      note: outputExists
+        ? "No snapshot found for this target."
+        : `Output directory not found. Run code generation for "${target}" first.`,
     };
   }
 
@@ -107,6 +112,7 @@ function buildTargetStatus(cwd: string, projectDir: string, projectName: string,
   return {
     target,
     output_dir: outputDir,
+    output_exists: outputExists,
     snapshot: true,
     snapshot_at: state.snapshot_at,
     baseline: {
@@ -147,11 +153,18 @@ function printReport(result: StatusResult): void {
   for (const target of result.targets) {
     const summary = target.snapshot
       ? `${target.changed} changed, ${target.added} added, ${target.removed} removed`
-      : "no snapshot";
-    const status = target.snapshot ? (target.behind ? "behind" : "up to date") : "needs baseline";
+      : target.output_exists
+        ? "no snapshot"
+        : "output missing";
+    const status = target.snapshot
+      ? (target.behind ? "behind" : "up to date")
+      : target.output_exists
+        ? "needs baseline"
+        : "needs generation";
 
     console.log(`${target.target}`);
     console.log(`  output: ${target.output_dir}`);
+    console.log(`  output exists: ${target.output_exists ? "yes" : "no"}`);
     console.log(`  snapshot: ${target.snapshot ? target.snapshot_at : "missing"}`);
     if (target.baseline.label) {
       console.log(`  baseline: ${target.baseline.label}`);