@kya-os/create-mcpi-app 1.7.37 → 1.7.38-canary.1

package/ARCHITECTURE_ANALYSIS.md

@@ -0,0 +1,392 @@
+# Deep Architecture Analysis: create-mcpi-app
+
+## Executive Summary
+
+After thorough analysis of `create-mcpi-app`, I've identified **significant architectural inefficiencies** that can be improved. The package currently has:
+- **7 unused dependencies** (~15MB+ of unnecessary code)
+- **Heavy runtime dependencies** used only for TypeScript types
+- **Redundant HTTP/crypto libraries** when native APIs are available
+- **Architectural patterns** that don't align with modern CLI tooling best practices
+
+## Current Dependency Analysis
+
+### ✅ Actually Used Dependencies
+
+| Dependency | Purpose | Can Optimize? |
+|------------|---------|---------------|
+| `fs-extra` | File operations | ✅ Use native `fs/promises` |
+| `chalk` | Terminal colors | ❌ Keep (essential) |
+| `commander` | CLI parsing | ❌ Keep (essential) |
+| `inquirer` | Interactive prompts | ❌ Keep (essential) |
+| `ora` | Loading spinners | ❌ Keep (essential) |
+| `base-x` | Base58 encoding | ❌ Keep (used in generate-identity) |
+| `zod` | Schema validation | ❌ Keep (used in config-builder) |
+| `@kya-os/contracts` | Type definitions | ⚠️ Only types needed |
+| `@kya-os/cli-effects` | UI effects | ❌ Keep (used) |
+| `@kya-os/mcp-i-core` | Types + `fetchRemoteConfig` | ⚠️ Only types + 1 function |
+| `@kya-os/mcp-i` | **ONLY FOR TYPES** | ❌❌❌ **MAJOR ISSUE** |
+
+### ❌ Unused Dependencies (Can Remove)
+
+1. **`axios`** (~500KB) - Not imported anywhere
+2. **`node-fetch`** (~200KB) - Node 20+ has native `fetch`
+3. **`jose`** (~300KB) - Not used (used in `@kya-os/cli` but not here)
+4. **`dotenv-cli`** (~100KB) - Not used
+5. **`swc-loader`** (~2MB) - Only in generated templates, not scaffolder
+6. **`tsx`** (~5MB) - Only in generated templates, not scaffolder
+7. **`@noble/ed25519`** (~100KB) - Not used (using `webcrypto` instead)
+
+**Total wasted: ~8MB+ of dependencies**
+
+### ⚠️ Problematic Dependencies
+
+#### 1. `@kya-os/mcp-i` - **CRITICAL ISSUE**
+
+**Current Usage:**
+- Only used for TypeScript types: `NodeRuntimeConfig`, `XmcpConfig`
+- Imported in `generate-config.ts` for type references in generated code
+
+**Problem:**
+- This package is **MASSIVE** (~50MB+ with dependencies):
+  - Includes `webpack`, `express`, `@swc/core`, `chokidar`, `webpack-node-externals`
+  - Includes `axios`, `jose`, `jsonwebtoken`, `handlebars`
+  - Includes entire MCP SDK and runtime
+  - **All of this is bundled just for TypeScript types!**
+
+**Impact:**
+- Slows down `npm install` for users
+- Increases bundle size unnecessarily
+- Violates separation of concerns (scaffolder shouldn't need runtime)
+
+#### 2. `@kya-os/mcp-i-core` - Moderate Issue
+
+**Current Usage:**
+- Types: `RemoteConfigCache`, `RemoteConfigOptions`
+- Function: `fetchRemoteConfig` (used in `config-builder.ts`)
+
+**Problem:**
+- Includes `@modelcontextprotocol/sdk` as dependency
+- Only needs types + 1 function, but pulls in entire SDK
+
+## Architecture Comparison
+
+### Modern CLI Scaffolders (Best Practices)
+
+#### create-next-app (Next.js)
+```json
+{
+  "dependencies": {
+    "commander": "^9.0.0",
+    "fs-extra": "^11.0.0",
+    "chalk": "^5.0.0"
+  }
+}
+```
+- **No runtime dependencies** - only scaffolding tools
+- Types are in separate `@types` packages or peer dependencies
+- Uses native Node.js APIs
+
+#### create-vite (Vite)
+```json
+{
+  "dependencies": {
+    "commander": "^9.0.0",
+    "fs-extra": "^11.0.0",
+    "chalk": "^5.0.0",
+    "minimist": "^1.2.0"
+  }
+}
+```
+- **Minimal dependencies** - only what's needed for scaffolding
+- No runtime framework dependencies
+
+#### create-react-app (Legacy - What NOT to do)
+```json
+{
+  "dependencies": {
+    // ... 50+ dependencies including webpack, babel, etc.
+  }
+}
+```
+- **Heavy dependencies** - includes entire build toolchain
+- This is why CRA is deprecated in favor of lighter alternatives
+
+### Our Current Architecture (create-mcpi-app)
+
+```json
+{
+  "dependencies": {
+    "@kya-os/mcp-i": "^1.5.5",  // ❌ 50MB+ runtime framework
+    "@kya-os/mcp-i-core": "^1.1.12",  // ⚠️ Includes SDK
+    "@kya-os/cli": "^1.3.3",  // ⚠️ Not used directly
+    "axios": "^1.12.0",  // ❌ Unused
+    "node-fetch": "^3.3.2",  // ❌ Unused (native fetch available)
+    "jose": "^6.0.12",  // ❌ Unused
+    // ... 7 more unused deps
+  }
+}
+```
+
+**We're following the CRA anti-pattern!**
+
+## Recommended Architecture Improvements
+
+### Option 1: Minimal Dependencies (Recommended)
+
+**Remove all unused dependencies and use type-only imports:**
+
+```json
+{
+  "dependencies": {
+    "chalk": "^5.3.0",
+    "commander": "^11.1.0",
+    "fs-extra": "^11.2.0",
+    "inquirer": "^12.9.4",
+    "ora": "^8.0.1",
+    "base-x": "^5.0.0",
+    "zod": "^3.25.76",
+    "@kya-os/cli-effects": "^1.0.19"
+  },
+  "devDependencies": {
+    "@kya-os/contracts": "^1.5.1",  // Types only
+    "@kya-os/mcp-i-core": "^1.1.12",  // Types only
+    "@types/node": "^20.19.19",
+    "typescript": "^5.3.0",
+    "vitest": "^4.0.5"
+  },
+  "peerDependencies": {
+    "@kya-os/mcp-i": ">=1.5.0"  // For types, but not bundled
+  }
+}
+```
+
+**Changes:**
+1. Move `@kya-os/contracts` and `@kya-os/mcp-i-core` to `devDependencies` (types only)
+2. Add `@kya-os/mcp-i` as `peerDependency` (types available but not bundled)
+3. Remove all unused dependencies
+4. Use native `fetch` instead of `axios`/`node-fetch`
+5. Use native `fs/promises` instead of `fs-extra` (or keep fs-extra if convenience is worth it)
+
+**Benefits:**
+- **~60MB reduction** in install size
+- Faster `npm install` times
+- Clearer separation of concerns
+- Aligns with modern CLI tooling patterns
+
+### Option 2: Extract Types Package (Best Long-term)
+
+Create a separate `@kya-os/mcp-i-types` package:
+
+```json
+{
+  "name": "@kya-os/mcp-i-types",
+  "version": "1.0.0",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts"
+    }
+  }
+}
+```
+
+**Benefits:**
+- Zero runtime dependencies
+- Can be used by any package needing types
+- Follows TypeScript best practices
+- Matches patterns used by major frameworks
+
+### Option 3: Use Type-Only Imports (Quick Fix)
+
+Keep current structure but use TypeScript's `import type`:
+
+```typescript
+// Instead of:
+import { NodeRuntimeConfig } from "@kya-os/mcp-i";
+
+// Use:
+import type { NodeRuntimeConfig } from "@kya-os/mcp-i";
+```
+
+Then move to `devDependencies`:
+```json
+{
+  "devDependencies": {
+    "@kya-os/mcp-i": "^1.5.5"  // Types only, not bundled
+  }
+}
+```
+
+**Note:** This still requires the package to be installed, but TypeScript will tree-shake it.
+
+## Specific Code Improvements
+
+### 1. Replace `fs-extra` with Native APIs
+
+```typescript
+// Current:
+import fs from "fs-extra";
+fs.ensureDirSync(path);
+fs.writeJsonSync(path, data);
+
+// Better:
+import { mkdir, writeFile } from "fs/promises";
+import { existsSync } from "fs";
+
+await mkdir(path, { recursive: true });
+await writeFile(path, JSON.stringify(data, null, 2));
+```
+
+**Trade-off:** More verbose, but removes dependency
+
+### 2. Use Native `fetch` Instead of `axios`/`node-fetch`
+
+```typescript
+// Current (if we were using axios):
+const response = await axios.get(url);
+
+// Better (native fetch):
+const response = await fetch(url);
+const data = await response.json();
+```
+
+**Note:** Node 20+ has native `fetch` - no dependency needed!
+
+### 3. Extract `fetchRemoteConfig` Function
+
+Instead of importing from `@kya-os/mcp-i-core`, extract the function:
+
+```typescript
+// In create-mcpi-app/src/utils/fetch-remote-config.ts
+export async function fetchRemoteConfig(
+  options: RemoteConfigOptions,
+  cache?: RemoteConfigCache
+): Promise<MCPIConfig | null> {
+  // Copy implementation from mcp-i-core
+  // This removes the dependency on the entire package
+}
+```
+
+**Trade-off:** Code duplication, but removes heavy dependency
+
+### 4. Use `import type` for All Type Imports
+
+```typescript
+// Current:
+import { ScaffolderResult } from "@kya-os/contracts";
+import type { NodeRuntimeConfig } from "@kya-os/mcp-i";
+
+// Better (all type-only):
+import type { ScaffolderResult } from "@kya-os/contracts";
+import type { NodeRuntimeConfig } from "@kya-os/mcp-i";
+```
+
+## Dependency Size Analysis
+
+### Current Install Size (Estimated)
+
+```
+@kya-os/mcp-i:        ~50MB (with dependencies)
+@kya-os/mcp-i-core:   ~5MB (with SDK)
+@kya-os/cli:          ~10MB
+axios:                ~500KB
+node-fetch:           ~200KB
+jose:                 ~300KB
+swc-loader:           ~2MB
+tsx:                  ~5MB
+@noble/ed25519:       ~100KB
+dotenv-cli:           ~100KB
+--------------------------------
+Total wasted:         ~73MB+
+```
+
+### Optimized Install Size
+
+```
+chalk:                ~50KB
+commander:            ~200KB
+fs-extra:             ~100KB
+inquirer:             ~500KB
+ora:                  ~100KB
+base-x:               ~50KB
+zod:                  ~500KB
+@kya-os/cli-effects:  ~200KB
+--------------------------------
+Total:                ~1.7MB
+```
+
+**Reduction: ~97% smaller!**
+
+## Migration Plan
+
+### Phase 1: Remove Unused Dependencies (Low Risk)
+
+1. Remove `axios`, `node-fetch`, `jose`, `dotenv-cli`, `swc-loader`, `tsx`, `@noble/ed25519`
+2. Test that scaffolder still works
+3. Verify generated templates still work
+
+**Time:** 1-2 hours  
+**Risk:** Low  
+**Impact:** Immediate size reduction
+
+### Phase 2: Move Type Dependencies to devDependencies (Medium Risk)
+
+1. Move `@kya-os/contracts` to `devDependencies`
+2. Move `@kya-os/mcp-i-core` to `devDependencies`
+3. Add `@kya-os/mcp-i` as `peerDependency`
+4. Update all imports to use `import type`
+5. Test thoroughly
+
+**Time:** 2-4 hours  
+**Risk:** Medium  
+**Impact:** Major size reduction
+
+### Phase 3: Extract fetchRemoteConfig (Optional)
+
+1. Copy `fetchRemoteConfig` implementation
+2. Remove `@kya-os/mcp-i-core` dependency
+3. Test config-builder functionality
+
+**Time:** 1-2 hours  
+**Risk:** Low  
+**Impact:** Further size reduction
+
+### Phase 4: Replace fs-extra (Optional)
+
+1. Replace `fs-extra` calls with native `fs/promises`
+2. Add helper functions for common operations
+3. Test file operations
+
+**Time:** 2-3 hours  
+**Risk:** Low  
+**Impact:** Small size reduction
+
+## Recommendations Summary
+
+### ✅ Immediate Actions (High Impact, Low Risk)
+
+1. **Remove 7 unused dependencies** → ~8MB reduction
+2. **Move type-only packages to devDependencies** → ~55MB reduction
+3. **Add `@kya-os/mcp-i` as peerDependency** → Users install only if needed
+
+### ⚠️ Consider (Medium Impact, Medium Risk)
+
+4. **Extract `fetchRemoteConfig` function** → Remove `@kya-os/mcp-i-core` dependency
+5. **Use native `fs/promises`** → Remove `fs-extra` dependency
+
+### 🎯 Long-term (High Impact, High Effort)
+
+6. **Create `@kya-os/mcp-i-types` package** → Zero runtime dependencies for types
+7. **Follow create-next-app pattern** → Industry-standard architecture
+
+## Conclusion
+
+The current architecture follows anti-patterns from legacy tools like `create-react-app`. By adopting modern CLI tooling patterns (like `create-next-app` or `create-vite`), we can:
+
+- **Reduce install size by ~97%** (from ~73MB to ~1.7MB)
+- **Improve install speed** significantly
+- **Align with industry best practices**
+- **Improve maintainability** with clearer dependencies
+
+The recommended approach is **Option 1** (Minimal Dependencies) as it provides the best balance of impact vs. effort.
+

package/DEPRECATION_WARNINGS_ANALYSIS.md

@@ -0,0 +1,192 @@
+# Deprecation Warnings Analysis
+
+## Summary
+
+The deprecation warnings seen when running `npx @kya-os/create-mcpi-app` are **transitive dependencies** from upstream packages. They cannot be directly fixed in `create-mcpi-app` without fixing the root packages.
+
+## Warning Sources
+
+### 1. `inflight@1.0.6` (deprecated - leaks memory)
+
+**Source Chain:**
+
+```
+@kya-os/mcp-i
+  └─ clean-webpack-plugin@4.0.0
+      └─ del@4.1.1
+          └─ rimraf@2.7.1
+              └─ glob@7.2.3
+                  └─ inflight@1.0.6 ❌
+
+@kya-os/mcp-i
+  └─ del@7.1.0
+      └─ rimraf@3.0.2
+          └─ glob@7.2.3
+              └─ inflight@1.0.6 ❌
+```
+
+**Fix Required In:** `@kya-os/mcp-i` package
+
+- Update `clean-webpack-plugin` to latest version (may have fixed this)
+- Update `del` to latest version (may have fixed this)
+- Or replace `clean-webpack-plugin` with native Node.js alternatives
+
+### 2. `phin@2.9.3` and `phin@3.7.1` (deprecated - no longer supported)
+
+**Source Chain:**
+
+```
+@kya-os/cli
+  └─ terminal-image@3.1.1
+      └─ render-gif@2.0.4
+          └─ jimp@0.14.0
+              └─ @jimp/core@0.14.0
+                  └─ load-bmfont@1.4.2
+                      └─ phin@3.7.1 ❌
+```
+
+**Fix Required In:** `@kya-os/cli` package
+
+- Update `terminal-image` to latest version
+- Or replace `terminal-image` with alternative that doesn't use deprecated `jimp`
+- Or update `jimp` to latest version (if available)
+
+### 3. `rimraf@2.7.1` and `rimraf@3.0.2` (deprecated - use v4+)
+
+**Source Chain:**
+
+```
+@kya-os/mcp-i
+  └─ clean-webpack-plugin@4.0.0
+      └─ del@4.1.1
+          └─ rimraf@2.7.1 ❌
+
+@kya-os/mcp-i
+  └─ del@7.1.0
+      └─ rimraf@3.0.2 ❌
+```
+
+**Fix Required In:** `@kya-os/mcp-i` package
+
+- Update `clean-webpack-plugin` to latest (may use rimraf@4+)
+- Update `del` to latest version (may use rimraf@4+)
+- Or add `rimraf@^5.0.0` as direct dependency to force resolution
+
+### 4. `glob@7.2.3` (deprecated - use v9+)
+
+**Source Chain:**
+
+```
+@kya-os/mcp-i
+  └─ clean-webpack-plugin@4.0.0
+      └─ del@4.1.1
+          └─ rimraf@2.7.1
+              └─ glob@7.2.3 ❌
+
+@kya-os/mcp-i
+  └─ del@7.1.0
+      └─ rimraf@3.0.2
+          └─ glob@7.2.3 ❌
+```
+
+**Fix Required In:** `@kya-os/mcp-i` package
+
+- Same as rimraf - update `clean-webpack-plugin` and `del` to latest versions
+
+### 5. `node-domexception@1.0.0` (deprecated - use native DOMException)
+
+**Source Chain:**
+
+```
+@modelcontextprotocol/inspector (optional dependency)
+  └─ node-fetch@3.3.2
+      └─ fetch-blob@3.2.0
+          └─ node-domexception@1.0.0 ❌
+```
+
+**Fix Required In:** `@modelcontextprotocol/inspector` package
+
+- This is an external package we don't control
+- Node.js 20+ has native DOMException, so this could be updated upstream
+
+## Solutions
+
+### Option 1: Fix in Upstream Packages (Recommended)
+
+**For `@kya-os/mcp-i`:**
+
+1. Update `clean-webpack-plugin` to latest version
+2. Update `del` to latest version
+3. Consider replacing `clean-webpack-plugin` with native `fs.rmSync` (Node.js 14.14+)
+
+**For `@kya-os/cli`:**
+
+1. Update `terminal-image` to latest version
+2. Consider replacing with alternative image display library
+3. Or make `terminal-image` optional/feature-flag
+
+**For `@modelcontextprotocol/inspector`:**
+
+- This is external - file issue with upstream maintainers
+- Or consider making it truly optional (not installed unless needed)
+
+### Option 2: Use npm/pnpm Overrides (Quick Fix)
+
+Add to `package.json`:
+
+```json
+{
+  "pnpm": {
+    "overrides": {
+      "rimraf": "^5.0.0",
+      "glob": "^11.0.0"
+    }
+  }
+}
+```
+
+**Note:** This forces newer versions but may cause compatibility issues if upstream packages aren't compatible.
+
+### Option 3: Accept Warnings (Current State)
+
+These are **warnings, not errors**. The package works fine. The warnings are:
+
+- Informational only
+- Don't affect functionality
+- Will be resolved when upstream packages update
+
+## Impact Assessment
+
+**Risk Level:** ⚠️ **LOW**
+
+- Warnings don't affect functionality
+- All deprecated packages still work
+- No security vulnerabilities (just deprecation notices)
+
+**User Experience Impact:** ⚠️ **MINIMAL**
+
+- Users see warnings but package works
+- Warnings are common in npm ecosystem
+- Most users ignore deprecation warnings
+
+## Recommendation
+
+**Short-term:** Accept the warnings - they don't affect functionality.
+
+**Medium-term:** Fix in upstream packages (`@kya-os/mcp-i` and `@kya-os/cli`):
+
+1. Update `clean-webpack-plugin` and `del` in `@kya-os/mcp-i`
+2. Update `terminal-image` in `@kya-os/cli` or make it optional
+3. File issue with `@modelcontextprotocol/inspector` maintainers
+
+**Long-term:** Consider replacing deprecated dependencies:
+
+- Replace `clean-webpack-plugin` with native `fs.rmSync`
+- Replace `terminal-image` with modern alternative
+- Make `@modelcontextprotocol/inspector` truly optional
+
+## Quick Wins
+
+1. **Update `del` in `@kya-os/mcp-i`** - Latest version may use newer `rimraf`
+2. **Update `clean-webpack-plugin`** - Latest version may have fixed dependencies
+3. **Make `terminal-image` optional** - Only install if needed for avatar display