openuispec 0.1.28 → 0.1.30

package/cli/index.ts

@@ -4,11 +4,15 @@
  *
  * Usage:
  *   openuispec init                           Create a new spec project
+ *   openuispec init --defaults                Scaffold non-interactively with unconfirmed defaults
+ *   openuispec configure-target <t>           Configure and confirm target stack choices
+ *   openuispec configure-target <t> --list-options  Print target stack prompt options as JSON
  *   openuispec drift [--target <t>]           Check for spec drift
  *   openuispec drift --snapshot --target <t>  Snapshot current state + git baseline
  *   openuispec drift --target <t> --explain   Explain semantic changes since baseline
- *   openuispec prepare --target <t>           Build an AI-ready target update bundle
+ *   openuispec prepare --target <t>           Build the target work bundle
  *   openuispec status                         Show cross-target baseline/drift status
+ *   openuispec check --target <t> [--json]    Composite validation + prepare readiness
  *   openuispec validate [group...]            Validate spec files against schemas
  */
 
@@ -45,13 +49,19 @@ async function main(): Promise<void> {
 
   switch (command) {
     case "init":
-      await init();
+      await init(rest);
       break;
 
     case "update-rules":
       updateRules();
       break;
 
+    case "configure-target": {
+      const { runConfigureTarget } = await import("./configure-target.js");
+      await runConfigureTarget(rest);
+      break;
+    }
+
     case "drift": {
       const { runDrift } = await import("../drift/index.js");
       runDrift(rest);
@@ -70,6 +80,12 @@ async function main(): Promise<void> {
       break;
     }
 
+    case "check": {
+      const { runCheck } = await import("../check/index.js");
+      runCheck(rest);
+      break;
+    }
+
     case "validate": {
       const { runValidate } = await import("../schema/validate.js");
       runValidate(rest);
@@ -85,16 +101,25 @@ OpenUISpec CLI v0.1
 
 Usage:
   openuispec init                           Create a new spec project
+  openuispec init --defaults                Scaffold non-interactively with unconfirmed defaults
+  openuispec init --no-configure-targets    Skip target stack setup during init
   openuispec update-rules                   Update AI rules to match installed version
+  openuispec configure-target <t> [--defaults] Configure target stack; --defaults stays unconfirmed
+  openuispec configure-target <t> --set k=v    Set specific stack values (confirmed)
+  openuispec configure-target <t> --list-options Print target stack prompt options as JSON
   openuispec drift [--target <t>]           Check for spec drift
   openuispec drift --snapshot --target <t>  Snapshot current state + git baseline
   openuispec drift --target <t> --explain   Explain semantic changes since baseline
-  openuispec prepare --target <t>           Build an AI-ready target update bundle
+  openuispec prepare --target <t>           Build the target work bundle
   openuispec status                         Show cross-target baseline/drift status
-  openuispec validate [group...]            Validate spec files
+  openuispec check --target <t> [--json]    Composite validation + prepare readiness
+  openuispec validate [group...] [--json]   Validate spec files
+  openuispec validate semantic --json       Semantic validation as JSON
 
 Validate groups: manifest, tokens, screens, flows, platform, locales, contracts, semantic
 
+Exit codes: 0 = success, 1 = missing config/usage error, 2 = validation failure
+
 Docs: https://openuispec.rsteam.uz
 `);
       break;
@@ -106,4 +131,7 @@ Docs: https://openuispec.rsteam.uz
   }
 }
 
-main();
+main().catch((err) => {
+  console.error(err instanceof Error ? err.message : String(err));
+  process.exit(1);
+});

package/cli/init.ts

@@ -15,12 +15,13 @@ import {
   existsSync,
   appendFileSync,
 } from "node:fs";
-import { join, relative, dirname } from "node:path";
+import { join, relative, dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
+import { SUPPORTED_TARGETS, isSupportedTarget, type SupportedTarget } from "../drift/index.js";
 
 // ── prompts ──────────────────────────────────────────────────────────
 
-async function ask(
+export async function ask(
   rl: ReturnType<typeof createInterface>,
   question: string,
   fallback?: string
@@ -47,21 +48,41 @@ async function askList(
     .filter((s) => options.includes(s));
 }
 
+export async function askChoice(
+  rl: ReturnType<typeof createInterface>,
+  question: string,
+  options: string[],
+  fallback: string
+): Promise<string> {
+  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: ReturnType<typeof createInterface>,
+  question: string,
+  fallback: boolean
+): Promise<boolean> {
+  const answer = await askChoice(rl, question, ["yes", "no"], fallback ? "yes" : "no");
+  return answer === "yes";
+}
+
 // ── scaffold ─────────────────────────────────────────────────────────
 
 function ensureDir(path: string): void {
-  if (!existsSync(path)) {
-    mkdirSync(path, { recursive: true });
-  }
+  mkdirSync(path, { recursive: true });
 }
 
-function writeIfMissing(path: string, content: string): boolean {
+function writeIfMissing(path: string, content: string, quiet = false): boolean {
   if (existsSync(path)) {
-    console.log(`  skip ${relative(process.cwd(), path)} (exists)`);
+    if (!quiet) console.log(`  skip ${relative(process.cwd(), path)} (exists)`);
     return false;
   }
   writeFileSync(path, content);
-  console.log(`  create ${relative(process.cwd(), path)}`);
+  if (!quiet) console.log(`  create ${relative(process.cwd(), path)}`);
   return true;
 }
 
@@ -85,7 +106,7 @@ function getPackageVersion(): string {
 function manifestTemplate(
   name: string,
   targets: string[],
-  specDir: string
+  options: { withApi: boolean; backendPath: string | null }
 ): string {
   const targetList = targets.join(", ");
   const outputLines = targets
@@ -126,7 +147,9 @@ generation:
   #   ios: "../ios-app/"                  # relative to this file
   #   android: "../android-app/"
   #   web: "../web-ui/"
-  output_format:
+${options.withApi ? `  code_roots:
+    backend: "${options.backendPath}"                # Required when api.endpoints are declared
+` : ""}  output_format:
 ${outputLines}
 
 data_model: {}
@@ -169,7 +192,7 @@ Do NOT guess the file format — skipping this step will produce invalid YAML th
 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 keys
+1. \`README.md\` — schema tables, file format reference, root wrapper keys
 2. \`spec/openuispec-v0.1.md\` — full specification (contracts, layout, expressions, etc.)
 3. \`examples/taskflow/openuispec/\` — complete working example with all file types
 4. \`schema/\` — JSON Schemas for validation
@@ -180,12 +203,19 @@ Do NOT guess the file format — skipping this step will produce invalid YAML th
 openuispec validate             # Validate spec files against schemas
 openuispec validate semantic    # Run semantic cross-reference linting
 openuispec validate screens     # Validate only screens
+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 an AI-ready target update bundle
+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
 \`\`\`
 
+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
@@ -253,7 +283,7 @@ This means the project has existing UI code but hasn't been specced yet. Your jo
        type: scroll_vertical
    \`\`\`
 4. **Extract tokens** — scan for colors, fonts, spacing and create files in \`${specDir}/tokens/\`.
-5. **Update the manifest** — fill in \`data_model\` and \`api.endpoints\` in \`${specDir}/openuispec.yaml\`.
+5. **Update the manifest** — fill in \`data_model\`, \`api.endpoints\`, and \`generation.code_roots.backend\` in \`${specDir}/openuispec.yaml\`.
 
 ## OpenUISpec Source Of Truth
 
@@ -274,7 +304,8 @@ Spec-first workflow:
 4. Run \`openuispec validate\`.
 5. Run \`openuispec validate semantic\`.
 6. Run \`openuispec drift --target <target> --explain\` to inspect semantic changes since that target's baseline.
-7. Run \`openuispec prepare --target <target>\` to build the AI/developer work bundle for that target.
+7. Run \`openuispec prepare --target <target>\` to build the target work bundle for that target. In \`bootstrap\` mode it provides first-generation constraints; in \`update\` mode it provides drift-based update scope.
+   If the target stack was filled from defaults, stop and ask the user to confirm or change it before implementation.
 8. Verify the affected UI targets build/run if possible.
 9. Only then run \`openuispec drift --snapshot --target <target>\` for affected targets, after that target output directory exists.
 10. Run \`openuispec drift --target <target> --explain\` again to confirm no spec changes remain for that target.
@@ -295,6 +326,7 @@ Platform-first workflow:
 - Do not treat \`openuispec drift\` as proof that generated UI matches the spec.
 - Do not skip \`--explain\` / \`prepare\` when another platform needs to catch up with shared spec changes.
 - Do not modify generated UI without checking whether the spec must change first.
+- Do not use \`configure-target --defaults\` as silent approval for implementation. Ask the user to confirm the stack first.
 
 ## CLI commands
 - \`openuispec init\` — scaffold a new spec project
@@ -303,7 +335,7 @@ Platform-first workflow:
 - \`openuispec drift --target <t>\` — check for spec drift
 - \`openuispec drift --target <t> --explain\` — explain semantic spec drift since the target baseline
 - \`openuispec drift --snapshot --target <t>\` — snapshot current state after the target output exists
-- \`openuispec prepare --target <t>\` — build an AI-ready target update bundle
+- \`openuispec prepare --target <t>\` — build the target work bundle and check whether stack confirmation is still pending
 - \`openuispec status\` — show cross-target baseline/drift status
 - \`openuispec update-rules\` — update AI rules to match installed package version
 - \`openuispec drift --all\` — include stubs in drift check
@@ -327,7 +359,7 @@ export function updateRules(): void {
   }
 
   // Detect targets from manifest
-  let targets = ["ios", "android", "web"];
+  let targets = [...SUPPORTED_TARGETS];
   try {
     const manifest = readFileSync(
       join(cwd, specDir, "openuispec.yaml"),
@@ -400,43 +432,180 @@ export function extractRulesVersion(filePath: string): string | null {
 
 export { getPackageVersion };
 
-// ── main ─────────────────────────────────────────────────────────────
+interface InitOptions {
+  defaults: boolean;
+  quiet: boolean;
+  name?: string;
+  specDir?: string;
+  targets?: string[];
+  withApi?: boolean;
+  backendPath?: string;
+  configureTargets?: boolean;
+}
 
-export async function init(): Promise<void> {
-  const rl = createInterface({ input: stdin, output: stdout });
+interface InitAnswers {
+  name: string;
+  specDir: string;
+  targets: string[];
+  withApi: boolean;
+  backendPath: string | null;
+  configureTargets: boolean;
+}
 
-  console.log("\nOpenUISpec — Project Setup\n");
+function parseTargetsValue(raw: string): string[] {
+  return raw
+    .split(",")
+    .map((value) => value.trim().toLowerCase())
+    .filter((value): value is SupportedTarget => isSupportedTarget(value));
+}
 
-  try {
-    // 1. Project name (display name in manifest, derived from current folder)
-    const cwd = process.cwd();
-    const defaultName = cwd.split("/").pop() || "MyApp";
-    const name = await ask(rl, "Project name", defaultName);
-
-    // 2. Spec directory
-    const specDir = await ask(rl, "Spec directory", "openuispec");
-
-    // 3. Platforms
-    const allTargets = ["ios", "android", "web"];
-    const targets = await askList(
-      rl,
-      "\nWhich platforms?",
-      allTargets,
-      allTargets
-    );
+function requireFlagValue(argv: string[], index: number, flag: string): string {
+  const value = argv[index + 1];
+  if (!value || value.startsWith("--")) {
+    console.error(`Error: ${flag} requires a value.`);
+    process.exit(1);
+  }
+  return value;
+}
 
-    if (targets.length === 0) {
-      console.error("At least one target is required.");
-      process.exit(1);
+function parseInitArgs(argv: string[]): InitOptions {
+  const options: InitOptions = { 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;
+      default:
+        if (arg.startsWith("--")) {
+          console.error(`Error: Unknown init option: ${arg}`);
+          process.exit(1);
+        }
     }
+  }
 
-    rl.close();
+  return options;
+}
+
+function collectDefaults(): InitAnswers {
+  const cwd = process.cwd();
+  const defaultName = cwd.split("/").pop() || "MyApp";
+  return {
+    name: defaultName,
+    specDir: "openuispec",
+    targets: [...SUPPORTED_TARGETS],
+    withApi: true,
+    backendPath: "../backend/",
+    configureTargets: true,
+  };
+}
+
+async function collectInteractiveAnswers(rl: ReturnType<typeof createInterface>): Promise<InitAnswers> {
+  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);
+
+  return {
+    name,
+    specDir,
+    targets,
+    withApi,
+    backendPath,
+    configureTargets,
+  };
+}
+
+function collectNonInteractiveAnswers(argv: string[]): InitAnswers {
+  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 `--defaults` 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;
+
+  return {
+    name: parsed.name ?? defaults.name,
+    specDir: parsed.specDir ?? defaults.specDir,
+    targets,
+    withApi,
+    backendPath,
+    configureTargets: parsed.configureTargets ?? defaults.configureTargets,
+  };
+}
+
+// ── main ─────────────────────────────────────────────────────────────
+
+export async function init(argv: string[] = []): Promise<void> {
+  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 ─────────────────────────────────────────────
 
-    console.log("\nScaffolding...\n");
+    if (!quiet) console.log("\nScaffolding...\n");
 
-    const root = join(cwd, specDir);
+    const root = join(cwd, answers.specDir);
     const dirs = [
       "tokens",
       "contracts",
@@ -455,14 +624,19 @@ export async function init(): Promise<void> {
 
     writeIfMissing(
       join(root, "openuispec.yaml"),
-      manifestTemplate(name, targets, specDir)
+      manifestTemplate(answers.name, answers.targets, {
+        withApi: answers.withApi,
+        backendPath: answers.backendPath,
+      }),
+      quiet
     );
 
     // ── spec README ──────────────────────────────────────────────
 
     writeIfMissing(
       join(root, "README.md"),
-      specReadmeTemplate(name, targets)
+      specReadmeTemplate(answers.name, answers.targets),
+      quiet
     );
 
     // ── .gitkeep for empty dirs ────────────────────────────────────
@@ -476,65 +650,78 @@ export async function init(): Promise<void> {
         const gk = join(dir, ".gitkeep");
         if (!existsSync(gk)) {
           writeFileSync(gk, "");
-          console.log(`  create ${relative(cwd, gk)}`);
+          if (!quiet) console.log(`  create ${relative(cwd, gk)}`);
         }
       }
     }
 
     // ── AI assistant rules ─────────────────────────────────────────
 
-    const rules = aiRulesBlock(specDir, targets);
+    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")) {
-          console.log(`  skip ${file} (already has OpenUISpec rules)`);
+          if (!quiet) console.log(`  skip ${file} (already has OpenUISpec rules)`);
           continue;
         }
         appendFileSync(filePath, "\n" + rules);
-        console.log(`  update ${file} (appended rules)`);
+        if (!quiet) console.log(`  update ${file} (appended rules)`);
       } else {
         writeFileSync(filePath, rules.trimStart());
-        console.log(`  create ${file}`);
+        if (!quiet) console.log(`  create ${file}`);
+      }
+    }
+
+    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 ───────────────────────────────────────────────────────
 
-    console.log(`
-Done! Your spec project is ready at ./${specDir}/
+    if (quiet) {
+      console.log(`./${answers.specDir}/`);
+    } else {
+      console.log(`
+Done! Your spec project is ready at ./${answers.specDir}/
 
 Getting started (new project):
-  1. Edit ${specDir}/openuispec.yaml — define your data model and API
-  2. Create screens in ${specDir}/screens/ (one YAML per screen)
-  3. Create flows in ${specDir}/flows/ (multi-step navigation)
+  1. Edit ${answers.specDir}/openuispec.yaml — define your data model and API
+  2. Create screens in ${answers.specDir}/screens/ (one YAML per screen)
+  3. Create flows in ${answers.specDir}/flows/ (multi-step navigation)
   4. Ask AI to generate native code from the spec
-  5. Run \`openuispec drift --snapshot --target ${targets[0]}\` to baseline the first accepted target state after that target output directory exists
+  5. 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 ${specDir}/screens/home.yaml as status: stub"
+     "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 drift --target ${targets[0]} --explain\` and \`openuispec prepare --target ${targets[0]}\` before asking AI to update a target
+  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 an AI-ready target update bundle
+  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.
 
 Docs: https://openuispec.rsteam.uz
 `);
+    }
   } catch (err) {
-    rl.close();
+    rl?.close();
     throw err;
   }
 }