openuispec 0.1.3 → 0.1.5

package/cli/init.ts

@@ -35,13 +35,9 @@ async function askList(
   options: string[],
   defaults: string[]
 ): Promise<string[]> {
-  console.log(`${question}`);
-  for (const opt of options) {
-    const mark = defaults.includes(opt) ? "[x]" : "[ ]";
-    console.log(`  ${mark} ${opt}`);
-  }
+  const defaultStr = defaults.join(", ");
   const raw = (
-    await rl.question(`Enter choices (comma-separated, enter for defaults): `)
+    await rl.question(`${question} [${options.join(", ")}] (${defaultStr}): `)
   ).trim();
   if (!raw) return defaults;
   return raw
@@ -122,84 +118,6 @@ api:
 `;
 }
 
-function starterColorTokens(): string {
-  return `# Design tokens: Color palette
-brand:
-  primary:
-    "50": "#EEF2FF"
-    "100": "#E0E7FF"
-    "500": "#6366F1"
-    "600": "#4F46E5"
-    "900": "#312E81"
-
-surface:
-  background: "#FFFFFF"
-  card: "#F9FAFB"
-  elevated: "#FFFFFF"
-
-text:
-  primary: "#111827"
-  secondary: "#6B7280"
-  disabled: "#D1D5DB"
-
-semantic:
-  success: "#10B981"
-  warning: "#F59E0B"
-  error: "#EF4444"
-  info: "#3B82F6"
-`;
-}
-
-function starterTypographyTokens(): string {
-  return `# Design tokens: Typography
-font_families:
-  sans: { default: "System" }
-
-type_scale:
-  title_lg:   { size: 28, weight: bold, tracking: 0, line_height: 1.2 }
-  title_md:   { size: 22, weight: semibold, tracking: 0, line_height: 1.3 }
-  title_sm:   { size: 17, weight: semibold, tracking: 0, line_height: 1.3 }
-  body_lg:    { size: 17, weight: regular, tracking: 0, line_height: 1.5 }
-  body_md:    { size: 15, weight: regular, tracking: 0, line_height: 1.5 }
-  body_sm:    { size: 13, weight: regular, tracking: 0, line_height: 1.4 }
-  label_lg:   { size: 15, weight: medium, tracking: 0.02, line_height: 1.3 }
-  label_md:   { size: 13, weight: medium, tracking: 0.02, line_height: 1.3 }
-  caption:    { size: 11, weight: regular, tracking: 0.02, line_height: 1.3 }
-`;
-}
-
-function starterSpacingTokens(): string {
-  return `# Design tokens: Spacing
-base_unit: 4
-platform_flex: "10%"
-
-scale:
-  "0":   0
-  "1":   4
-  "2":   8
-  "3":   12
-  "4":   16
-  "5":   20
-  "6":   24
-  "8":   32
-  "10":  40
-  "12":  48
-  "16":  64
-`;
-}
-
-function starterLocale(): string {
-  return JSON.stringify(
-    {
-      app: {
-        name: "My App",
-      },
-    },
-    null,
-    2
-  );
-}
-
 function aiRulesBlock(specDir: string, targets: string[]): string {
   const targetList = targets.map((t) => `"${t}"`).join(", ");
   return `
@@ -207,49 +125,67 @@ function aiRulesBlock(specDir: string, targets: string[]): string {
 # ================================
 # 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}
+
+## What is OpenUISpec
+OpenUISpec is a YAML-based spec format that describes an app's UI semantically — tokens, screens, flows, and platform overrides. AI reads the spec and generates native code (SwiftUI, Compose, React). AI reads native code and updates the spec. The spec is the sync layer between platforms.
 
 ## Spec location
 - Spec root: \`${specDir}/\`
-- Manifest: \`${specDir}/openuispec.yaml\`
-- Always read \`openuispec.yaml\` first to understand the project structure.
-
-## Before making UI changes
-1. Read the relevant spec files (screens, tokens, flows) before modifying any UI code.
-2. If the change requires a spec update, modify the spec files FIRST, then update generated code.
-3. Never modify generated code directly — change the spec and regenerate.
-
-## After modifying spec files
-1. Run \`openuispec drift --snapshot --target <target>\` for each affected platform.
-2. Targets in this project: ${targetList}.
-3. Run \`openuispec drift\` to verify no untracked drift remains.
+- Manifest: \`${specDir}/openuispec.yaml\` — always read this first.
+- Tokens: \`${specDir}/tokens/\` — colors, typography, spacing, motion, icons, themes
+- Screens: \`${specDir}/screens/\` — one YAML file per screen
+- Flows: \`${specDir}/flows/\` — multi-step navigation journeys
+- Contracts: \`${specDir}/contracts/\` — UI component definitions
+- Platform: \`${specDir}/platform/\` — per-target overrides (iOS, Android, Web)
+- Locales: \`${specDir}/locales/\` — i18n strings (JSON, ICU MessageFormat)
+
+## If spec directories are empty (first-time setup)
+This means the project has existing UI code but hasn't been specced yet. Your job:
+
+1. **Find existing screens** — scan the codebase for UI screen files (SwiftUI views, Compose screens, React components/pages).
+2. **Create stubs** — for each screen, create \`${specDir}/screens/<name>.yaml\` with:
+   \`\`\`yaml
+   screen_name:
+     semantic: "Brief description of what this screen does"
+     status: stub
+     layout:
+       type: scroll_vertical
+   \`\`\`
+3. **Extract tokens** — scan the codebase for colors, fonts, spacing values and create token files in \`${specDir}/tokens/\`.
+4. **Update the manifest** — fill in \`data_model\` and \`api.endpoints\` in \`${specDir}/openuispec.yaml\` based on the existing code.
+5. **Spec screens on demand** — when the user asks to spec a screen, read the native code, create a full spec, and change \`status: draft\` → \`ready\`.
 
 ## Screen and flow status
-Screens and flows have a \`status\` field that controls drift tracking:
 - \`stub\` — placeholder, not yet specced. Drift detection skips these.
-- \`draft\` — in progress, actively being specced. Tracked by drift.
+- \`draft\` — actively being specced. Tracked by drift.
 - \`ready\` — fully specified (default if omitted). Tracked by drift.
 
-When adopting OpenUISpec in an existing project:
-1. Create spec files for existing screens as \`status: stub\` initially.
-2. When speccing a screen from existing code, change status to \`draft\`.
-3. Once the spec is complete and reviewed, change to \`ready\` (or remove the field).
-4. Only \`draft\` and \`ready\` screens trigger drift failures in CI.
-
-## Spec file conventions
-- Tokens (colors, typography, spacing, motion, icons) live in \`${specDir}/tokens/\`.
-- Contracts (UI component definitions) live in \`${specDir}/contracts/\`.
-- Screens live in \`${specDir}/screens/\`. One screen per file.
-- Navigation flows live in \`${specDir}/flows/\`.
-- Platform overrides live in \`${specDir}/platform/\`.
-- Localization strings live in \`${specDir}/locales/\`.
-
-## Key rules
-- The spec uses 7 contract families: nav_container, surface, action_trigger, input_field, data_display, collection, feedback.
-- Custom contracts are prefixed with \`x_\` (e.g., \`x_media_player\`).
-- Data binding uses \`$data:\`, \`$state:\`, \`$param:\`, \`$t:\` prefixes.
-- Actions use typed action objects (navigate, api_call, set_state, confirm, etc.).
-- When adding a new screen, also create the corresponding spec file.
-- When renaming or removing a screen, update the spec and all flow references.
+## Making UI changes
+1. Read the relevant spec files before modifying any UI code.
+2. If the change requires a spec update, modify the spec FIRST, then update code.
+3. Never modify generated code without updating the spec.
+4. When adding a new screen, create the corresponding spec file.
+5. When removing a screen, remove the spec file and update flow references.
+
+## After modifying spec files
+1. Run \`openuispec validate\` to check specs against the schema.
+2. Run \`openuispec drift --snapshot --target <target>\` for each affected platform.
+3. Run \`openuispec drift\` to verify no untracked drift remains.
+
+## Spec format reference
+- 7 contract families: nav_container, surface, action_trigger, input_field, data_display, collection, feedback
+- Custom contracts: prefixed with \`x_\` (e.g., \`x_media_player\`)
+- Data binding: \`$data:\`, \`$state:\`, \`$param:\`, \`$t:\` prefixes
+- Actions: typed objects (navigate, api_call, set_state, confirm, sequence, feedback, etc.)
+- Adaptive layout: size classes (compact, regular, expanded) with per-section overrides
+
+## CLI commands
+- \`openuispec init\` — scaffold a new spec project
+- \`openuispec validate [group...]\` — validate spec files against schemas
+- \`openuispec drift --target <t>\` — check for spec drift
+- \`openuispec drift --snapshot --target <t>\` — snapshot current state
+- \`openuispec drift --all\` — include stubs in drift check
 `;
 }
 
@@ -261,10 +197,9 @@ export async function init(): Promise<void> {
   console.log("\nOpenUISpec — Project Setup\n");
 
   try {
-    // 1. Project name
+    // 1. Project name (display name in manifest, derived from current folder)
     const cwd = process.cwd();
-    const defaultName =
-      cwd.split("/").pop()?.replace(/[^a-zA-Z0-9]/g, "") || "MyApp";
+    const defaultName = cwd.split("/").pop() || "MyApp";
     const name = await ask(rl, "Project name", defaultName);
 
     // 2. Spec directory
@@ -276,7 +211,7 @@ export async function init(): Promise<void> {
       rl,
       "\nWhich platforms?",
       allTargets,
-      ["ios", "android"]
+      allTargets
     );
 
     if (targets.length === 0) {
@@ -284,16 +219,6 @@ export async function init(): Promise<void> {
       process.exit(1);
     }
 
-    // 4. Starter tokens?
-    const wantTokens = await ask(rl, "Include starter tokens? (y/n)", "y");
-
-    // 5. AI rules?
-    const wantRules = await ask(
-      rl,
-      "Add rules to CLAUDE.md and AGENTS.md? (y/n)",
-      "y"
-    );
-
     rl.close();
 
     // ── create folders ─────────────────────────────────────────────
@@ -322,27 +247,6 @@ export async function init(): Promise<void> {
       manifestTemplate(name, targets, specDir)
     );
 
-    // ── starter tokens ─────────────────────────────────────────────
-
-    if (wantTokens.toLowerCase().startsWith("y")) {
-      writeIfMissing(join(root, "tokens", "color.yaml"), starterColorTokens());
-      writeIfMissing(
-        join(root, "tokens", "typography.yaml"),
-        starterTypographyTokens()
-      );
-      writeIfMissing(
-        join(root, "tokens", "spacing.yaml"),
-        starterSpacingTokens()
-      );
-    }
-
-    // ── starter locale ─────────────────────────────────────────────
-
-    writeIfMissing(
-      join(root, "locales", "en.json"),
-      starterLocale() + "\n"
-    );
-
     // ── .gitkeep for empty dirs ────────────────────────────────────
 
     for (const d of dirs) {
@@ -361,23 +265,21 @@ export async function init(): Promise<void> {
 
     // ── AI assistant rules ─────────────────────────────────────────
 
-    if (wantRules.toLowerCase().startsWith("y")) {
-      const rules = aiRulesBlock(specDir, 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)`);
-            continue;
-          }
-          appendFileSync(filePath, "\n" + rules);
-          console.log(`  update ${file} (appended rules)`);
-        } else {
-          writeFileSync(filePath, rules.trimStart());
-          console.log(`  create ${file}`);
+    const rules = aiRulesBlock(specDir, 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)`);
+          continue;
         }
+        appendFileSync(filePath, "\n" + rules);
+        console.log(`  update ${file} (appended rules)`);
+      } else {
+        writeFileSync(filePath, rules.trimStart());
+        console.log(`  create ${file}`);
       }
     }
 
@@ -386,14 +288,28 @@ export async function init(): Promise<void> {
     console.log(`
 Done! Your spec project is ready at ./${specDir}/
 
-Next steps:
-  1. Edit ${specDir}/openuispec.yaml to define your data model and API
-  2. Add screens in ${specDir}/screens/
-  3. Add flows in ${specDir}/flows/
-  4. Generate code for your target platform
+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)
+  4. Ask AI to generate native code from the spec
   5. Run \`openuispec drift --snapshot --target ${targets[0]}\` to baseline
 
-Learn more: https://github.com/anthropics/openuispec
+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"
+  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
+
+Commands:
+  openuispec validate             Validate spec files
+  openuispec drift --target ios   Check for spec changes
+  openuispec drift --snapshot --target ios   Save current state
+
+AI rules have been added to CLAUDE.md and AGENTS.md.
+
+Learn more: https://github.com/rsktash/openuispec
 `);
   } catch (err) {
     rl.close();

package/package.json

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