feat: add Swift CLI preview-tool with declaration-level dependency resolution (#5)

Replace Ruby-based SPM preview path (preview-spm.sh + xcodeproj gem) with
native Swift implementation via preview-tool preview-spm subcommand. Add
SPMProjectCreator to build temporary Xcode projects for SPM package previews.
Update scripts/preview to route SPM packages to preview-tool. Remove dead
Ruby files (inject-preview-target.rb, preview-spm.sh). Update docs to remove
Ruby prerequisite.

Author: Iron-Ham

.claude/commands/preview.md

@@ -30,49 +30,46 @@ This will automatically:
 
 ### Preview Modes
 
-#### Mode 1: Dynamic Preview Injection (Fastest - Recommended)
+The unified `preview` script auto-detects the best mode. You can also be explicit:
 
-For files with `#Preview` in an Xcode project, this injects a minimal PreviewHost target:
+#### Xcode Project with #Preview (Fastest)
+
+Injects a minimal PreviewHost target, builds only required modules (~3-4 seconds):
 
 ```bash
-"${PREVIEW_BUILD_PATH:-$HOME/XcodePreviews}"/scripts/preview-dynamic.sh \
+"${PREVIEW_BUILD_PATH:-$HOME/XcodePreviews}"/scripts/preview \
   "<path-to-file.swift>" \
   --project "<path.xcodeproj>" \
   --output /tmp/preview.png
 ```
 
-**Advantages:**
-- Builds only the required modules (3-4 seconds vs minutes)
-- Works with static modules/libraries
-- Automatically includes resource bundles (Tuist and standard naming)
-- No pre-existing preview scheme required
-
-#### Mode 2: SPM Package
+#### SPM Package
 
-For files in Swift Package Manager packages:
+Auto-detected from Package.swift in parent directories:
 
 ```bash
-"${PREVIEW_BUILD_PATH:-$HOME/XcodePreviews}"/scripts/preview-spm.sh \
+"${PREVIEW_BUILD_PATH:-$HOME/XcodePreviews}"/scripts/preview \
   "<path-to-file.swift>" \
   --output /tmp/preview.png
 ```
 
-#### Mode 3: Standalone Swift File (No Dependencies)
+#### Standalone Swift File (No Dependencies)
 
 For Swift files that only use system frameworks (SwiftUI, UIKit, Foundation):
 
 ```bash
-"${PREVIEW_BUILD_PATH:-$HOME/XcodePreviews}"/scripts/preview-minimal.sh \
+"${PREVIEW_BUILD_PATH:-$HOME/XcodePreviews}"/scripts/preview \
   "<path-to-file.swift>" \
   --output /tmp/preview.png
 ```
 
-#### Mode 4: Capture Current Simulator
+#### Capture Current Simulator
 
 Just screenshot whatever is currently on screen:
 
 ```bash
-"${PREVIEW_BUILD_PATH:-$HOME/XcodePreviews}"/scripts/capture-simulator.sh \
+"${PREVIEW_BUILD_PATH:-$HOME/XcodePreviews}"/scripts/preview \
+  --capture \
   --output /tmp/preview.png
 ```
 
@@ -96,7 +93,7 @@ Read /tmp/preview.png
 ```
 User: /preview ~/MyApp/Modules/Components/Button.swift
 → Auto-detects MyApp.xcodeproj
-→ Uses preview-dynamic.sh for fast build (~3 seconds)
+→ Injects PreviewHost target for fast build (~3 seconds)
 → Capture screenshot showing Button component
 → Analyze visual output
 ```
@@ -105,7 +102,7 @@ User: /preview ~/MyApp/Modules/Components/Button.swift
 ```
 User: /preview ~/MyPackage/Sources/UI/Card.swift
 → Detects Package.swift
-→ Uses preview-spm.sh
+→ Creates temporary Xcode project with SPM dependency
 → Capture screenshot
 → Analyze visual output
 ```
@@ -114,7 +111,7 @@ User: /preview ~/MyPackage/Sources/UI/Card.swift
 ```
 User: /preview MyView.swift
 → Detects system-only imports
-→ Use preview-minimal.sh to build minimal host
+→ Builds minimal host app
 → Capture screenshot
 → Analyze visual output
 ```

.codex/skills/xcode-preview-capture/SKILL.md

@@ -10,11 +10,7 @@ Use this skill to build SwiftUI previews and inspect screenshots.
 ## Prerequisites
 
 - Xcode + iOS Simulator installed
-- Ruby gem dependency:
-
-```bash
-gem install xcodeproj --user-install
-```
+- Swift toolchain (preview-tool auto-builds on first run)
 - `PREVIEW_BUILD_PATH` set to this repository root
   - Example: `export PREVIEW_BUILD_PATH=/absolute/path/to/XcodePreviews`
 

.cursor/rules/preview.mdc

@@ -28,19 +28,19 @@ A toolkit for building and capturing SwiftUI previews for visual analysis.
 | Project Type | Approach | Build Time | Script |
 |--------------|----------|------------|--------|
 | **Standalone Swift** | Minimal host app | ~5 seconds | `preview-minimal.sh` |
-| **Xcode project** | Dynamic target injection | ~3-4 seconds | `preview-dynamic.sh` |
-| **SPM package** | Temporary project creation | ~20 seconds | `preview-spm.sh` |
+| **Xcode project** | Dynamic target injection | ~3-4 seconds | `preview-tool` |
+| **SPM package** | Temporary project creation | ~20 seconds | `preview-tool` |
 
-## Scripts
+## Scripts & Tools
 
-| Script | Purpose |
-|--------|---------|
-| `preview` | Unified entry point - auto-detects best approach |
-| `preview-dynamic.sh` | Dynamic target injection for Xcode projects |
-| `preview-spm.sh` | Preview from SPM packages |
-| `preview-minimal.sh` | Build standalone Swift files |
-| `capture-simulator.sh` | Screenshot current simulator |
-| `sim-manager.sh` | Simulator management |
+| Path | Purpose |
+|------|---------|
+| `scripts/preview` | Unified entry point - auto-detects best approach |
+| `scripts/preview-minimal.sh` | Build standalone Swift files |
+| `scripts/xcode-preview.sh` | Build full Xcode project schemes |
+| `scripts/capture-simulator.sh` | Screenshot current simulator |
+| `scripts/sim-manager.sh` | Simulator management |
+| `tools/preview-tool` | Swift CLI for dynamic preview injection, SPM preview, dependency resolution |
 
 ## Workflow for Cursor
 
@@ -59,4 +59,4 @@ When asked to preview a SwiftUI view:
 
 - macOS with Xcode installed
 - iOS Simulator
-- Ruby with `xcodeproj` gem: `gem install xcodeproj --user-install`
+- Swift toolchain (preview-tool auto-builds on first run)

.cursor/skills/preview/SKILL.md

@@ -32,21 +32,23 @@ Auto-detects project type and uses the best approach:
   --output /tmp/preview-capture.png
 ```
 
-### Dynamic Preview Injection (Xcode Projects)
+### Xcode Project with #Preview
 
-Fast builds by injecting a minimal PreviewHost target:
+Fast builds by injecting a minimal PreviewHost target (handled automatically by the unified script):
 
 ```bash
-"${PREVIEW_BUILD_PATH:-$HOME/XcodePreviews}"/scripts/preview-dynamic.sh \
+"${PREVIEW_BUILD_PATH:-$HOME/XcodePreviews}"/scripts/preview \
   <path-to-file.swift> \
   --project <path.xcodeproj> \
   --output /tmp/preview.png
 ```
 
 ### SPM Package Preview
 
+Auto-detected from Package.swift in parent directories:
+
 ```bash
-"${PREVIEW_BUILD_PATH:-$HOME/XcodePreviews}"/scripts/preview-spm.sh \
+"${PREVIEW_BUILD_PATH:-$HOME/XcodePreviews}"/scripts/preview \
   <path-to-file.swift> \
   --output /tmp/preview.png
 ```
@@ -56,7 +58,7 @@ Fast builds by injecting a minimal PreviewHost target:
 Build a standalone Swift file with system frameworks only:
 
 ```bash
-"${PREVIEW_BUILD_PATH:-$HOME/XcodePreviews}"/scripts/preview-minimal.sh \
+"${PREVIEW_BUILD_PATH:-$HOME/XcodePreviews}"/scripts/preview \
   <path-to-file.swift> \
   --output /tmp/preview.png
 ```

.gitignore

@@ -17,6 +17,7 @@ DerivedData/
 build/
 *.app
 *.o
+tools/preview-tool/.build/
 
 # Temporary files
 *.swp

CLAUDE.md

@@ -25,8 +25,8 @@ A toolkit for building and capturing SwiftUI previews for visual analysis.
 | Project Type | Approach | Build Time | Script |
 |--------------|----------|------------|--------|
 | **Standalone Swift** | Minimal host app | ~5 seconds | `preview-minimal.sh` |
-| **Xcode project** | Dynamic target injection | ~3-4 seconds | `preview-dynamic.sh` |
-| **SPM package** | Temporary project creation | ~20 seconds | `preview-spm.sh` |
+| **Xcode project** | Dynamic target injection | ~3-4 seconds | `preview-tool` |
+| **SPM package** | Temporary project creation | ~20 seconds | `preview-tool` |
 
 ### Dynamic Preview Injection
 
@@ -41,17 +41,16 @@ For Xcode projects, the toolkit:
 
 This is much faster than building a full app scheme.
 
-## Scripts
+## Scripts & Tools
 
-| Script | Purpose |
-|--------|---------|
-| `preview` | Unified entry point - auto-detects best approach |
-| `preview-dynamic.sh` | Dynamic target injection for Xcode projects |
-| `preview-spm.sh` | Preview from SPM packages |
-| `preview-minimal.sh` | Build standalone Swift files |
-| `xcode-preview.sh` | Build full Xcode project schemes |
-| `capture-simulator.sh` | Screenshot current simulator |
-| `sim-manager.sh` | Simulator management |
+| Path | Purpose |
+|------|---------|
+| `scripts/preview` | Unified entry point - auto-detects best approach |
+| `scripts/preview-minimal.sh` | Build standalone Swift files |
+| `scripts/xcode-preview.sh` | Build full Xcode project schemes |
+| `scripts/capture-simulator.sh` | Screenshot current simulator |
+| `scripts/sim-manager.sh` | Simulator management |
+| `tools/preview-tool` | Swift CLI for dynamic preview injection, SPM preview, dependency resolution |
 
 ## Usage Examples
 
@@ -87,10 +86,7 @@ This is much faster than building a full app scheme.
 
 - macOS with Xcode installed
 - iOS Simulator
-- Ruby with `xcodeproj` gem:
-  ```bash
-  gem install xcodeproj --user-install
-  ```
+- Swift toolchain (preview-tool auto-builds on first run)
 
 ## Workflow for Claude
 

README.md

@@ -14,16 +14,10 @@ A CLI toolset for building and capturing SwiftUI previews programmatically. Desi
 
 - macOS with Xcode installed
 - iOS Simulator
-- Ruby (comes with macOS) with `xcodeproj` gem
+- Swift toolchain (preview-tool auto-builds on first run)
 
 ## Installation
 
-### Prerequisites
-
-```bash
-gem install xcodeproj --user-install
-```
-
 ### Claude Code: Plugin Marketplace (Recommended)
 
 Install via the Claude Code plugin marketplace:
@@ -110,16 +104,6 @@ The `preview` script auto-detects the best approach:
 
 ### Direct Scripts
 
-**For Xcode projects with `#Preview` blocks:**
-```bash
-./scripts/preview-dynamic.sh MyView.swift --project MyApp.xcodeproj
-```
-
-**For SPM packages:**
-```bash
-./scripts/preview-spm.sh MyView.swift --package /path/to/Package.swift
-```
-
 **For standalone Swift files (system imports only):**
 ```bash
 ./scripts/preview-minimal.sh MyView.swift
@@ -201,16 +185,15 @@ Ask Codex to preview a SwiftUI file. The skill instructs Codex to:
 2. Capture `/tmp/preview*.png`
 3. Read the screenshot and provide UI analysis
 
-## Scripts
+## Scripts & Tools
 
-| Script | Purpose |
-|--------|---------|
-| `preview` | Unified entry point |
-| `preview-dynamic.sh` | Xcode project preview injection |
-| `preview-spm.sh` | SPM package preview |
-| `preview-minimal.sh` | Standalone files |
-| `capture-simulator.sh` | Screenshot capture |
-| `sim-manager.sh` | Simulator utilities |
+| Path | Purpose |
+|------|---------|
+| `scripts/preview` | Unified entry point (auto-detects best approach) |
+| `scripts/preview-minimal.sh` | Standalone files (system imports only) |
+| `scripts/capture-simulator.sh` | Screenshot capture |
+| `scripts/sim-manager.sh` | Simulator utilities |
+| `tools/preview-tool` | Swift CLI for dynamic preview injection + SPM preview |
 
 ## Project Structure
 
@@ -238,11 +221,14 @@ XcodePreviews/
 │       └── SKILL.md                # Claude Code plugin skill
 ├── scripts/
 │   ├── preview                     # Unified entry point
-│   ├── preview-dynamic.sh          # Xcode project injection
-│   ├── preview-spm.sh              # SPM package preview
 │   ├── preview-minimal.sh          # Standalone files
 │   ├── capture-simulator.sh
 │   └── sim-manager.sh
+├── tools/
+│   └── preview-tool/               # Swift CLI (auto-built on first run)
+│       ├── Package.swift
+│       ├── Sources/
+│       └── Tests/
 └── templates/
 ```