openuispec 0.2.18 → 0.2.20

package/dist/cli/init.js

@@ -0,0 +1,1047 @@
+/**
+ * openuispec init — interactive project scaffolding
+ *
+ * Creates folder structure, manifest, and AI assistant rules
+ * (CLAUDE.md / AGENTS.md) so AI tools track spec changes properly.
+ */
+import { createInterface } from "node:readline/promises";
+import { stdin, stdout } from "node:process";
+import { mkdirSync, writeFileSync, readFileSync, readdirSync, existsSync, appendFileSync, unlinkSync, } from "node:fs";
+import { join, relative } from "node:path";
+import { SUPPORTED_TARGETS, isSupportedTarget } from "../drift/index.js";
+import { readPackageVersion, resolvePackagePath } from "../runtime/package-paths.js";
+export function listInitOptions() {
+    const defaults = collectDefaults();
+    return {
+        command: "init",
+        note: "After init, run `openuispec configure-target <target> --list-options` for each target to get stack choices.",
+        questions: [
+            {
+                key: "name",
+                prompt: "Project name",
+                type: "text",
+                default: defaults.name,
+            },
+            {
+                key: "spec_dir",
+                prompt: "Spec directory",
+                type: "text",
+                default: defaults.specDir,
+            },
+            {
+                key: "targets",
+                prompt: "Which platforms?",
+                type: "list",
+                default: defaults.targets,
+                options: [...SUPPORTED_TARGETS],
+            },
+            {
+                key: "with_api",
+                prompt: "Will this spec declare API endpoints?",
+                type: "yes_no",
+                default: defaults.withApi,
+            },
+            {
+                key: "backend_path",
+                prompt: "Backend folder path relative to openuispec.yaml",
+                type: "text",
+                default: defaults.backendPath ?? "../backend/",
+            },
+            {
+                key: "configure_targets",
+                prompt: "Configure target stacks now?",
+                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.",
+    };
+}
+// ── prompts ──────────────────────────────────────────────────────────
+export async function ask(rl, question, fallback) {
+    const suffix = fallback ? ` (${fallback})` : "";
+    const answer = (await rl.question(`${question}${suffix}: `)).trim();
+    return answer || fallback || "";
+}
+async function askList(rl, question, options, defaults) {
+    const defaultStr = defaults.join(", ");
+    const raw = (await rl.question(`${question} [${options.join(", ")}] (${defaultStr}): `)).trim();
+    if (!raw)
+        return defaults;
+    return raw
+        .split(",")
+        .map((s) => s.trim().toLowerCase())
+        .filter((s) => options.includes(s));
+}
+export async function askChoice(rl, question, options, fallback) {
+    const answer = (await rl.question(`${question} [${options.join(", ")}] (${fallback}): `))
+        .trim()
+        .toLowerCase();
+    if (!answer)
+        return fallback;
+    return options.includes(answer) ? answer : fallback;
+}
+async function askYesNo(rl, question, fallback) {
+    const answer = await askChoice(rl, question, ["yes", "no"], fallback ? "yes" : "no");
+    return answer === "yes";
+}
+// ── scaffold ─────────────────────────────────────────────────────────
+function ensureDir(path) {
+    mkdirSync(path, { recursive: true });
+}
+function writeIfMissing(path, content, quiet = false) {
+    if (existsSync(path)) {
+        if (!quiet)
+            console.log(`  skip ${relative(process.cwd(), path)} (exists)`);
+        return false;
+    }
+    writeFileSync(path, content);
+    if (!quiet)
+        console.log(`  create ${relative(process.cwd(), path)}`);
+    return true;
+}
+// ── version ─────────────────────────────────────────────────────────
+const RULES_START_MARKER = "<!-- openuispec-rules-start -->";
+const RULES_END_MARKER = "<!-- openuispec-rules-end -->";
+function getPackageVersion() {
+    return readPackageVersion(import.meta.url);
+}
+// ── templates ────────────────────────────────────────────────────────
+function manifestTemplate(name, targets, options) {
+    const targetList = targets.join(", ");
+    const outputLines = targets
+        .map((t) => {
+        if (t === "ios")
+            return `    ios: { language: swift, framework: swiftui, min_version: "17.0" }`;
+        if (t === "android")
+            return `    android: { language: kotlin, framework: compose, min_sdk: 26 }`;
+        if (t === "web")
+            return `    web: { language: typescript, framework: react, bundler: vite }`;
+        return `    ${t}: {}`;
+    })
+        .join("\n");
+    function yamlPathsBlock(paths) {
+        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.2
+spec_version: "0.2"
+
+project:
+  name: "${name}"
+  description: ""
+
+includes:
+  tokens: "./tokens/"
+  contracts: "./contracts/"
+  components: "./components/"
+  screens: "./screens/"
+  flows: "./flows/"
+  platform: "./platform/"
+  locales: "./locales/"
+
+i18n:
+  default_locale: "en"
+  supported_locales: [en]
+  fallback_strategy: "default"
+
+generation:
+  targets: [${targetList}]
+  # extra_rules:                        # Optional: project-wide AI authoring conventions
+  #   - "Generation hint strings may start with [common], [ios], [android], or [web] to indicate scope."
+  # output_dir:                          # Optional: map targets to code directories
+  #   ios: "../ios-app/"                  # relative to this file
+  #   android: "../android-app/"
+  #   web: "../web-ui/"
+${options.withApi ? `  code_roots:
+    backend: "${options.backendPath}"                # Required when api.endpoints are declared
+` : ""}  output_format:
+${outputLines}
+${sharedBlock}${structureBlock}
+data_model: {}
+
+api:
+  base_url: "/api/v1"
+  auth: "bearer_token"
+  endpoints: {}
+`;
+}
+function specReadmeTemplate(name, targets) {
+    const targetList = targets.join(", ");
+    return `# ${name} — OpenUISpec
+
+This directory contains the **OpenUISpec** semantic UI specification for **${name}**.
+
+**Start here:** read \`openuispec.yaml\` — it defines the project structure, data model, API endpoints, and generation targets (**${targetList}**).
+
+## 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) |
+| \`components/\` | Reusable component compositions — contract slot compositions with states and variants |
+| \`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 wrapper keys
+2. \`spec/openuispec-v0.2.md\` — full specification (contracts, layout, expressions, etc.)
+3. \`examples/taskflow/openuispec/\` — complete working example with all file types
+4. \`schema/\` — JSON Schemas for validation
+
+## MCP Tools (recommended for AI assistants)
+
+When the openuispec MCP server is configured, AI assistants should use these tools instead of CLI commands:
+
+| Tool | When to use |
+|------|-------------|
+| \`openuispec_spec_types\` | Discover available spec types and their descriptions. |
+| \`openuispec_spec_schema\` | Get the full JSON schema for a specific spec type — exact structure, required fields, allowed values. |
+| \`openuispec_prepare\` | **Before any UI code generation.** Returns spec context, platform config, and constraints. |
+| \`openuispec_read_specs\` | Load spec file contents — the authoritative source for tokens, screens, contracts. |
+| \`openuispec_check\` | After editing spec files. Validates schema + semantics + readiness. Optional \`screens\`/\`contracts\` params scope the audit. |
+| \`openuispec_validate\` | Schema-only validation, optionally by group. |
+| \`openuispec_drift\` | Detect spec changes since last snapshot. |
+| \`openuispec_status\` | To understand cross-target state (baselines, drift, next steps). |
+| \`openuispec_get_screen\` | Get a single screen spec by name — faster than \`read_specs\` for targeted edits. |
+| \`openuispec_get_contract\` | Get a single contract spec, optionally filtered to one variant. |
+| \`openuispec_get_tokens\` | Get tokens for a specific category (color, typography, spacing, etc.). |
+| \`openuispec_get_locale\` | Get a single locale file, optionally filtered to specific keys. |
+| \`openuispec_screenshot\` | Screenshot the web app at a route via headless browser (requires \`puppeteer\`). |
+| \`openuispec_screenshot_android\` | Screenshot Android app on emulator — works with any project via \`project_dir\`. |
+| \`openuispec_screenshot_ios\` | Screenshot iOS app on Simulator via XCUITest — works with any project via \`project_dir\`. |
+
+## CLI commands
+
+\`\`\`bash
+# Workflow
+openuispec validate             # Validate spec files against schemas
+openuispec validate semantic    # Run semantic cross-reference linting
+openuispec configure-target ${targets[0]} [--defaults] # Configure target stack; --defaults stays unconfirmed
+openuispec status               # Show cross-target baseline/drift status
+openuispec drift --target ${targets[0]} --explain   # Explain semantic spec drift
+openuispec prepare --target ${targets[0]}          # Build the target work bundle
+openuispec drift --snapshot --target ${targets[0]} # Snapshot current state + git baseline after target output exists
+
+# Spec access
+openuispec read-specs [paths...]          # Read spec file contents as JSON
+openuispec get-screen <name>              # Get a single screen spec
+openuispec get-contract <name> [--variant v] # Get a contract spec
+openuispec get-tokens <category>          # Get tokens for a category
+openuispec get-locale <locale> [--keys k1,k2] # Get a locale file
+openuispec spec-types                     # List available spec types
+openuispec spec-schema <type>             # Get JSON schema for a spec type
+
+# Screenshots
+openuispec screenshot --route /home --theme dark --output-dir screenshots
+openuispec screenshot-android --screen home --project-dir /path/to/android
+openuispec screenshot-ios --screen home --project-dir /path/to/ios --scheme MyApp
+\`\`\`
+
+The target work bundle has two modes:
+- \`bootstrap\` when no snapshot exists yet, for first-time generation
+- \`update\` after a snapshot exists, for drift-based target updates
+
+If target stack values were written with \`--defaults\`, treat them as unconfirmed. Before generating code, ask the user to confirm or change the stack and run \`openuispec configure-target <target>\` without \`--defaults\`.
+
+## Learn more
+
+Docs: https://openuispec.rsteam.uz
+`;
+}
+function aiRulesBlock(specDir, targets) {
+    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.
+# Spec files are the single source of truth for all UI across platforms.
+# Targets: ${targetList}
+
+## MANDATORY — UI work requires OpenUISpec tools
+
+When the user's request involves UI — screens, navigation, layout, tokens, flows, localization,
+or any visual/structural change — you MUST use the OpenUISpec tools before writing any code.
+
+### MCP Tools (use these when available)
+
+Call these MCP tools directly. They return structured JSON with everything you need.
+
+**Pre-generation:**
+1. Call \`openuispec_prepare\` with the target platform — returns spec context, platform config, constraints.
+   Use \`include_specs: true\` to embed all spec contents in one call (saves a separate read_specs).
+2. Call \`openuispec_read_specs\` to load spec file contents if not using include_specs.
+   Without paths: returns file listing. With paths: returns contents. Use these as the AUTHORITATIVE source.
+3. If spec changes are needed, update spec files FIRST, then call \`openuispec_check\`.
+4. Generate or update the platform UI code based on the spec contents.
+
+**Post-generation (EVERY TIME after writing UI code):**
+5. Call \`openuispec_check\` to validate spec files (schema + semantics) and confirm prepare readiness.
+   Note: this validates the SPEC, not the generated code.
+6. Call \`openuispec_check\` with \`audit: true\` to get a spec-derived checklist, then manually review
+   the generated code against it. For each screen, verify:
+   - Every field/action in the spec has a corresponding UI element
+   - Token values (colors, spacing, radii) match exactly — no approximations
+   - Contract \`must_handle\` states are all implemented (loading, error, empty, etc.)
+   - Adaptive breakpoints match the spec's \`size_classes\`
+   - Locale keys match \`$t:\` references
+   - Navigation targets match flow definitions
+7. Report any real gaps found and fix them before finishing.
+
+**Iterating before baseline:**
+Generated code rarely needs just one pass. Read the spec, audit the generated code against it,
+take screenshots to verify visuals, then fix gaps and repeat.
+Multiple generate → review → fix cycles are expected before the user accepts the result.
+
+**Baseline reminder:**
+After generation, remind the user to review the output and run the baseline when satisfied:
+> When you're happy with the generated output, run: \`openuispec drift --snapshot --target <t>\`
+> This records the spec state so future changes are tracked as incremental drift.
+Do not baseline on your own initiative — only run the snapshot when the user asks.
+
+**Creating new spec files:**
+- Call \`openuispec_spec_types\` to discover available spec types.
+- Call \`openuispec_spec_schema\` with the specific type to get the full JSON schema.
+- Write the spec file following the schema exactly.
+
+**Focused getters (prefer these for incremental edits over \`read_specs\`):**
+- \`openuispec_get_screen(name)\` — single screen spec
+- \`openuispec_get_contract(name, variant?)\` — single contract, optionally one variant
+- \`openuispec_get_component(name, variant?)\` — single component, optionally one variant
+- \`openuispec_get_tokens(category)\` — single token category (color, typography, spacing, etc.)
+- \`openuispec_get_locale(locale, keys?)\` — single locale file, optionally filtered keys
+- \`openuispec_check(target, audit?, screens?, contracts?)\` — validation + optional scoped audit checklist
+
+Use \`read_specs\` for full-project generation; use focused getters when editing one screen or contract.
+
+**Other tools:**
+- \`openuispec_status\` — cross-target summary, good starting point
+- \`openuispec_drift\` with \`explain: true\` — property-level spec changes
+- \`openuispec_validate\` — schema-only validation by group
+
+### CLI fallback (when MCP is not available)
+
+If MCP tools are not available, use these CLI commands with \`--json\` flag:
+
+**Status & discovery:**
+- \`openuispec status --json\` — cross-target status
+- \`openuispec spec-types\` — list available spec types
+- \`openuispec spec-schema <type>\` — get JSON schema for a spec type
+
+**Spec access:**
+- \`openuispec read-specs [paths...]\` — read spec file contents
+- \`openuispec get-screen <name>\` — get a single screen spec
+- \`openuispec get-contract <name> [--variant v]\` — get a contract spec
+- \`openuispec get-component <name> [--variant v]\` — get a component spec
+- \`openuispec get-tokens <category>\` — get tokens for a category
+- \`openuispec get-locale <locale> [--keys k1,k2]\` — get a locale file
+
+**Validation & generation workflow:**
+- \`openuispec validate [group...] --json\` — validate spec files against JSON Schemas
+- \`openuispec check --target <t> --json\` — validate spec files + check target generation readiness
+- \`openuispec prepare --target <t> --json\` — build AI-ready work bundle
+- \`openuispec drift --target <t> --explain --json\` — semantic drift
+
+**Visual verification:**
+- \`openuispec screenshot --route /path\` — screenshot the web app
+- \`openuispec screenshot --route /path --init-script "..."\` — inject auth/role before rendering (web only; app must implement \`__ous_init\` bootstrapper)
+- \`openuispec screenshot-android [--project-dir path]\` — screenshot Android app
+- \`openuispec screenshot-ios [--project-dir path]\` — screenshot iOS app
+
+### Other CLI commands
+- \`openuispec init\` — scaffold a new spec project
+- \`openuispec configure-target <t>\` — configure target platform stack
+- \`openuispec update-rules\` — update AI rules to match installed package version
+- \`openuispec drift --snapshot --target <t>\` — snapshot current state (user-initiated, after reviewing generated output)
+
+## Spec format reference
+
+The spec format, schemas, and generation rules are in the installed \`openuispec\` package.
+You MUST read the reference files before creating or editing spec files — do NOT guess the format.
+
+**Find the package:** \`node_modules/openuispec/\` or run \`npm root -g\` → \`<prefix>/openuispec/\`.
+**Online fallback:** \`https://openuispec.rsteam.uz/llms-full.txt\`
+
+**Reference files (read in order):**
+1. \`README.md\` — schema tables, file format, root wrapper keys
+2. \`spec/openuispec-v0.2.md\` — full specification
+3. \`examples/taskflow/openuispec/\` — complete working example
+4. \`schema/\` — JSON Schemas for every file type
+
+## Spec location
+- Spec root: \`${specDir}/\` — read \`${specDir}/openuispec.yaml\` first for actual paths.
+- Default dirs: tokens/, screens/, flows/, contracts/, components/, platform/, locales/
+
+## When to start from spec vs platform code
+
+**Spec-first** (use \`openuispec_prepare\` or \`openuispec prepare\`):
+- Screen structure, navigation, fields, actions, validation, data binding changes
+- Token, variant, contract, flow, or localization changes
+- Changes affecting multiple platforms
+- Requests in product/UI terms
+
+**Platform-first** (skip spec tools):
+- Platform-specific polish (iOS-only, Android-only, web-only)
+- Local bug fixes that don't alter shared semantic behavior
+
+## If spec directories are empty (first-time setup)
+
+Read \`spec/openuispec-v0.2.md\` from the package first, then:
+1. Scan codebase for UI screens → create \`${specDir}/screens/<name>.yaml\` as \`status: stub\`
+2. Extract tokens (colors, fonts, spacing) → \`${specDir}/tokens/\`
+3. Create contract extensions → \`${specDir}/contracts/\`
+4. Create locale files → \`${specDir}/locales/<locale>.json\`
+5. Fill in \`data_model\`, \`api.endpoints\` in \`${specDir}/openuispec.yaml\`
+
+## Rules
+- Do not baseline on your own initiative — the user decides when generated output is accepted.
+- After generation, always remind the user to review and baseline: \`openuispec drift --snapshot --target <t>\`.
+- Do not modify generated UI without checking whether the spec must change first.
+- Do not use \`configure-target --defaults\` as silent approval — ask the user to confirm.
+- Always read spec format from the installed package, not from cached/memorized content.
+${RULES_END_MARKER}
+`;
+}
+// ── update-rules ────────────────────────────────────────────────────
+export function updateRules() {
+    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 = [...SUPPORTED_TARGETS];
+    try {
+        const manifest = readFileSync(join(cwd, specDir, "openuispec.yaml"), "utf-8");
+        const match = manifest.match(/targets:\s*\[([^\]]+)\]/);
+        if (match) {
+            const parsedTargets = match[1]
+                .split(",")
+                .map((t) => t.trim().replace(/['"]/g, ""))
+                .filter(isSupportedTarget);
+            if (parsedTargets.length > 0) {
+                targets = parsedTargets;
+            }
+        }
+    }
+    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}`);
+    }
+    // Migrate old spec doc version references to current
+    migrateDocVersionRefs(cwd, specDir);
+    // Ensure MCP server is configured
+    configureMcp(cwd, true);
+}
+// ── spec doc version migration ──────────────────────────────────────
+function getCurrentSpecDocVersion() {
+    const specDir = resolvePackagePath(import.meta.url, "spec");
+    try {
+        const files = readdirSync(specDir);
+        const match = files
+            .map((f) => f.match(/^openuispec-v(.+)\.md$/))
+            .filter(Boolean)
+            .sort()
+            .pop();
+        return match ? match[1] : null;
+    }
+    catch {
+        return null;
+    }
+}
+function migrateDocVersionRefs(cwd, specDir) {
+    const currentVersion = getCurrentSpecDocVersion();
+    if (!currentVersion)
+        return;
+    const currentRef = `openuispec-v${currentVersion}`;
+    const pattern = /openuispec-v(\d+\.\d+)/g;
+    const filesToCheck = [
+        join(cwd, specDir, "README.md"),
+        join(cwd, "CLAUDE.md"),
+        join(cwd, "AGENTS.md"),
+    ];
+    for (const filePath of filesToCheck) {
+        if (!existsSync(filePath))
+            continue;
+        const content = readFileSync(filePath, "utf-8");
+        const oldRefs = [...content.matchAll(pattern)]
+            .filter((m) => m[1] !== currentVersion);
+        if (oldRefs.length === 0)
+            continue;
+        const migrated = content.replace(pattern, (_match, ver) => ver === currentVersion ? _match : currentRef);
+        writeFileSync(filePath, migrated);
+        const relPath = relative(cwd, filePath);
+        const oldVersions = [...new Set(oldRefs.map((m) => m[1]))].join(", ");
+        console.log(`  updated ${relPath} (migrated v${oldVersions} → v${currentVersion} doc references)`);
+    }
+}
+// ── shared MCP config ───────────────────────────────────────────────
+const EXPECTED_MCP_CONFIG = {
+    command: "openuispec",
+    args: ["mcp"],
+};
+/**
+ * MCP config files by agent:
+ *   .mcp.json              — Claude Code (project scope)
+ *   .vscode/mcp.json       — VS Code / Copilot Chat
+ *   .gemini/settings.json  — Gemini CLI (if .gemini/ exists)
+ *
+ * All use the same { mcpServers: { openuispec: { command, args } } } shape.
+ */
+const JSON_MCP_PATHS = [
+    ".mcp.json",
+    join(".vscode", "mcp.json"),
+    join(".gemini", "settings.json"),
+];
+/** Codex uses TOML: .codex/config.toml */
+const CODEX_CONFIG_PATH = join(".codex", "config.toml");
+const CODEX_MCP_BLOCK = `\n[mcp_servers.openuispec]\ncommand = "openuispec"\nargs = ["mcp"]\n`;
+function configureCodexMcp(cwd, quiet) {
+    const codexDir = join(cwd, ".codex");
+    const configPath = join(codexDir, "config.toml");
+    try {
+        let content = "";
+        try {
+            content = readFileSync(configPath, "utf-8");
+        }
+        catch {
+            // file doesn't exist — will create
+        }
+        if (content.includes("[mcp_servers.openuispec]")) {
+            if (!quiet)
+                console.log(`  skip ${CODEX_CONFIG_PATH} (openuispec MCP already configured)`);
+            return false;
+        }
+        if (!existsSync(codexDir))
+            mkdirSync(codexDir);
+        writeFileSync(configPath, content + CODEX_MCP_BLOCK);
+        if (!quiet)
+            console.log(`  ${content ? "update" : "create"} ${CODEX_CONFIG_PATH} (MCP server configured)`);
+        return true;
+    }
+    catch {
+        if (!quiet)
+            console.log(`  skip ${CODEX_CONFIG_PATH} (could not configure MCP server)`);
+        return false;
+    }
+}
+function configureMcp(cwd, showRestart, quiet = false) {
+    let changed = false;
+    for (const relPath of JSON_MCP_PATHS) {
+        const configPath = join(cwd, relPath);
+        // Optional dirs: only write config if the parent directory already exists
+        const optionalParent = [".vscode", ".gemini"].find((d) => relPath.startsWith(d));
+        if (optionalParent && !existsSync(join(cwd, optionalParent)))
+            continue;
+        try {
+            let config = {};
+            try {
+                config = JSON.parse(readFileSync(configPath, "utf-8"));
+            }
+            catch {
+                // file doesn't exist or isn't valid JSON — start fresh
+            }
+            if (!config.mcpServers)
+                config.mcpServers = {};
+            const existing = config.mcpServers.openuispec;
+            const needsUpdate = !existing ||
+                existing.command !== EXPECTED_MCP_CONFIG.command ||
+                JSON.stringify(existing.args) !== JSON.stringify(EXPECTED_MCP_CONFIG.args);
+            if (needsUpdate) {
+                config.mcpServers.openuispec = { ...EXPECTED_MCP_CONFIG };
+                writeFileSync(configPath, JSON.stringify(config, null, 2) + "\n");
+                if (!quiet)
+                    console.log(`  ${existing ? "update" : "create"} ${relPath} (MCP server configured)`);
+                changed = true;
+            }
+            else {
+                if (!quiet)
+                    console.log(`  skip ${relPath} (openuispec MCP already configured)`);
+            }
+        }
+        catch {
+            if (!quiet)
+                console.log(`  skip ${relPath} (could not configure MCP server)`);
+        }
+    }
+    // Codex: .codex/config.toml (TOML format)
+    if (configureCodexMcp(cwd, quiet))
+        changed = true;
+    if (showRestart && changed)
+        console.log(`\n  Restart your AI coding agent to activate the MCP server.`);
+    // Clean up stale .claude.json MCP config from older versions
+    const claudeJsonPath = join(cwd, ".claude.json");
+    try {
+        const claudeJson = JSON.parse(readFileSync(claudeJsonPath, "utf-8"));
+        if (claudeJson.mcpServers?.openuispec) {
+            delete claudeJson.mcpServers.openuispec;
+            if (Object.keys(claudeJson.mcpServers).length === 0)
+                delete claudeJson.mcpServers;
+            if (Object.keys(claudeJson).length === 0) {
+                unlinkSync(claudeJsonPath);
+                if (!quiet)
+                    console.log(`  remove .claude.json (migrated MCP config)`);
+            }
+            else {
+                writeFileSync(claudeJsonPath, JSON.stringify(claudeJson, null, 2) + "\n");
+                if (!quiet)
+                    console.log(`  update .claude.json (removed stale MCP config)`);
+            }
+        }
+    }
+    catch {
+        // .claude.json doesn't exist or not parseable — nothing to clean up
+    }
+}
+/**
+ * Extract the rules version from a CLAUDE.md / AGENTS.md file.
+ * Returns null if no version marker is found.
+ */
+export function extractRulesVersion(filePath) {
+    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 };
+function parseTargetsValue(raw) {
+    return raw
+        .split(",")
+        .map((value) => value.trim().toLowerCase())
+        .filter((value) => isSupportedTarget(value));
+}
+function requireFlagValue(argv, index, flag) {
+    const value = argv[index + 1];
+    if (!value || value.startsWith("--")) {
+        console.error(`Error: ${flag} requires a value.`);
+        process.exit(1);
+    }
+    return value;
+}
+function parseInitArgs(argv) {
+    const options = { defaults: argv.includes("--defaults"), quiet: argv.includes("--quiet") };
+    for (let index = 0; index < argv.length; index++) {
+        const arg = argv[index];
+        switch (arg) {
+            case "--defaults":
+            case "--quiet":
+                break;
+            case "--name":
+                options.name = requireFlagValue(argv, index, arg);
+                index++;
+                break;
+            case "--spec-dir":
+                options.specDir = requireFlagValue(argv, index, arg);
+                index++;
+                break;
+            case "--targets":
+                options.targets = parseTargetsValue(requireFlagValue(argv, index, arg));
+                index++;
+                break;
+            case "--backend":
+                options.backendPath = requireFlagValue(argv, index, arg);
+                index++;
+                break;
+            case "--with-api":
+                options.withApi = true;
+                break;
+            case "--no-api":
+                options.withApi = false;
+                break;
+            case "--configure-targets":
+                options.configureTargets = true;
+                break;
+            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}`);
+                    process.exit(1);
+                }
+        }
+    }
+    return options;
+}
+function collectDefaults() {
+    const cwd = process.cwd();
+    const defaultName = cwd.split("/").pop() || "MyApp";
+    return {
+        name: defaultName,
+        specDir: "openuispec",
+        targets: [...SUPPORTED_TARGETS],
+        withApi: true,
+        backendPath: "../backend/",
+        configureTargets: true,
+        sharedLayers: [],
+        structures: [],
+    };
+}
+const SHARED_LAYER_DEFAULTS = {
+    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) {
+    const mobilePlatforms = targets.filter((t) => t === "ios" || t === "android");
+    if (mobilePlatforms.length < 2) {
+        return { sharedLayers: [], structures: [] };
+    }
+    const preset = SHARED_LAYER_DEFAULTS.kmp;
+    const sharedLayers = [{
+            name: "mobile_common",
+            platforms: mobilePlatforms,
+            language: preset.language,
+            root: preset.root,
+            tracks: preset.tracks,
+            scope: preset.scope,
+            paths: preset.paths,
+        }];
+    const structures = 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, targets) {
+    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 = [{
+            name: layerName,
+            platforms: platformsRaw,
+            language,
+            root,
+            tracks: tracksRaw,
+            scope,
+            paths: defaultLayer.paths,
+        }];
+    const structures = [];
+    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) {
+    const defaults = collectDefaults();
+    const name = await ask(rl, "Project name", defaults.name);
+    const specDir = await ask(rl, "Spec directory", defaults.specDir);
+    const targets = await askList(rl, "\nWhich platforms?", [...SUPPORTED_TARGETS], defaults.targets);
+    if (targets.length === 0) {
+        console.error("At least one target is required.");
+        process.exit(1);
+    }
+    const withApi = await askYesNo(rl, "Will this spec declare API endpoints?", defaults.withApi);
+    const backendPath = withApi
+        ? 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,
+        specDir,
+        targets,
+        withApi,
+        backendPath,
+        configureTargets,
+        sharedLayers,
+        structures,
+    };
+}
+function collectNonInteractiveAnswers(argv) {
+    const parsed = parseInitArgs(argv);
+    const defaults = collectDefaults();
+    if (!parsed.defaults && argv.filter((a) => a !== "--quiet").length === 0) {
+        console.error("Error: `openuispec init` needs a TTY for prompts.\n" +
+            "Run with `--list-options` to get prompt definitions as JSON, or pass flags such as `--name`, `--targets`, `--with-api`, `--backend`, and `--configure-targets`.");
+        process.exit(1);
+    }
+    const targets = parsed.targets && parsed.targets.length > 0 ? parsed.targets : defaults.targets;
+    if (targets.length === 0) {
+        console.error("Error: --targets must include at least one of ios, android, web.");
+        process.exit(1);
+    }
+    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,
+        specDir: parsed.specDir ?? defaults.specDir,
+        targets,
+        withApi,
+        backendPath,
+        configureTargets: parsed.configureTargets ?? defaults.configureTargets,
+        sharedLayers,
+        structures,
+    };
+}
+// ── main ─────────────────────────────────────────────────────────────
+export async function init(argv = []) {
+    if (argv.includes("--list-options")) {
+        console.log(JSON.stringify(listInitOptions(), null, 2));
+        return;
+    }
+    const quiet = argv.includes("--quiet");
+    const interactive = stdin.isTTY && stdout.isTTY && !argv.includes("--defaults");
+    const rl = interactive ? createInterface({ input: stdin, output: stdout }) : null;
+    if (!quiet)
+        console.log("\nOpenUISpec — Project Setup\n");
+    try {
+        const cwd = process.cwd();
+        const answers = rl ? await collectInteractiveAnswers(rl) : collectNonInteractiveAnswers(argv);
+        rl?.close();
+        // ── create folders ─────────────────────────────────────────────
+        if (!quiet)
+            console.log("\nScaffolding...\n");
+        const root = join(cwd, answers.specDir);
+        const dirs = [
+            "tokens",
+            "contracts",
+            "components",
+            "screens",
+            "flows",
+            "platform",
+            "locales",
+        ];
+        ensureDir(root);
+        for (const d of dirs) {
+            ensureDir(join(root, d));
+        }
+        // ── manifest ───────────────────────────────────────────────────
+        writeIfMissing(join(root, "openuispec.yaml"), manifestTemplate(answers.name, answers.targets, {
+            withApi: answers.withApi,
+            backendPath: answers.backendPath,
+            sharedLayers: answers.sharedLayers,
+            structures: answers.structures,
+        }), quiet);
+        // ── spec README ──────────────────────────────────────────────
+        writeIfMissing(join(root, "README.md"), specReadmeTemplate(answers.name, answers.targets), quiet);
+        // ── .gitkeep for empty dirs ────────────────────────────────────
+        for (const d of dirs) {
+            const dir = join(root, d);
+            const entries = existsSync(dir)
+                ? readdirSync(dir).filter((f) => f !== ".gitkeep")
+                : [];
+            if (entries.length === 0) {
+                const gk = join(dir, ".gitkeep");
+                if (!existsSync(gk)) {
+                    writeFileSync(gk, "");
+                    if (!quiet)
+                        console.log(`  create ${relative(cwd, gk)}`);
+                }
+            }
+        }
+        // ── AI assistant rules ─────────────────────────────────────────
+        const rules = aiRulesBlock(answers.specDir, answers.targets);
+        for (const file of ["CLAUDE.md", "AGENTS.md"]) {
+            const filePath = join(cwd, file);
+            if (existsSync(filePath)) {
+                const existing = readFileSync(filePath, "utf-8");
+                if (existing.includes("OpenUISpec")) {
+                    if (!quiet)
+                        console.log(`  skip ${file} (already has OpenUISpec rules)`);
+                    continue;
+                }
+                appendFileSync(filePath, "\n" + rules);
+                if (!quiet)
+                    console.log(`  update ${file} (appended rules)`);
+            }
+            else {
+                writeFileSync(filePath, rules.trimStart());
+                if (!quiet)
+                    console.log(`  create ${file}`);
+            }
+        }
+        // ── MCP server configuration ────────────────────────────────────
+        configureMcp(cwd, false, quiet);
+        if (answers.configureTargets) {
+            if (!quiet)
+                console.log("\nConfiguring target stacks...\n");
+            const { runConfigureTarget } = await import("./configure-target.js");
+            for (const target of answers.targets) {
+                await runConfigureTarget([target, ...(interactive ? [] : ["--defaults"]), ...(quiet ? ["--silent"] : [])]);
+            }
+        }
+        // ── done ───────────────────────────────────────────────────────
+        if (quiet) {
+            console.log(`./${answers.specDir}/`);
+        }
+        else {
+            console.log(`
+Done! Your spec project is ready at ./${answers.specDir}/
+
+Getting started (new project):
+  1. Edit ${answers.specDir}/openuispec.yaml — define your data model and API
+  2. Create tokens in ${answers.specDir}/tokens/ (colors, typography, spacing, etc.)
+  3. Create contract extensions in ${answers.specDir}/contracts/ (visual variants for the 7 built-in contracts)
+  4. Create screens in ${answers.specDir}/screens/ (one YAML per screen)
+  5. Create flows in ${answers.specDir}/flows/ (multi-step navigation)
+  6. Create locale files in ${answers.specDir}/locales/ (one JSON per supported locale)
+  7. Run \`openuispec validate\` and \`openuispec validate semantic\` to check everything
+  8. Ask AI to generate native code from the spec
+  9. Run \`openuispec drift --snapshot --target ${answers.targets[0]}\` to baseline the first accepted target state after that target output directory exists
+
+Getting started (existing project):
+  1. Ask AI to read your existing UI code and generate spec files:
+     "Read src/screens/HomeScreen.swift and create ${answers.specDir}/screens/home.yaml as status: stub"
+  2. Spec screens incrementally: stub → draft → ready
+  3. Only ready/draft screens are tracked by drift detection
+  4. Run \`openuispec validate\` to check specs against the schema
+  5. Use \`openuispec prepare --target ${answers.targets[0]}\` before first-time generation, then use \`openuispec drift --target ${answers.targets[0]} --explain\` and \`openuispec prepare --target ${answers.targets[0]}\` before asking AI to update a target
+
+Commands:
+  openuispec validate             Validate spec files
+  openuispec validate semantic   Check semantic cross-references
+  openuispec configure-target ios [--defaults]   Configure target stack; --defaults stays unconfirmed
+  openuispec status   Show cross-target baseline/drift status
+  openuispec drift --target ios --explain   Explain semantic spec changes
+  openuispec prepare --target ios   Build the target work bundle
+  openuispec drift --snapshot --target ios   Save current state + git baseline after target output exists
+
+AI rules have been added to CLAUDE.md and AGENTS.md.
+MCP server configured (AI assistants will use openuispec tools automatically).
+
+Docs: https://openuispec.rsteam.uz
+`);
+        }
+    }
+    catch (err) {
+        rl?.close();
+        throw err;
+    }
+}