morphkit-cli 0.1.0 → 0.2.0

package/CONTRIBUTING.md

@@ -0,0 +1,145 @@
+# Contributing to Morphkit
+
+Thank you for your interest in contributing to Morphkit! This guide will help you get set up and productive.
+
+## Prerequisites
+
+- **Bun** 1.0+ (primary runtime and test runner)
+- **Node.js** 18+ (for compatibility)
+- **TypeScript** 5.7+ (strict mode enforced)
+
+## Getting Started
+
+```bash
+# Clone your fork
+git clone https://github.com/<your-username>/morphkit.git
+cd morphkit
+
+# Install dependencies
+bun install
+
+# Run tests
+bun test
+
+# Type-check
+bun run typecheck
+```
+
+Verify everything passes before making changes.
+
+## Architecture Overview
+
+Morphkit uses a three-stage pipeline:
+
+```
+CLI → Analyzer → Semantic Model → Generator
+```
+
+1. **Analyzer** (`src/analyzer/`) — Parses TypeScript/React source using ts-morph. Extracts components, routes, state, and API calls.
+2. **Semantic Model** (`src/semantic/`) — Transforms analyzer output into a framework-agnostic `SemanticAppModel`, then adapts it for iOS patterns.
+3. **Generator** (`src/generator/`) — Produces SwiftUI views, models, navigation, and networking code from the semantic model.
+
+Each stage is independent and independently testable. The `SemanticAppModel` is the boundary between analysis and generation.
+
+## Code Style
+
+### TypeScript
+
+- Strict mode is enforced (`bun run typecheck` must pass with zero errors).
+- Use `const` by default. Use `let` only when reassignment is necessary.
+- Prefer explicit return types on exported functions.
+
+### Zod-First Types
+
+All shared types are defined as Zod schemas in `src/semantic/model.ts` and inferred via `z.infer<>`. This is the single source of truth.
+
+```typescript
+// Correct: define the schema, infer the type
+export const ScreenSchema = z.object({ ... });
+export type Screen = z.infer<typeof ScreenSchema>;
+
+// Incorrect: defining standalone interfaces for shared types
+export interface Screen { ... }
+```
+
+When adding new fields, update the Zod schema in `model.ts` first, then update the builder and generators.
+
+### Pipeline Conventions
+
+- Analyzers have their own types (`ExtractedComponent`, `ExtractedRoute`, etc.) that are mapped to semantic model types in the builder.
+- Generators must conform to model types, not define their own.
+- Reuse the `typeDefToSwift()` function in `swiftui-generator.ts` for TypeScript-to-Swift type conversion. Do not duplicate it.
+
+## Testing
+
+### Requirements
+
+- All existing tests must pass before submitting a PR.
+- Add tests for any new feature or bug fix.
+- Tests should verify generated output structure, not exact string matches.
+
+### Test Structure
+
+```
+test/
+├── analyzer/       # Unit tests for each extractor
+├── semantic/       # Builder tests
+├── generator/      # Generator output tests
+├── e2e/            # Full pipeline integration tests
+└── __fixtures__/   # Sample Next.js app for integration tests
+```
+
+### Running Tests
+
+```bash
+bun test                     # Run all tests
+bun test test/analyzer/      # Run analyzer tests only
+bun run typecheck            # TypeScript strict checking
+```
+
+### Integration Tests
+
+Use `test/__fixtures__/` for integration test data. The fixture directory contains a sample Next.js e-commerce app that exercises the full pipeline. Add new fixture files there when testing new patterns.
+
+## Pull Request Process
+
+1. **Fork** the repository and create a feature branch from `main`.
+2. **Branch naming**: `feat/description`, `fix/description`, or `docs/description`.
+3. **Make your changes** following the code style guidelines above.
+4. **Test**: Run `bun test` and `bun run typecheck`. Both must pass.
+5. **Commit** with clear, descriptive messages.
+6. **Open a PR** against `main` with:
+   - A summary of what changed and why.
+   - How to test the changes.
+   - Any relevant issue numbers.
+
+PRs require review before merging. Maintainers may request changes.
+
+## Adding Support for New Frameworks
+
+Morphkit is designed to be extensible. To add support for a new source framework (e.g., Vue, Svelte) or a new generation target:
+
+### New Source Framework
+
+1. Add extractors in `src/analyzer/` following the pattern of existing extractors (component, route, state, API).
+2. Update `src/analyzer/repo-scanner.ts` to detect the framework.
+3. Map extracted data to the existing `SemanticAppModel` types in `src/semantic/builder.ts`.
+4. Add fixture files in `test/__fixtures__/` and write tests.
+
+### New Generation Target
+
+1. Add a new generator directory under `src/generator/`.
+2. Consume the `SemanticAppModel` — do not add analyzer-specific logic to generators.
+3. Add templates in `templates/` if needed.
+4. Write tests that verify output structure.
+
+### New Layout or View Pattern
+
+1. Add the pattern to the appropriate Zod schema in `src/semantic/model.ts`.
+2. Update the adapter in `src/semantic/adapter.ts` to map web patterns to the new pattern.
+3. Add generation logic in the relevant generator.
+4. Add test coverage.
+
+## Questions?
+
+Open an issue on [GitHub](https://github.com/ashlrai/morphkit/issues) or start a discussion. We're happy to help.

package/README.md

@@ -4,30 +4,110 @@
 
 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)
+[![npm version](https://badge.fury.io/js/morphkit-cli.svg)](https://www.npmjs.com/package/morphkit-cli)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![CI](https://github.com/ashlrai/morphkit/actions/workflows/ci.yml/badge.svg)](https://github.com/ashlrai/morphkit/actions)
 
-**[morphkit.dev](https://morphkit.dev)**  |  **[GitHub](https://github.com/ashlrai/morphkit)**  |  **[Issues](https://github.com/ashlrai/morphkit/issues)**
+**[morphkit.dev](https://morphkit.dev)**  |  **[Docs](https://morphkit.dev/docs)**  |  **[GitHub](https://github.com/ashlrai/morphkit)**  |  **[Issues](https://github.com/ashlrai/morphkit/issues)**
 
 ---
 
 ## Quick Start
 
 ```bash
-# Install dependencies
-bun install
+# 1. See what Morphkit will build (always free)
+npx morphkit-cli plan ./my-webapp
 
-# Analyze your web app and see the semantic model
-bunx morphkit analyze ./my-nextjs-app
+# 2. Generate a full SwiftUI Xcode project
+npx morphkit-cli generate ./my-webapp -o ./ios-app
 
-# Generate a full SwiftUI Xcode project
-bunx morphkit generate ./my-nextjs-app --output ./ios-app
+# 3. Auto-complete all TODOs with AI (uses your Claude API key)
+npx morphkit-cli complete ./ios-app
 
-# Open in Xcode
-open ./ios-app/MyNextjsApp/Package.swift
+# 4. Build and run
+cd ios-app && swift build
+open Package.swift  # Opens in Xcode
 ```
 
-That's it. Three commands from web app to Xcode project.
+Morphkit auto-detects your backend stack (Supabase, Stripe, SSE streaming, etc.)
+and generates the right iOS SDK integrations. No configuration needed.
+
+---
+
+## Using with Claude Code
+
+Morphkit generates everything Claude Code needs to complete the iOS app screen-by-screen:
+
+```bash
+# 1. Generate the iOS project
+npx morphkit generate ./my-nextjs-app --output ./ios-app
+
+# 2. Register the MCP server in Claude Code
+npx morphkit setup
+
+# 3. Open in Claude Code and complete everything
+cd ios-app
+# Run /complete-all to wire up every screen
+```
+
+### What gets generated for AI
+
+| File | Purpose |
+|------|---------|
+| `CLAUDE.md` | Implementation guide with API contract, Swift conventions, completion manifest |
+| `.claude/commands/` | Slash commands: `/complete-screen`, `/verify`, `/next`, `/complete-all` |
+| `.claude/settings.json` | Auto-registers the MCP server so tools are available immediately |
+
+### MCP Tools
+
+| Tool | Description |
+|------|-------------|
+| `morphkit_analyze` | Analyze a web app and return its semantic model |
+| `morphkit_generate` | Generate a complete SwiftUI project from a web app |
+| `morphkit_plan` | Generate a prioritized implementation plan |
+| `morphkit_screen_context` | Get full context for completing a specific screen |
+| `morphkit_verify` | Check project completion: build status, TODO census, completion % |
+| `morphkit_next_task` | Get the next recommended screen to implement |
+| `morphkit_completion_status` | Machine-readable JSON with exact TODO locations for automated loops |
+| `morphkit_complete_screen` | Full context for completing a single screen (view, API, models, reference) |
+| `morphkit_fix_build_error` | Parse Swift build errors and return structured context for fixes |
+
+### Plan Command
+
+```bash
+# Analyze your app and get a comprehensive iOS conversion plan (always free)
+npx morphkit plan ./my-webapp
+```
+
+### Complete Command
+
+```bash
+# Auto-complete all MORPHKIT-TODOs using Claude API
+npx morphkit complete ./ios-app
+```
+
+### Doctor Command
+
+```bash
+# Diagnose your Morphkit configuration
+npx morphkit doctor
+```
+
+### Verify Command
+
+```bash
+npx morphkit verify ./ios-app
+```
+
+```
+Build:   ✓ pass (0 errors)
+TODOs:   12 remaining (wire-api-fetch: 8, wire-api-action: 4)
+Screens: 4/6 complete (67%)
+API:     6/8 endpoints wired (75%)
+Models:  5/5 complete (100%)
+Overall: 72% complete
+Next:    Complete CartView — 3 TODOs remaining
+```
 
 ---
 
@@ -71,11 +151,28 @@ Every generated file includes a source mapping comment tracing back to the origi
 - **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.
+- **AI-enhanced analysis (optional)** — Connect Claude, OpenAI, or 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.
 
 ---
 
+## Auto-Detected Integrations
+
+Morphkit automatically detects your backend services and generates the right iOS SDK integration:
+
+| Web Service | iOS Output | Detection |
+|-------------|-----------|-----------|
+| Supabase | Supabase Swift SDK (`SupabaseManager.swift`) | `@supabase/supabase-js` in package.json |
+| Stripe | WKWebView Checkout (`PaymentManager.swift`) | `stripe` in package.json |
+| SSE Streaming | URLSession AsyncBytes (`SSEClient.swift`) | `text/event-stream` in API routes |
+| react-markdown | MarkdownUI package | `react-markdown` in package.json |
+| Firebase | Firebase iOS SDK | `firebase` in package.json |
+| Clerk | Clerk iOS | `@clerk/nextjs` in package.json |
+
+No configuration needed — Morphkit reads your `package.json` and source files to determine what to generate.
+
+---
+
 ## How It Works
 
 Morphkit runs a three-stage pipeline:
@@ -309,6 +406,82 @@ bunx morphkit preview ./my-app --screen Products
 |--------|-------------|
 | `-s, --screen <name>` | Preview only files matching a specific screen name |
 
+### `morphkit verify <path>`
+
+Check completion status of a generated iOS project.
+
+```bash
+bunx morphkit verify ./ios-app
+```
+
+Reports build status, TODO census by category, screen/API/model completion percentages, and recommends the next step.
+
+### `morphkit setup`
+
+Register the Morphkit MCP server in Claude Code's settings.
+
+```bash
+bunx morphkit setup
+```
+
+Writes to `.claude/settings.json` so Claude Code can call `morphkit_analyze`, `morphkit_verify`, etc. directly.
+
+### `morphkit sync <source> <target>`
+
+Re-sync a generated iOS project after changes to the source web app.
+
+```bash
+bunx morphkit sync ./my-nextjs-app ./ios-app
+```
+
+### `morphkit watch <path>`
+
+Watch a web app directory and re-generate on changes.
+
+```bash
+bunx morphkit watch ./my-nextjs-app --output ./ios-app
+```
+
+### `morphkit plan <path>`
+
+Analyze a web app and generate a comprehensive iOS conversion plan. Always free — no API key required.
+
+```bash
+npx morphkit-cli plan ./my-webapp
+npx morphkit-cli plan ./my-webapp --output plan.md
+```
+
+| Option | Description |
+|--------|-------------|
+| `-o, --output <file>` | Write the plan to a file instead of stdout |
+
+### `morphkit complete <project-path>`
+
+Auto-complete all MORPHKIT-TODOs in a generated iOS project using the Claude API.
+
+```bash
+npx morphkit-cli complete ./ios-app
+npx morphkit-cli complete ./ios-app --model claude-sonnet-4-6 --max-iterations 30
+npx morphkit-cli complete ./ios-app --dry-run
+```
+
+| Option | Description |
+|--------|-------------|
+| `--model <model>` | Claude model to use (default: `claude-sonnet-4-6`) |
+| `--max-iterations <n>` | Maximum completion iterations (default: `30`) |
+| `--dry-run` | Preview changes without writing files |
+| `-v, --verbose` | Show detailed completion output |
+
+### `morphkit doctor`
+
+Diagnose Morphkit configuration and environment.
+
+```bash
+npx morphkit-cli doctor
+```
+
+Checks: Bun runtime, Swift toolchain, API keys, config file, MCP server registration.
+
 ---
 
 ## Configuration
@@ -317,11 +490,33 @@ bunx morphkit preview ./my-app --screen Products
 
 | 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. |
+| `ANTHROPIC_API_KEY` | No | Anthropic API key for Claude-powered analysis (recommended) |
+| `OPENAI_API_KEY` | No | OpenAI API key for GPT-powered analysis |
+| `XAI_API_KEY` | No | xAI API key for Grok-powered analysis |
+| `MORPHKIT_API_KEY` | No | Morphkit API key for cloud features and usage metering |
+
+### AI Provider Configuration
+
+Morphkit supports multiple AI providers for enhanced analysis. The AI layer is fully optional — all core functionality works without it using heuristic-based analysis.
+
+```bash
+# Use Claude (recommended)
+export ANTHROPIC_API_KEY=sk-ant-...
+morphkit generate ./app --ai-provider claude
+
+# Use OpenAI
+export OPENAI_API_KEY=sk-...
+morphkit generate ./app --ai-provider openai
 
-### AI Enhancement (Optional)
+# Use Grok
+export XAI_API_KEY=xai-...
+morphkit generate ./app --ai-provider grok
 
-When `XAI_API_KEY` is set, Morphkit can use xAI Grok to:
+# Disable AI (heuristics only)
+morphkit generate ./app --no-ai
+```
+
+When an AI provider is configured, Morphkit uses it to:
 
 - **Analyze intent** — understand *why* a component exists, not just what it renders
 - **Map components** — intelligently match React patterns to SwiftUI equivalents
@@ -329,7 +524,7 @@ When `XAI_API_KEY` is set, Morphkit can use xAI Grok to:
 - **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.
+If multiple API keys are set, Morphkit auto-detects the best available provider. You can override with `--ai-provider`.
 
 ---
 
@@ -338,8 +533,8 @@ The AI layer is fully optional. All core functionality works without it.
 | 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 |
+| Next.js Pages Router | Partial | Route detection, component/state extraction, generation working |
+| React + Vite | Partial | Component/state extraction, React Router detection working |
 | React + CRA | Planned | Same as Vite support |
 
 ### Supported Web Patterns
@@ -409,7 +604,7 @@ bun install
 ### Commands
 
 ```bash
-# Run all tests (53 tests, 376 assertions)
+# Run all tests (263 tests, 1422 assertions)
 bun test
 
 # TypeScript strict type checking
@@ -432,7 +627,7 @@ The test suite covers the full pipeline with a sample Next.js e-commerce app (`t
 - **Swift quality tests** — Validates generated code compiles and follows iOS conventions
 
 ```
-53 pass | 0 fail | 376 expect() calls
+263 pass | 0 fail | 1422 expect() calls
 ```
 
 ### Project Conventions
@@ -444,6 +639,112 @@ The test suite covers the full pipeline with a sample Next.js e-commerce app (`t
 
 ---
 
+## Authentication
+
+Morphkit uses API keys for authentication and usage metering.
+
+```bash
+# Set your API key as an environment variable
+export MORPHKIT_API_KEY=morphkit_sk_your_key_here
+
+# Or pass it directly
+morphkit generate ./my-app --api-key morphkit_sk_your_key_here
+
+# Or save it to ~/.morphkit/config
+mkdir -p ~/.morphkit
+echo "api_key = morphkit_sk_your_key_here" > ~/.morphkit/config
+```
+
+**Free tier**: 20 conversions/month. **Pro** ($19/mo): unlimited conversions.
+
+Get your API key at [morphkit.dev/dashboard](https://morphkit.dev/dashboard).
+
+### Self-Hosted
+
+Morphkit is fully open-source (MIT). For enterprise users who want to self-host:
+
+1. Clone the repository
+2. Set up your own Supabase project for auth/metering (optional)
+3. Set `MORPHKIT_API_URL` to your instance URL, or run without auth
+
+```bash
+# Run without authentication (local/self-hosted mode)
+bun run src/index.ts generate ./my-app
+```
+
+---
+
+## Contributing
+
+We welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+
+```bash
+# Quick start for contributors
+git clone https://github.com/ashlrai/morphkit.git
+cd morphkit
+bun install
+bun test          # Run tests
+bun run typecheck # Type checking
+```
+
+---
+
+## Limitations & Unsupported Patterns
+
+- **Frameworks:** Only Next.js App Router and plain React + Vite are currently supported. Next.js Pages Router has partial support (route detection only).
+- **CSS-in-JS:** Styled-components, Emotion, and other CSS-in-JS libraries are not extracted. Tailwind CSS utility classes and plain CSS are supported.
+- **GraphQL:** GraphQL schemas and queries are detected in analysis but do not produce generated networking code. REST/fetch patterns are fully supported.
+- **Monorepo:** Monorepo project structures (Turborepo, Nx, Lerna) are untested and may not resolve cross-package imports correctly.
+- **Real-time data:** WebSocket connections and real-time data subscriptions (e.g., Supabase Realtime, Socket.io) are not supported. These are surfaced as TODOs in generated code.
+- **Server Components:** React Server Components are analyzed for route structure but their server-side data fetching is mapped to client-side `async/await` patterns.
+
+---
+
+## Troubleshooting
+
+**"No components found"**
+Ensure you are pointing Morphkit at the project root directory that contains `package.json`. Morphkit uses `package.json` to detect the framework and find source files.
+
+**"Swift syntax error" warnings after generation**
+Check the warning details in the CLI output. Common causes:
+- Type mismatches where a scalar was assigned an array value (these are emitted as TODOs)
+- Missing entity definitions for referenced types
+- Complex generic types that don't have a direct Swift equivalent
+
+These warnings are non-fatal — the generated project is still usable but may need manual fixes in the flagged files.
+
+**Stack trace or crash on error**
+Report the issue at [github.com/ashlrai/morphkit/issues](https://github.com/ashlrai/morphkit/issues) with the full error output and your framework/version info.
+
+**AI provider not working**
+- Verify your API key is set correctly: `echo $ANTHROPIC_API_KEY`
+- Try with `--no-ai` to confirm the issue is AI-specific
+- Check that your API key has sufficient quota/credits
+
+---
+
+## Roadmap
+
+- [x] Next.js App Router (full support)
+- [x] TypeScript interfaces → Swift Codable structs
+- [x] Zustand/Redux state → @Observable stores
+- [x] API routes → URLSession client
+- [ ] Next.js Pages Router
+- [x] React + Vite
+- [ ] Remix
+- [ ] Vue.js / Nuxt
+- [ ] Android (Jetpack Compose) output
+- [ ] Watch app generation
+- [ ] Widget generation
+
+---
+
+## Security
+
+Report security vulnerabilities to security@morphkit.dev. See [SECURITY.md](SECURITY.md).
+
+---
+
 ## License
 
 MIT — [AshlrAI](https://ashlr.ai)