@noego/stitch 1.0.0

package/docs/project.md

@@ -0,0 +1,856 @@
+# Stitch Project Plan: YAML Modularization for Groom Application
+
+## Problem Statement
+
+The Groom barber shop application has grown to use large OpenAPI YAML files that are becoming difficult to maintain:
+
+- **Backend OpenAPI**: `/Users/shavauhngabay/dev/groom/backend/openapi.yaml` (1,511 lines)
+- **Frontend OpenAPI**: `/Users/shavauhngabay/dev/groom/frontend/openapi.yaml` (466 lines)
+
+These monolithic files contain:
+- **Backend**: API endpoint definitions with controllers, middleware, and schemas
+- **Frontend**: Route definitions with Svelte views and layouts for the Forge framework
+
+As the application grows, these files will become increasingly unwieldy and difficult to collaborate on.
+
+## Current Architecture Analysis
+
+### Backend (`/groom/backend/`)
+- Uses `@noego/dinner` framework for API routing
+- OpenAPI file defines REST endpoints with custom extensions:
+  - `x-controller`: Points to controller classes
+  - `x-action`: Specifies controller methods
+  - `x-middleware`: Defines middleware chains
+- File structure includes paths, components/schemas, and security definitions
+- Consumed by dinner framework for automatic route generation
+
+### Frontend (`/groom/frontend/`)
+- Uses `@noego/forge` framework for SSR/client-side routing
+- OpenAPI file defines page routes with custom extensions:
+  - `x-view`: Specifies Svelte component to render
+  - `x-layout`: Defines layout component hierarchy
+- Consumed by forge framework for automatic route generation and component loading
+- Client configured in `client.ts` to load `frontend/openapi.yaml`
+- Server configured in `app.ts` to load same OpenAPI file
+
+## Solution: Stitch YAML Modularization Tool
+
+### Core Concept
+Stitch will allow breaking down large OpenAPI YAML files into smaller, manageable modules that can be combined at build time or runtime.
+
+### Proposed File Structure
+
+#### Backend Modularization
+```
+/groom/backend/
+├── stitch.yaml              # Main stitch configuration
+├── openapi/
+│   ├── base.yaml           # OpenAPI header, info, servers
+│   ├── security.yaml       # Security schemes and definitions
+│   ├── components/
+│   │   ├── schemas/
+│   │   │   ├── user.yaml
+│   │   │   ├── business.yaml
+│   │   │   └── booking.yaml
+│   │   └── responses.yaml
+│   └── paths/
+│       ├── users.yaml      # All user-related endpoints
+│       ├── businesses.yaml # All business-related endpoints
+│       ├── bookings.yaml   # All booking-related endpoints
+│       └── auth.yaml       # Authentication endpoints
+```
+
+#### Frontend Modularization
+```
+/groom/frontend/
+├── stitch.yaml              # Main stitch configuration
+├── openapi/
+│   ├── base.yaml           # OpenAPI header and info
+│   ├── layouts.yaml        # Global layout definitions
+│   └── routes/
+│       ├── home.yaml       # Home page routes
+│       ├── users.yaml      # User-related pages
+│       ├── businesses.yaml # Business-related pages
+│       ├── bookings.yaml   # Booking-related pages
+│       └── auth.yaml       # Authentication pages
+```
+
+### Stitch Configuration Format
+
+**Simple and Clean**: Stitch uses a minimal configuration format that just lists files to merge.
+
+#### Backend `stitch.yaml`
+```yaml
+stitch:
+  - openapi/base.yaml
+  - openapi/security.yaml
+  - openapi/paths/*.yaml
+  - openapi/components/responses.yaml
+  - openapi/components/schemas/*.yaml
+```
+
+#### Frontend `stitch.yaml`
+```yaml
+stitch:
+  - openapi/base.yaml
+  - openapi/layouts.yaml
+  - openapi/routes/*.yaml
+```
+
+**How it works:**
+- Files are merged in order using deep merge
+- Supports glob patterns (e.g., `*.yaml`, `**/*.yaml`)
+- Globs are expanded and sorted alphabetically
+- Later files override earlier files for conflicting keys
+- Arrays and objects are merged intelligently
+- All paths are relative to the stitch.yaml file location
+
+### Implementation Strategy
+
+The approach is to build Stitch as a standalone tool first, then update forge and dinner to use Stitch for YAML loading. This ensures Stitch works independently before integration.
+
+#### Phase 1: Standalone Stitch Tool (Current Focus)
+
+**Goal**: Create a working YAML modularization tool that can be used independently via CLI or programmatic API.
+
+##### Step 1: Core Dependencies & Setup
+```bash
+# Add required dependencies
+npm install js-yaml @types/js-yaml chokidar @types/chokidar ajv ajv-formats glob @types/glob
+```
+
+Dependencies needed:
+- `js-yaml` - YAML parsing and serialization (same as forge uses)
+- `chokidar` - File watching for watch mode
+- `ajv` + `ajv-formats` - JSON Schema validation for OpenAPI validation
+- `glob` - Glob pattern matching for file expansion
+
+##### Step 2: Core Engine Implementation
+
+**File Structure:**
+```
+src/
+├── index.ts              # Main API exports
+├── cli/
+│   └── StitchCLI.ts     # CLI argument parser (already exists)
+├── core/
+│   ├── StitchEngine.ts  # Main processing engine
+│   ├── ConfigParser.ts  # Parse stitch.yaml configuration
+│   ├── YamlMerger.ts    # YAML merging logic
+│   └── Validator.ts     # OpenAPI validation
+├── types/
+│   └── StitchTypes.ts   # TypeScript interfaces
+└── utils/
+    └── FileUtils.ts     # File system utilities
+```
+
+**Core Components:**
+
+1. **StitchEngine.ts** - Main orchestrator
+   ```typescript
+   export class StitchEngine {
+     async build(configPath: string, options: BuildOptions): Promise<StitchResult>
+     buildSync(configPath: string, options: BuildOptions): StitchResult
+     async watch(configPath: string, options: WatchOptions): Promise<void>
+   }
+   
+   // Processing flow:
+   // 1. Parse stitch.yaml config
+   // 2. Expand any glob patterns to actual file paths
+   // 3. Load and parse each YAML file in order
+   // 4. Deep merge files in order (later files override earlier)
+   // 5. Validate merged result if requested
+   // 6. Output as YAML/JSON to stdout or file
+   ```
+
+2. **ConfigParser.ts** - Parse stitch.yaml files
+   ```typescript
+   export interface StitchConfig {
+     stitch: string[];  // Array of file paths/globs to merge in order
+   }
+   
+   export class ConfigParser {
+     parseConfig(configPath: string): StitchConfig
+     resolveFilePaths(patterns: string[], baseDir: string): string[]
+     expandGlobs(patterns: string[], baseDir: string): string[]
+   }
+   ```
+
+3. **YamlMerger.ts** - Deep YAML merging
+   ```typescript
+   export class YamlMerger {
+     mergeFiles(files: string[]): any
+     deepMerge(target: any, source: any): any
+     
+     // Deep merge rules:
+     // - Objects: merge properties, source overrides target
+     // - Arrays: source replaces target completely  
+     // - Primitives: source overrides target
+   }
+   ```
+
+4. **Validator.ts** - OpenAPI schema validation
+   ```typescript
+   export class Validator {
+     validateOpenAPI(yamlContent: any): ValidationResult
+     validateYamlSyntax(yamlString: string): ValidationResult
+   }
+   ```
+
+##### Step 3: CLI Implementation
+
+Update `cli.ts` to implement actual functionality:
+
+```typescript
+// cli.ts updates needed
+switch(command.toLowerCase()){
+  case "build":
+    const inputFile = commands[1] || 'stitch.yaml';
+    const engine = new StitchEngine();
+    const result = await engine.build(inputFile, {
+      output: args.flags.output,
+      format: args.flags.format || 'yaml',
+      validate: args.flags.validate,
+      quiet: args.flags.quiet
+    });
+    
+    if (result.success) {
+      if (!args.flags.quiet) {
+        if (args.flags.output) {
+          console.log(`Built successfully to ${args.flags.output}`);
+        } else {
+          console.log(result.data); // Output to stdout
+        }
+      }
+    } else {
+      console.error(result.error);
+      process.exit(1);
+    }
+    break;
+
+  case "watch":
+    const watchFile = commands[1] || 'stitch.yaml';
+    const engine = new StitchEngine();
+    await engine.watch(watchFile, {
+      output: args.flags.output,
+      format: args.flags.format || 'yaml',
+      validate: args.flags.validate,
+      quiet: args.flags.quiet
+    });
+    break;
+}
+```
+
+##### Step 4: Programmatic API
+
+Export clean API in `src/index.ts`:
+
+```typescript
+export { StitchEngine } from './core/StitchEngine';
+export * from './types/StitchTypes';
+
+// Convenience functions
+export const stitch = {
+  build: async (options: BuildOptions) => new StitchEngine().build(options.input || 'stitch.yaml', options),
+  buildSync: (options: BuildOptions) => new StitchEngine().buildSync(options.input || 'stitch.yaml', options),
+  watch: async (options: WatchOptions) => new StitchEngine().watch(options.input || 'stitch.yaml', options),
+};
+```
+
+##### Step 5: Testing Strategy
+
+Create test files to validate functionality:
+
+```
+test/
+├── fixtures/
+│   ├── simple/
+│   │   ├── stitch.yaml          # stitch: [base.yaml, paths.yaml]
+│   │   ├── base.yaml           # OpenAPI header, info
+│   │   └── paths.yaml          # paths section
+│   └── complex/
+│       ├── stitch.yaml         # stitch: [base.yaml, paths/users.yaml, ...]
+│       ├── base.yaml          # OpenAPI header, info, servers
+│       ├── paths/
+│       │   ├── users.yaml     # paths: { /users: {...} }
+│       │   └── businesses.yaml # paths: { /businesses: {...} }
+│       └── components/
+│           └── schemas.yaml   # components: { schemas: {...} }
+└── StitchEngine.test.ts
+```
+
+**Example simple test case:**
+
+`test/fixtures/simple/stitch.yaml`:
+```yaml
+stitch:
+  - base.yaml
+  - paths.yaml
+```
+
+**Example with globs:**
+
+`test/fixtures/complex/stitch.yaml`:
+```yaml
+stitch:
+  - base.yaml
+  - paths/*.yaml
+  - components/**/*.yaml
+```
+
+`test/fixtures/simple/base.yaml`:
+```yaml
+openapi: '3.0.3'
+info:
+  title: Test API
+  version: '1.0.0'
+```
+
+`test/fixtures/simple/paths.yaml`:
+```yaml
+paths:
+  /test:
+    get:
+      summary: Test endpoint
+      responses:
+        '200':
+          description: OK
+```
+
+**Expected merged result:**
+```yaml
+openapi: '3.0.3'
+info:
+  title: Test API
+  version: '1.0.0'
+paths:
+  /test:
+    get:
+      summary: Test endpoint
+      responses:
+        '200':
+          description: OK
+```
+
+#### Phase 2: Integration with Forge/Dinner (Future)
+
+Once Stitch is working standalone:
+
+1. **Update forge** to use Stitch for YAML loading
+   - Modify `src/parser/openapi.ts` to optionally use Stitch
+   - Add fallback to current behavior for backward compatibility
+
+2. **Update dinner** to use Stitch for YAML loading  
+   - Similar integration approach
+
+3. **Groom Migration**
+   - Split existing YAML files using working Stitch tool
+   - Update build processes to use Stitch
+
+#### Success Criteria for Phase 1
+
+1. ✅ CLI commands work: `stitch build`, `stitch watch`
+2. ✅ Options work: `--output`, `--format`, `--validate`, `--quiet`  
+3. ✅ Programmatic API works: `stitch.build()`, `stitch.buildSync()`
+4. ✅ YAML merging preserves OpenAPI structure correctly
+5. ✅ Watch mode detects file changes and rebuilds
+6. ✅ Validation catches invalid YAML and OpenAPI issues
+7. ✅ Error messages are clear and helpful
+8. ✅ Performance is acceptable (< 1 second for typical builds)
+
+## Phase 1.5: Binary Distribution Setup (Current Task)
+
+**Goal**: Package Stitch as a distributable npm package with a global CLI binary.
+
+### Tasks to Complete
+
+1. **Build System Setup**
+   - Configure TypeScript compilation for distribution
+   - Set up proper build pipeline for binary distribution
+   - Ensure all dependencies are properly bundled/referenced
+
+2. **Binary Configuration**
+   - Add `bin` field to package.json pointing to compiled CLI
+   - Create executable CLI entry point
+   - Set proper file permissions and shebang
+
+3. **Package.json Updates**
+   - Configure proper exports for both programmatic and CLI usage
+   - Set up build scripts for distribution
+   - Ensure proper entry points for different use cases
+
+4. **Distribution Testing**
+   - Test global installation: `npm install -g .`
+   - Verify `stitch` command works globally
+   - Test both local and global package usage
+   - Ensure programmatic API still works after build
+
+### Implementation Plan
+
+#### Step 1: TypeScript Build Configuration
+
+**Current Issue**: We're using `tsx` for development, but need compiled JavaScript for distribution.
+
+**Solution**: 
+- Configure TypeScript to compile to a `bin/` directory
+- Create a standalone CLI entry point that doesn't require tsx
+- Update build scripts to generate distribution-ready files
+
+**Updated File Structure:**
+```
+dist/               # Compiled JavaScript output
+├── core/
+│   ├── StitchEngine.js
+│   ├── ConfigParser.js
+│   ├── YamlMerger.js
+│   └── Validator.js
+├── types/
+│   └── StitchTypes.js
+├── cli/
+│   └── StitchCLI.js
+└── index.js       # Main API export
+
+bin/
+└── stitch.js      # CLI entry point (executable)
+
+src/               # Source TypeScript (unchanged)
+cli.ts             # Development CLI (stays for dev)
+```
+
+#### Step 2: CLI Entry Point Creation
+
+Create `bin/stitch.js` as the executable entry point:
+
+```javascript
+#!/usr/bin/env node
+
+// Production CLI entry point - uses compiled JavaScript
+const { StitchEngine } = require('../dist/core/StitchEngine');
+const { StitchCLIFactory } = require('../dist/cli/StitchCLI');
+
+// Similar logic to cli.ts but using compiled modules
+// Handle all CLI commands and flags
+```
+
+#### Step 3: Package.json Configuration
+
+**Add Binary Configuration:**
+```json
+{
+  "bin": {
+    "stitch": "./bin/stitch.js"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist/**/*",
+    "bin/**/*",
+    "README.md"
+  ]
+}
+```
+
+**Updated Scripts:**
+```json
+{
+  "scripts": {
+    "build": "tsc && npm run build:bin",
+    "build:bin": "node scripts/create-bin.js",
+    "build:client": "vite build --config vite.config.js",
+    "build:ssr": "SSR=true vite build --ssr", 
+    "dev": "tsx cli.ts",
+    "test": "jest",
+    "prepublishOnly": "npm run build",
+    "postinstall": "chmod +x bin/stitch.js"
+  }
+}
+```
+
+#### Step 4: TypeScript Configuration Updates
+
+**Update tsconfig.json:**
+```json
+{
+  "compilerOptions": {
+    "outDir": "dist",
+    "declaration": true,
+    "declarationMap": true,
+    "target": "ES2020",
+    "module": "CommonJS",
+    "moduleResolution": "node"
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "test", "bin"]
+}
+```
+
+#### Step 5: Distribution Workflow
+
+1. **Development**: Use `npm run dev` (tsx cli.ts)
+2. **Testing**: Use `npm test` (jest on source files)
+3. **Building**: Use `npm run build` (compile + create bin)
+4. **Local Install**: Use `npm install -g .` (test global CLI)
+5. **Publishing**: Use `npm publish` (with prepublishOnly hook)
+
+### Testing Plan
+
+1. **Build Test**: `npm run build` should create dist/ and bin/
+2. **Local Install Test**: `npm install -g .` should make `stitch` available
+3. **CLI Test**: `stitch build test/fixtures/simple/stitch.yaml` should work
+4. **API Test**: `import { stitch } from 'stitch'` should work
+5. **Uninstall Test**: `npm uninstall -g stitch` should clean up
+
+### Success Criteria for Phase 1.5
+
+1. ✅ `npm run build` generates distribution files
+2. ✅ `npm install -g .` installs CLI globally  
+3. ✅ `stitch build [file]` works from any directory
+4. ✅ Programmatic API works: `require('stitch')` or `import { stitch }`
+5. ✅ Package is ready for npm publish
+6. ✅ All original functionality preserved
+7. ✅ Binary has proper permissions and works cross-platform
+8. ✅ Clean uninstall with `npm uninstall -g stitch`
+
+## Phase 2: Client-Side / Vite Integration
+
+**Goal**: Enable Stitch to work in browser environments with Vite's `?raw` import system.
+
+### Background
+
+Currently Stitch reads YAML files from the filesystem using Node.js `fs` module. This works great for:
+- CLI usage (server-side)
+- Node.js programmatic API
+
+However, for client-side usage (like in forge framework), we need to support Vite's import system where YAML content is imported at build time using the `?raw` suffix.
+
+**Current forge pattern:**
+```typescript
+// Dynamic YAML import with Vite's raw import
+let open_api_config = (await import(/* @vite-ignore */ config+'?raw')).default;
+open_api_config = yaml.load(open_api_config);
+routes = transform_openapi_config(open_api_config);
+```
+
+### Proposed Enhancement
+
+#### New API: Content-Based Merging
+
+Add support for merging YAML content directly (not just file paths):
+
+```typescript
+// New interface for content-based merging
+export interface StitchContentConfig {
+  stitch: Array<string | { content: string; name?: string }>;
+}
+
+// New methods on YamlMerger
+export class YamlMerger {
+  // Existing file-based method
+  mergeFiles(filePaths: string[]): any
+  
+  // New content-based method
+  mergeContent(contents: Array<{ content: string; name?: string }>): any
+  
+  // Mixed method (files + content)
+  merge(items: Array<string | { content: string; name?: string }>): any
+}
+```
+
+#### Usage Examples
+
+**Pure content merging (client-side):**
+```typescript
+import baseYaml from './openapi/base.yaml?raw';
+import pathsYaml from './openapi/paths.yaml?raw';
+import { YamlMerger } from 'stitch';
+
+const merger = new YamlMerger();
+const result = merger.mergeContent([
+  { content: baseYaml, name: 'base.yaml' },
+  { content: pathsYaml, name: 'paths.yaml' }
+]);
+```
+
+**Mixed file and content merging:**
+```typescript
+const merger = new YamlMerger();
+const result = merger.merge([
+  'base.yaml',  // File path (Node.js)
+  { content: importedYaml, name: 'imported.yaml' }  // Raw content
+]);
+```
+
+**Vite integration helper:**
+```typescript
+// Helper function for Vite environments
+export async function stitchFromViteImports(imports: Record<string, () => Promise<{ default: string }>>) {
+  const contents = await Promise.all(
+    Object.entries(imports).map(async ([path, importFn]) => ({
+      content: (await importFn()).default,
+      name: path
+    }))
+  );
+  
+  const merger = new YamlMerger();
+  return merger.mergeContent(contents);
+}
+
+// Usage:
+const imports = import.meta.glob('./openapi/*.yaml', { as: 'raw' });
+const merged = await stitchFromViteImports(imports);
+```
+
+#### Implementation Plan
+
+1. **Extend YamlMerger class**
+   - Add `mergeContent()` method for content-based merging
+   - Add `merge()` method for mixed file/content merging
+   - Maintain existing `mergeFiles()` for backward compatibility
+
+2. **Update StitchEngine**
+   - Add content-based build methods
+   - Support mixed configurations
+   - Maintain file-based CLI functionality
+
+3. **Add Vite helpers**
+   - Helper functions for common Vite patterns
+   - Integration utilities for `import.meta.glob()`
+   - Documentation and examples
+
+4. **Browser compatibility**
+   - Ensure YamlMerger works in browser environments
+   - Remove Node.js-specific dependencies from core merge logic
+   - Provide separate builds for Node.js vs browser
+
+#### File Structure Changes
+
+```
+src/
+├── core/
+│   ├── StitchEngine.ts       # Node.js + content support
+│   ├── YamlMerger.ts         # Universal (Node.js + browser)
+│   └── ViteHelper.ts         # NEW: Vite-specific utilities
+├── browser/
+│   └── index.ts              # NEW: Browser-specific exports
+└── node/
+    └── index.ts              # NEW: Node.js-specific exports
+```
+
+#### Package.json Exports
+
+```json
+{
+  "exports": {
+    ".": {
+      "browser": "./dist/browser/index.js",
+      "node": "./dist/node/index.js",
+      "default": "./dist/index.js"
+    },
+    "./vite": "./dist/core/ViteHelper.js"
+  }
+}
+```
+
+### Benefits
+
+1. **Universal Usage**: Same merging logic works in Node.js and browser
+2. **Vite Integration**: Native support for Vite's import system
+3. **Performance**: No runtime file system access in browser builds
+4. **Flexibility**: Mix file-based and content-based merging
+5. **Backward Compatibility**: Existing CLI and Node.js API unchanged
+
+### Success Criteria for Phase 2
+
+1. ✅ `YamlMerger.mergeContent()` works with raw YAML strings
+2. ✅ Vite helper functions simplify `import.meta.glob()` usage
+3. ✅ Browser build works without Node.js dependencies
+4. ✅ Mixed file + content merging works in Node.js
+5. ✅ Existing CLI and Node.js functionality preserved
+6. ✅ forge framework can use Stitch instead of custom merge logic
+7. ✅ Documentation covers both server and client usage patterns
+
+## Phase 2: Complete ✅
+
+**Goal**: Enable Stitch to work in browser environments with Vite's `?raw` import system.
+
+### Implemented Features
+
+#### Content-Based Merging API
+- `YamlMerger.mergeContent()` - Merge raw YAML content strings
+- `YamlMerger.merge()` - Mixed file paths and content merging
+- `StitchEngine.buildFromContent()` - Build from content without filesystem
+
+#### Vite Integration Helpers
+- `stitchFromViteImports()` - Work with `import.meta.glob()`
+- `stitchFromOrderedViteImports()` - Specific merge order
+- `stitchFromSortedViteImports()` - Alphabetical ordering
+- `stitchFromContent()` - Direct content merging
+- `stitchFromRawContent()` - Simple string array merging
+
+#### Browser/Server Separation
+- Browser entry point: `src/browser/index.ts` (no Node.js deps)
+- Server entry point: `src/index.ts` (full functionality)
+- Separate builds via Vite configuration
+- Package.json exports for environment-specific imports
+
+#### Usage Examples
+
+**Client-side with Vite:**
+```typescript
+import { stitchFromViteImports } from 'stitch/browser';
+
+const imports = import.meta.glob('./openapi/*.yaml', { as: 'raw' });
+const merged = await stitchFromViteImports(imports);
+```
+
+**Direct content merging:**
+```typescript
+import { stitchFromContent } from 'stitch/browser';
+
+const contents = [
+  { content: baseYaml, name: 'base.yaml' },
+  { content: pathsYaml, name: 'paths.yaml' }
+];
+const result = stitchFromContent(contents);
+```
+
+**Mixed file + content (Node.js):**
+```typescript
+import { YamlMerger } from 'stitch';
+
+const merger = new YamlMerger();
+const result = merger.merge([
+  'base.yaml',  // File path
+  { content: importedYaml, name: 'imported.yaml' }  // Raw content
+]);
+```
+
+#### Implementation Order
+
+1. **Dependencies** - Add js-yaml, chokidar, ajv, glob packages
+2. **Types** - Define TypeScript interfaces (simplified)
+3. **ConfigParser** - Parse simple stitch.yaml format
+4. **YamlMerger** - Deep merge implementation  
+5. **Validator** - OpenAPI validation (optional)
+6. **StitchEngine** - Simple orchestration: parse config → load files → merge → output
+7. **CLI** - Wire up build/watch commands to engine
+8. **API** - Export programmatic interface
+9. **Tests** - Validate with simple merge examples
+
+**Core logic is much simpler now:**
+- Parse `stitch.yaml` → get array of files/globs
+- Expand globs to actual file paths (sorted alphabetically)
+- Load each YAML file in order
+- Deep merge them sequentially 
+- Output result as YAML or JSON
+
+**Glob Examples:**
+- `*.yaml` - All YAML files in current directory
+- `**/*.yaml` - All YAML files recursively
+- `paths/*.yaml` - All YAML files in paths directory
+- `components/**/*.yaml` - All YAML files in components and subdirectories
+
+### Migration Plan
+
+#### Step 1: Extract Backend API
+1. Create backend stitch configuration
+2. Split `backend/openapi.yaml` into modules:
+   - Extract user endpoints to `paths/users.yaml`
+   - Extract business endpoints to `paths/businesses.yaml`
+   - Extract schemas to component files
+3. Update build process to generate `openapi.yaml`
+4. Verify dinner framework still works correctly
+
+#### Step 2: Extract Frontend Routes
+1. Create frontend stitch configuration
+2. Split `frontend/openapi.yaml` into route modules
+3. Update build process to generate `openapi.yaml`
+4. Verify forge framework still works correctly
+
+#### Step 3: Team Workflow
+1. Establish conventions for module organization
+2. Create documentation for adding new routes/endpoints
+3. Setup CI validation to ensure merged output is valid
+
+### Benefits
+
+1. **Maintainability**: Smaller, focused files are easier to understand and modify
+2. **Collaboration**: Reduces merge conflicts when multiple developers work on different features
+3. **Organization**: Logical grouping of related functionality
+4. **Reusability**: Common components can be shared across modules
+5. **Validation**: Individual modules can be validated independently
+6. **Scalability**: New features can be added as new modules without touching existing files
+
+### Technical Requirements
+
+1. **YAML Processing**: Robust YAML parsing and merging capabilities
+2. **OpenAPI Validation**: Ensure merged output conforms to OpenAPI 3.0.3 spec
+3. **File Watching**: Efficient file system monitoring for development
+4. **Path Resolution**: Proper handling of relative paths and includes
+5. **Error Handling**: Clear error messages for validation and merge conflicts
+6. **Performance**: Fast builds for development workflow
+
+### Success Criteria
+
+1. Backend and frontend OpenAPI files successfully split into manageable modules
+2. Generated combined files are identical to original monolithic files
+3. Both dinner (backend) and forge (frontend) frameworks work without modification
+4. Development workflow remains smooth with watch mode
+5. Build times are acceptable (< 1 second for typical changes)
+6. Clear error messages help developers fix issues quickly
+
+## Phase 3: VSCode Schema Integration ✅
+
+**Goal**: Enable automatic schema validation in VSCode for YAML files.
+
+### Implemented Features
+
+#### Install Command
+- `stitch install <schema-file> --target <patterns>` - Install JSON schema for VSCode
+- Automatically creates/updates `.vscode/settings.json` 
+- Supports comma-separated file patterns and globs
+- Preserves existing VSCode settings
+
+#### CLI Usage
+```bash
+# Install schema for all YAML files
+stitch install schemas/schema.json --target "*.yaml"
+
+# Install schema for specific patterns
+stitch install openapi-schema.json --target "stitch.yaml,openapi/*.yaml"
+
+# Custom VSCode settings path
+stitch install schemas/schema.json --target "*.yaml" --vscode custom/.vscode/settings.json
+```
+
+#### Generated VSCode Configuration
+```json
+{
+  "yaml.schemas": {
+    "test/fixtures/simple/schema.json": [
+      "*.yaml",
+      "openapi/*.yaml"
+    ]
+  }
+}
+```
+
+#### Programmatic API
+```typescript
+import { StitchEngine } from 'stitch';
+
+const engine = new StitchEngine();
+const result = engine.install({
+  schemaPath: 'schemas/schema.json',
+  targets: ['*.yaml', 'openapi/*.yaml'],
+  vscodeSettingsPath: '.vscode/settings.json'  // optional
+});
+```
+
+#### Benefits
+- **IDE Integration**: Real-time YAML validation in VSCode
+- **Development Experience**: Catch schema errors as you type
+- **Team Consistency**: Share schema validation across team members
+- **Automated Setup**: No manual VSCode configuration required
+
+This modularization will significantly improve the maintainability and scalability of the Groom application's API and route definitions while preserving the existing framework integrations. Stitch is now a complete YAML modularization tool that works seamlessly across CLI, Node.js server environments, browser/Vite environments, and provides IDE integration for enhanced development experience.