@jungjaehoon/mama-os 0.1.1

package/templates/workspace/skill-forge/error-handler.ts

@@ -0,0 +1,354 @@
+/**
+ * Skill Forge - Error Handler
+ *
+ * 통합 에러 처리 + 복구 전략
+ */
+
+import { SessionPhase, SessionState } from './types';
+
+// ===== Error Types =====
+
+export type SkillForgeErrorCode =
+  | 'ARCHITECT_FAILED'
+  | 'DEVELOPER_FAILED'
+  | 'QA_FAILED'
+  | 'API_ERROR'
+  | 'TIMEOUT'
+  | 'INVALID_INPUT'
+  | 'FILE_ERROR'
+  | 'STATE_ERROR'
+  | 'UNKNOWN';
+
+export interface SkillForgeError extends Error {
+  code: SkillForgeErrorCode;
+  phase?: SessionPhase;
+  retryable: boolean;
+  userMessage: string;
+  details?: Record<string, unknown>;
+}
+
+// ===== Error Factory =====
+
+export function createError(
+  code: SkillForgeErrorCode,
+  message: string,
+  options?: {
+    phase?: SessionPhase;
+    retryable?: boolean;
+    details?: Record<string, unknown>;
+  }
+): SkillForgeError {
+  const error = new Error(message) as SkillForgeError;
+  error.code = code;
+  error.phase = options?.phase;
+  error.retryable = options?.retryable ?? false;
+  error.details = options?.details;
+  error.userMessage = getUserMessage(code, message);
+  return error;
+}
+
+function getUserMessage(code: SkillForgeErrorCode, original: string): string {
+  const messages: Record<SkillForgeErrorCode, string> = {
+    ARCHITECT_FAILED: '🏗️ 설계 단계에서 오류가 발생했습니다. 다시 시도해 주세요.',
+    DEVELOPER_FAILED: '💻 코드 생성 중 오류가 발생했습니다. 설계를 단순화해 보세요.',
+    QA_FAILED: '🔍 검증 단계에서 오류가 발생했습니다.',
+    API_ERROR: '🔌 API 연결 오류입니다. 잠시 후 다시 시도해 주세요.',
+    TIMEOUT: '⏱️ 시간 초과되었습니다. 요청을 간소화해 보세요.',
+    INVALID_INPUT: '❓ 입력이 올바르지 않습니다. 형식을 확인해 주세요.',
+    FILE_ERROR: '📁 파일 처리 중 오류가 발생했습니다.',
+    STATE_ERROR: '⚠️ 세션 상태 오류입니다. 새로 시작해 주세요.',
+    UNKNOWN: '❌ 예기치 않은 오류가 발생했습니다.',
+  };
+  return messages[code];
+}
+
+// ===== Error Handler =====
+
+export interface ErrorHandlerConfig {
+  maxRetries: number;
+  retryDelayMs: number;
+  onError?: (error: SkillForgeError) => void;
+}
+
+const DEFAULT_ERROR_CONFIG: ErrorHandlerConfig = {
+  maxRetries: 3,
+  retryDelayMs: 1000,
+};
+
+export class ErrorHandler {
+  private config: ErrorHandlerConfig;
+  private retryCount: Map<string, number> = new Map();
+
+  constructor(config?: Partial<ErrorHandlerConfig>) {
+    this.config = { ...DEFAULT_ERROR_CONFIG, ...config };
+  }
+
+  /**
+   * Handle an error with optional retry logic
+   */
+  async handle<T>(
+    key: string,
+    operation: () => Promise<T>,
+    options?: { phase?: SessionPhase }
+  ): Promise<T> {
+    const retries = this.retryCount.get(key) || 0;
+
+    try {
+      const result = await operation();
+      this.retryCount.delete(key); // Success - reset retry count
+      return result;
+    } catch (err) {
+      const error = this.wrapError(err, options?.phase);
+
+      // Notify handler
+      this.config.onError?.(error);
+
+      // Check if we should retry
+      if (error.retryable && retries < this.config.maxRetries) {
+        this.retryCount.set(key, retries + 1);
+        console.log(`[ErrorHandler] Retry ${retries + 1}/${this.config.maxRetries}: ${key}`);
+
+        await this.delay(this.config.retryDelayMs * (retries + 1));
+        return this.handle(key, operation, options);
+      }
+
+      this.retryCount.delete(key);
+      throw error;
+    }
+  }
+
+  /**
+   * Wrap unknown errors into SkillForgeError
+   */
+  wrapError(err: unknown, phase?: SessionPhase): SkillForgeError {
+    // Already wrapped
+    if (isSkillForgeError(err)) {
+      return err;
+    }
+
+    const message = err instanceof Error ? err.message : String(err);
+
+    // Detect error type from message
+    const code = this.detectErrorCode(message);
+
+    return createError(code, message, {
+      phase,
+      retryable: this.isRetryable(code, message),
+      details: { original: err },
+    });
+  }
+
+  private detectErrorCode(message: string): SkillForgeErrorCode {
+    const lower = message.toLowerCase();
+
+    if (lower.includes('timeout') || lower.includes('timed out')) {
+      return 'TIMEOUT';
+    }
+    if (lower.includes('api') || lower.includes('fetch') || lower.includes('network')) {
+      return 'API_ERROR';
+    }
+    if (lower.includes('file') || lower.includes('enoent') || lower.includes('permission')) {
+      return 'FILE_ERROR';
+    }
+    if (lower.includes('json') || lower.includes('parse') || lower.includes('invalid')) {
+      return 'INVALID_INPUT';
+    }
+    if (lower.includes('architect')) {
+      return 'ARCHITECT_FAILED';
+    }
+    if (lower.includes('developer')) {
+      return 'DEVELOPER_FAILED';
+    }
+    if (lower.includes('qa')) {
+      return 'QA_FAILED';
+    }
+
+    return 'UNKNOWN';
+  }
+
+  private isRetryable(code: SkillForgeErrorCode, message: string): boolean {
+    // These are generally retryable
+    const retryableCodes: SkillForgeErrorCode[] = ['API_ERROR', 'TIMEOUT'];
+
+    if (retryableCodes.includes(code)) {
+      return true;
+    }
+
+    // Check for rate limiting
+    if (message.includes('rate limit') || message.includes('429')) {
+      return true;
+    }
+
+    return false;
+  }
+
+  private delay(ms: number): Promise<void> {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
+}
+
+function isSkillForgeError(err: unknown): err is SkillForgeError {
+  return err instanceof Error && 'code' in err && 'retryable' in err;
+}
+
+// ===== Recovery Strategies =====
+
+export interface RecoveryStrategy {
+  canRecover(error: SkillForgeError, state: SessionState): boolean;
+  recover(error: SkillForgeError, state: SessionState): SessionState;
+}
+
+/**
+ * Rollback to previous phase on error
+ */
+export const rollbackStrategy: RecoveryStrategy = {
+  canRecover(error, state) {
+    return ['ARCHITECT_FAILED', 'DEVELOPER_FAILED', 'QA_FAILED'].includes(error.code);
+  },
+
+  recover(error, state) {
+    const rollbackMap: Partial<Record<SessionPhase, SessionPhase>> = {
+      architect: 'idle',
+      architect_review: 'architect',
+      developer: 'architect_review',
+      developer_review: 'developer',
+      qa: 'developer_review',
+      qa_review: 'qa',
+    };
+
+    const newPhase = rollbackMap[state.phase] || 'idle';
+    console.log(`[Recovery] Rolling back from ${state.phase} to ${newPhase}`);
+
+    return {
+      ...state,
+      phase: newPhase,
+      updatedAt: new Date().toISOString(),
+    };
+  },
+};
+
+/**
+ * Skip to next phase on non-critical error
+ */
+export const skipStrategy: RecoveryStrategy = {
+  canRecover(error, state) {
+    // Only skip QA if it fails but we have developer output
+    return error.code === 'QA_FAILED' && !!state.artifacts.developerOutput;
+  },
+
+  recover(error, state) {
+    console.log(`[Recovery] Skipping QA, marking as completed with warning`);
+
+    return {
+      ...state,
+      phase: 'completed' as SessionPhase,
+      artifacts: {
+        ...state.artifacts,
+        qaOutput: {
+          passed: false,
+          checklist: [],
+          issues: [
+            {
+              severity: 'warning' as const,
+              description: 'QA 검증이 실패했지만 스킵됨',
+            },
+          ],
+          recommendation: 'revise' as const,
+        },
+      },
+      updatedAt: new Date().toISOString(),
+    };
+  },
+};
+
+// ===== Error Formatters =====
+
+export function formatErrorForDiscord(error: SkillForgeError): string {
+  const lines = [`## ❌ 오류 발생`, '', error.userMessage, ''];
+
+  if (error.retryable) {
+    lines.push('> 💡 이 오류는 자동으로 재시도됩니다.');
+  }
+
+  if (error.phase) {
+    lines.push(`📍 **단계:** ${error.phase}`);
+  }
+
+  lines.push(`🔖 **코드:** \`${error.code}\``);
+
+  return lines.join('\n');
+}
+
+export function formatErrorForLog(error: SkillForgeError): string {
+  return JSON.stringify({
+    code: error.code,
+    message: error.message,
+    phase: error.phase,
+    retryable: error.retryable,
+    timestamp: new Date().toISOString(),
+    details: error.details,
+  });
+}
+
+// ===== Test =====
+
+async function runTest() {
+  console.log('🛡️ Error Handler Test\n');
+
+  const handler = new ErrorHandler({
+    maxRetries: 2,
+    retryDelayMs: 100,
+    onError: (err) => console.log(`[Callback] ${err.code}: ${err.message}`),
+  });
+
+  // Test 1: Successful operation
+  console.log('=== Test 1: Success ===');
+  const result1 = await handler.handle('test1', async () => 'success');
+  console.log('Result:', result1);
+
+  // Test 2: Retryable failure
+  console.log('\n=== Test 2: Retryable Failure ===');
+  let attempts = 0;
+  try {
+    await handler.handle('test2', async () => {
+      attempts++;
+      if (attempts < 3) {
+        throw new Error('API rate limit exceeded');
+      }
+      return 'success after retries';
+    });
+  } catch (err) {
+    console.log('Final error:', (err as SkillForgeError).code);
+  }
+  console.log('Attempts:', attempts);
+
+  // Test 3: Non-retryable failure
+  console.log('\n=== Test 3: Non-retryable ===');
+  try {
+    await handler.handle('test3', async () => {
+      throw new Error('Invalid input format');
+    });
+  } catch (err) {
+    const sfError = err as SkillForgeError;
+    console.log('Error code:', sfError.code);
+    console.log('Retryable:', sfError.retryable);
+    console.log('User message:', sfError.userMessage);
+  }
+
+  // Test 4: Error wrapping
+  console.log('\n=== Test 4: Error Wrapping ===');
+  const wrapped = handler.wrapError(new Error('Architect JSON parse failed'), 'architect');
+  console.log('Wrapped:', wrapped.code, wrapped.phase);
+
+  // Test 5: Discord format
+  console.log('\n=== Test 5: Discord Format ===');
+  const discordMsg = formatErrorForDiscord(wrapped);
+  console.log(discordMsg);
+
+  console.log('\n✅ All error handler tests complete');
+}
+
+const isMainModule = import.meta.url === `file://${process.argv[1]}`;
+if (isMainModule) {
+  runTest();
+}

package/templates/workspace/skill-forge/mama-integration.ts

@@ -0,0 +1,357 @@
+/**
+ * Skill Forge - MAMA Integration
+ *
+ * MAMA MCP 서버와 연동하여 decision/checkpoint 관리
+ */
+
+import { SessionState, ArchitectOutput, QAOutput } from './types';
+
+// ===== MAMA Decision Types =====
+
+export interface MAMADecision {
+  type: 'decision';
+  topic: string;
+  decision: string;
+  reasoning: string;
+  confidence: number;
+}
+
+export interface MAMACheckpoint {
+  type: 'checkpoint';
+  summary: string;
+  next_steps: string;
+  open_files: string[];
+}
+
+// ===== Decision Builders =====
+
+export function buildSkillDecision(state: SessionState): MAMADecision {
+  const arch = state.artifacts.architectOutput;
+  const qa = state.artifacts.qaOutput;
+
+  if (!arch) {
+    throw new Error('No architect output available');
+  }
+
+  const decision = `skill_${arch.skillName}`;
+  const qaStatus = qa ? (qa.passed ? 'QA passed' : 'QA failed') : 'QA pending';
+
+  return {
+    type: 'decision',
+    topic: `skill_forge_${arch.skillName}`,
+    decision: `Created skill '${arch.skillName}' - ${arch.purpose}`,
+    reasoning: buildDecisionReasoning(arch, qa),
+    confidence: calculateConfidence(state),
+  };
+}
+
+function buildDecisionReasoning(arch: ArchitectOutput, qa?: QAOutput): string {
+  const sections: string[] = [];
+
+  // 1. Context
+  sections.push(`(1) Context - Skill Forge를 통해 '${arch.skillName}' 스킬 생성 요청됨`);
+
+  // 2. Evidence
+  const evidence = [
+    `워크플로우 ${arch.workflow.length}단계 설계`,
+    `파일 ${arch.fileStructure.length}개 구조화`,
+    `복잡도: ${arch.estimatedComplexity}`,
+  ];
+  if (qa) {
+    evidence.push(
+      `QA 체크리스트: ${qa.checklist.filter((c) => c.passed).length}/${qa.checklist.length} 통과`
+    );
+  }
+  sections.push(`(2) Evidence - ${evidence.join(', ')}`);
+
+  // 3. Alternatives
+  sections.push(`(3) Alternatives - 수동 작성 대비 자동화된 구조 설계 채택`);
+
+  // 4. Risks
+  const risks = qa?.issues.filter((i) => i.severity === 'critical').map((i) => i.description) || [];
+  sections.push(`(4) Risks - ${risks.length ? risks.join(', ') : '주요 리스크 없음'}`);
+
+  // 5. Rationale
+  sections.push(`(5) Rationale - Architect→Developer→QA 파이프라인으로 일관된 품질 보장`);
+
+  return sections.join('; ');
+}
+
+function calculateConfidence(state: SessionState): number {
+  const qa = state.artifacts.qaOutput;
+
+  if (!qa) return 0.5;
+
+  if (qa.passed && qa.recommendation === 'approve') {
+    return 0.9;
+  } else if (qa.passed) {
+    return 0.7;
+  } else if (qa.recommendation === 'revise') {
+    return 0.5;
+  } else {
+    return 0.3;
+  }
+}
+
+// ===== Checkpoint Builders =====
+
+export function buildSessionCheckpoint(state: SessionState): MAMACheckpoint {
+  const { phase, artifacts, request } = state;
+
+  // Summary with 4-section format
+  const summary = buildCheckpointSummary(state);
+
+  // Next steps
+  const nextSteps = buildNextSteps(state);
+
+  // Open files
+  const openFiles = buildOpenFiles(state);
+
+  return {
+    type: 'checkpoint',
+    summary,
+    next_steps: nextSteps,
+    open_files: openFiles,
+  };
+}
+
+function buildCheckpointSummary(state: SessionState): string {
+  const { phase, artifacts, request } = state;
+  const sections: string[] = [];
+
+  // 1. Goal & Progress
+  sections.push(`🎯 Goal & Progress - '${request.name}' 스킬 생성, 현재 ${phase} 단계`);
+
+  // 2. Evidence
+  const evidence: string[] = [];
+  if (artifacts.architectOutput) {
+    evidence.push(`Architect: Verified (${artifacts.architectOutput.workflow.length}단계 설계)`);
+  }
+  if (artifacts.developerOutput) {
+    evidence.push(`Developer: Verified (${artifacts.developerOutput.files.length}개 파일)`);
+  }
+  if (artifacts.qaOutput) {
+    evidence.push(`QA: ${artifacts.qaOutput.passed ? 'Passed' : 'Failed'}`);
+  }
+  sections.push(`✅ Evidence - ${evidence.join(', ') || 'Not run'}`);
+
+  // 3. Unfinished & Risks
+  const unfinished: string[] = [];
+  if (phase === 'architect' || phase === 'architect_review') {
+    unfinished.push('Developer 작업 대기');
+    unfinished.push('QA 검증 대기');
+  } else if (phase === 'developer' || phase === 'developer_review') {
+    unfinished.push('QA 검증 대기');
+  }
+  sections.push(`⏳ Unfinished & Risks - ${unfinished.join(', ') || '없음'}`);
+
+  // 4. Related decisions
+  sections.push(`Related decisions: skill_forge_${request.name}`);
+
+  return sections.join('; ');
+}
+
+function buildNextSteps(state: SessionState): string {
+  const { phase, request } = state;
+  const steps: string[] = [];
+
+  // DoD
+  steps.push(`DoD: '${request.name}' 스킬이 QA 통과 후 output 폴더에 저장`);
+
+  // Quick verification
+  steps.push(`Verification: cd ~/.mama/workspace/skill-forge && npx tsx test-e2e.ts`);
+
+  // Phase-specific
+  switch (phase) {
+    case 'architect':
+    case 'architect_review':
+      steps.push('Next: Architect 출력 검토 후 Developer 진행');
+      break;
+    case 'developer':
+    case 'developer_review':
+      steps.push('Next: Developer 출력 검토 후 QA 진행');
+      break;
+    case 'qa':
+    case 'qa_review':
+      steps.push('Next: QA 결과 확인 후 최종 승인');
+      break;
+    case 'completed':
+      steps.push('Done: 생성된 파일을 MAMA에 등록');
+      break;
+  }
+
+  return steps.join('; ');
+}
+
+function buildOpenFiles(state: SessionState): string[] {
+  const files = [
+    '~/.mama/workspace/skill-forge/orchestrator.ts',
+    '~/.mama/workspace/skill-forge/types.ts',
+  ];
+
+  // Add generated files if any
+  const developerOutput = state.artifacts.developerOutput;
+  if (developerOutput) {
+    for (const file of developerOutput.files) {
+      files.push(`~/.mama/workspace/skill-forge/output/generated-skills/${file.path}`);
+    }
+  }
+
+  return files;
+}
+
+// ===== MCP Call Helpers =====
+
+/**
+ * Format decision for MAMA MCP save call
+ */
+export function formatDecisionForMCP(decision: MAMADecision): Record<string, unknown> {
+  return {
+    type: 'decision',
+    topic: decision.topic,
+    decision: decision.decision,
+    reasoning: decision.reasoning,
+    confidence: decision.confidence,
+  };
+}
+
+/**
+ * Format checkpoint for MAMA MCP save call
+ */
+export function formatCheckpointForMCP(checkpoint: MAMACheckpoint): Record<string, unknown> {
+  return {
+    type: 'checkpoint',
+    summary: checkpoint.summary,
+    next_steps: checkpoint.next_steps,
+    open_files: checkpoint.open_files,
+  };
+}
+
+// ===== Integration Events =====
+
+export type MAMAEvent =
+  | { type: 'DECISION_SAVED'; topic: string; id: string }
+  | { type: 'CHECKPOINT_SAVED'; id: string }
+  | { type: 'MAMA_ERROR'; error: string };
+
+export interface MAMAIntegration {
+  saveDecision(state: SessionState): Promise<MAMAEvent>;
+  saveCheckpoint(state: SessionState): Promise<MAMAEvent>;
+  searchRelated(topic: string): Promise<string[]>;
+}
+
+/**
+ * Mock implementation for testing
+ * Real implementation would use MCP client
+ */
+export function createMockMAMAIntegration(): MAMAIntegration {
+  let decisionCount = 0;
+  let checkpointCount = 0;
+
+  return {
+    async saveDecision(state: SessionState): Promise<MAMAEvent> {
+      const decision = buildSkillDecision(state);
+      decisionCount++;
+      console.log(`[MAMA] Saved decision: ${decision.topic}`);
+      console.log(`[MAMA] Reasoning: ${decision.reasoning}`);
+      return {
+        type: 'DECISION_SAVED',
+        topic: decision.topic,
+        id: `decision_${decisionCount}`,
+      };
+    },
+
+    async saveCheckpoint(state: SessionState): Promise<MAMAEvent> {
+      const checkpoint = buildSessionCheckpoint(state);
+      checkpointCount++;
+      console.log(`[MAMA] Saved checkpoint`);
+      console.log(`[MAMA] Summary: ${checkpoint.summary}`);
+      return {
+        type: 'CHECKPOINT_SAVED',
+        id: `checkpoint_${checkpointCount}`,
+      };
+    },
+
+    async searchRelated(topic: string): Promise<string[]> {
+      console.log(`[MAMA] Searching for: ${topic}`);
+      return []; // Mock returns empty
+    },
+  };
+}
+
+// ===== Test =====
+
+async function runTest() {
+  console.log('🔗 MAMA Integration Test\n');
+
+  // Mock session state
+  const mockState: SessionState = {
+    id: 'test-123',
+    phase: 'completed',
+    request: {
+      name: 'hello-world',
+      description: '간단한 인사 스킬',
+      triggers: ['/hello'],
+      capabilities: ['인사하기'],
+      rawInput: '/forge hello-world',
+    },
+    artifacts: {
+      architectOutput: {
+        skillName: 'hello-world',
+        purpose: '유저에게 인사하는 간단한 스킬',
+        triggers: ['/hello', '안녕'],
+        workflow: [
+          { step: 1, action: 'parse', description: '입력 파싱' },
+          { step: 2, action: 'respond', description: '인사 응답' },
+        ],
+        fileStructure: [
+          { path: 'skills/hello-world/index.ts', purpose: '메인 로직' },
+          { path: 'skills/hello-world/types.ts', purpose: '타입 정의' },
+        ],
+        toolsRequired: ['Read'],
+        estimatedComplexity: 'simple',
+      },
+      developerOutput: {
+        files: [
+          { path: 'skills/hello-world/index.ts', content: '...', language: 'typescript' },
+          { path: 'skills/hello-world/types.ts', content: '...', language: 'typescript' },
+        ],
+        installInstructions: ['npm install'],
+        testCommands: ['npm test'],
+      },
+      qaOutput: {
+        passed: true,
+        checklist: [
+          { item: '타입 정의 완료', passed: true },
+          { item: '메인 함수 존재', passed: true },
+        ],
+        issues: [],
+        recommendation: 'approve',
+      },
+    },
+    countdown: null,
+    createdAt: new Date().toISOString(),
+    updatedAt: new Date().toISOString(),
+  };
+
+  const mama = createMockMAMAIntegration();
+
+  console.log('=== Decision ===\n');
+  const decision = buildSkillDecision(mockState);
+  console.log(JSON.stringify(decision, null, 2));
+
+  console.log('\n=== Checkpoint ===\n');
+  const checkpoint = buildSessionCheckpoint(mockState);
+  console.log(JSON.stringify(checkpoint, null, 2));
+
+  console.log('\n=== Save via Integration ===\n');
+  await mama.saveDecision(mockState);
+  await mama.saveCheckpoint(mockState);
+
+  console.log('\n✅ Test complete');
+}
+
+const isMainModule = import.meta.url === `file://${process.argv[1]}`;
+if (isMainModule) {
+  runTest();
+}