@ema.co/mcp-toolkit 2026.1.25 → 2026.1.26-4

package/docs/CODEBASE-ANALYSIS-2026-01-23.md

@@ -1,936 +0,0 @@
-# Comprehensive Codebase Analysis Report
-
-**Date**: January 23, 2026  
-**Scope**: Full ema-mcp-toolkit codebase  
-**Analysts**: Architecture, Security, API, SDK, MCP, Test, Performance, Quality experts
-
----
-
-## Executive Summary
-
-| Dimension     | Health Score | Status                                        |
-| ------------- | ------------ | --------------------------------------------- |
-| Architecture  | 7/10         | 🟡 Good structure, circular dependency issue  |
-| Security      | 6/10         | 🟡 Foundation solid, input validation gaps    |
-| API Contracts | 7/10         | 🟡 Good generation, type assertion overuse    |
-| SDK Layer     | 6/10         | 🟡 Architectural debt, error handling gaps    |
-| MCP Layer     | 7/10         | 🟡 Well-structured, missing graceful shutdown |
-| Test Coverage | 5/10         | 🟠 Handler coverage good, SDK gaps            |
-| Performance   | 5/10         | 🟠 N+1 patterns, sync file I/O                |
-| Code Quality  | 6.5/10       | 🟡 Type safety gaps, code duplication         |
-
-**Overall Health**: 6.2/10 🟡
-
-**Critical Issues**: 8  
-**High Priority**: 23  
-**Medium Priority**: 34  
-**Low Priority**: 18
-
----
-
-## Table of Contents
-
-1. [Critical Issues (Fix Immediately)](#1-critical-issues-fix-immediately)
-2. [High Priority Issues](#2-high-priority-issues)
-3. [Medium Priority Issues](#3-medium-priority-issues)
-4. [Architecture Analysis](#4-architecture-analysis)
-5. [Security Analysis](#5-security-analysis)
-6. [API Contracts Analysis](#6-api-contracts-analysis)
-7. [SDK Layer Analysis](#7-sdk-layer-analysis)
-8. [MCP Layer Analysis](#8-mcp-layer-analysis)
-9. [Test Coverage Analysis](#9-test-coverage-analysis)
-10. [Performance Analysis](#10-performance-analysis)
-11. [Code Quality Analysis](#11-code-quality-analysis)
-12. [Recommended Action Plan](#12-recommended-action-plan)
-
----
-
-## 1. Critical Issues (Fix Immediately)
-
-### CRIT-001: Circular Dependency - sync.ts ↔ sdk/sync.ts
-
-**Location**: `src/sync.ts` ↔ `src/sdk/sync.ts`  
-**Impact**: Module initialization failures, undefined exports, runtime errors  
-**Category**: Architecture
-
-```typescript
-// src/sync.ts imports SDK
-import type { AppConfig } from "./sdk/config.js";
-import { EmaClient } from "./sdk/client.js";
-
-// src/sdk/sync.ts imports root sync
-import { fingerprintPersona, syncOnce } from "../sync.js";
-```
-
-**Fix**:
-
-1. Move `fingerprintPersona`, `syncOnce`, `transformWorkflowForTarget` into `src/sdk/sync-engine.ts`
-2. Have `src/sdk/sync.ts` re-export from sync-engine
-3. Remove `src/sync.ts` or make it a thin wrapper
-
----
-
-### CRIT-002: Synchronous File I/O Blocking Event Loop
-
-**Location**: `src/sdk/version-storage.ts` (entire file)  
-**Impact**: Blocks Node.js event loop, poor concurrency, request timeouts  
-**Category**: Performance
-
-Found 15+ synchronous calls:
-
-- `fs.readFileSync()` (lines 118, 188, 232, 305, 352, 396)
-- `fs.writeFileSync()` (lines 163, 198, 221, 263, 267, 438)
-- `fs.existsSync()` (lines 95, 107, 116, 183, 220, 227, 300, 347, 394)
-
-**Fix**: Migrate all file operations to `fs/promises`:
-
-```typescript
-// Before
-const content = fs.readFileSync(path, "utf8");
-
-// After
-const content = await fs.readFile(path, "utf8");
-```
-
----
-
-### CRIT-003: N+1 Query Pattern in Sync Loop
-
-**Location**: `src/sync.ts:259-273`  
-**Impact**: For 100 personas, 100 sequential API calls (~10-30 seconds)  
-**Category**: Performance
-
-```typescript
-for (let p of personas) {
-  if (!p.workflow_def) {
-    const fullPersona = await masterClient.getPersonaById(p.id); // Sequential!
-  }
-}
-```
-
-**Fix**: Batch fetch in parallel:
-
-```typescript
-const missingIds = personas.filter((p) => !p.workflow_def).map((p) => p.id);
-const fullPersonas = await Promise.all(
-  missingIds.map((id) => masterClient.getPersonaById(id)),
-);
-```
-
----
-
-### CRIT-004: Path Traversal Vulnerability in File Upload
-
-**Location**: `src/mcp/server.ts:3930-3937`  
-**Impact**: Potential unauthorized file system access  
-**Category**: Security
-
-```typescript
-// File path from user input used directly without normalization
-const filename = path.basename(filePath); // basename used but path not validated first
-```
-
-**Fix**:
-
-```typescript
-function validateFilePath(userPath: string, baseDir: string): string {
-  const normalized = path.normalize(path.resolve(baseDir, userPath));
-  if (!normalized.startsWith(path.resolve(baseDir))) {
-    throw new Error("Path traversal detected");
-  }
-  return normalized;
-}
-```
-
----
-
-### CRIT-005: Missing Graceful Shutdown Handler
-
-**Location**: `src/mcp/server.ts:5762`  
-**Impact**: Resource leaks, incomplete operations, data corruption  
-**Category**: MCP Layer
-
-No SIGTERM/SIGINT handlers found for:
-
-- Client connection cleanup
-- Cache persistence
-- In-flight request completion
-
-**Fix**:
-
-```typescript
-process.on("SIGTERM", async () => {
-  console.log("Shutting down gracefully...");
-  await server.close();
-  clientCache.clear();
-  process.exit(0);
-});
-
-process.on("SIGINT", async () => {
-  console.log("Received SIGINT, shutting down...");
-  await server.close();
-  process.exit(0);
-});
-```
-
----
-
-### CRIT-006: Workflow Namespace Validation Missing
-
-**Location**: `src/sdk/workflow-transformer.ts:552`  
-**Impact**: Silent deployment failures  
-**Category**: SDK Layer
-
-```typescript
-// Preserves namespace but doesn't validate structure
-compiled.workflow_def.workflowName = originalDef.workflowName;
-// If originalDef.workflowName is malformed, deployment fails silently
-```
-
-**Fix**: Add namespace structure validation:
-
-```typescript
-function validateWorkflowNamespace(namespace: unknown): boolean {
-  if (!namespace || typeof namespace !== "object") return false;
-  const ns = namespace as { namespaces?: unknown[]; name?: string };
-  return Array.isArray(ns.namespaces) && typeof ns.name === "string";
-}
-```
-
----
-
-### CRIT-007: Insufficient Input Validation in Handlers
-
-**Location**: `src/mcp/handlers-consolidated.ts:1762-2254`  
-**Impact**: Injection risks, API errors, data corruption  
-**Category**: Security
-
-User inputs passed to APIs without strict validation. No schema validation before API calls.
-
-**Fix**: Add Zod validation at handler entry:
-
-```typescript
-const PersonaUpdateSchema = z.object({
-  id: z.string().uuid(),
-  name: z.string().min(1).max(255).optional(),
-  workflow_spec: WorkflowSpecSchema.optional(),
-});
-
-// In handler
-const validated = PersonaUpdateSchema.parse(input);
-```
-
----
-
-### CRIT-008: Error Messages Expose Sensitive Information
-
-**Location**: `src/mcp/server.ts:5829`, `src/sdk/client.ts:532-613`  
-**Impact**: Information disclosure, security vulnerability  
-**Category**: Security
-
-Error messages include API response bodies that may contain sensitive data:
-
-```typescript
-// Full error details serialized to JSON in responses
-message: `API error (${response.status}): ${response.statusText}`,
-body: responseData, // May contain sensitive info
-```
-
-**Fix**: Sanitize error messages before returning:
-
-```typescript
-function sanitizeErrorForResponse(error: EmaApiError): string {
-  // Return generic message, log full details internally
-  logger.error("API Error", { details: error.body });
-  return `API error (${error.statusCode}): Operation failed`;
-}
-```
-
----
-
-## 2. High Priority Issues
-
-### HIGH-001: Large Monolithic Files
-
-| File                               | Lines  | Issue                                |
-| ---------------------------------- | ------ | ------------------------------------ |
-| `src/mcp/server.ts`                | ~5,914 | Contains handlers, helpers, auto-fix |
-| `src/mcp/handlers-consolidated.ts` | ~3,381 | Incomplete modularization            |
-| `src/sdk/client.ts`                | ~2,717 | Legacy + current mixed               |
-
-**Fix**: Complete handler extraction to `src/mcp/handlers/`
-
----
-
-### HIGH-002: Manual Type Assertions Bypassing Safety
-
-**Found**: 19 instances of `as unknown` or `as any` in SDK
-
-| Location                                   | Issue                           |
-| ------------------------------------------ | ------------------------------- |
-| `src/sdk/workflow-fixer.ts:70,199,337,376` | `as unknown[]` casts            |
-| `src/sdk/intent-architect.ts:490`          | `as unknown as IntentSpec`      |
-| `src/sdk/grpc-client.ts:253`               | `as unknown as Parameters<...>` |
-| `src/sdk/client.ts:1479`                   | `as unknown as BodyInit`        |
-
-**Fix**: Replace with proper types or runtime validation:
-
-```typescript
-// Before
-const def = workflowDef as Record<string, unknown>;
-
-// After
-function isWorkflowDef(obj: unknown): obj is WorkflowDef {
-  return typeof obj === "object" && obj !== null && "actions" in obj;
-}
-if (!isWorkflowDef(workflowDef)) throw new Error("Invalid workflow");
-```
-
----
-
-### HIGH-003: Duplicate EmaApiError Class
-
-**Locations**:
-
-- `src/sdk/client.ts:83-93`
-- `src/sdk/ema-client.ts:55-65`
-
-Identical implementations causing maintenance burden.
-
-**Fix**: Extract to `src/sdk/errors.ts`:
-
-```typescript
-// src/sdk/errors.ts
-export class EmaApiError extends Error {
-  constructor(
-    message: string,
-    public readonly statusCode: number,
-    public readonly body: unknown,
-  ) {
-    super(message);
-    this.name = "EmaApiError";
-  }
-}
-```
-
----
-
-### HIGH-004: Sequential Target Environment Sync
-
-**Location**: `src/sync.ts:316-334`  
-**Impact**: For 3 targets, 3x slower than necessary
-
-**Fix**: Use `Promise.allSettled()`:
-
-```typescript
-const results = await Promise.allSettled(
-  targets.map((target) => syncToTarget(persona, target)),
-);
-```
-
----
-
-### HIGH-005: Double API Call in getPersonaById
-
-**Location**: `src/sdk/client.ts:369-406`  
-**Impact**: 2x API calls per persona fetch
-
-Always tries primary endpoint then fallback, even if primary succeeds.
-
-**Fix**: Only call fallback if primary fails or returns incomplete data.
-
----
-
-### HIGH-006: Excessive Deep Cloning
-
-**Locations**:
-
-- `src/sdk/client.ts:494` - workflow namespace fix
-- `src/mcp/handlers-consolidated.ts:1137` - workflow cloning
-- `src/sync.ts:149` - workflow transformation
-
-Large workflows (50-500KB) cloned via `JSON.parse(JSON.stringify())`.
-
-**Fix**: Use `structuredClone()`:
-
-```typescript
-// Before
-const cloned = JSON.parse(JSON.stringify(workflow));
-
-// After
-const cloned = structuredClone(workflow);
-```
-
----
-
-### HIGH-007: Unknown Action Type Falls Back to call_llm
-
-**Location**: `src/sdk/workflow-transformer.ts:392-415`
-
-```typescript
-function mapToActionType(rawName: string): ActionType {
-  const mapping: Record<string, ActionType> = { ... };
-  return mapping[rawName] || ("call_llm" as ActionType); // Silent fallback!
-}
-```
-
-**Impact**: Unknown action types silently converted, causing runtime errors.
-
-**Fix**: Return `'unknown'` type or throw error for unmapped actions.
-
----
-
-### HIGH-008: Core SDK Files Missing Unit Tests
-
-| File                        | Lines  | Status           |
-| --------------------------- | ------ | ---------------- |
-| `src/sdk/client.ts`         | ~2,400 | No unit tests    |
-| `src/sdk/ema-client.ts`     | ~405   | No unit tests    |
-| `src/sdk/grpc-client.ts`    | ~300   | Integration only |
-| `src/sdk/client-adapter.ts` | ~200   | No tests         |
-| `src/sdk/knowledge.ts`      | ~400   | No tests         |
-| `src/sdk/sync.ts`           | ~250   | Integration only |
-
-**Impact**: Core API client functionality untested.
-
-**Fix**: Add comprehensive unit tests with mocked API responses.
-
----
-
-### HIGH-009: Field Name Mismatch - workflow_def vs workflow
-
-**Locations**: `src/sdk/client.ts`, `src/sdk/ema-client.ts`
-
-GET returns `workflow_def`, UPDATE expects `workflow`. Handled in code but not typed consistently.
-
-**Fix**: Standardize on one name or add explicit type aliases:
-
-```typescript
-type WorkflowField = "workflow_def" | "workflow";
-interface PersonaResponse {
-  workflow_def?: WorkflowDef; // GET response
-}
-interface PersonaUpdateRequest {
-  workflow?: WorkflowDef; // UPDATE request
-}
-```
-
----
-
-### HIGH-010: Contract Validation Script Too Shallow
-
-**Location**: `scripts/check-api-contracts.ts:66-75`
-
-Only compares schema names and field counts, not:
-
-- Field types
-- Enum value changes
-- Required field changes
-
-**Fix**: Add deep JSON comparison with type awareness.
-
----
-
-## 3. Medium Priority Issues
-
-### Error Handling
-
-| ID      | Issue                        | Location                           |
-| ------- | ---------------------------- | ---------------------------------- |
-| MED-001 | Inconsistent error patterns  | Multiple files                     |
-| MED-002 | Swallowed errors in handlers | `handlers/persona/create.ts:94-96` |
-| MED-003 | Missing error context        | `client.ts:323-330`                |
-| MED-004 | Error propagation gaps       | `workflow-validator.ts:150-151`    |
-
-### Performance
-
-| ID      | Issue                          | Location            |
-| ------- | ------------------------------ | ------------------- |
-| MED-005 | Pre-fetch in updateAiEmployee  | `client.ts:476-550` |
-| MED-006 | No persona caching             | Multiple handlers   |
-| MED-007 | Prepared statements not cached | `state.ts`          |
-| MED-008 | File size limits missing       | `server.ts:4230`    |
-
-### Type Safety
-
-| ID      | Issue                 | Location                  |
-| ------- | --------------------- | ------------------------- |
-| MED-009 | Excessive `any` usage | 102 instances in 32 files |
-| MED-010 | Type assertions       | 2000+ instances           |
-| MED-011 | Non-null assertions   | 1415 instances            |
-| MED-012 | Missing return types  | 7 functions               |
-
-### Code Quality
-
-| ID      | Issue                               | Location                           |
-| ------- | ----------------------------------- | ---------------------------------- |
-| MED-013 | Duplicate `checkDeprecatedParams()` | 3 files                            |
-| MED-014 | Duplicate `SanitizationSession`     | `dashboard-clone.ts`               |
-| MED-015 | Deprecated params without warnings  | `handlers/persona/create.ts:67-69` |
-| MED-016 | 354 TODO/FIXME comments             | Throughout codebase                |
-
-### Security
-
-| ID      | Issue                            | Location                |
-| ------- | -------------------------------- | ----------------------- |
-| MED-017 | Debug logging may expose tokens  | `client.ts:105,512-535` |
-| MED-018 | Secret detection false negatives | `resources.ts:123-124`  |
-| MED-019 | HTTPS enforcement not explicit   | `ema-client.ts:72`      |
-
-### Testing
-
-| ID      | Issue                                    | Location           |
-| ------- | ---------------------------------------- | ------------------ |
-| MED-020 | No coverage thresholds                   | `vitest.config.ts` |
-| MED-021 | Integration tests excluded from coverage | Config             |
-| MED-022 | 15+ SDK files with no tests              | Multiple           |
-
----
-
-## 4. Architecture Analysis
-
-### Layer Separation (Score: 7/10)
-
-**Strengths**:
-
-- Clear SDK/MCP separation
-- MCP correctly imports from SDK
-- Centralized types prevent circular dependencies
-- Good handler dispatch pattern
-
-**Weaknesses**:
-
-- `src/sync.ts` violates SDK ownership (should be in SDK)
-- Circular dependency between `sync.ts` ↔ `sdk/sync.ts`
-- Incomplete handler modularization
-
-### File Structure
-
-```
-src/
-├── index.ts          # HTTP sync server (Fastify)
-├── sync.ts           # ⚠️ Should be in sdk/
-├── ui.ts             # Dashboard UI
-├── cli/              # CLI tool
-├── mcp/              # MCP server layer
-│   ├── server.ts     # ⚠️ 5,914 lines - too large
-│   ├── handlers-consolidated.ts  # ⚠️ 3,381 lines - incomplete modularization
-│   ├── handlers/     # ✓ Modular handlers (in progress)
-│   ├── tools-*.ts    # Tool definitions
-│   ├── prompts.ts    # MCP prompts
-│   └── resources.ts  # MCP resources
-└── sdk/              # Core SDK layer
-    ├── client.ts     # ⚠️ Deprecated, still maintained
-    ├── ema-client.ts # ✓ New primary client
-    ├── workflow-*.ts # Workflow transformation
-    ├── state.ts      # SQLite state management
-    └── generated/    # Proto/OpenAPI generated
-```
-
-### Module Dependencies
-
-```mermaid
-graph TD
-    MCP[src/mcp/*] --> SDK[src/sdk/*]
-    CLI[src/cli/*] --> SDK
-    CLI --> SYNC[src/sync.ts]
-    MCP --> SYNC
-    SYNC --> SDK
-    SDK_SYNC[src/sdk/sync.ts] --> SYNC
-    SDK_SYNC --> SDK
-
-    style SYNC fill:#ff6b6b,stroke:#333
-    style SDK_SYNC fill:#ff6b6b,stroke:#333
-```
-
-**Issue**: Circular dependency `SYNC ↔ SDK_SYNC`
-
----
-
-## 5. Security Analysis
-
-### Authentication (Score: 7/10)
-
-**Strengths**:
-
-- Tokens read from environment variables
-- No hardcoded secrets found
-- Config validation via Zod schemas
-- Token refresh with caching
-
-**Weaknesses**:
-
-- Token may be exposed in error messages
-- No explicit token rotation
-
-### Input Validation (Score: 5/10)
-
-**Strengths**:
-
-- Path traversal protection in resources handler
-- Some sanitization exists for persona data
-
-**Weaknesses**:
-
-- Insufficient validation in most handlers
-- File paths not consistently validated
-- No rate limiting
-
-### Data Exposure (Score: 6/10)
-
-**Strengths**:
-
-- Secret detection patterns in resources
-- Blocked files list for sensitive files
-
-**Weaknesses**:
-
-- Error messages may contain sensitive data
-- Debug logging may expose tokens
-- Full API responses in errors
-
-### Recommendations
-
-1. **Immediate**: Add input validation to all handlers
-2. **Immediate**: Sanitize error messages
-3. **Short-term**: Add rate limiting
-4. **Short-term**: Add request size limits
-5. **Long-term**: Security audit of all file operations
-
----
-
-## 6. API Contracts Analysis
-
-### Proto Files (Score: 8/10)
-
-**Strengths**:
-
-- Complete proto-generated types
-- Proper deprecation markers (345+ instances)
-- Uses `@bufbuild/protobuf` codegen v2
-
-**Weaknesses**:
-
-- 30+ TODO comments indicating future changes
-- Some deprecated fields still in use
-
-### OpenAPI Spec (Score: 8/10)
-
-**Strengths**:
-
-- OpenAPI 3.1.0 spec present and cached
-- 8000+ lines covering all REST endpoints
-- Types include proper nullable handling
-
-**Weaknesses**:
-
-- Contract validation script too shallow
-- Manual type assertions bypass safety
-
-### Field Naming Issues
-
-| API Context     | Field Name                      | Issue                       |
-| --------------- | ------------------------------- | --------------------------- |
-| GET Persona     | `workflow_def`                  | Different from UPDATE       |
-| UPDATE Persona  | `workflow`                      | Different from GET          |
-| Widget Format   | `{ name, type, [name]: {...} }` | Complex structure not typed |
-| Results Mapping | `"<actionName>.<outputName>"`   | String keys, not object     |
-
----
-
-## 7. SDK Layer Analysis
-
-### Client Architecture
-
-```
-EmaClientV2 (ema-client.ts)     ← Primary, uses generated OpenAPI client
-    ↓
-EmaClientAdapter (client-adapter.ts)
-    ↓
-EmaClient (client.ts)           ← Deprecated, legacy compatibility
-    ↓
-GrpcClient (grpc-client.ts)     ← gRPC for Connect-ES
-```
-
-**Issue**: Both `EmaClient` and `EmaClientV2` actively maintained despite deprecation.
-
-### Workflow System
-
-| File                      | Lines | Test Coverage | Issues                             |
-| ------------------------- | ----- | ------------- | ---------------------------------- |
-| `workflow-transformer.ts` | ~600  | ✓ Good        | Silent fallback for unknown types  |
-| `workflow-generator.ts`   | ~400  | ✓ Good        | Enum validation incomplete         |
-| `workflow-validator.ts`   | ~200  | ✗ None        | Untested                           |
-| `workflow-fixer.ts`       | ~500  | ✓ Good        | Multiple `as unknown` casts        |
-| `workflow-optimizer.ts`   | ~300  | ✗ None        | Performance issue for large graphs |
-| `workflow-merge.ts`       | ~350  | ✓ Good        | Force replace breaks downstream    |
-
-### State Management
-
-**File**: `src/sdk/state.ts`
-
-**Strengths**:
-
-- SQLite with WAL mode
-- ON CONFLICT for upserts
-
-**Weaknesses**:
-
-- No prepared statement caching
-- Database connection never closed
-- No transaction batching
-- Missing error handling
-
----
-
-## 8. MCP Layer Analysis
-
-### Handler Structure (Score: 7/10)
-
-**Modularized Handlers** (in `src/mcp/handlers/`):
-
-- ✅ persona: get, list, create, update, delete, compare
-- ✅ data: list, upload, delete, sanitize, replicate
-- ✅ action, env, template, reference, sync
-
-**Remaining in `handlers-consolidated.ts`**:
-
-- ❌ version\_\* modes (330 lines)
-- ❌ handleWorkflow (962 lines)
-
-### Server Setup Issues
-
-1. **No graceful shutdown** - SIGTERM/SIGINT not handled
-2. **No error recovery** - No retry/backoff for API failures
-3. **Unbounded caches** - clientCache, agentCatalogCache never cleared
-
-### Response Consistency
-
-| Handler          | Shape                        | Issue        |
-| ---------------- | ---------------------------- | ------------ |
-| `handleGet`      | Flat object                  | Inconsistent |
-| `handleCreate`   | Nested with `actions_result` | Inconsistent |
-| `handleWorkflow` | Varies by mode               | Inconsistent |
-
-**Fix**: Standardize on consistent response shape with `_tip`, `_next_step`, `_metadata`.
-
----
-
-## 9. Test Coverage Analysis
-
-### Coverage Summary
-
-| Category    | Files | Tested | Coverage |
-| ----------- | ----- | ------ | -------- |
-| Handlers    | 10    | 8      | 80%      |
-| SDK Core    | 15    | 6      | 40%      |
-| Workflow    | 8     | 5      | 63%      |
-| Integration | 7     | 7      | 100%     |
-
-**Total Test Cases**: ~1,423
-
-### Critical Gaps
-
-| File                            | Lines | Impact               |
-| ------------------------------- | ----- | -------------------- |
-| `src/sdk/client.ts`             | 2,400 | Core API client      |
-| `src/sdk/ema-client.ts`         | 405   | New primary client   |
-| `src/sdk/grpc-client.ts`        | 300   | gRPC operations      |
-| `src/sdk/client-adapter.ts`     | 200   | V1/V2 bridging       |
-| `src/sdk/knowledge.ts`          | 400   | Knowledge management |
-| `src/sdk/workflow-validator.ts` | 200   | Validation logic     |
-
-### Missing Test Types
-
-1. **Error handling tests** - Network failures, timeouts
-2. **Edge case tests** - Empty inputs, malformed data
-3. **Concurrent operation tests** - Race conditions
-4. **Security tests** - Injection, traversal
-
-### Configuration Gap
-
-No coverage thresholds in `vitest.config.ts`:
-
-```typescript
-// Recommended addition
-coverage: {
-  thresholds: {
-    lines: 80,
-    functions: 80,
-    branches: 75,
-    statements: 80
-  }
-}
-```
-
----
-
-## 10. Performance Analysis
-
-### API Call Patterns
-
-| Issue                  | Impact                  | Location            |
-| ---------------------- | ----------------------- | ------------------- |
-| N+1 in sync loop       | 10-30s for 100 personas | `sync.ts:259-273`   |
-| Sequential target sync | 3x slower               | `sync.ts:316-334`   |
-| Double fetch in update | 2x API calls            | `client.ts:476-550` |
-| Pre-fetch always       | Extra call per update   | `client.ts:369-406` |
-
-### Memory Issues
-
-| Issue                | Impact                                 | Location                    |
-| -------------------- | -------------------------------------- | --------------------------- |
-| Deep clone with JSON | 3-5x memory for large workflows        | Multiple                    |
-| Unbounded caches     | Memory leak in long-running            | `resources.ts`, `server.ts` |
-| Version storage      | 50-100MB per persona for 1000 versions | `version-storage.ts`        |
-
-### File I/O Issues
-
-**All file operations in `version-storage.ts` are synchronous**:
-
-- 6 `readFileSync` calls
-- 6 `writeFileSync` calls
-- 9 `existsSync` calls
-
-**Impact**: Blocks event loop, poor concurrency.
-
-### SQLite Issues
-
-| Issue                       | Impact                       | Fix              |
-| --------------------------- | ---------------------------- | ---------------- |
-| No prepared statement cache | Compilation overhead         | Cache statements |
-| No transaction batching     | Extra I/O                    | Use transactions |
-| Single connection           | Multiple connections created | Use singleton    |
-
----
-
-## 11. Code Quality Analysis
-
-### Type Safety Metrics
-
-| Metric                    | Count | Severity |
-| ------------------------- | ----- | -------- |
-| `any` types               | 102   | HIGH     |
-| Type assertions (`as`)    | 2000+ | HIGH     |
-| Non-null assertions (`!`) | 1415  | MEDIUM   |
-| Missing return types      | 7     | MEDIUM   |
-
-### Code Duplication
-
-| Duplicate                 | Locations                  | Fix                  |
-| ------------------------- | -------------------------- | -------------------- |
-| `checkDeprecatedParams()` | 3 files                    | Extract to utils     |
-| `SanitizationSession`     | `dashboard-clone.ts` + SDK | Use SDK version      |
-| `EmaApiError`             | 2 files                    | Extract to errors.ts |
-
-### Documentation
-
-- **JSDoc Coverage**: 23,151 comments across 172 files
-- **TODO/FIXME**: 354 instances
-- **Commented code**: 100+ lines in `server.ts`
-
-### Configuration Quality
-
-```json
-// tsconfig.json - Good but could be stricter
-{
-  "strict": true // ✓
-  // Missing recommended flags:
-  // "noUnusedLocals": true,
-  // "noUnusedParameters": true
-}
-```
-
----
-
-## 12. Recommended Action Plan
-
-### Phase 1: Critical (Week 1-2)
-
-| Priority | Issue                       | Effort | Files                      |
-| -------- | --------------------------- | ------ | -------------------------- |
-| P0       | Fix circular dependency     | 2h     | `sync.ts`, `sdk/sync.ts`   |
-| P0       | Add input validation        | 4h     | `handlers-consolidated.ts` |
-| P0       | Fix path traversal          | 2h     | `server.ts`                |
-| P0       | Add graceful shutdown       | 2h     | `server.ts`                |
-| P0       | Sanitize error messages     | 3h     | `client.ts`, `server.ts`   |
-| P0       | Migrate to async file I/O   | 4h     | `version-storage.ts`       |
-| P0       | Fix N+1 query pattern       | 2h     | `sync.ts`                  |
-| P0       | Validate workflow namespace | 1h     | `workflow-transformer.ts`  |
-
-**Estimated Total**: 20 hours
-
-### Phase 2: High Priority (Week 3-4)
-
-| Priority | Issue                           | Effort | Files                        |
-| -------- | ------------------------------- | ------ | ---------------------------- |
-| P1       | Complete handler modularization | 8h     | `handlers-consolidated.ts`   |
-| P1       | Extract shared error class      | 1h     | Create `sdk/errors.ts`       |
-| P1       | Add SDK unit tests              | 16h    | `client.ts`, `ema-client.ts` |
-| P1       | Replace type assertions         | 8h     | `workflow-fixer.ts`, etc.    |
-| P1       | Add coverage thresholds         | 1h     | `vitest.config.ts`           |
-| P1       | Fix double API call             | 2h     | `client.ts`                  |
-| P1       | Use structuredClone             | 2h     | Multiple                     |
-
-**Estimated Total**: 38 hours
-
-### Phase 3: Medium Priority (Week 5-8)
-
-| Priority | Issue                        | Effort | Files                    |
-| -------- | ---------------------------- | ------ | ------------------------ |
-| P2       | Consolidate duplicate code   | 4h     | Multiple                 |
-| P2       | Standardize error handling   | 6h     | All handlers             |
-| P2       | Add prepared statement cache | 3h     | `state.ts`               |
-| P2       | Improve contract validation  | 4h     | `check-api-contracts.ts` |
-| P2       | Add deprecation warnings     | 2h     | Handlers                 |
-| P2       | Standardize response format  | 4h     | All handlers             |
-
-**Estimated Total**: 23 hours
-
-### Phase 4: Technical Debt (Ongoing)
-
-- Remove 100+ lines of commented code
-- Address 354 TODO/FIXME comments
-- Reduce `any` usage from 102 to <20
-- Add JSDoc to internal functions
-- Enable additional TypeScript strict flags
-
----
-
-## Appendix A: Files Requiring Immediate Attention
-
-| File                               | Issues                           | Priority |
-| ---------------------------------- | -------------------------------- | -------- |
-| `src/sync.ts`                      | Circular dependency, N+1 queries | P0       |
-| `src/mcp/server.ts`                | Size, shutdown, path traversal   | P0       |
-| `src/sdk/version-storage.ts`       | Sync file I/O                    | P0       |
-| `src/mcp/handlers-consolidated.ts` | Size, validation                 | P0-P1    |
-| `src/sdk/client.ts`                | Duplicate class, double fetch    | P1       |
-| `src/sdk/workflow-transformer.ts`  | Namespace validation             | P0       |
-| `src/sdk/workflow-fixer.ts`        | Type assertions                  | P1       |
-
-## Appendix B: Metrics Summary
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│                    Codebase Metrics                          │
-├─────────────────────────────────────────────────────────────┤
-│ Total TypeScript Files: 172                                  │
-│ Total Lines of Code: ~45,000                                 │
-│ Test Files: 59                                               │
-│ Test Cases: ~1,423                                           │
-│ Dependencies: 10 production, 11 dev                          │
-├─────────────────────────────────────────────────────────────┤
-│ Critical Issues: 8                                           │
-│ High Priority: 23                                            │
-│ Medium Priority: 34                                          │
-│ Low Priority: 18                                             │
-├─────────────────────────────────────────────────────────────┤
-│ Overall Health Score: 6.2/10                                 │
-└─────────────────────────────────────────────────────────────┘
-```
-
----
-
-_Report generated by comprehensive static analysis_  
-_Last updated: January 23, 2026_