morphkit-cli 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AshlrAI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,449 @@
+# Morphkit
+
+> Your React app → Native iOS. In seconds.
+
+Morphkit is a semantic AI agent that understands your TypeScript/React web app's *intent* — not just its code — and generates a production-quality SwiftUI Xcode project. It parses your components, routes, state, and API calls, builds a framework-agnostic semantic model, then emits idiomatic Swift targeting iOS 17+.
+
+[![npm version](https://badge.fury.io/js/morphkit.svg)](https://www.npmjs.com/package/morphkit)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+**[morphkit.dev](https://morphkit.dev)**  |  **[GitHub](https://github.com/ashlrai/morphkit)**  |  **[Issues](https://github.com/ashlrai/morphkit/issues)**
+
+---
+
+## Quick Start
+
+```bash
+# Install dependencies
+bun install
+
+# Analyze your web app and see the semantic model
+bunx morphkit analyze ./my-nextjs-app
+
+# Generate a full SwiftUI Xcode project
+bunx morphkit generate ./my-nextjs-app --output ./ios-app
+
+# Open in Xcode
+open ./ios-app/MyNextjsApp/Package.swift
+```
+
+That's it. Three commands from web app to Xcode project.
+
+---
+
+## What Gets Generated
+
+Morphkit produces a complete, buildable Swift Package with this structure:
+
+```
+ios-app/
+├── Package.swift                       # Swift Package manifest (iOS 17+)
+├── MyApp/
+│   ├── MyAppApp.swift                  # @main app entry point
+│   ├── ContentView.swift               # Root navigation (TabView + NavigationStack)
+│   ├── Info.plist                       # App configuration
+│   ├── Assets.xcassets/                 # Colors, app icon placeholders
+│   ├── Models/                          # Codable structs from your TS interfaces
+│   ├── Views/                           # SwiftUI views from your React components
+│   ├── Navigation/                      # Router, routes enum, tab configuration
+│   ├── Networking/                      # Typed URLSession API client
+│   └── State/                           # @Observable stores from your state management
+├── Tests/
+│   └── MyAppTests.swift                # Test stubs
+└── README.md                            # Generated project documentation
+```
+
+Every generated file includes a source mapping comment tracing back to the original web file:
+
+```swift
+// Generated by Morphkit from: types/product.ts
+```
+
+---
+
+## Features
+
+- **Semantic understanding** — Morphkit doesn't do string replacement. It builds an intermediate *semantic model* that captures what your app does, then generates native code from that understanding.
+- **Full TypeScript type extraction** — Interfaces, type aliases, enums, and union types are converted to `Codable` Swift structs and enums with full fidelity.
+- **React component analysis** — Detects layout patterns (list, detail, form, dashboard, settings) and generates the appropriate SwiftUI view composition.
+- **Route-to-navigation mapping** — Next.js App Router file-based routes become `TabView`, `NavigationStack`, and deep link handlers.
+- **State management translation** — `useState`, Zustand stores, Redux, and Context patterns map to `@Observable` classes and `@State` bindings.
+- **API client generation** — `fetch` calls and API routes become a typed `URLSession` networking layer with `async/await`.
+- **Confidence scoring** — Every generated file is tagged high/medium/low confidence so you know what to review first.
+- **Preview data factories** — `#if DEBUG` extensions with `.preview()` methods for every model, so SwiftUI previews work out of the box.
+- **AI-enhanced analysis (optional)** — Connect xAI Grok for deeper intent extraction, smarter component mapping, and navigation planning.
+- **Zero runtime dependencies** — Generated Swift code uses only Foundation and SwiftUI. No third-party pods or packages.
+
+---
+
+## How It Works
+
+Morphkit runs a three-stage pipeline:
+
+```
+┌─────────────┐      ┌──────────────────┐      ┌─────────────────┐
+│  1. Analyze  │  →   │  2. Semantic      │  →   │  3. Generate     │
+│              │      │     Model         │      │                  │
+│  ts-morph    │      │  Zod-validated    │      │  SwiftUI views   │
+│  AST parsing │      │  app description  │      │  Swift models    │
+│  Route scan  │      │  Platform adapt   │      │  Navigation      │
+│  State scan  │      │                   │      │  Networking      │
+│  API scan    │      │                   │      │  State stores    │
+└─────────────┘      └──────────────────┘      └─────────────────┘
+```
+
+**Stage 1: Analyze** — Uses [ts-morph](https://ts-morph.com) to parse your TypeScript AST. Extracts components, routes, state patterns, API calls, types, and framework metadata. Detects Next.js App Router, Pages Router, or plain React.
+
+**Stage 2: Semantic Model** — Builds a framework-agnostic `SemanticAppModel` (validated with Zod schemas) that describes *what* the app does: its entities, screens, navigation flows, state management, API endpoints, auth patterns, and theme. An optional platform adapter then maps web patterns to iOS equivalents.
+
+**Stage 3: Generate** — Five specialized generators emit Swift code from the semantic model: views, models, navigation, networking, and state. The output is a complete Swift Package that opens directly in Xcode.
+
+---
+
+## Example
+
+Given this TypeScript in your Next.js app:
+
+```typescript
+// types/product.ts
+export interface Product {
+  id: string;
+  name: string;
+  description: string;
+  price: number;
+  imageUrl: string;
+  category: string;
+  inStock: boolean;
+  rating?: number;
+  createdAt: Date;
+}
+
+export type SortOrder = 'price-asc' | 'price-desc' | 'name' | 'rating';
+```
+
+Morphkit generates:
+
+```swift
+// Generated by Morphkit from: types/product.ts
+
+import Foundation
+
+struct Product: Codable, Identifiable, Hashable {
+    let id: String
+    var name: String
+    var description: String
+    var price: Double
+    var imageUrl: String
+    var category: String
+    var inStock: Bool
+    var rating: Double?
+    var createdAt: Date
+}
+
+enum SortOrder: String, Codable, CaseIterable {
+    case priceAsc = "price-asc"
+    case priceDesc = "price-desc"
+    case name
+    case rating
+}
+
+// MARK: - Preview Data
+
+#if DEBUG
+extension Product {
+    static func preview() -> Product {
+        Product(
+            id: "preview-1",
+            name: "Sample Product",
+            description: "A sample product for previewing",
+            price: 29.99,
+            imageUrl: "https://picsum.photos/200",
+            category: "Sample",
+            inStock: true,
+            rating: nil,
+            createdAt: .now
+        )
+    }
+}
+#endif
+```
+
+And your `app/products/page.tsx` list component becomes a native SwiftUI view:
+
+```swift
+// Generated by Morphkit from: app/products/page.tsx
+
+import SwiftUI
+
+struct ProductsView: View {
+    @State private var products: [Product] = []
+    @State private var searchQuery: String = ""
+    @State private var sortOrder: SortOrder = .priceAsc
+    @State private var isLoading: Bool = false
+    @State private var errorMessage: String?
+
+    var body: some View {
+        List {
+            ForEach(products) { product in
+                NavigationLink(value: AppRoute.productsDetail(id: product.id)) {
+                    HStack(spacing: 12) {
+                        AsyncImage(url: URL(string: product.imageUrl)) { image in
+                            image.resizable().aspectRatio(contentMode: .fill)
+                        } placeholder: {
+                            Image(systemName: "photo.circle.fill")
+                                .foregroundStyle(.secondary)
+                        }
+                        .frame(width: 44, height: 44)
+                        .clipShape(RoundedRectangle(cornerRadius: 8))
+                        VStack(alignment: .leading, spacing: 4) {
+                            Text(product.name)
+                                .font(.headline)
+                            Text(product.category)
+                                .font(.subheadline)
+                                .foregroundStyle(.secondary)
+                            Text(product.price, format: .currency(code: "USD"))
+                                .font(.subheadline)
+                                .fontWeight(.semibold)
+                        }
+                        Spacer()
+                    }
+                }
+            }
+        }
+        .searchable(text: $searchQuery)
+        .refreshable { await loadData() }
+        .navigationTitle("Products")
+        .task { await loadData() }
+    }
+
+    private func loadData() async {
+        isLoading = true
+        defer { isLoading = false }
+        do {
+            products = try await APIClient.shared.fetchProduct()
+        } catch {
+            errorMessage = error.localizedDescription
+        }
+    }
+}
+```
+
+The root `ContentView.swift` wires everything together with tab-based navigation:
+
+```swift
+// Generated by Morphkit
+
+import SwiftUI
+
+struct ContentView: View {
+    @State private var router = Router()
+
+    var body: some View {
+        TabView(selection: $router.selectedTab) {
+            NavigationStack {
+                HomeView()
+                    .navigationDestination(for: AppRoute.self) { route in
+                        routeView(for: route)
+                    }
+            }
+            .tabItem {
+                Label(AppTab.home.title, systemImage: AppTab.home.systemImage)
+            }
+            .tag(AppTab.home)
+            // ... Products, Cart tabs
+        }
+        .environment(router)
+        .onOpenURL { url in
+            router.handleDeepLink(url)
+        }
+    }
+}
+```
+
+---
+
+## CLI Reference
+
+### `morphkit analyze <path>`
+
+Analyze a web app and output its semantic model as JSON.
+
+```bash
+bunx morphkit analyze ./my-app
+bunx morphkit analyze ./my-app --output model.json
+bunx morphkit analyze ./my-app --verbose
+```
+
+| Option | Description |
+|--------|-------------|
+| `-o, --output <file>` | Write the semantic model JSON to a file instead of stdout |
+| `-v, --verbose` | Show detailed analysis output (component counts, route counts, etc.) |
+
+### `morphkit generate <path>`
+
+Generate a complete SwiftUI Xcode project from a web app.
+
+```bash
+bunx morphkit generate ./my-app
+bunx morphkit generate ./my-app --output ./ios-app --name ShopKit
+bunx morphkit generate ./my-app --model model.json
+```
+
+| Option | Description |
+|--------|-------------|
+| `-o, --output <dir>` | Output directory for the iOS project (default: `./ios-app`) |
+| `-n, --name <name>` | App name — must be PascalCase (default: from `package.json`) |
+| `--model <file>` | Use a pre-built semantic model JSON instead of re-analyzing |
+| `-v, --verbose` | Show detailed generation output |
+
+### `morphkit preview <path>`
+
+Preview what would be generated without writing any files to disk.
+
+```bash
+bunx morphkit preview ./my-app
+bunx morphkit preview ./my-app --screen Products
+```
+
+| Option | Description |
+|--------|-------------|
+| `-s, --screen <name>` | Preview only files matching a specific screen name |
+
+---
+
+## Configuration
+
+### Environment Variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `XAI_API_KEY` | No | xAI API key for AI-enhanced analysis. When set, Morphkit uses Grok (`grok-4-1-fast-reasoning`) for deeper intent extraction, component mapping, navigation planning, and state architecture recommendations. Without it, Morphkit falls back to heuristic-based analysis. |
+
+### AI Enhancement (Optional)
+
+When `XAI_API_KEY` is set, Morphkit can use xAI Grok to:
+
+- **Analyze intent** — understand *why* a component exists, not just what it renders
+- **Map components** — intelligently match React patterns to SwiftUI equivalents
+- **Plan navigation** — decide whether tabs, stacks, or mixed patterns are most idiomatic
+- **Architect state** — recommend `@Observable` store structure based on your Zustand/Redux/Context patterns
+- **Generate code** — produce more nuanced SwiftUI for complex screen layouts
+
+The AI layer is fully optional. All core functionality works without it.
+
+---
+
+## Supported Frameworks
+
+| Framework | Status | Notes |
+|-----------|--------|-------|
+| Next.js App Router | Supported | Full support for file-based routing, layouts, loading states, API routes |
+| Next.js Pages Router | Planned | Route detection works; component analysis coming |
+| React + Vite | Planned | Component and state extraction works; routing TBD |
+| React + CRA | Planned | Same as Vite support |
+
+### Supported Web Patterns
+
+| Web Pattern | iOS Equivalent |
+|-------------|----------------|
+| `useState` | `@State` |
+| Zustand stores | `@Observable` classes |
+| Redux stores | `@Observable` singletons via `@Environment` |
+| React Context | `@Environment` with custom `EnvironmentKey` |
+| React Query / SWR | `async/await` with `.task { }` |
+| `fetch` / `axios` | Typed `URLSession` via `APIClient` |
+| Next.js file routing | `NavigationStack` + `TabView` |
+| Dynamic routes (`[id]`) | `.navigationDestination(for:)` |
+| CSS / Tailwind | SwiftUI modifiers + theme configuration |
+
+---
+
+## Architecture
+
+```
+src/
+├── index.ts                  # CLI entry (Commander.js + chalk + ora)
+├── analyzer/                 # Stage 1: Web app analysis
+│   ├── repo-scanner.ts       # File discovery, framework detection
+│   ├── ast-parser.ts         # TypeScript AST parsing (ts-morph)
+│   ├── component-extractor   # React component analysis
+│   ├── route-extractor       # Next.js route tree extraction
+│   ├── state-extractor       # State management detection
+│   └── api-extractor         # API endpoint extraction
+├── semantic/                 # Stage 2: Semantic model
+│   ├── model.ts              # Zod schemas (single source of truth for all types)
+│   ├── builder.ts            # Analyzer output → SemanticAppModel
+│   └── adapter.ts            # Web patterns → iOS patterns
+├── generator/                # Stage 3: SwiftUI code generation
+│   ├── swiftui-generator     # View generation (List, Form, Detail, Dashboard)
+│   ├── model-generator       # Swift Codable structs from entities
+│   ├── navigation-generator  # TabView, NavigationStack, Router
+│   ├── networking-generator  # URLSession API client
+│   └── project-generator     # Xcode project orchestrator
+└── ai/                       # AI integration (optional)
+    ├── grok-client.ts        # OpenAI SDK → xAI endpoint
+    ├── structured-output.ts  # Zod schemas for AI responses
+    └── prompts/              # Intent, component, code gen prompts
+```
+
+The `SemanticAppModel` (defined as Zod schemas in `src/semantic/model.ts`) is the central contract. Everything before it is analysis; everything after it is generation. This separation means you can swap out the analyzer (to support Vue, Angular, etc.) or the generator (to target Kotlin/Compose, Flutter, etc.) without touching the other side.
+
+---
+
+## Development
+
+### Prerequisites
+
+- [Bun](https://bun.sh) 1.0+
+- Node.js 20+ (alternative runtime)
+- TypeScript 5.7+
+
+### Setup
+
+```bash
+git clone https://github.com/ashlrai/morphkit.git
+cd morphkit
+bun install
+```
+
+### Commands
+
+```bash
+# Run all tests (53 tests, 376 assertions)
+bun test
+
+# TypeScript strict type checking
+bun run typecheck
+
+# Run against a local web app
+bun run src/index.ts analyze ./path-to-app
+bun run src/index.ts generate ./path-to-app --output ./ios-output
+bun run src/index.ts preview ./path-to-app
+```
+
+### Test Suite
+
+The test suite covers the full pipeline with a sample Next.js e-commerce app (`test/__fixtures__/sample-nextjs-app/`):
+
+- **Analyzer tests** — AST parsing, component extraction, route detection, state pattern recognition
+- **Semantic tests** — Model building, type mapping, adapter transformations
+- **Generator tests** — Swift model output, view generation, navigation, networking
+- **E2E tests** — Full pipeline from source scan to generated Xcode project
+- **Swift quality tests** — Validates generated code compiles and follows iOS conventions
+
+```
+53 pass | 0 fail | 376 expect() calls
+```
+
+### Project Conventions
+
+- All types are Zod schemas first, TypeScript types inferred via `z.infer<>` (see `src/semantic/model.ts`)
+- Generated Swift targets iOS 17+ (`@Observable`, not `ObservableObject`; `#Preview`, not `PreviewProvider`)
+- Entity names are PascalCase, variables camelCase in generated Swift
+- Every generated file carries confidence scoring and source provenance
+
+---
+
+## License
+
+MIT — [AshlrAI](https://ashlr.ai)