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

package/docs/CODEBASE-ANALYSIS-PRIORITIZED.md

@@ -1,774 +0,0 @@
-# Prioritized Codebase Issues
-
-**Date**: January 23, 2026
-
----
-
-## Impact vs Effort Matrix
-
-```
-                    HIGH IMPACT
-                         │
-    ┌────────────────────┼────────────────────┐
-    │                    │                    │
-    │   QUICK WINS       │   BIG BETS         │
-    │   (Do First)       │   (Plan Carefully) │
-    │                    │                    │
-LOW ├────────────────────┼────────────────────┤ HIGH
-EFFORT                   │                    EFFORT
-    │                    │                    │
-    │   FILL-INS         │   MONEY PITS       │
-    │   (If Time)        │   (Avoid/Defer)    │
-    │                    │                    │
-    └────────────────────┼────────────────────┘
-                         │
-                    LOW IMPACT
-```
-
----
-
-## Section 1: Quick Wins (High Impact, Low Effort)
-
-These deliver immediate value with minimal risk. Do these first.
-
-### QW-1: Add Graceful Shutdown Handler
-
-**Effort**: 30 min | **Impact**: Prevents data corruption, resource leaks
-
-```typescript
-// src/mcp/server.ts - Add near server initialization
-process.on("SIGTERM", () => {
-  server.close();
-  process.exit(0);
-});
-process.on("SIGINT", () => {
-  server.close();
-  process.exit(0);
-});
-```
-
----
-
-### QW-2: Extract Shared EmaApiError Class
-
-**Effort**: 30 min | **Impact**: Eliminates duplicate code, single source of truth
-
-**Files to change**:
-
-- Create `src/sdk/errors.ts`
-- Update `src/sdk/client.ts`
-- Update `src/sdk/ema-client.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";
-  }
-}
-```
-
----
-
-### QW-3: Add Coverage Thresholds
-
-**Effort**: 15 min | **Impact**: Prevents test coverage regression
-
-```typescript
-// vitest.config.ts - Add to coverage section
-coverage: {
-  thresholds: {
-    lines: 70,
-    functions: 70,
-    branches: 60,
-    statements: 70
-  }
-}
-```
-
----
-
-### QW-4: Use structuredClone Instead of JSON.parse/stringify
-
-**Effort**: 1 hour | **Impact**: 30-50% faster cloning, lower memory
-
-**Files**: `src/sdk/client.ts:494`, `src/mcp/handlers-consolidated.ts:1137`, `src/sync.ts:149`
-
-```typescript
-// Before
-const cloned = JSON.parse(JSON.stringify(workflow));
-
-// After
-const cloned = structuredClone(workflow);
-```
-
----
-
-### QW-5: Consolidate checkDeprecatedParams
-
-**Effort**: 45 min | **Impact**: DRY, single place to update
-
-**Current locations** (delete from):
-
-- `src/mcp/handlers-consolidated.ts:219`
-- `src/mcp/handlers/sync/index.ts:16`
-- `src/mcp/handlers/action/index.ts:20`
-
-**Move to**: `src/mcp/handlers/utils.ts` (already exists)
-
----
-
-### QW-6: Fix Unknown Action Type Silent Fallback
-
-**Effort**: 30 min | **Impact**: Prevents silent runtime errors
-
-```typescript
-// src/sdk/workflow-transformer.ts:392-415
-function mapToActionType(rawName: string): ActionType | 'unknown' {
-  const mapping: Record<string, ActionType> = { ... };
-  const result = mapping[rawName];
-  if (!result) {
-    console.warn(`Unknown action type: ${rawName}, preserving as-is`);
-    return 'unknown';
-  }
-  return result;
-}
-```
-
----
-
-### QW-7: Add Workflow Namespace Validation
-
-**Effort**: 30 min | **Impact**: Prevents silent deployment failures
-
-```typescript
-// src/sdk/workflow-transformer.ts - Add before line 552
-function validateWorkflowNamespace(ns: unknown): boolean {
-  if (!ns || typeof ns !== "object") return false;
-  const namespace = ns as { namespaces?: unknown[]; name?: string };
-  return (
-    Array.isArray(namespace.namespaces) && typeof namespace.name === "string"
-  );
-}
-
-// Then use it
-if (!validateWorkflowNamespace(originalDef.workflowName)) {
-  throw new Error("Invalid workflow namespace structure");
-}
-compiled.workflow_def.workflowName = originalDef.workflowName;
-```
-
----
-
-### Quick Wins Summary
-
-| ID   | Task                         | Effort | Impact            |
-| ---- | ---------------------------- | ------ | ----------------- |
-| QW-1 | Graceful shutdown            | 30 min | Data safety       |
-| QW-2 | Extract EmaApiError          | 30 min | DRY               |
-| QW-3 | Coverage thresholds          | 15 min | Quality gate      |
-| QW-4 | Use structuredClone          | 1 hour | Performance       |
-| QW-5 | Consolidate deprecated check | 45 min | DRY               |
-| QW-6 | Fix action type fallback     | 30 min | Error prevention  |
-| QW-7 | Namespace validation         | 30 min | Deployment safety |
-
-**Total Quick Wins**: ~4 hours for 7 high-impact fixes
-
----
-
-## Section 2: Security Fixes (Must Do)
-
-Security issues grouped by attack surface.
-
-### SEC-1: Input Validation (HIGH)
-
-**Effort**: 4 hours | **Impact**: Prevents injection, corruption
-
-**Add Zod validation at handler entry points**:
-
-```typescript
-// src/mcp/handlers/utils.ts - Add
-import { z } from "zod";
-
-export const PersonaIdSchema = z.string().uuid();
-export const FilePathSchema = z
-  .string()
-  .refine((p) => !p.includes("..") && !p.startsWith("/"), "Invalid file path");
-
-// Use in handlers
-const id = PersonaIdSchema.parse(args.id);
-```
-
-**Priority handlers**:
-
-1. `handlePersona` - persona CRUD
-2. `handleData` - file operations
-3. `handleKnowledge` - file uploads
-
----
-
-### SEC-2: Path Traversal Fix (CRITICAL)
-
-**Effort**: 1 hour | **Impact**: Prevents unauthorized file access
-
-```typescript
-// src/mcp/handlers/utils.ts - Add
-export function validateAndResolvePath(
-  userPath: string,
-  baseDir: string,
-): string {
-  const resolved = path.resolve(baseDir, userPath);
-  const normalized = path.normalize(resolved);
-
-  if (!normalized.startsWith(path.resolve(baseDir))) {
-    throw new Error("Path traversal detected");
-  }
-
-  return normalized;
-}
-```
-
-**Apply to**:
-
-- `src/mcp/server.ts:3930-3937` (file upload)
-- `src/mcp/server.ts:4140-4149` (file operations)
-
----
-
-### SEC-3: Sanitize Error Messages (HIGH)
-
-**Effort**: 2 hours | **Impact**: Prevents information disclosure
-
-```typescript
-// src/sdk/errors.ts - Add
-export function sanitizeErrorForResponse(error: unknown): string {
-  if (error instanceof EmaApiError) {
-    // Log full details internally
-    console.error("API Error", { status: error.statusCode, body: error.body });
-    // Return sanitized message
-    return `API error (${error.statusCode}): Operation failed`;
-  }
-  return error instanceof Error ? error.message : "Unknown error";
-}
-```
-
-**Apply to**:
-
-- `src/mcp/server.ts:5829`
-- `src/sdk/client.ts:532-613`
-
----
-
-### SEC-4: Debug Logging Token Safety (MEDIUM)
-
-**Effort**: 1 hour | **Impact**: Prevents token exposure
-
-```typescript
-// src/sdk/logging.ts - Add
-export function sanitizeForLogging(obj: unknown): unknown {
-  if (typeof obj !== "object" || obj === null) return obj;
-  const sanitized = { ...obj } as Record<string, unknown>;
-  const sensitiveKeys = [
-    "token",
-    "bearer",
-    "authorization",
-    "api_key",
-    "password",
-  ];
-  for (const key of Object.keys(sanitized)) {
-    if (sensitiveKeys.some((k) => key.toLowerCase().includes(k))) {
-      sanitized[key] = "[REDACTED]";
-    }
-  }
-  return sanitized;
-}
-```
-
----
-
-### Security Fixes Summary
-
-| ID    | Task               | Effort  | Severity |
-| ----- | ------------------ | ------- | -------- |
-| SEC-1 | Input validation   | 4 hours | HIGH     |
-| SEC-2 | Path traversal fix | 1 hour  | CRITICAL |
-| SEC-3 | Sanitize errors    | 2 hours | HIGH     |
-| SEC-4 | Token safety       | 1 hour  | MEDIUM   |
-
-**Total Security**: ~8 hours
-
----
-
-## Section 3: Performance Fixes
-
-Issues ordered by user-visible impact.
-
-### PERF-1: Parallelize Sync Operations (CRITICAL)
-
-**Effort**: 2 hours | **Impact**: 3-10x faster sync
-
-**N+1 Query Fix** (`src/sync.ts:259-273`):
-
-```typescript
-// Before: Sequential
-for (let p of personas) {
-  if (!p.workflow_def) {
-    const full = await masterClient.getPersonaById(p.id);
-  }
-}
-
-// After: Parallel batches
-const missingWorkflow = personas.filter((p) => !p.workflow_def);
-const batches = chunk(missingWorkflow, 10); // 10 at a time
-for (const batch of batches) {
-  const results = await Promise.all(
-    batch.map((p) => masterClient.getPersonaById(p.id)),
-  );
-  // Merge results...
-}
-```
-
-**Target Sync Fix** (`src/sync.ts:316-334`):
-
-```typescript
-// Before: Sequential
-for (const target of targets) {
-  await syncToTarget(persona, target);
-}
-
-// After: Parallel
-const results = await Promise.allSettled(
-  targets.map((target) => syncToTarget(persona, target)),
-);
-```
-
----
-
-### PERF-2: Async File I/O (HIGH)
-
-**Effort**: 4 hours | **Impact**: Unblocks event loop
-
-**File**: `src/sdk/version-storage.ts`
-
-Convert all sync operations:
-
-```typescript
-// Before
-const content = fs.readFileSync(path, 'utf8');
-fs.writeFileSync(path, data);
-if (fs.existsSync(path)) { ... }
-
-// After
-import { readFile, writeFile, access } from 'fs/promises';
-
-const content = await readFile(path, 'utf8');
-await writeFile(path, data);
-try {
-  await access(path);
-  // exists
-} catch {
-  // doesn't exist
-}
-```
-
-**Methods to update** (15 total):
-
-- `getLatestSnapshot` → `getLatestSnapshotAsync`
-- `saveSnapshot` → `saveSnapshotAsync`
-- etc.
-
----
-
-### PERF-3: Cache Prepared Statements (MEDIUM)
-
-**Effort**: 1 hour | **Impact**: Faster SQLite queries
-
-```typescript
-// src/sdk/state.ts - Change pattern
-class StateStore {
-  // Cache statements at class level
-  private readonly getMappingStmt: Statement;
-  private readonly upsertMappingStmt: Statement;
-
-  constructor(dbPath: string) {
-    this.db = new Database(dbPath);
-    // Prepare once
-    this.getMappingStmt = this.db.prepare(`SELECT ...`);
-    this.upsertMappingStmt = this.db.prepare(`INSERT ...`);
-  }
-
-  getMapping(id: string) {
-    return this.getMappingStmt.get(id); // Use cached
-  }
-}
-```
-
----
-
-### PERF-4: Eliminate Double API Call (MEDIUM)
-
-**Effort**: 1 hour | **Impact**: 50% fewer update API calls
-
-```typescript
-// src/sdk/client.ts:476-550
-// Before: Always fetch existing persona
-async updateAiEmployee(req: UpdateRequest) {
-  const existing = await this.getPersonaById(req.id); // Extra call!
-  // ...fix namespace...
-  return this.doUpdate(req);
-}
-
-// After: Only fetch if namespace missing
-async updateAiEmployee(req: UpdateRequest) {
-  if (req.workflow && !hasValidNamespace(req.workflow)) {
-    const existing = await this.getPersonaById(req.id);
-    copyNamespace(existing.workflow_def, req.workflow);
-  }
-  return this.doUpdate(req);
-}
-```
-
----
-
-### Performance Fixes Summary
-
-| ID     | Task                  | Effort  | Speedup   |
-| ------ | --------------------- | ------- | --------- |
-| PERF-1 | Parallelize sync      | 2 hours | 3-10x     |
-| PERF-2 | Async file I/O        | 4 hours | Unblocks  |
-| PERF-3 | Cache statements      | 1 hour  | ~20%      |
-| PERF-4 | Eliminate double call | 1 hour  | 50% fewer |
-
-**Total Performance**: ~8 hours
-
----
-
-## Section 4: Architecture Fixes
-
-Structural issues that compound over time.
-
-### ARCH-1: Fix Circular Dependency (CRITICAL)
-
-**Effort**: 2 hours | **Impact**: Prevents module failures
-
-**Problem**:
-
-```
-src/sync.ts → imports → src/sdk/config.ts
-src/sdk/sync.ts → imports → src/sync.ts (circular!)
-```
-
-**Solution**:
-
-1. Create `src/sdk/sync-engine.ts` with core logic
-2. Move `fingerprintPersona`, `syncOnce`, `transformWorkflowForTarget`
-3. Have `src/sdk/sync.ts` re-export
-4. Make `src/sync.ts` a thin wrapper or delete
-
-```
-src/sdk/sync-engine.ts  ← NEW: core logic
-src/sdk/sync.ts         ← re-exports sync-engine
-src/sync.ts             ← DELETE or thin wrapper
-```
-
----
-
-### ARCH-2: Complete Handler Modularization (HIGH)
-
-**Effort**: 8 hours | **Impact**: Maintainability, testability
-
-**Current state**:
-
-- `handlers-consolidated.ts`: 3,381 lines
-- `server.ts`: 5,914 lines
-
-**Target state**:
-
-```
-src/mcp/handlers/
-├── persona/     ✅ Done
-├── data/        ✅ Done
-├── action/      ✅ Done
-├── sync/        ✅ Done
-├── workflow/    ❌ NEW - Extract from handlers-consolidated
-├── version/     ❌ NEW - Extract version_* modes
-└── utils.ts     ✅ Done
-```
-
-**Steps**:
-
-1. Create `src/mcp/handlers/workflow/index.ts`
-2. Move `handleWorkflow` (962 lines) to workflow handler
-3. Create `src/mcp/handlers/version/index.ts`
-4. Move version modes (330 lines)
-5. Reduce `handlers-consolidated.ts` to dispatch only
-
----
-
-### ARCH-3: Split server.ts (MEDIUM)
-
-**Effort**: 4 hours | **Impact**: Readability, maintainability
-
-**Current**: 5,914 lines doing many things
-
-**Target**:
-
-```
-src/mcp/
-├── server.ts           ← 500 lines: init, routing only
-├── tools/
-│   ├── index.ts        ← tool registration
-│   └── helpers.ts      ← tool helpers
-├── middleware/
-│   └── error-handler.ts
-└── lifecycle.ts        ← startup, shutdown
-```
-
----
-
-### Architecture Fixes Summary
-
-| ID     | Task             | Effort  | Impact          |
-| ------ | ---------------- | ------- | --------------- |
-| ARCH-1 | Fix circular dep | 2 hours | Stability       |
-| ARCH-2 | Extract handlers | 8 hours | Maintainability |
-| ARCH-3 | Split server.ts  | 4 hours | Readability     |
-
-**Total Architecture**: ~14 hours
-
----
-
-## Section 5: Test Coverage
-
-Focus on highest-risk untested code.
-
-### TEST-1: SDK Client Tests (HIGH)
-
-**Effort**: 8 hours | **Impact**: Core API client coverage
-
-**Untested files** (highest risk):
-
-- `src/sdk/client.ts` (2,400 lines)
-- `src/sdk/ema-client.ts` (405 lines)
-
-**Test approach**:
-
-```typescript
-// test/sdk/ema-client.test.ts
-import { vi } from "vitest";
-import { EmaClientV2 } from "../src/sdk/ema-client";
-
-vi.mock("../src/sdk/generated/api-client", () => ({
-  getPersonas: vi.fn(),
-  updatePersona: vi.fn(),
-}));
-
-describe("EmaClientV2", () => {
-  it("handles API errors correctly", async () => {
-    // Mock 404 response
-    // Assert EmaApiError thrown
-  });
-
-  it("preserves workflow namespace on update", async () => {
-    // Critical business logic
-  });
-});
-```
-
----
-
-### TEST-2: Workflow Validator/Optimizer Tests (MEDIUM)
-
-**Effort**: 4 hours | **Impact**: Validation logic coverage
-
-**Untested**:
-
-- `src/sdk/workflow-validator.ts`
-- `src/sdk/workflow-optimizer.ts`
-
----
-
-### TEST-3: Error Path Tests (MEDIUM)
-
-**Effort**: 4 hours | **Impact**: Resilience coverage
-
-Add tests for:
-
-- Network failures
-- Timeout scenarios
-- Malformed responses
-- Concurrent operations
-
----
-
-### Test Coverage Summary
-
-| ID     | Task             | Effort  | Coverage Gain |
-| ------ | ---------------- | ------- | ------------- |
-| TEST-1 | SDK client tests | 8 hours | +15%          |
-| TEST-2 | Validator tests  | 4 hours | +5%           |
-| TEST-3 | Error path tests | 4 hours | +5%           |
-
-**Total Testing**: ~16 hours
-
----
-
-## Section 6: Code Quality
-
-Technical debt that slows development.
-
-### QUAL-1: Reduce Type Assertions (HIGH)
-
-**Effort**: 8 hours | **Impact**: Type safety
-
-**Focus files** (highest assertion count):
-
-1. `src/sdk/workflow-fixer.ts` - 4 `as unknown` casts
-2. `src/sdk/intent-architect.ts` - 1 unsafe cast
-3. `src/mcp/handlers-consolidated.ts` - Many `as Record<...>`
-
-**Strategy**: Add type guards:
-
-```typescript
-// src/sdk/type-guards.ts
-export function isWorkflowDef(obj: unknown): obj is WorkflowDef {
-  return (
-    typeof obj === "object" &&
-    obj !== null &&
-    "actions" in obj &&
-    Array.isArray((obj as { actions: unknown }).actions)
-  );
-}
-
-// Usage
-if (!isWorkflowDef(workflowDef)) {
-  throw new Error("Invalid workflow definition");
-}
-// Now TypeScript knows it's WorkflowDef
-```
-
----
-
-### QUAL-2: Remove Dead Code (LOW)
-
-**Effort**: 2 hours | **Impact**: Cleaner codebase
-
-- Remove 100+ lines of commented code in `server.ts`
-- Run `npm run lint:unused` to find unused exports
-- Delete or extract to separate "legacy" file
-
----
-
-### QUAL-3: Address Critical TODOs (MEDIUM)
-
-**Effort**: Varies | **Impact**: Completes incomplete features
-
-**High-priority TODOs**:
-
-```typescript
-// src/mcp/server.ts:1624
-"TODO: Add support for 3rd party data sources";
-
-// src/mcp/handlers-consolidated.ts:359
-"TODO: Deprecate handleWorkflow and move remaining logic";
-```
-
----
-
-### Code Quality Summary
-
-| ID     | Task             | Effort  | Impact       |
-| ------ | ---------------- | ------- | ------------ |
-| QUAL-1 | Type guards      | 8 hours | Safety       |
-| QUAL-2 | Remove dead code | 2 hours | Cleanliness  |
-| QUAL-3 | Address TODOs    | Varies  | Completeness |
-
----
-
-## Recommended Execution Order
-
-### Sprint 1: Quick Wins + Critical Security (1 week)
-
-| Day | Tasks                      | Hours |
-| --- | -------------------------- | ----- |
-| 1   | QW-1, QW-2, QW-3           | 1.25h |
-| 1   | SEC-2 (path traversal)     | 1h    |
-| 2   | QW-4, QW-5, QW-6, QW-7     | 2.75h |
-| 2   | SEC-3 (error sanitization) | 2h    |
-| 3   | ARCH-1 (circular dep)      | 2h    |
-| 3   | SEC-1 (input validation)   | 4h    |
-| 4   | PERF-1 (parallelize sync)  | 2h    |
-| 5   | Buffer / PR review         | -     |
-
-**Sprint 1 Total**: ~15 hours of work
-
-### Sprint 2: Performance + Architecture (1 week)
-
-| Day | Tasks                       | Hours |
-| --- | --------------------------- | ----- |
-| 1-2 | PERF-2 (async file I/O)     | 4h    |
-| 2   | PERF-3, PERF-4              | 2h    |
-| 3-4 | ARCH-2 (handler extraction) | 8h    |
-| 5   | Buffer / PR review          | -     |
-
-**Sprint 2 Total**: ~14 hours of work
-
-### Sprint 3: Testing + Quality (1 week)
-
-| Day | Tasks                     | Hours |
-| --- | ------------------------- | ----- |
-| 1-2 | TEST-1 (SDK client tests) | 8h    |
-| 3   | TEST-2, TEST-3            | 8h    |
-| 4-5 | QUAL-1 (type guards)      | 8h    |
-
-**Sprint 3 Total**: ~24 hours of work
-
----
-
-## Quick Reference Card
-
-### Do Today (< 2 hours total)
-
-1. ✅ Add graceful shutdown (30 min)
-2. ✅ Add coverage thresholds (15 min)
-3. ✅ Fix action type fallback (30 min)
-4. ✅ Add namespace validation (30 min)
-
-### Do This Week
-
-1. 🔒 Fix path traversal
-2. 🔒 Add input validation
-3. 🔒 Sanitize error messages
-4. 🏗️ Fix circular dependency
-5. ⚡ Parallelize sync operations
-
-### Do This Month
-
-1. ⚡ Async file I/O migration
-2. 🏗️ Complete handler extraction
-3. 🧪 Add SDK client tests
-4. 🔧 Add type guards
-
----
-
-## Metrics to Track
-
-After implementing fixes:
-
-| Metric                   | Current | Target |
-| ------------------------ | ------- | ------ |
-| Test coverage            | ~45%    | 70%    |
-| `any` types              | 102     | <20    |
-| Type assertions          | 2000+   | <500   |
-| Sync time (100 personas) | ~30s    | ~5s    |
-| server.ts lines          | 5,914   | <1,000 |
-| Critical issues          | 8       | 0      |
-
----
-
-_Generated: January 23, 2026_