openuispec 0.1.20 → 0.1.23

package/README.md

@@ -96,7 +96,7 @@ openuispec/
 │   │   └── icons.schema.json          # Icon token schema
 │   ├── defs/
 │   │   ├── common.schema.json          # Shared types (icons, badges, etc.)
-│   │   ├── action.schema.json          # 13 action types (discriminated union)
+│   │   ├── action.schema.json          # 14 action types (discriminated union)
 │   │   ├── data-binding.schema.json    # Data sources, state, params
 │   │   ├── adaptive.schema.json        # Adaptive override pattern
 │   │   └── validation.schema.json     # Validation rule definitions
@@ -210,7 +210,7 @@ Paths are relative to `openuispec.yaml`. The `.openuispec-state.json` file is st
 | 6. Navigation flows | Multi-screen journeys with transitions and progress |
 | 7. Platform adaptation | Per-target overrides for iOS, Android, Web |
 | 8. AI generation contract | Compliance levels (MUST/SHOULD/MAY), validation, drift detection |
-| 9. Action system | 13 action types, composition, optimistic updates |
+| 9. Action system | 14 action types, composition, optimistic updates |
 | 10. Data binding & state | Sources, paths, format expressions, reactivity, caching |
 | 11. Internationalization | Locale files, `$t:` references, ICU MessageFormat, RTL, platform mapping |
 | 12. Custom contract extensions | `x_` prefixed domain-specific contracts, registration, dependencies |

package/cli/index.ts

@@ -9,7 +9,33 @@
  *   openuispec validate [group...]            Validate spec files against schemas
  */
 
-import { init } from "./init.js";
+import { init, updateRules, extractRulesVersion, getPackageVersion } from "./init.js";
+import { join } from "node:path";
+import { existsSync, readFileSync } from "node:fs";
+
+function checkRulesVersion(): void {
+  const cwd = process.cwd();
+  const installed = getPackageVersion();
+  for (const file of ["CLAUDE.md", "AGENTS.md"]) {
+    const filePath = join(cwd, file);
+    if (!existsSync(filePath)) continue;
+    const rulesVersion = extractRulesVersion(filePath);
+    if (rulesVersion && rulesVersion !== installed) {
+      console.log(
+        `\n⚠  ${file} rules were generated by v${rulesVersion} but v${installed} is installed.` +
+        `\n   Run: openuispec update-rules\n`
+      );
+    } else if (!rulesVersion) {
+      const content = readFileSync(filePath, "utf-8");
+      if (content.includes("OpenUISpec")) {
+        console.log(
+          `\n⚠  ${file} has OpenUISpec rules without a version marker.` +
+          `\n   Run: openuispec update-rules\n`
+        );
+      }
+    }
+  }
+}
 
 async function main(): Promise<void> {
   const [command, ...rest] = process.argv.slice(2);
@@ -19,6 +45,10 @@ async function main(): Promise<void> {
       await init();
       break;
 
+    case "update-rules":
+      updateRules();
+      break;
+
     case "drift": {
       const { runDrift } = await import("../drift/index.js");
       runDrift(rest);
@@ -28,6 +58,7 @@ async function main(): Promise<void> {
     case "validate": {
       const { runValidate } = await import("../schema/validate.js");
       runValidate(rest);
+      checkRulesVersion();
       break;
     }
 
@@ -39,6 +70,7 @@ OpenUISpec CLI v0.1
 
 Usage:
   openuispec init                           Create a new spec project
+  openuispec update-rules                   Update AI rules to match installed version
   openuispec drift [--target <t>]           Check for spec drift
   openuispec drift --snapshot --target <t>  Snapshot current state
   openuispec validate [group...]            Validate spec files

package/cli/init.ts

@@ -15,7 +15,8 @@ import {
   existsSync,
   appendFileSync,
 } from "node:fs";
-import { join, relative } from "node:path";
+import { join, relative, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
 
 // ── prompts ──────────────────────────────────────────────────────────
 
@@ -64,6 +65,21 @@ function writeIfMissing(path: string, content: string): boolean {
   return true;
 }
 
+// ── version ─────────────────────────────────────────────────────────
+
+const RULES_START_MARKER = "<!-- openuispec-rules-start -->";
+const RULES_END_MARKER = "<!-- openuispec-rules-end -->";
+
+function getPackageVersion(): string {
+  const pkgPath = join(
+    dirname(fileURLToPath(import.meta.url)),
+    "..",
+    "package.json"
+  );
+  const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
+  return pkg.version;
+}
+
 // ── templates ────────────────────────────────────────────────────────
 
 function manifestTemplate(
@@ -175,7 +191,10 @@ Docs: https://openuispec.rsteam.uz
 
 function aiRulesBlock(specDir: string, targets: string[]): string {
   const targetList = targets.map((t) => `"${t}"`).join(", ");
+  const version = getPackageVersion();
   return `
+${RULES_START_MARKER}
+<!-- openuispec-rules-version: ${version} -->
 # OpenUISpec — AI Assistant Rules
 # ================================
 # This project uses OpenUISpec to define UI as a semantic spec.
@@ -242,18 +261,110 @@ This means the project has existing UI code but hasn't been specced yet. Your jo
 
 ## After modifying spec files
 1. Run \`openuispec validate\` to check specs against the schema.
-2. Run \`openuispec drift --snapshot --target <target>\` for each affected platform.
-3. Run \`openuispec drift\` to verify no untracked drift remains.
+2. **Update the generated code** for each affected platform to match the new spec.
+3. Run \`openuispec drift --snapshot --target <target>\` to baseline the updated state.
+4. Run \`openuispec drift\` to verify no untracked drift remains.
 
 ## CLI commands
 - \`openuispec init\` — scaffold a new spec project
 - \`openuispec validate [group...]\` — validate spec files against schemas
 - \`openuispec drift --target <t>\` — check for spec drift
 - \`openuispec drift --snapshot --target <t>\` — snapshot current state
+- \`openuispec update-rules\` — update AI rules to match installed package version
 - \`openuispec drift --all\` — include stubs in drift check
+${RULES_END_MARKER}
 `;
 }
 
+// ── update-rules ────────────────────────────────────────────────────
+
+export function updateRules(): void {
+  const cwd = process.cwd();
+  const version = getPackageVersion();
+
+  // Detect spec dir from existing openuispec.yaml
+  let specDir = "openuispec";
+  for (const candidate of ["openuispec", "spec", "."]) {
+    if (existsSync(join(cwd, candidate, "openuispec.yaml"))) {
+      specDir = candidate;
+      break;
+    }
+  }
+
+  // Detect targets from manifest
+  let targets = ["ios", "android", "web"];
+  try {
+    const manifest = readFileSync(
+      join(cwd, specDir, "openuispec.yaml"),
+      "utf-8"
+    );
+    const match = manifest.match(/targets:\s*\[([^\]]+)\]/);
+    if (match) {
+      targets = match[1].split(",").map((t) => t.trim().replace(/['"]/g, ""));
+    }
+  } catch {}
+
+  const rules = aiRulesBlock(specDir, targets);
+  let updated = 0;
+
+  for (const file of ["CLAUDE.md", "AGENTS.md"]) {
+    const filePath = join(cwd, file);
+    if (!existsSync(filePath)) continue;
+
+    const content = readFileSync(filePath, "utf-8");
+
+    // Try marker-based replacement first
+    const startIdx = content.indexOf(RULES_START_MARKER);
+    const endIdx = content.indexOf(RULES_END_MARKER);
+
+    if (startIdx !== -1 && endIdx !== -1) {
+      const before = content.slice(0, startIdx);
+      const after = content.slice(endIdx + RULES_END_MARKER.length);
+      writeFileSync(filePath, before + rules.trimStart().trimEnd() + after);
+      console.log(`  updated ${file} (v${version})`);
+      updated++;
+      continue;
+    }
+
+    // Fallback: find the OpenUISpec rules block by header pattern
+    // The block runs from the header to EOF (it's always the last content)
+    const headerIdx = content.indexOf("# OpenUISpec — AI Assistant Rules");
+    if (headerIdx !== -1) {
+      const before = content.slice(0, headerIdx);
+      const newContent = before + rules.trimStart().trimEnd() + "\n";
+      writeFileSync(filePath, newContent);
+      console.log(`  updated ${file} (v${version}, migrated to markers)`);
+      updated++;
+      continue;
+    }
+
+    console.log(`  skip ${file} (no OpenUISpec rules block found)`);
+  }
+
+  if (updated === 0) {
+    console.log(
+      "No CLAUDE.md or AGENTS.md with OpenUISpec rules found.\nRun `openuispec init` first."
+    );
+  } else {
+    console.log(`\nAI rules updated to v${version}`);
+  }
+}
+
+/**
+ * Extract the rules version from a CLAUDE.md / AGENTS.md file.
+ * Returns null if no version marker is found.
+ */
+export function extractRulesVersion(filePath: string): string | null {
+  if (!existsSync(filePath)) return null;
+  const content = readFileSync(filePath, "utf-8");
+  const match = content.match(
+    /<!-- openuispec-rules-version:\s*([^\s]+)\s*-->/
+  );
+  return match ? match[1] : null;
+}
+
+export { getPackageVersion };
+
 // ── main ─────────────────────────────────────────────────────────────
 
 export async function init(): Promise<void> {

package/examples/todo-orbit/AGENTS.md

@@ -1,29 +1,52 @@
+<!-- openuispec-rules-start -->
+<!-- openuispec-rules-version: 0.1.22 -->
 # OpenUISpec — AI Assistant Rules
 # ================================
 # This project uses OpenUISpec to define UI as a semantic spec.
 # Spec files are the single source of truth for all UI across platforms.
 # Targets: "ios", "android", "web"
 
+## 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 the reference files listed below 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 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
+4. `schema/` — JSON Schemas for every file type
+
+These files are updated with each package version. Always read from the installed package,
+not from cached or memorized content, to ensure you use the latest spec.
+
 ## What is OpenUISpec
 OpenUISpec is a YAML-based spec format that describes an app's UI semantically — tokens, screens, flows, and platform overrides. AI reads the spec and generates native code (SwiftUI, Compose, React). AI reads native code and updates the spec. The spec is the sync layer between platforms.
 
 ## Spec location
 - Spec root: `openuispec/`
 - Manifest: `openuispec/openuispec.yaml` — always read this first.
-- Tokens: `openuispec/tokens/` — colors, typography, spacing, motion, icons, themes
-- Screens: `openuispec/screens/` — one YAML file per screen
-- Flows: `openuispec/flows/` — multi-step navigation journeys
-- Contracts: `openuispec/contracts/` — UI component definitions
-- Platform: `openuispec/platform/` — per-target overrides (iOS, Android, Web)
-- Locales: `openuispec/locales/` — i18n strings (JSON, ICU MessageFormat)
+- Tokens: `openuispec/tokens/`
+- Screens: `openuispec/screens/`
+- Flows: `openuispec/flows/`
+- Contracts: `openuispec/contracts/`
+- Platform: `openuispec/platform/`
+- Locales: `openuispec/locales/`
 
-**Note:** These are the default paths. Actual paths are in `includes:` in `openuispec.yaml` and may use relative paths (e.g. `../../shared/locales`). Always read `openuispec.yaml` to find the real directories.
+**Note:** These are the default paths. Actual paths are in `includes:` in `openuispec.yaml` and may use relative paths. Always read `openuispec.yaml` to find the real directories.
 
 ## If spec directories are empty (first-time setup)
 This means the project has existing UI code but hasn't been specced yet. Your job:
 
-1. **Find existing screens** — scan the codebase for UI screen files (SwiftUI views, Compose screens, React components/pages).
-2. **Create stubs** — for each screen, create `openuispec/screens/<name>.yaml` with:
+1. **Read the spec first** — find and read `spec/openuispec-v0.1.md` from the installed package.
+2. **Find existing screens** — scan the codebase for UI screen files.
+3. **Create stubs** — for each screen, create `openuispec/screens/<name>.yaml` with:
    ```yaml
    screen_name:
      semantic: "Brief description of what this screen does"
@@ -31,14 +54,8 @@ This means the project has existing UI code but hasn't been specced yet. Your jo
      layout:
        type: scroll_vertical
    ```
-3. **Extract tokens** — scan the codebase for colors, fonts, spacing values and create token files in `openuispec/tokens/`.
-4. **Update the manifest** — fill in `data_model` and `api.endpoints` in `openuispec/openuispec.yaml` based on the existing code.
-5. **Spec screens on demand** — when the user asks to spec a screen, read the native code, create a full spec, and change `status: draft` → `ready`.
-
-## Screen and flow status
-- `stub` — placeholder, not yet specced. Drift detection skips these.
-- `draft` — actively being specced. Tracked by drift.
-- `ready` — fully specified (default if omitted). Tracked by drift.
+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.
@@ -49,79 +66,15 @@ This means the project has existing UI code but hasn't been specced yet. Your jo
 
 ## After modifying spec files
 1. Run `openuispec validate` to check specs against the schema.
-2. Run `openuispec drift --snapshot --target <target>` for each affected platform.
-3. Run `openuispec drift` to verify no untracked drift remains.
-
-## Learning OpenUISpec — where to find the docs
-All documentation is in the installed `openuispec` package. Search in this order:
-1. **Local:** `node_modules/openuispec/` (project dependency)
-2. **Global:** run `npm root -g` to get the global prefix, then look in `<prefix>/openuispec/`
-3. **Online fallback:** if not installed, fetch from:
-   - `https://openuispec.rsteam.uz/llms-full.txt` — complete spec + all JSON schemas
-   - `https://openuispec.rsteam.uz/llms.txt` — concise summary with links
-
-Inside the package:
-1. **Full specification:** `spec/openuispec-v0.1.md` — the complete spec (read this to understand the format)
-2. **Example app:** `examples/taskflow/` — a complete working app with all file types
-3. **JSON Schemas:** `schema/` — validation schemas that define the exact structure of every file type
-
-## Token file structure — root wrapper key required
-Every token file must have a single root key matching the token type. Do NOT put properties at the top level.
-- `tokens/color.yaml` → root key: `color`
-- `tokens/typography.yaml` → root key: `typography`
-- `tokens/spacing.yaml` → root key: `spacing`
-- `tokens/elevation.yaml` → root key: `elevation`
-- `tokens/motion.yaml` → root key: `motion`
-- `tokens/layout.yaml` → root key: `layout`
-- `tokens/themes.yaml` → root key: `themes`
-- `tokens/icons.yaml` → root key: `icons`
-
-## File formats and schemas — read before creating spec files
-Before creating or editing any spec file, read the corresponding JSON Schema. Do not guess the file format.
-
-| File | Schema (in `schema/` inside the installed package) | Root key |
-|------|--------|----------|
-| `openuispec.yaml` | `openuispec.schema.json` | `spec_version` |
-| `screens/*.yaml` | `screen.schema.json` | `<screen_id>` |
-| `flows/*.yaml` | `flow.schema.json` | `<flow_id>` |
-| `platform/*.yaml` | `platform.schema.json` | `platform` |
-| `locales/*.json` | `locale.schema.json` | (object) |
-| `contracts/x_*.yaml` | `custom-contract.schema.json` | `contract` |
-| `tokens/color.yaml` | `tokens/color.schema.json` | `color` |
-| `tokens/typography.yaml` | `tokens/typography.schema.json` | `typography` |
-| `tokens/spacing.yaml` | `tokens/spacing.schema.json` | `spacing` |
-| `tokens/elevation.yaml` | `tokens/elevation.schema.json` | `elevation` |
-| `tokens/motion.yaml` | `tokens/motion.schema.json` | `motion` |
-| `tokens/layout.yaml` | `tokens/layout.schema.json` | `layout` |
-| `tokens/themes.yaml` | `tokens/themes.schema.json` | `themes` |
-| `tokens/icons.yaml` | `tokens/icons.schema.json` | `icons` |
-
-Shared type definitions (actions, data-binding, adaptive, validation, common) are in `schema/defs/`.
-
-Workflow: read the schema → read an example from `examples/taskflow/` → create the YAML → run `openuispec validate`.
-
-## Spec format reference
-- 7 contract families: nav_container, surface, action_trigger, input_field, data_display, collection, feedback
-- Custom contracts: prefixed with `x_` (e.g., `x_media_player`)
-- Data binding: `$data:`, `$state:`, `$param:`, `$t:` prefixes
-- Actions: typed objects (navigate, api_call, set_state, confirm, sequence, feedback, etc.)
-- Adaptive layout: size classes (compact, regular, expanded) with per-section overrides
-
-## Output directories
-Drift tracks spec changes per target. By default state is stored in `generated/<target>/<project>/`.
-To map targets to actual code directories, set `generation.output_dir` in `openuispec.yaml`:
-```yaml
-generation:
-  output_dir:
-    web: "../web-ui/"
-    android: "../kmp-ui/"
-    ios: "../kmp-ui/iosApp/"
-```
-Paths are relative to `openuispec.yaml`. The `.openuispec-state.json` file is stored inside each output directory.
+2. **Update the generated code** for each affected platform to match the new spec.
+3. Run `openuispec drift --snapshot --target <target>` to baseline the updated state.
+4. Run `openuispec drift` to verify no untracked drift remains.
 
 ## CLI commands
 - `openuispec init` — scaffold a new spec project
 - `openuispec validate [group...]` — validate spec files against schemas
 - `openuispec drift --target <t>` — check for spec drift
 - `openuispec drift --snapshot --target <t>` — snapshot current state
+- `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,3 +1,5 @@
+<!-- openuispec-rules-start -->
+<!-- openuispec-rules-version: 0.1.22 -->
 # OpenUISpec — AI Assistant Rules
 # ================================
 # This project uses OpenUISpec to define UI as a semantic spec.
@@ -64,12 +66,15 @@ This means the project has existing UI code but hasn't been specced yet. Your jo
 
 ## After modifying spec files
 1. Run `openuispec validate` to check specs against the schema.
-2. Run `openuispec drift --snapshot --target <target>` for each affected platform.
-3. Run `openuispec drift` to verify no untracked drift remains.
+2. **Update the generated code** for each affected platform to match the new spec.
+3. Run `openuispec drift --snapshot --target <target>` to baseline the updated state.
+4. Run `openuispec drift` to verify no untracked drift remains.
 
 ## CLI commands
 - `openuispec init` — scaffold a new spec project
 - `openuispec validate [group...]` — validate spec files against schemas
 - `openuispec drift --target <t>` — check for spec drift
 - `openuispec drift --snapshot --target <t>` — snapshot current state
+- `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/screens/home.yaml

@@ -122,7 +122,7 @@ home:
           item_variant: compact
           item_props_map:
             title: "item.title"
-            subtitle: "{item.due_date | format:date_relative}"
+            subtitle: "{item.due_date | format:date_relative.abbreviated}"
             leading:
               contract: input_field
               input_type: checkbox

package/examples/todo-orbit/openuispec/screens/settings.yaml

@@ -61,6 +61,7 @@ settings:
         children:
           - contract: input_field
             input_type: select
+            render_hint: segmented
             props:
               label: "$t:settings.language"
               icon: { ref: "globe", position: leading }
@@ -71,6 +72,7 @@ settings:
 
           - contract: input_field
             input_type: select
+            render_hint: segmented
             props:
               label: "$t:settings.theme"
               options:

package/package.json

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

package/schema/defs/action.schema.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://openuispec.org/schema/defs/action.schema.json",
   "title": "OpenUISpec Action",
-  "description": "Discriminated union of the 13 action types in OpenUISpec",
+  "description": "Discriminated union of the 14 action types in OpenUISpec",
 
   "type": "object",
   "required": ["type"],