openuispec 0.2.11 → 0.2.13

package/README.md

@@ -46,7 +46,7 @@ This scaffolds a spec directory, starter tokens, and **configures the MCP server
 ## Key concepts
 
 - **Tokens** — design values (color, typography, spacing, elevation, motion) with semantic names and constrained ranges
-- **Contracts** — 7 behavioral component families defined by role, props, state machines, and accessibility
+- **Contracts** — 7 reusable UI component families defined by role, props, interaction states, and accessibility
 - **Screens** — compositions of contracts with data bindings, adaptive layout, and conditional rendering
 - **Flows** — multi-screen navigation journeys, intent-based and platform-agnostic
 - **Actions** — 13 typed action types with composition, error handling, and optimistic updates
@@ -80,7 +80,7 @@ When you ask your AI to "add a settings page" or "update the home feed," the MCP
 
 **Using without MCP?** You can provide spec context to any AI manually:
 
-> Generate a native iOS app from this OpenUISpec. Follow all contract state machines, apply token ranges for iOS, and implement navigation flows as defined.
+> Generate a native iOS app from this OpenUISpec. Follow all contract UI states, apply token ranges for iOS, and implement navigation flows as defined.
 
 ## Examples
 

package/check/index.ts

@@ -14,10 +14,13 @@ import { existsSync, readFileSync } from "node:fs";
 import { join, resolve } from "node:path";
 import YAML from "yaml";
 import {
+  computeSharedDrift,
   findProjectDir,
+  hasDriftChanges,
   readManifest,
   readProjectName,
   resolveOutputDir,
+  sharedLayersForTarget,
 } from "../drift/index.js";
 import {
   buildAjv,
@@ -153,6 +156,20 @@ function determinePrepare(
     );
   }
 
+  // Check for shared layer drift (only when tracks are configured)
+  const sharedLayers = sharedLayersForTarget(projectDir, target);
+  for (const layer of sharedLayers) {
+    if (layer.tracks.length === 0) continue;
+    const driftResult = computeSharedDrift(projectDir, layer);
+    if (driftResult.state !== null) {
+      if (hasDriftChanges(driftResult.drift)) {
+        warnings.push(
+          `Shared layer "${layer.name}" has spec drift — shared code may need updates before ${target} generation.`
+        );
+      }
+    }
+  }
+
   const ready =
     missing.length === 0 && backendContextReady && !pendingUserConfirmation;
 

package/cli/index.ts

@@ -95,6 +95,19 @@ function checkRulesVersion(): void {
 
 // ── spec helpers (shared with MCP server) ────────────────────────────
 
+function lookupLocaleKey(content: Record<string, unknown>, key: string): { found: boolean; value: unknown } {
+  if (key in content) return { found: true, value: content[key] };
+  const parts = key.split(".");
+  let current: unknown = content;
+  for (const part of parts) {
+    if (current === null || current === undefined || typeof current !== "object" || Array.isArray(current)) {
+      return { found: false, value: undefined };
+    }
+    current = (current as Record<string, unknown>)[part];
+  }
+  return current !== undefined ? { found: true, value: current } : { found: false, value: undefined };
+}
+
 function resolveSpecDir(projectDir: string, manifest: any, key: string): string {
   return resolve(projectDir, manifest.includes?.[key] ?? `./${key}/`);
 }
@@ -293,7 +306,10 @@ async function main(): Promise<void> {
       const content = JSON.parse(readFileSync(filePath, "utf-8"));
       if (keys) {
         const filtered: Record<string, unknown> = {};
-        for (const key of keys) { if (key in content) filtered[key] = content[key]; }
+        for (const key of keys) {
+          const result = lookupLocaleKey(content, key);
+          if (result.found) filtered[key] = result.value;
+        }
         console.log(JSON.stringify(filtered, null, 2));
       } else {
         console.log(JSON.stringify(content, null, 2));

package/cli/init.ts

@@ -33,6 +33,7 @@ export type InitOptionsResponse = {
     options?: string[];
   }>;
   configure_targets_note: string;
+  shared_layer_note?: string;
 };
 
 export function listInitOptions(): InitOptionsResponse {
@@ -78,9 +79,17 @@ export function listInitOptions(): InitOptionsResponse {
         type: "yes_no",
         default: defaults.configureTargets,
       },
+      {
+        key: "with_shared",
+        prompt: "Does the project share code between platforms (e.g. KMP commonMain)?",
+        type: "yes_no",
+        default: false,
+      },
     ],
     configure_targets_note:
       "If configure_targets is true, use `openuispec configure-target <target> --list-options` for each target after init to present stack choices to the user.",
+    shared_layer_note:
+      "If with_shared is true, add shared layer config to generation.shared in the manifest. Each shared layer needs: name, platforms (subset of targets), language, root (path relative to openuispec.yaml), tracks (spec categories: manifest, contracts, flows, screens, tokens, platform, locales), and scope (what code belongs there). Also add generation.structure entries for each target to define where platform-specific UI code goes and its scope.",
   };
 }
 
@@ -171,7 +180,12 @@ function getPackageVersion(): string {
 function manifestTemplate(
   name: string,
   targets: string[],
-  options: { withApi: boolean; backendPath: string | null }
+  options: {
+    withApi: boolean;
+    backendPath: string | null;
+    sharedLayers: SharedLayerAnswers[];
+    structures: StructureAnswers[];
+  }
 ): string {
   const targetList = targets.join(", ");
   const outputLines = targets
@@ -186,6 +200,38 @@ function manifestTemplate(
     })
     .join("\n");
 
+  function yamlPathsBlock(paths: Record<string, string>): string {
+    const entries = Object.entries(paths);
+    return entries.length > 0
+      ? `\n      paths:\n${entries.map(([k, v]) => `        ${k}: "${v}"`).join("\n")}`
+      : "";
+  }
+
+  let sharedBlock = "";
+  if (options.sharedLayers.length > 0) {
+    const layers = options.sharedLayers.map((layer) => {
+      const tracksLine = layer.tracks.length > 0
+        ? `\n      tracks: [${layer.tracks.join(", ")}]`
+        : "";
+      return `    ${layer.name}:
+      platforms: [${layer.platforms.join(", ")}]
+      language: ${layer.language}
+      root: "${layer.root}"
+      scope: "${layer.scope}"${tracksLine}${yamlPathsBlock(layer.paths)}`;
+    }).join("\n");
+    sharedBlock = `  shared:\n${layers}\n`;
+  }
+
+  let structureBlock = "";
+  if (options.structures.length > 0) {
+    const entries = options.structures.map((s) => {
+      const scopeLine = s.scope ? `\n      scope: "${s.scope}"` : "";
+      return `    ${s.target}:
+      root: "${s.root}"${scopeLine}${yamlPathsBlock(s.paths)}`;
+    }).join("\n");
+    structureBlock = `  structure:\n${entries}\n`;
+  }
+
   return `# ${name} — OpenUISpec v0.1
 spec_version: "0.1"
 
@@ -218,7 +264,7 @@ ${options.withApi ? `  code_roots:
     backend: "${options.backendPath}"                # Required when api.endpoints are declared
 ` : ""}  output_format:
 ${outputLines}
-
+${sharedBlock}${structureBlock}
 data_model: {}
 
 api:
@@ -679,6 +725,23 @@ export function extractRulesVersion(filePath: string): string | null {
 
 export { getPackageVersion };
 
+interface SharedLayerAnswers {
+  name: string;
+  platforms: string[];
+  language: string;
+  root: string;
+  tracks: string[];
+  scope: string;
+  paths: Record<string, string>;
+}
+
+interface StructureAnswers {
+  target: string;
+  root: string;
+  scope: string;
+  paths: Record<string, string>;
+}
+
 interface InitOptions {
   defaults: boolean;
   quiet: boolean;
@@ -688,6 +751,7 @@ interface InitOptions {
   withApi?: boolean;
   backendPath?: string;
   configureTargets?: boolean;
+  withShared?: boolean;
 }
 
 interface InitAnswers {
@@ -697,6 +761,8 @@ interface InitAnswers {
   withApi: boolean;
   backendPath: string | null;
   configureTargets: boolean;
+  sharedLayers: SharedLayerAnswers[];
+  structures: StructureAnswers[];
 }
 
 function parseTargetsValue(raw: string): string[] {
@@ -752,6 +818,12 @@ function parseInitArgs(argv: string[]): InitOptions {
       case "--no-configure-targets":
         options.configureTargets = false;
         break;
+      case "--with-shared":
+        options.withShared = true;
+        break;
+      case "--no-shared":
+        options.withShared = false;
+        break;
       default:
         if (arg.startsWith("--")) {
           console.error(`Error: Unknown init option: ${arg}`);
@@ -773,9 +845,127 @@ function collectDefaults(): InitAnswers {
     withApi: true,
     backendPath: "../backend/",
     configureTargets: true,
+    sharedLayers: [],
+    structures: [],
   };
 }
 
+const SHARED_LAYER_DEFAULTS: Record<string, {
+  language: string;
+  root: string;
+  tracks: string[];
+  scope: string;
+  paths: Record<string, string>;
+  structureScope: Record<string, string>;
+}> = {
+  kmp: {
+    language: "kotlin",
+    root: "../shared",
+    tracks: [],
+    scope: "Business logic, data models, repositories, API clients, view models/stores. No UI rendering.",
+    paths: { domain: "commonMain/domain/", features: "commonMain/features/" },
+    structureScope: {
+      ios: "Pure SwiftUI views and navigation. All business logic comes from the shared layer.",
+      android: "Pure Compose UI and navigation. All business logic comes from the shared layer.",
+    },
+  },
+};
+
+function defaultSharedConfig(targets: string[]): {
+  sharedLayers: SharedLayerAnswers[];
+  structures: StructureAnswers[];
+} {
+  const mobilePlatforms = targets.filter((t) => t === "ios" || t === "android");
+  if (mobilePlatforms.length < 2) {
+    return { sharedLayers: [], structures: [] };
+  }
+
+  const preset = SHARED_LAYER_DEFAULTS.kmp;
+  const sharedLayers: SharedLayerAnswers[] = [{
+    name: "mobile_common",
+    platforms: mobilePlatforms,
+    language: preset.language,
+    root: preset.root,
+    tracks: preset.tracks,
+    scope: preset.scope,
+    paths: preset.paths,
+  }];
+
+  const structures: StructureAnswers[] = mobilePlatforms.map((t) => ({
+    target: t,
+    root: preset.root,
+    scope: preset.structureScope[t] ?? `Pure ${t} UI. Business logic comes from the shared layer.`,
+    paths: { ui: `${t}App/ui/` },
+  }));
+
+  return { sharedLayers, structures };
+}
+
+async function collectSharedLayerAnswers(
+  rl: ReturnType<typeof createInterface>,
+  targets: string[],
+): Promise<{ sharedLayers: SharedLayerAnswers[]; structures: StructureAnswers[] }> {
+  const withShared = await askYesNo(rl, "\nShare code between platforms (e.g. KMP commonMain)?", false);
+  if (!withShared) return { sharedLayers: [], structures: [] };
+
+  const defaults = defaultSharedConfig(targets);
+  const defaultLayer = defaults.sharedLayers[0];
+  if (!defaultLayer) return { sharedLayers: [], structures: [] };
+
+  console.log("\n  Shared layer defaults (KMP):");
+  console.log(`    platforms: ${defaultLayer.platforms.join(", ")}`);
+  console.log(`    language: ${defaultLayer.language}`);
+  console.log(`    root: ${defaultLayer.root}`);
+  console.log(`    scope: ${defaultLayer.scope}`);
+
+  const useDefaults = await askYesNo(rl, "  Use these defaults?", true);
+  if (useDefaults) return defaults;
+
+  const layerName = await ask(rl, "  Shared layer name", defaultLayer.name);
+  const platformsRaw = await askList(rl, "  Platforms", targets, defaultLayer.platforms);
+  const language = await ask(rl, "  Language", defaultLayer.language);
+  const root = await ask(rl, "  Root path (relative to openuispec.yaml)", defaultLayer.root);
+  const scope = await ask(rl, "  Scope (what code belongs here)", defaultLayer.scope);
+  const wantTracks = await askYesNo(rl, "  Enable hash-based drift tracking for this layer?", false);
+  const tracksRaw = wantTracks
+    ? await askList(
+        rl,
+        "  Tracked spec categories",
+        ["manifest", "tokens", "contracts", "screens", "flows", "platform", "locales"],
+        ["manifest", "contracts", "flows"]
+      )
+    : [];
+
+  const sharedLayers: SharedLayerAnswers[] = [{
+    name: layerName,
+    platforms: platformsRaw,
+    language,
+    root,
+    tracks: tracksRaw,
+    scope,
+    paths: defaultLayer.paths,
+  }];
+
+  const structures: StructureAnswers[] = [];
+  for (const t of platformsRaw) {
+    const defaultStructure = defaults.structures.find((s) => s.target === t);
+    const structRoot = await ask(rl, `  ${t} structure root`, defaultStructure?.root ?? root);
+    const structScope = await ask(
+      rl,
+      `  ${t} scope (what code belongs in the ${t} target)`,
+      defaultStructure?.scope ?? `Pure ${t} UI rendering.`
+    );
+    structures.push({
+      target: t,
+      root: structRoot,
+      scope: structScope,
+      paths: defaultStructure?.paths ?? { ui: `${t}App/ui/` },
+    });
+  }
+
+  return { sharedLayers, structures };
+}
+
 async function collectInteractiveAnswers(rl: ReturnType<typeof createInterface>): Promise<InitAnswers> {
   const defaults = collectDefaults();
   const name = await ask(rl, "Project name", defaults.name);
@@ -792,6 +982,7 @@ async function collectInteractiveAnswers(rl: ReturnType<typeof createInterface>)
     ? await ask(rl, "Backend folder path relative to openuispec.yaml", defaults.backendPath ?? "../backend/")
     : null;
   const configureTargets = await askYesNo(rl, "Configure target stacks now?", defaults.configureTargets);
+  const { sharedLayers, structures } = await collectSharedLayerAnswers(rl, targets);
 
   return {
     name,
@@ -800,6 +991,8 @@ async function collectInteractiveAnswers(rl: ReturnType<typeof createInterface>)
     withApi,
     backendPath,
     configureTargets,
+    sharedLayers,
+    structures,
   };
 }
 
@@ -823,6 +1016,8 @@ function collectNonInteractiveAnswers(argv: string[]): InitAnswers {
 
   const withApi = parsed.withApi ?? defaults.withApi;
   const backendPath = withApi ? parsed.backendPath ?? defaults.backendPath : null;
+  const withShared = parsed.withShared ?? false;
+  const { sharedLayers, structures } = withShared ? defaultSharedConfig(targets) : { sharedLayers: [], structures: [] };
 
   return {
     name: parsed.name ?? defaults.name,
@@ -831,6 +1026,8 @@ function collectNonInteractiveAnswers(argv: string[]): InitAnswers {
     withApi,
     backendPath,
     configureTargets: parsed.configureTargets ?? defaults.configureTargets,
+    sharedLayers,
+    structures,
   };
 }
 
@@ -879,6 +1076,8 @@ export async function init(argv: string[] = []): Promise<void> {
       manifestTemplate(answers.name, answers.targets, {
         withApi: answers.withApi,
         backendPath: answers.backendPath,
+        sharedLayers: answers.sharedLayers,
+        structures: answers.structures,
       }),
       quiet
     );

package/docs/file-formats.md

@@ -64,6 +64,42 @@ Paths are relative to `openuispec.yaml`. The `.openuispec-state.json` file recor
 - `generation.extra_rules` can hold project-wide generation conventions
 - `drift --snapshot` requires that target output directory to already exist
 
+## Shared code layers
+
+Projects that share business logic between platforms (e.g. KMP `commonMain`) can declare `generation.shared` to tell AI what code belongs in the shared layer vs platform-specific targets:
+
+```yaml
+generation:
+  targets: [ios, android, web]
+  shared:
+    mobile_common:
+      platforms: [ios, android]
+      language: kotlin
+      root: "../shared"
+      scope: "Business logic, data models, repositories, API clients, view models. No UI rendering."
+      # tracks: [manifest]              # optional — enables hash-based drift detection for this layer
+      paths:
+        domain: "commonMain/domain/"
+        features: "commonMain/features/"
+  structure:
+    ios:
+      root: "../shared"
+      scope: "Pure SwiftUI views and navigation. All business logic comes from the shared layer."
+      paths:
+        ui: "iosApp/ui/"
+    android:
+      root: "../shared"
+      scope: "Pure Compose UI and navigation. All business logic comes from the shared layer."
+      paths:
+        ui: "androidApp/ui/"
+```
+
+- **`scope`** (required on shared, optional on structure) — tells AI what code belongs where. This is the primary mechanism for routing generation work between shared and platform layers.
+- **`tracks`** (optional) — when set, enables hash-based drift detection scoped to specific spec categories (`manifest`, `tokens`, `contracts`, `screens`, `flows`, `platform`, `locales`). When omitted, the shared layer relies on `scope` alone.
+- **`structure`** — when present, overrides the heuristic code root discovery for a target. Paths are relative to `root`.
+- Shared layers are not targets — they are tracked alongside targets in `prepare` and `status` output.
+- `openuispec init --with-shared` scaffolds KMP defaults when both ios and android targets are selected.
+
 ## Spec sections overview
 
 | Section | What it defines |

package/docs/implementation-notes.md

@@ -87,6 +87,13 @@
   - backend generation context
     - if the manifest declares `api.endpoints`, `generation.code_roots.backend` is required
     - `prepare` should surface the resolved backend root so AI can inspect backend code when generating API clients
+- Shared code layers (`generation.shared`):
+  - when configured, `prepare` includes `shared_layers` in its output with per-layer `scope`, `already_generated`, and `guidance`
+  - `scope` tells AI what code belongs in the shared layer vs the platform target — this is the primary routing mechanism
+  - optional `tracks` enables hash-based drift detection scoped to specific spec categories
+  - `generation.structure` overrides heuristic code root discovery when present, and its `scope` field tells AI what goes in the platform-specific target
+  - `suggestCodeRoots` includes shared layer roots and structure paths alongside target output directories
+  - generation rules include shared layer and target scope descriptions
 - Important positioning:
   - `prepare` does not generate code
   - `prepare` does not verify code correctness