zyflow 0.6.4

package/src/types/errors.ts

@@ -0,0 +1,253 @@
+/**
+ * Global Error Handling - Type Definitions
+ * Comprehensive error types and interfaces for the error handling system
+ * @module types/errors
+ */
+
+// =============================================
+// Error Type Enums
+// =============================================
+
+/** Error types that can occur in the system */
+export enum ErrorType {
+  NETWORK = 'NETWORK',
+  COMPONENT = 'COMPONENT',
+  VALIDATION = 'VALIDATION',
+  STATE = 'STATE',
+  TASK = 'TASK',
+  SSE = 'SSE',
+}
+
+// =============================================
+// Error Severity Levels
+// =============================================
+
+/** Error severity levels */
+export enum ErrorSeverity {
+  INFO = 'info',
+  WARNING = 'warning',
+  ERROR = 'error',
+  CRITICAL = 'critical',
+}
+
+// =============================================
+// Error Codes (23 total)
+// =============================================
+
+/** Network error codes (1000-1002) */
+export enum NetworkErrorCode {
+  CONNECTION_FAILED = 'ERR_NETWORK_1000',
+  REQUEST_TIMEOUT = 'ERR_NETWORK_1001',
+  INVALID_RESPONSE = 'ERR_NETWORK_1002',
+}
+
+/** Component error codes (2000-2001) */
+export enum ComponentErrorCode {
+  RENDER_ERROR = 'ERR_COMPONENT_2000',
+  HOOK_ERROR = 'ERR_COMPONENT_2001',
+}
+
+/** Validation error codes (3000-3001) */
+export enum ValidationErrorCode {
+  INPUT_VALIDATION_FAILED = 'ERR_VALIDATION_3000',
+  SCHEMA_VALIDATION_FAILED = 'ERR_VALIDATION_3001',
+}
+
+/** State error codes (4000-4001) */
+export enum StateErrorCode {
+  STATE_MUTATION_FAILED = 'ERR_STATE_4000',
+  CONTEXT_VALUE_MISSING = 'ERR_STATE_4001',
+}
+
+/** Task error codes (5000-5002) */
+export enum TaskErrorCode {
+  TASK_EXECUTION_FAILED = 'ERR_TASK_5000',
+  SPEC_PARSING_FAILED = 'ERR_TASK_5001',
+  TASK_TIMEOUT = 'ERR_TASK_5002',
+}
+
+/** SSE error codes (6000-6002) */
+export enum SSEErrorCode {
+  CONNECTION_LOST = 'ERR_SSE_6000',
+  EVENT_PARSING_FAILED = 'ERR_SSE_6001',
+  EVENT_HANDLER_ERROR = 'ERR_SSE_6002',
+}
+
+/** Union of all error codes */
+export type ErrorCode =
+  | NetworkErrorCode
+  | ComponentErrorCode
+  | ValidationErrorCode
+  | StateErrorCode
+  | TaskErrorCode
+  | SSEErrorCode
+
+// =============================================
+// Error Context Interface
+// =============================================
+
+/** Context information for an error */
+export interface ErrorContext {
+  // Error identification
+  code: ErrorCode
+  message: string
+  severity: ErrorSeverity
+  type: ErrorType
+
+  // Timestamps
+  timestamp: number
+
+  // Location information
+  component?: string
+  function?: string
+  line?: number
+  column?: number
+
+  // Error details
+  originalError?: Error
+  stack?: string
+
+  // Context data
+  userAction?: string
+  applicationState?: Record<string, unknown>
+  requestData?: Record<string, unknown>
+  responseData?: Record<string, unknown>
+
+  // Recovery information
+  recoverable: boolean
+  suggestedActions: string[]
+
+  // Metadata
+  isDevelopment: boolean
+  userId?: string
+  sessionId?: string
+
+  // Deduplication
+  count?: number
+  lastOccurrence?: number
+}
+
+// =============================================
+// Error Display Configurations
+// =============================================
+
+/** Configuration for error display */
+export interface ErrorDisplayConfig {
+  duration?: number
+  position?: 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right'
+  closable?: boolean
+  showDetails?: boolean
+}
+
+/** Error toast notification config */
+export interface ErrorToastConfig extends ErrorDisplayConfig {
+  action?: {
+    label: string
+    onClick: () => void | Promise<void>
+  }
+  dismissible?: boolean
+}
+
+/** Error dialog config */
+export interface ErrorDialogConfig extends ErrorDisplayConfig {
+  actions?: Array<{
+    label: string
+    onClick: () => void | Promise<void>
+    variant?: 'default' | 'destructive'
+  }>
+}
+
+// =============================================
+// Error Recovery Strategies
+// =============================================
+
+/** Recovery action types */
+export enum RecoveryActionType {
+  RETRY = 'retry',
+  SKIP = 'skip',
+  RESET = 'reset',
+  NAVIGATE = 'navigate',
+  IGNORE = 'ignore',
+  REPORT = 'report',
+}
+
+/** Recovery action */
+export interface RecoveryAction {
+  type: RecoveryActionType
+  label: string
+  description?: string
+  onClick?: () => void | Promise<void>
+}
+
+// =============================================
+// HTTP Status to Error Mapping
+// =============================================
+
+/** Mapping of HTTP status codes to error types and codes */
+export const HTTP_STATUS_TO_ERROR_CODE: Record<number, { type: ErrorType; code: ErrorCode; severity: ErrorSeverity }> = {
+  // 4xx - Validation errors (except 429)
+  400: { type: ErrorType.VALIDATION, code: ValidationErrorCode.INPUT_VALIDATION_FAILED, severity: ErrorSeverity.ERROR },
+  401: { type: ErrorType.VALIDATION, code: ValidationErrorCode.INPUT_VALIDATION_FAILED, severity: ErrorSeverity.WARNING },
+  403: { type: ErrorType.VALIDATION, code: ValidationErrorCode.INPUT_VALIDATION_FAILED, severity: ErrorSeverity.WARNING },
+  404: { type: ErrorType.VALIDATION, code: ValidationErrorCode.INPUT_VALIDATION_FAILED, severity: ErrorSeverity.WARNING },
+  422: { type: ErrorType.VALIDATION, code: ValidationErrorCode.SCHEMA_VALIDATION_FAILED, severity: ErrorSeverity.ERROR },
+  429: { type: ErrorType.NETWORK, code: NetworkErrorCode.REQUEST_TIMEOUT, severity: ErrorSeverity.WARNING },
+
+  // 5xx - Network errors
+  500: { type: ErrorType.NETWORK, code: NetworkErrorCode.INVALID_RESPONSE, severity: ErrorSeverity.CRITICAL },
+  502: { type: ErrorType.NETWORK, code: NetworkErrorCode.INVALID_RESPONSE, severity: ErrorSeverity.CRITICAL },
+  503: { type: ErrorType.NETWORK, code: NetworkErrorCode.INVALID_RESPONSE, severity: ErrorSeverity.CRITICAL },
+  504: { type: ErrorType.NETWORK, code: NetworkErrorCode.REQUEST_TIMEOUT, severity: ErrorSeverity.CRITICAL },
+}
+
+// =============================================
+// Error Response Format
+// =============================================
+
+/** Standardized error response from API */
+export interface ErrorResponse {
+  success: false
+  error: {
+    code: ErrorCode
+    message: string
+    details?: Record<string, unknown>
+    timestamp: number
+  }
+}
+
+// =============================================
+// Type Guards
+// =============================================
+
+export function isErrorCode(value: unknown): value is ErrorCode {
+  if (typeof value !== 'string') return false
+  const allCodes = [
+    ...Object.values(NetworkErrorCode),
+    ...Object.values(ComponentErrorCode),
+    ...Object.values(ValidationErrorCode),
+    ...Object.values(StateErrorCode),
+    ...Object.values(TaskErrorCode),
+    ...Object.values(SSEErrorCode),
+  ]
+  return allCodes.includes(value as ErrorCode)
+}
+
+export function isErrorType(value: unknown): value is ErrorType {
+  return Object.values(ErrorType).includes(value as ErrorType)
+}
+
+export function isErrorSeverity(value: unknown): value is ErrorSeverity {
+  return Object.values(ErrorSeverity).includes(value as ErrorSeverity)
+}
+
+export function isErrorContext(value: unknown): value is ErrorContext {
+  if (typeof value !== 'object' || value === null) return false
+  const context = value as Record<string, unknown>
+  return (
+    typeof context.code === 'string' &&
+    typeof context.message === 'string' &&
+    typeof context.severity === 'string' &&
+    typeof context.timestamp === 'number' &&
+    typeof context.recoverable === 'boolean'
+  )
+}

package/src/types/flow.ts

@@ -0,0 +1,382 @@
+/**
+ * Flow API Types with MoAI SPEC Support
+ *
+ * Discriminated union types for handling both OpenSpec and MoAI SPEC formats
+ */
+
+// =============================================
+// Stage Types
+// =============================================
+export type Stage = 'spec' | 'changes' | 'task' | 'code' | 'test' | 'commit' | 'docs'
+export type ChangeStatus = 'active' | 'completed' | 'archived'
+export type FlowTaskStatus = 'todo' | 'in-progress' | 'review' | 'done' | 'archived'
+
+// =============================================
+// OpenSpec Change Type (File-based, for backward compatibility)
+// =============================================
+export interface OpenSpecChange {
+  type: 'openspec'
+  id: string
+  title: string
+  description?: string
+  progress: number // 0-100
+  totalTasks: number
+  completedTasks: number
+  updatedAt?: string // ISO 8601 date string
+}
+
+// =============================================
+// MoAI SPEC Type (MoAI Framework)
+// =============================================
+export interface MoaiSpecRequirement {
+  id: string
+  title: string
+  description: string
+  type: 'functional' | 'non-functional' | 'constraint'
+  priority: 'critical' | 'high' | 'medium' | 'low'
+}
+
+export interface MoaiSpecAcceptanceCriteria {
+  id: string
+  description: string
+  priority: 'critical' | 'high' | 'medium' | 'low'
+}
+
+export interface MoaiSpecProgress {
+  completed: number
+  total: number
+  percentage: number
+}
+
+export interface MoaiSpec {
+  type: 'spec'
+  id: string
+  specId?: string // SPEC-XXX format
+  title: string
+  status: ChangeStatus
+  progress: MoaiSpecProgress
+  spec: {
+    content: string
+    requirements: MoaiSpecRequirement[]
+  }
+  plan: {
+    content: string
+    tags: Array<{
+      id: string
+      name: string
+      color?: string
+    }>
+    progress: MoaiSpecProgress
+  }
+  acceptance: {
+    content: string
+    criteria: MoaiSpecAcceptanceCriteria[]
+  }
+  createdAt: string
+  updatedAt: string
+  archivedAt?: string
+}
+
+// =============================================
+// Discriminated Union Type
+// =============================================
+/**
+ * FlowItem represents either an OpenSpec change or a MoAI SPEC
+ * Use the `type` discriminator to distinguish between them
+ *
+ * @example
+ * ```tsx
+ * const items: FlowItem[] = await fetchFlowItems()
+ * items.forEach(item => {
+ *   if (item.type === 'spec') {
+ *     // Handle MoAI SPEC
+ *     console.log(item.spec.requirements)
+ *   } else if (item.type === 'openspec') {
+ *     // Handle OpenSpec change
+ *     console.log(item.description)
+ *   }
+ * })
+ * ```
+ */
+export type FlowItem = OpenSpecChange | MoaiSpec
+
+// =============================================
+// Type Guards for Discriminated Union
+// =============================================
+/**
+ * Type guard to check if a FlowItem is an OpenSpec change
+ */
+export function isOpenSpecChange(item: FlowItem): item is OpenSpecChange {
+  return item.type === 'openspec'
+}
+
+/**
+ * Type guard to check if a FlowItem is a MoAI SPEC
+ */
+export function isMoaiSpec(item: FlowItem): item is MoaiSpec {
+  return item.type === 'spec'
+}
+
+// =============================================
+// Stage Info (for database queries)
+// =============================================
+export interface StageInfo {
+  stage?: Stage
+  total: number
+  completed: number
+  tasks: FlowTask[]
+}
+
+// =============================================
+// Flow Change (Database-based)
+// =============================================
+export interface FlowChange {
+  id: string
+  projectId: string
+  title: string
+  specPath?: string
+  status: ChangeStatus
+  currentStage: Stage
+  progress: number // 0-100
+  createdAt: string
+  updatedAt: string
+  stages?: Record<Stage, StageInfo>
+  // UI 집계 데이터 (Change 상세 조회 시 포함)
+  completedTasks?: number
+  totalTasks?: number
+}
+
+// =============================================
+// Task Origin Type
+// =============================================
+export type TaskOrigin = 'openspec' | 'inbox' | 'imported' | 'backlog'
+
+// =============================================
+// Flow Task (Database-based)
+// =============================================
+export interface FlowTask {
+  id: number
+  changeId?: string
+  stage: Stage
+  origin?: TaskOrigin
+  title: string
+  description?: string
+  status: FlowTaskStatus
+  priority: 'low' | 'medium' | 'high'
+  tags?: string[]
+  assignee?: string
+  order: number
+  groupTitle?: string
+  groupOrder?: number
+  taskOrder?: number
+  majorTitle?: string
+  subOrder?: number
+  displayId?: string
+
+  // Backlog-specific fields
+  parentTaskId?: number
+  blockedBy?: string[]
+  plan?: string
+  acceptanceCriteria?: string
+  notes?: string
+  dueDate?: string
+  milestone?: string
+  backlogFileId?: string
+
+  createdAt: string
+  updatedAt: string
+  archivedAt?: string
+}
+
+// =============================================
+// Legacy Types (for backward compatibility)
+// =============================================
+
+// Legacy Change type (same as OpenSpecChange)
+export interface Change extends OpenSpecChange {
+  type: 'openspec'
+}
+
+// Task item from tasks.md
+export interface Task {
+  id: string
+  title: string
+  completed: boolean
+  groupId: string
+  lineNumber: number
+  indent?: number
+  displayId?: string
+}
+
+// Task group (section in tasks.md)
+export interface TaskGroup {
+  id: string
+  title: string
+  tasks: Task[]
+  majorOrder?: number
+  displayId?: string
+}
+
+// Parsed tasks.md structure
+export interface TasksFile {
+  changeId: string
+  groups: TaskGroup[]
+}
+
+// =============================================
+// API Response Wrapper
+// =============================================
+export interface ApiResponse<T> {
+  success: boolean
+  data?: T
+  error?: string
+  code?: string
+  details?: unknown
+}
+
+// =============================================
+// Response Types
+// =============================================
+
+export interface ChangesResponse {
+  changes: Change[]
+}
+
+export interface TasksResponse {
+  changeId: string
+  groups: TaskGroup[]
+}
+
+export interface ToggleTaskResponse {
+  task: Task
+}
+
+export interface DetailPlan {
+  taskId: string
+  changeId: string
+  content: string
+  exists: boolean
+}
+
+export interface Spec {
+  id: string
+  title: string
+  requirementsCount: number
+}
+
+export interface SpecsResponse {
+  specs: Spec[]
+}
+
+export interface SpecContentResponse {
+  id: string
+  content: string
+}
+
+// =============================================
+// Flow API Response Types
+// =============================================
+export interface FlowChangesResponse {
+  changes: FlowChange[]
+}
+
+export interface FlowChangeDetailResponse {
+  change: FlowChange
+  stages: Record<Stage, StageInfo>
+}
+
+export interface FlowTasksResponse {
+  tasks: FlowTask[]
+}
+
+export interface FlowSyncResponse {
+  synced: number
+  created: number
+  updated: number
+}
+
+// =============================================
+// Change Counts Response
+// =============================================
+export interface ProjectChangeCounts {
+  active: number
+  completed: number
+  total: number
+}
+
+export interface FlowChangeCountsResponse {
+  counts: Record<string, number>
+  detailed: Record<string, ProjectChangeCounts>
+}
+
+// =============================================
+// Extended Types
+// =============================================
+
+export interface ExtendedTaskGroup extends TaskGroup {
+  majorOrder?: number
+  majorTitle?: string
+  subOrder?: number
+  groupTitle?: string
+  groupOrder?: number
+}
+
+export interface ExtendedTasksFile extends TasksFile {
+  groups: ExtendedTaskGroup[]
+}
+
+// =============================================
+// Settings & Integration Types
+// =============================================
+
+export type SettingsSource = 'local' | 'global' | 'hybrid'
+
+export interface LocalSettingsStatus {
+  hasLocal: boolean
+  hasGlobal: boolean
+  primary: SettingsSource
+}
+
+export interface LocalSettingsStatusResponse {
+  projectPath: string
+  status: LocalSettingsStatus
+}
+
+export interface InitLocalSettingsResponse {
+  success: boolean
+  zyflowPath: string
+  created: string[]
+}
+
+export interface ExportToLocalResponse {
+  success: boolean
+  zyflowPath: string
+  exported: string[]
+}
+
+// =============================================
+// Archived Changes
+// =============================================
+
+export interface ArchivedChange {
+  id: string
+  title: string
+  progress: number
+  totalTasks: number
+  completedTasks: number
+  archivedAt: string | null
+}
+
+export interface ArchivedChangesResponse {
+  changes: ArchivedChange[]
+}
+
+export interface ArchivedChangeDetail {
+  id: string
+  files: Record<string, string>
+}
+
+export interface ArchivedChangeDetailResponse {
+  id: string
+  files: Record<string, string>
+}