openuispec 0.1.13 → 0.1.15

package/README.md

@@ -155,6 +155,21 @@ brand:
 
 Validate with: `openuispec validate`
 
+## Output directories
+
+By default, drift stores state in `generated/<target>/<project>/`. To point targets to your actual code directories, add `output_dir` to `openuispec.yaml`:
+
+```yaml
+generation:
+  targets: [ios, android, web]
+  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.
+
 ## Spec at a glance
 
 | Section | What it defines |

package/cli/init.ts

@@ -106,6 +106,10 @@ i18n:
 
 generation:
   targets: [${targetList}]
+  # output_dir:                          # Optional: map targets to code directories
+  #   ios: "../ios-app/"                  # relative to this file
+  #   android: "../android-app/"
+  #   web: "../web-ui/"
   output_format:
 ${outputLines}
 
@@ -137,6 +141,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.
@@ -244,10 +254,23 @@ openuispec drift --snapshot --target ${targets[0]}  # Snapshot current state
 openuispec drift --all          # Include stubs in drift check
 \`\`\`
 
-## Targets
+## Targets and output directories
 
 This project generates native code for: **${targetList}**
 
+By default, drift stores state in \`generated/<target>/<project>/\`. To point targets to your actual code directories, add \`output_dir\` to \`openuispec.yaml\`:
+
+\`\`\`yaml
+generation:
+  targets: [ios, android, web]
+  output_dir:
+    web: "../web-ui/"
+    android: "../kmp-ui/"
+    ios: "../kmp-ui/iosApp/"
+\`\`\`
+
+Paths are relative to \`openuispec.yaml\`.
+
 ## Learn more
 
 All docs and examples are in the installed \`openuispec\` package — check \`node_modules/openuispec/\` or run \`npm root -g\` for the global install path.
@@ -281,6 +304,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:
 
@@ -369,6 +394,18 @@ Workflow: read the schema → read an example from \`examples/taskflow/\` → cr
 - 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.
+
 ## CLI commands
 - \`openuispec init\` — scaffold a new spec project
 - \`openuispec validate [group...]\` — validate spec files against schemas

package/drift/index.ts

@@ -159,27 +159,60 @@ function readProjectName(projectDir: string): string {
   return doc.project?.name ?? basename(projectDir);
 }
 
+/** Read per-target output_dir map from the manifest. */
+function readOutputDirs(projectDir: string): Record<string, string> {
+  try {
+    const doc = YAML.parse(readFileSync(join(projectDir, "openuispec.yaml"), "utf-8"));
+    return doc.generation?.output_dir ?? {};
+  } catch {
+    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 resolveOutputDir(projectDir: string, projectName: string, target: string): string {
+  const outputDirs = readOutputDirs(projectDir);
+  if (outputDirs[target]) {
+    return resolve(projectDir, outputDirs[target]);
+  }
+  // Default: generated/<target>/<project_name> relative to cwd
+  return resolve(projectDir, "..", "generated", target, projectName);
 }
 
-function stateFilePath(cwd: string, projectName: string, target: string): string {
-  return join(resolveOutputDir(cwd, projectName, target), STATE_FILE);
+function stateFilePath(projectDir: string, projectName: string, target: string): string {
+  return join(resolveOutputDir(projectDir, projectName, target), STATE_FILE);
 }
 
-function discoverTargets(cwd: string, projectName: string): string[] {
-  const generatedDir = resolve(cwd, "generated");
-  if (!existsSync(generatedDir)) return [];
-  try {
-    return readdirSync(generatedDir)
-      .filter((entry) =>
-        existsSync(stateFilePath(cwd, projectName, entry))
-      )
-      .sort();
-  } catch {
-    return [];
+function discoverTargets(projectDir: string, projectName: string): string[] {
+  const outputDirs = readOutputDirs(projectDir);
+  const targets: string[] = [];
+
+  // Check configured output_dir entries
+  for (const [target, dir] of Object.entries(outputDirs)) {
+    const resolved = resolve(projectDir, dir);
+    if (existsSync(join(resolved, STATE_FILE))) {
+      targets.push(target);
+    }
+  }
+
+  // Also check default generated/ directory
+  const generatedDir = resolve(projectDir, "..", "generated");
+  if (existsSync(generatedDir)) {
+    try {
+      for (const entry of readdirSync(generatedDir)) {
+        if (!targets.includes(entry)) {
+          const defaultPath = join(generatedDir, entry, projectName, STATE_FILE);
+          if (existsSync(defaultPath)) {
+            targets.push(entry);
+          }
+        }
+      }
+    } catch {
+      // ignore
+    }
   }
+
+  return targets.sort();
 }
 
 /**
@@ -197,7 +230,7 @@ function normalizeEntry(value: string | FileEntry): FileEntry {
 
 function snapshot(cwd: string, projectDir: string, target: string): void {
   const projectName = readProjectName(projectDir);
-  const outDir = resolveOutputDir(cwd, projectName, target);
+  const outDir = resolveOutputDir(projectDir, projectName, target);
   if (!existsSync(outDir)) {
     console.error(
       `Error: Output directory not found: ${relative(cwd, outDir)}\n` +
@@ -226,7 +259,7 @@ function snapshot(cwd: string, projectDir: string, target: string): void {
     files: entries,
   };
 
-  const outPath = stateFilePath(cwd, projectName, target);
+  const outPath = stateFilePath(projectDir, projectName, target);
   writeFileSync(outPath, JSON.stringify(state, null, 2) + "\n");
   console.log(`Snapshot saved: ${relative(cwd, outPath)}`);
   console.log(`  ${Object.keys(entries).length} files hashed`);
@@ -301,7 +334,7 @@ function check(
   includeAll: boolean
 ): void {
   const projectName = readProjectName(projectDir);
-  const statePath = stateFilePath(cwd, projectName, target);
+  const statePath = stateFilePath(projectDir, projectName, target);
   if (!existsSync(statePath)) {
     console.error(
       `No snapshot found for target "${target}".\n` +
@@ -331,7 +364,7 @@ function checkAll(
   includeAll: boolean
 ): void {
   const projectName = readProjectName(projectDir);
-  const targets = discoverTargets(cwd, projectName);
+  const targets = discoverTargets(projectDir, projectName);
   if (targets.length === 0) {
     console.error(
       "No snapshots found. Run: openuispec drift --snapshot --target <target>"
@@ -342,7 +375,7 @@ function checkAll(
   let anyDrift = false;
 
   for (const target of targets) {
-    const statePath = stateFilePath(cwd, projectName, target);
+    const statePath = stateFilePath(projectDir, projectName, target);
     const state: StateFile = JSON.parse(readFileSync(statePath, "utf-8"));
     const result = computeDrift(projectDir, state, includeAll);
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openuispec",
-  "version": "0.1.13",
+  "version": "0.1.15",
   "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/openuispec.schema.json

@@ -104,6 +104,13 @@
             "type": "string"
           }
         },
+        "output_dir": {
+          "type": "object",
+          "description": "Per-target output directory (relative to openuispec.yaml). Defaults to generated/<target>/<project_name> if not set.",
+          "additionalProperties": {
+            "type": "string"
+          }
+        },
         "output_format": {
           "type": "object",
           "description": "Per-target generation config",

package/schema/validate.ts

@@ -148,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> = {
@@ -167,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",
@@ -180,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}`);
         }
@@ -191,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;
@@ -202,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;
@@ -213,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;
@@ -224,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;
@@ -235,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,
@@ -291,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)}`);