openuispec 0.1.28 → 0.1.30

package/docs/implementation-notes.md

@@ -36,24 +36,61 @@
 
 ## `prepare` command
 
-- `openuispec prepare --target <target>` is the operational bridge between spec drift and AI implementation work.
+- `openuispec prepare --target <target>` is the operational bridge between the spec and AI implementation work.
+- `openuispec configure-target <target>` is the target stack selection step that feeds `prepare`.
+  - it should offer preset defaults for known stacks
+  - it must still allow custom values when the project uses frameworks or libraries outside the catalog
+  - `openuispec init --no-configure-targets` should remain available for users who want to defer target stack decisions until later
+  - `--defaults` is an unattended fallback only; it must not count as user confirmation for implementation
+- It should support two modes:
+  1. bootstrap mode when no target snapshot exists yet
+  2. update mode when a target snapshot exists
 - It should be documented as:
-  1. read the target's snapshot baseline
-  2. compute semantic spec changes since that baseline
-  3. produce an AI-ready bundle with likely target scope
+  1. if no snapshot exists, produce a first-time generation bundle from the manifest and current spec files
+  2. if a snapshot exists, compute semantic spec changes since that baseline
+  3. produce the target work bundle with likely target scope
 - Current output includes:
   - project and target
   - output directory
   - likely code roots
-  - baseline commit info
-  - semantic change summary
-  - per-spec-file work items
-  - best-effort candidate target files
+  - mode (`bootstrap` or `update`)
+  - baseline commit info when available
+  - target stack summary from `platform/<target>.yaml`
+  - selected option refs for known preset values
+  - semantic change summary for update mode
+  - per-spec-file work items or first-time generation spec inventory
+  - best-effort candidate target files for update mode
   - next-step guidance
+- Selected option refs should be package-manager oriented, not artifact web pages:
+  - Android: Gradle plugin ids plus `group:artifact:{latest}` library coordinates
+  - Web: npm package specs like `react-router@{latest}`
+  - iOS: package identifiers plus docs links
+- `prepare` must also carry dependency guidance explaining that these refs are anchors only.
+  - AI should add supporting build, plugin, repository, annotation-processing, runtime, dev, and test dependencies required by the chosen stack and current toolchain
+  - AI should resolve exact versions and wiring from current platform docs instead of assuming the preset list is exhaustive
+- Bootstrap mode should surface soft warnings when configured framework/stack values are custom and therefore not covered by preset dependency refs.
+  - these warnings should explain that dependency guidance is incomplete, not silently omit the missing refs
+- Bootstrap mode should also surface pending stack confirmation when values were auto-applied from defaults.
+  - `generation_ready` must remain false in that state
+  - AI consumers should ask the user to confirm or change the stack before starting implementation
+- Bootstrap mode should also carry explicit generation constraints for the target:
+  - localization rules
+    - use target-native runtime localization resources
+    - forbid in-memory string maps embedded in app code
+  - file structure rules
+    - forbid single-file app output
+    - require separate screen/component/support/resource modules
+  - platform setup rules
+    - refresh current target/framework setup guidance before generation
+    - do not rely on stale memory for project layout, resource wiring, navigation APIs, or packaging conventions
+  - target-specific directory expectations for generated code
+  - 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
 - Important positioning:
   - `prepare` does not generate code
   - `prepare` does not verify code correctness
-  - `prepare` packages the spec delta into scoped implementation work for AI or developers
+  - `prepare` packages either the current spec or the spec delta into scoped implementation work for AI or developers
 
 ## Semantic linting
 

package/docs/release-notes-v0.1.26.md

@@ -11,7 +11,7 @@ This release expands OpenUISpec as a spec-management and AI-orchestration tool f
   Drift snapshots now record the git baseline commit and branch for each target.
 
 - `openuispec prepare --target <target>`
-  Produces an AI-ready target update bundle with:
+  Produces the target work bundle with:
   - semantic change summary
   - likely code roots
   - candidate target files

package/drift/index.ts

@@ -22,6 +22,8 @@ import { execFileSync } from "node:child_process";
 import YAML from "yaml";
 
 const STATE_FILE = ".openuispec-state.json";
+export const SUPPORTED_TARGETS = ["ios", "android", "web"] as const;
+export type SupportedTarget = typeof SUPPORTED_TARGETS[number];
 
 // ── types ─────────────────────────────────────────────────────────────
 
@@ -73,7 +75,7 @@ export interface ExplainResult {
 
 // ── helpers ───────────────────────────────────────────────────────────
 
-function listFiles(dir: string, ext: string): string[] {
+export function listFiles(dir: string, ext: string): string[] {
   try {
     return readdirSync(dir)
       .filter((f) => f.endsWith(ext))
@@ -84,6 +86,10 @@ function listFiles(dir: string, ext: string): string[] {
   }
 }
 
+export function isSupportedTarget(value: string): value is SupportedTarget {
+  return (SUPPORTED_TARGETS as readonly string[]).includes(value);
+}
+
 function hashFile(filePath: string): string {
   const content = readFileSync(filePath);
   const hash = createHash("sha256").update(content).digest("hex");
@@ -106,7 +112,7 @@ function parseSpecDocument(relPath: string, content: string): unknown {
 }
 
 /** Read the status field from a screen or flow YAML file. */
-function readStatus(filePath: string): string {
+export function readStatus(filePath: string): string {
   try {
     const doc = YAML.parse(readFileSync(filePath, "utf-8"));
     if (doc && typeof doc === "object") {
@@ -123,12 +129,12 @@ function readStatus(filePath: string): string {
 }
 
 /** Returns true if a file is a screen or flow (has status semantics). */
-function hasStatusSemantics(relPath: string): boolean {
+export function hasStatusSemantics(relPath: string): boolean {
   const dir = dirname(relPath);
   return dir === "screens" || dir === "flows";
 }
 
-function discoverSpecFiles(projectDir: string): string[] {
+export function discoverSpecFiles(projectDir: string): string[] {
   const manifest = join(projectDir, "openuispec.yaml");
   if (!existsSync(manifest)) {
     console.error(`Error: No openuispec.yaml found in ${projectDir}`);
@@ -434,11 +440,14 @@ export function findProjectDir(cwd: string): string {
   process.exit(1);
 }
 
+/** Read and parse the manifest YAML. */
+export function readManifest(projectDir: string): Record<string, any> {
+  return YAML.parse(readFileSync(join(projectDir, "openuispec.yaml"), "utf-8"));
+}
+
 /** Read the project name from the manifest. */
 export function readProjectName(projectDir: string): string {
-  const doc = YAML.parse(
-    readFileSync(join(projectDir, "openuispec.yaml"), "utf-8")
-  );
+  const doc = readManifest(projectDir);
   return doc.project?.name ?? basename(projectDir);
 }
 
@@ -677,7 +686,7 @@ function check(
 
   const d = result.drift;
   const hasDrift = d.changed.length > 0 || d.added.length > 0 || d.removed.length > 0;
-  process.exit(hasDrift ? 1 : 0);
+  process.exit(hasDrift ? 2 : 0);
 }
 
 function checkAll(
@@ -721,7 +730,7 @@ function checkAll(
     }
   }
 
-  process.exit(anyDrift ? 1 : 0);
+  process.exit(anyDrift ? 2 : 0);
 }
 
 // ── output ────────────────────────────────────────────────────────────

package/examples/taskflow/AGENTS.md

@@ -1,5 +1,5 @@
 <!-- openuispec-rules-start -->
-<!-- openuispec-rules-version: 0.1.28 -->
+<!-- openuispec-rules-version: 0.1.29 -->
 # OpenUISpec — AI Assistant Rules
 # ================================
 # This project uses OpenUISpec to define UI as a semantic spec.
@@ -55,7 +55,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 `openuispec/tokens/`.
-5. **Update the manifest** — fill in `data_model` and `api.endpoints` in `openuispec/openuispec.yaml`.
+5. **Update the manifest** — fill in `data_model`, `api.endpoints`, and `generation.code_roots.backend` in `openuispec/openuispec.yaml`.
 
 ## OpenUISpec Source Of Truth
 
@@ -76,7 +76,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.
@@ -97,6 +98,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
@@ -105,7 +107,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

package/examples/taskflow/CLAUDE.md

@@ -1,5 +1,5 @@
 <!-- openuispec-rules-start -->
-<!-- openuispec-rules-version: 0.1.28 -->
+<!-- openuispec-rules-version: 0.1.29 -->
 # OpenUISpec — AI Assistant Rules
 # ================================
 # This project uses OpenUISpec to define UI as a semantic spec.
@@ -55,7 +55,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 `openuispec/tokens/`.
-5. **Update the manifest** — fill in `data_model` and `api.endpoints` in `openuispec/openuispec.yaml`.
+5. **Update the manifest** — fill in `data_model`, `api.endpoints`, and `generation.code_roots.backend` in `openuispec/openuispec.yaml`.
 
 ## OpenUISpec Source Of Truth
 
@@ -76,7 +76,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.
@@ -97,6 +98,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
@@ -105,7 +107,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

package/examples/taskflow/backend/.gitkeep

@@ -0,0 +1 @@
+

package/examples/taskflow/openuispec/README.md

@@ -27,7 +27,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
@@ -38,12 +38,17 @@ Do NOT guess the file format — skipping this step will produce invalid YAML th
 openuispec validate             # Validate spec files against schemas
 openuispec validate semantic    # Check semantic cross-references
 openuispec validate screens     # Validate only screens
+openuispec configure-target ios [--defaults] # Configure target stack defaults
 openuispec status               # Show which targets are behind
 openuispec drift --target ios --explain   # Explain semantic spec drift since ios baseline
-openuispec prepare --target ios           # Build an AI-ready ios update bundle
+openuispec prepare --target ios           # Build the target work bundle
 openuispec drift --snapshot --target ios  # Snapshot current state + git baseline after ios 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
+
 ## Learn more
 
 Docs: https://openuispec.rsteam.uz

package/examples/taskflow/openuispec/openuispec.yaml

@@ -31,6 +31,8 @@ i18n:
 
 generation:
   targets: [ios, android, web]
+  code_roots:
+    backend: "../backend/"
   output_format:
     ios: { language: swift, framework: swiftui, min_version: "17.0" }
     android: { language: kotlin, framework: compose, min_sdk: 26 }

package/examples/todo-orbit/AGENTS.md

@@ -1,5 +1,5 @@
 <!-- openuispec-rules-start -->
-<!-- openuispec-rules-version: 0.1.28 -->
+<!-- openuispec-rules-version: 0.1.29 -->
 # OpenUISpec — AI Assistant Rules
 # ================================
 # This project uses OpenUISpec to define UI as a semantic spec.
@@ -55,7 +55,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 `openuispec/tokens/`.
-5. **Update the manifest** — fill in `data_model` and `api.endpoints` in `openuispec/openuispec.yaml`.
+5. **Update the manifest** — fill in `data_model`, `api.endpoints`, and `generation.code_roots.backend` in `openuispec/openuispec.yaml`.
 
 ## OpenUISpec Source Of Truth
 
@@ -76,7 +76,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.
@@ -97,6 +98,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
@@ -105,7 +107,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

package/examples/todo-orbit/CLAUDE.md

@@ -1,5 +1,5 @@
 <!-- openuispec-rules-start -->
-<!-- openuispec-rules-version: 0.1.28 -->
+<!-- openuispec-rules-version: 0.1.29 -->
 # OpenUISpec — AI Assistant Rules
 # ================================
 # This project uses OpenUISpec to define UI as a semantic spec.
@@ -55,7 +55,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 `openuispec/tokens/`.
-5. **Update the manifest** — fill in `data_model` and `api.endpoints` in `openuispec/openuispec.yaml`.
+5. **Update the manifest** — fill in `data_model`, `api.endpoints`, and `generation.code_roots.backend` in `openuispec/openuispec.yaml`.
 
 ## OpenUISpec Source Of Truth
 
@@ -76,7 +76,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.
@@ -97,6 +98,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
@@ -105,7 +107,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

package/examples/todo-orbit/backend/.gitkeep

@@ -0,0 +1 @@
+

package/examples/todo-orbit/openuispec/README.md

@@ -27,7 +27,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
@@ -38,12 +38,17 @@ Do NOT guess the file format — skipping this step will produce invalid YAML th
 openuispec validate             # Validate spec files against schemas
 openuispec validate semantic    # Check semantic cross-references
 openuispec validate screens     # Validate only screens
+openuispec configure-target ios [--defaults] # Configure target stack defaults
 openuispec status               # Show which targets are behind
 openuispec drift --target ios --explain   # Explain semantic spec drift since ios baseline
-openuispec prepare --target ios           # Build an AI-ready ios update bundle
+openuispec prepare --target ios           # Build the target work bundle
 openuispec drift --snapshot --target ios  # Snapshot current state + git baseline after ios 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 a target snapshot was created before baseline metadata was added, `--explain` and `status` will ask you to re-run `openuispec drift --snapshot --target <target>` for that target.
 
 ## Learn more

package/examples/todo-orbit/openuispec/openuispec.yaml

@@ -29,6 +29,8 @@ generation:
   #   ios: "../ios-app/"                  # relative to this file
   #   android: "../android-app/"
   #   web: "../web-ui/"
+  code_roots:
+    backend: "../backend/"
   output_format:
     ios: { language: swift, framework: swiftui, min_version: "17.0" }
     android: { language: kotlin, framework: compose, min_sdk: 26 }

package/package.json

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