openuispec 0.1.12 → 0.1.14

package/cli/index.ts

@@ -45,7 +45,7 @@ Usage:
 
 Validate groups: manifest, tokens, screens, flows, platform, locales, custom_contracts
 
-Docs: node_modules/openuispec/spec/openuispec-v0.1.md
+Docs: https://openuispec.rsteam.uz
 `);
       break;
 

package/cli/init.ts

@@ -137,6 +137,12 @@ OpenUISpec is a YAML-based format that describes your app's UI semantically —
 | \`platform/\` | Platform overrides — per-target (iOS, Android, Web) behaviors |
 | \`locales/\` | Localization — i18n strings (JSON, ICU MessageFormat) |
 
+All directory paths are configured in \`openuispec.yaml\` under \`includes:\` and support relative paths. For example, to share locales across projects:
+\`\`\`yaml
+includes:
+  locales: "../../shared/locales"   # resolved relative to openuispec.yaml
+\`\`\`
+
 ## Getting started
 
 **Start here:** read \`openuispec.yaml\` — it's the root manifest that defines the project structure, data model, API endpoints, and generation targets.
@@ -170,16 +176,19 @@ OpenUISpec is a YAML-based format that describes your app's UI semantically —
 - \`draft\` — actively being specced. Tracked by drift.
 - \`ready\` — fully specified (default if omitted). Tracked by drift.
 
-## Learning OpenUISpec — local files and online reference
+## Learning OpenUISpec — where to find the docs
 
-All documentation is included in the installed package at \`node_modules/openuispec/\`:
-1. **Full specification:** \`node_modules/openuispec/spec/openuispec-v0.1.md\`
-2. **Example app:** \`node_modules/openuispec/examples/taskflow/\`
-3. **JSON Schemas:** \`node_modules/openuispec/schema/\`
+All documentation is included in the installed \`openuispec\` package. Search for it in this order:
+1. **Local:** \`node_modules/openuispec/\` (if installed as a project dependency)
+2. **Global:** run \`npm root -g\` to find the global prefix, then look in \`<prefix>/openuispec/\`
+3. **Online fallback:** if the package is not installed at all, fetch from:
+   - \`https://openuispec.rsteam.uz/llms-full.txt\` — complete spec + all JSON schemas in one file
+   - \`https://openuispec.rsteam.uz/llms.txt\` — concise summary with links
 
-If the package is not in node_modules, fetch the full reference from:
-- \`https://openuispec.rsteam.uz/llms-full.txt\` — complete spec + all JSON schemas in one file
-- \`https://openuispec.rsteam.uz/llms.txt\` — concise summary with links
+Inside the package:
+- **Full specification:** \`spec/openuispec-v0.1.md\`
+- **Example app:** \`examples/taskflow/\`
+- **JSON Schemas:** \`schema/\`
 
 ## Token file structure — root wrapper key required
 
@@ -219,9 +228,9 @@ Root keys: \`color\`, \`typography\`, \`spacing\`, \`elevation\`, \`motion\`, \`
 | \`tokens/themes.yaml\` | \`tokens/themes.schema.json\` | \`themes\` |
 | \`tokens/icons.yaml\` | \`tokens/icons.schema.json\` | \`icons\` |
 
-All schemas are in \`node_modules/openuispec/schema/\`. Shared type definitions (actions, data-binding, adaptive, validation, common) are in \`schema/defs/\`.
+All schemas are in \`schema/\` inside the installed package. Shared type definitions (actions, data-binding, adaptive, validation, common) are in \`schema/defs/\`.
 
-**Workflow:** read the schema → read an example from \`node_modules/openuispec/examples/taskflow/\` → create the YAML → run \`openuispec validate\`.
+**Workflow:** read the schema → read an example from \`examples/taskflow/\` → create the YAML → run \`openuispec validate\`.
 
 ## Spec format quick reference
 
@@ -247,12 +256,12 @@ This project generates native code for: **${targetList}**
 
 ## Learn more
 
-All docs and examples are local in \`node_modules/openuispec/\` — read from disk, not from GitHub.
+All docs and examples are in the installed \`openuispec\` package — check \`node_modules/openuispec/\` or run \`npm root -g\` for the global install path.
 
-- Full spec: \`node_modules/openuispec/spec/openuispec-v0.1.md\`
-- Example app: \`node_modules/openuispec/examples/taskflow/\`
-- JSON Schemas: \`node_modules/openuispec/schema/\`
-- Repository: \`node_modules/openuispec/\` (all files included)
+- Full spec: \`spec/openuispec-v0.1.md\`
+- Example app: \`examples/taskflow/\`
+- JSON Schemas: \`schema/\`
+- Online reference: \`https://openuispec.rsteam.uz/llms-full.txt\`
 `;
 }
 
@@ -278,6 +287,8 @@ OpenUISpec is a YAML-based spec format that describes an app's UI semantically
 - Platform: \`${specDir}/platform/\` — per-target overrides (iOS, Android, Web)
 - Locales: \`${specDir}/locales/\` — i18n strings (JSON, ICU MessageFormat)
 
+**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.
+
 ## If spec directories are empty (first-time setup)
 This means the project has existing UI code but hasn't been specced yet. Your job:
 
@@ -311,15 +322,18 @@ This means the project has existing UI code but hasn't been specced yet. Your jo
 2. Run \`openuispec drift --snapshot --target <target>\` for each affected platform.
 3. Run \`openuispec drift\` to verify no untracked drift remains.
 
-## Learning OpenUISpec — local files and online reference
-All documentation is included in the installed package at \`node_modules/openuispec/\`:
-1. **Full specification:** \`node_modules/openuispec/spec/openuispec-v0.1.md\` — the complete spec (read this to understand the format)
-2. **Example app:** \`node_modules/openuispec/examples/taskflow/\` — a complete working app with all file types
-3. **JSON Schemas:** \`node_modules/openuispec/schema/\` — validation schemas that define the exact structure of every file type
+## 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
 
-If the package is not in node_modules, fetch the full reference from:
-- \`https://openuispec.rsteam.uz/llms-full.txt\` — complete spec + all JSON schemas in one file
-- \`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.
@@ -335,7 +349,7 @@ Every token file must have a single root key matching the token type. Do NOT put
 ## 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 \`node_modules/openuispec/schema/\`) | Root key |
+| File | Schema (in \`schema/\` inside the installed package) | Root key |
 |------|--------|----------|
 | \`openuispec.yaml\` | \`openuispec.schema.json\` | \`spec_version\` |
 | \`screens/*.yaml\` | \`screen.schema.json\` | \`<screen_id>\` |
@@ -354,7 +368,7 @@ Before creating or editing any spec file, read the corresponding JSON Schema. Do
 
 Shared type definitions (actions, data-binding, adaptive, validation, common) are in \`schema/defs/\`.
 
-Workflow: read the schema → read an example from \`node_modules/openuispec/examples/taskflow/\` → create the YAML → run \`openuispec validate\`.
+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
@@ -499,7 +513,7 @@ Commands:
 
 AI rules have been added to CLAUDE.md and AGENTS.md.
 
-Docs: node_modules/openuispec/spec/openuispec-v0.1.md
+Docs: https://openuispec.rsteam.uz
 `);
   } catch (err) {
     rl.close();

package/package.json

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

package/schema/locale.schema.json

@@ -18,9 +18,25 @@
   },
   "patternProperties": {
     "^[a-zA-Z_][a-zA-Z0-9_.]*$": {
-      "type": "string",
-      "description": "Translation string (ICU MessageFormat)"
+      "$ref": "#/$defs/message_value"
     }
   },
-  "additionalProperties": false
+  "additionalProperties": false,
+  "$defs": {
+    "message_value": {
+      "description": "Translation string (ICU MessageFormat) or nested group of translations",
+      "oneOf": [
+        { "type": "string" },
+        {
+          "type": "object",
+          "patternProperties": {
+            "^[a-zA-Z_][a-zA-Z0-9_.]*$": {
+              "$ref": "#/$defs/message_value"
+            }
+          },
+          "additionalProperties": false
+        }
+      ]
+    }
+  }
 }

package/schema/validate.ts

@@ -97,10 +97,8 @@ function validateFile(
   }
 
   // Convert schema URL to a local path for display
-  const schemaLocalPath = schemaId.replace(
-    BASE,
-    "node_modules/openuispec/schema/",
-  );
+  const schemaRelPath = schemaId.replace(BASE, "");
+  const schemaLocalPath = resolve(SCHEMA_DIR, schemaRelPath);
 
   const errors: ErrorObject[] = validate.errors ?? [];
   console.log(`  FAIL  ${name} (${errors.length} error(s))`);
@@ -150,9 +148,46 @@ function validateFile(
 
 // ── validation groups ────────────────────────────────────────────────
 
+// ── includes resolution ──────────────────────────────────────────────
+
+interface Includes {
+  tokens: string;
+  contracts: string;
+  screens: string;
+  flows: string;
+  platform: string;
+  locales: string;
+}
+
+const DEFAULT_INCLUDES: Includes = {
+  tokens: "./tokens/",
+  contracts: "./contracts/",
+  screens: "./screens/",
+  flows: "./flows/",
+  platform: "./platform/",
+  locales: "./locales/",
+};
+
+function readIncludes(projectDir: string): Includes {
+  const manifestPath = join(projectDir, "openuispec.yaml");
+  try {
+    const manifest = loadYaml(manifestPath) as Record<string, unknown>;
+    const inc = manifest?.includes as Partial<Includes> | undefined;
+    return { ...DEFAULT_INCLUDES, ...inc };
+  } catch {
+    return DEFAULT_INCLUDES;
+  }
+}
+
+function resolveInclude(projectDir: string, includePath: string): string {
+  return resolve(projectDir, includePath);
+}
+
+// ── validation groups ────────────────────────────────────────────────
+
 interface ValidationGroup {
   label: string;
-  run(ajv: AjvInstance, projectDir: string): number;
+  run(ajv: AjvInstance, projectDir: string, includes: Includes): number;
 }
 
 const GROUPS: Record<string, ValidationGroup> = {
@@ -169,8 +204,9 @@ const GROUPS: Record<string, ValidationGroup> = {
 
   tokens: {
     label: "Tokens",
-    run(ajv, projectDir) {
+    run(ajv, projectDir, includes) {
       let errors = 0;
+      const tokensDir = resolveInclude(projectDir, includes.tokens);
       const tokenMap: Record<string, string> = {
         "color.yaml": "color.schema.json",
         "typography.yaml": "typography.schema.json",
@@ -182,7 +218,7 @@ const GROUPS: Record<string, ValidationGroup> = {
         "icons.yaml": "icons.schema.json",
       };
       for (const [data, schema] of Object.entries(tokenMap)) {
-        const filePath = join(projectDir, "tokens", data);
+        const filePath = join(tokensDir, data);
         if (existsSync(filePath)) {
           errors += validateFile(ajv, filePath, `${BASE}tokens/${schema}`);
         }
@@ -193,9 +229,10 @@ const GROUPS: Record<string, ValidationGroup> = {
 
   screens: {
     label: "Screens",
-    run(ajv, projectDir) {
+    run(ajv, projectDir, includes) {
       let errors = 0;
-      for (const f of listFiles(join(projectDir, "screens"), ".yaml")) {
+      const dir = resolveInclude(projectDir, includes.screens);
+      for (const f of listFiles(dir, ".yaml")) {
         errors += validateFile(ajv, f, `${BASE}screen.schema.json`);
       }
       return errors;
@@ -204,9 +241,10 @@ const GROUPS: Record<string, ValidationGroup> = {
 
   flows: {
     label: "Flows",
-    run(ajv, projectDir) {
+    run(ajv, projectDir, includes) {
       let errors = 0;
-      for (const f of listFiles(join(projectDir, "flows"), ".yaml")) {
+      const dir = resolveInclude(projectDir, includes.flows);
+      for (const f of listFiles(dir, ".yaml")) {
         errors += validateFile(ajv, f, `${BASE}flow.schema.json`);
       }
       return errors;
@@ -215,9 +253,10 @@ const GROUPS: Record<string, ValidationGroup> = {
 
   platform: {
     label: "Platform",
-    run(ajv, projectDir) {
+    run(ajv, projectDir, includes) {
       let errors = 0;
-      for (const f of listFiles(join(projectDir, "platform"), ".yaml")) {
+      const dir = resolveInclude(projectDir, includes.platform);
+      for (const f of listFiles(dir, ".yaml")) {
         errors += validateFile(ajv, f, `${BASE}platform.schema.json`);
       }
       return errors;
@@ -226,9 +265,10 @@ const GROUPS: Record<string, ValidationGroup> = {
 
   locales: {
     label: "Locales",
-    run(ajv, projectDir) {
+    run(ajv, projectDir, includes) {
       let errors = 0;
-      for (const f of listFiles(join(projectDir, "locales"), ".json")) {
+      const dir = resolveInclude(projectDir, includes.locales);
+      for (const f of listFiles(dir, ".json")) {
         errors += validateFile(ajv, f, `${BASE}locale.schema.json`);
       }
       return errors;
@@ -237,9 +277,10 @@ const GROUPS: Record<string, ValidationGroup> = {
 
   custom_contracts: {
     label: "Custom contracts",
-    run(ajv, projectDir) {
+    run(ajv, projectDir, includes) {
       let errors = 0;
-      for (const f of listFiles(join(projectDir, "contracts"), ".yaml")) {
+      const dir = resolveInclude(projectDir, includes.contracts);
+      for (const f of listFiles(dir, ".yaml")) {
         if (basename(f).startsWith("x_")) {
           errors += validateFile(
             ajv,
@@ -293,13 +334,14 @@ export function runValidate(argv: string[]): void {
   }
 
   const projectDir = findProjectDir(process.cwd());
+  const includes = readIncludes(projectDir);
   const ajv = buildAjv();
   let totalErrors = 0;
 
   for (const key of selected) {
     const group = GROUPS[key];
     console.log(`\n${group.label}:`);
-    totalErrors += group.run(ajv, projectDir);
+    totalErrors += group.run(ajv, projectDir, includes);
   }
 
   console.log(`\n${"=".repeat(50)}`);