@sylphx/flow 1.0.1 → 1.0.3

package/src/types/api/errors.ts

@@ -0,0 +1,118 @@
+import { z } from 'zod';
+
+// ============================================================================
+// API ERROR INTERFACES
+// ============================================================================
+
+/**
+ * API error information
+ */
+export interface ApiError {
+  /** Error code */
+  code: string;
+  /** Error message */
+  message: string;
+  /** HTTP status code */
+  statusCode?: number;
+  /** Error type for categorization */
+  type:
+    | 'validation'
+    | 'authentication'
+    | 'authorization'
+    | 'not_found'
+    | 'conflict'
+    | 'rate_limit'
+    | 'server_error'
+    | 'network'
+    | 'timeout';
+  /** Detailed error description */
+  description?: string;
+  /** Field-specific errors (for validation errors) */
+  fieldErrors?: Record<string, string[]>;
+  /** Stack trace (development only) */
+  stack?: string;
+  /** Error context information */
+  context?: Record<string, unknown>;
+  /** Suggestions for resolution */
+  suggestions?: string[];
+}
+
+/**
+ * Enhanced error with additional context
+ */
+export interface EnhancedError extends Error {
+  /** Error code */
+  code: string;
+  /** HTTP status code */
+  statusCode?: number;
+  /** Error type */
+  type: ApiError['type'];
+  /** Error context */
+  context?: ErrorContext;
+  /** Suggestions for resolution */
+  suggestions?: string[];
+  /** Original error that caused this error */
+  originalError?: Error;
+  /** Timestamp when error occurred */
+  timestamp: string;
+  /** Request ID for tracing */
+  requestId?: string;
+}
+
+/**
+ * Error context information
+ */
+export interface ErrorContext {
+  /** User ID if available */
+  userId?: string;
+  /** Session ID if available */
+  sessionId?: string;
+  /** IP address if available */
+  ipAddress?: string;
+  /** User agent if available */
+  userAgent?: string;
+  /** Request path */
+  path?: string;
+  /** HTTP method */
+  method?: string;
+  /** Additional context data */
+  data?: Record<string, unknown>;
+}
+
+// ============================================================================
+// ZOD SCHEMAS
+// ============================================================================
+
+export const ErrorContextSchema = z.object({
+  userId: z.string().optional(),
+  sessionId: z.string().optional(),
+  ipAddress: z.string().optional(),
+  userAgent: z.string().optional(),
+  path: z.string().optional(),
+  method: z.enum(['GET', 'POST', 'PUT', 'DELETE', 'PATCH', 'HEAD', 'OPTIONS']).optional(),
+  data: z.record(z.unknown()).optional(),
+});
+
+export const EnhancedErrorSchema = z.object({
+  name: z.string(),
+  message: z.string(),
+  code: z.string(),
+  statusCode: z.number().optional(),
+  type: z.enum([
+    'validation',
+    'authentication',
+    'authorization',
+    'not_found',
+    'conflict',
+    'rate_limit',
+    'server_error',
+    'network',
+    'timeout',
+  ]),
+  context: ErrorContextSchema.optional(),
+  suggestions: z.array(z.string()).optional(),
+  originalError: z.instanceof(Error).optional(),
+  timestamp: z.string(),
+  requestId: z.string().optional(),
+  stack: z.string().optional(),
+});

package/src/types/api/index.ts

@@ -0,0 +1,55 @@
+/**
+ * API types barrel export
+ * Organized API-related types and interfaces
+ */
+
+// Batch operation types
+export type {
+  BatchApiResult,
+  BatchOperationResult,
+} from './batch.js';
+export {
+  BatchApiResultSchema,
+  BatchOperationResultSchema,
+} from './batch.js';
+
+// Error types
+export type {
+  ApiError,
+  EnhancedError,
+  ErrorContext,
+} from './errors.js';
+
+export {
+  EnhancedErrorSchema,
+  ErrorContextSchema,
+} from './errors.js';
+
+// Request types
+export type { HttpRequestConfig } from './requests.js';
+
+export { HttpRequestConfigSchema } from './requests.js';
+// Response types
+export type {
+  ApiResponse,
+  HttpResponse,
+  PaginationInfo,
+  RateLimitInfo,
+} from './responses.js';
+export {
+  ApiResponseSchema,
+  HttpResponseSchema,
+  PaginationInfoSchema,
+  RateLimitInfoSchema,
+} from './responses.js';
+
+// WebSocket types
+export type {
+  WebSocketConnectionStatus,
+  WebSocketMessage,
+} from './websockets.js';
+
+export {
+  WebSocketConnectionStatusSchema,
+  WebSocketMessageSchema,
+} from './websockets.js';

package/src/types/api/requests.ts

@@ -0,0 +1,76 @@
+import { z } from 'zod';
+
+// ============================================================================
+// API REQUEST INTERFACES
+// ============================================================================
+
+/**
+ * HTTP request configuration
+ */
+export interface HttpRequestConfig {
+  /** Request URL */
+  url: string;
+  /** HTTP method */
+  method: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' | 'HEAD' | 'OPTIONS';
+  /** Request headers */
+  headers?: Record<string, string>;
+  /** Request body */
+  body?: unknown;
+  /** Query parameters */
+  params?: Record<string, string | number | boolean>;
+  /** Request timeout in milliseconds */
+  timeout?: number;
+  /** Number of retry attempts */
+  retries?: number;
+  /** Retry delay in milliseconds */
+  retryDelay?: number;
+  /** Whether to validate SSL certificates */
+  validateSSL?: boolean;
+  /** Request ID for tracing */
+  requestId?: string;
+  /** User agent */
+  userAgent?: string;
+  /** Authentication token */
+  token?: string;
+  /** API key */
+  apiKey?: string;
+  /** Request metadata */
+  metadata?: {
+    /** Source of the request */
+    source?: string;
+    /** Request priority */
+    priority?: 'low' | 'normal' | 'high';
+    /** Request tags */
+    tags?: string[];
+    /** Custom metadata */
+    data?: Record<string, unknown>;
+  };
+}
+
+// ============================================================================
+// ZOD SCHEMAS
+// ============================================================================
+
+export const HttpRequestConfigSchema = z.object({
+  url: z.string().url(),
+  method: z.enum(['GET', 'POST', 'PUT', 'DELETE', 'PATCH', 'HEAD', 'OPTIONS']),
+  headers: z.record(z.string()).optional(),
+  body: z.unknown().optional(),
+  params: z.record(z.union([z.string(), z.number(), z.boolean()])).optional(),
+  timeout: z.number().positive().optional(),
+  retries: z.number().min(0).optional(),
+  retryDelay: z.number().min(0).optional(),
+  validateSSL: z.boolean().optional(),
+  requestId: z.string().optional(),
+  userAgent: z.string().optional(),
+  token: z.string().optional(),
+  apiKey: z.string().optional(),
+  metadata: z
+    .object({
+      source: z.string().optional(),
+      priority: z.enum(['low', 'normal', 'high']).optional(),
+      tags: z.array(z.string()).optional(),
+      data: z.record(z.unknown()).optional(),
+    })
+    .optional(),
+});

package/src/types/api/responses.ts

@@ -0,0 +1,180 @@
+import { z } from 'zod';
+
+// ============================================================================
+// API RESPONSE INTERFACES
+// ============================================================================
+
+/**
+ * Standard API response wrapper
+ */
+export interface ApiResponse<T = unknown> {
+  /** Response success status */
+  success: boolean;
+  /** Response data */
+  data?: T;
+  /** Response message */
+  message?: string;
+  /** Response metadata */
+  metadata?: {
+    /** Response timestamp */
+    timestamp: string;
+    /** Request ID for tracing */
+    requestId?: string;
+    /** API version */
+    version?: string;
+    /** Response time in milliseconds */
+    responseTime?: number;
+    /** Pagination information */
+    pagination?: PaginationInfo;
+    /** Rate limiting information */
+    rateLimit?: RateLimitInfo;
+  };
+  /** Error information */
+  error?: ApiError;
+}
+
+/**
+ * HTTP response wrapper
+ */
+export interface HttpResponse<T = unknown> {
+  /** Response data */
+  data: T;
+  /** HTTP status code */
+  status: number;
+  /** HTTP status text */
+  statusText: string;
+  /** Response headers */
+  headers: Record<string, string>;
+  /** Response metadata */
+  metadata?: {
+    /** Response timestamp */
+    timestamp: string;
+    /** Request ID for tracing */
+    requestId?: string;
+    /** Response time in milliseconds */
+    responseTime?: number;
+    /** Response size in bytes */
+    size?: number;
+    /** Cached response indicator */
+    fromCache?: boolean;
+  };
+}
+
+/**
+ * Pagination information
+ */
+export interface PaginationInfo {
+  /** Current page number */
+  page: number;
+  /** Items per page */
+  limit: number;
+  /** Total number of items */
+  total: number;
+  /** Total number of pages */
+  totalPages: number;
+  /** Whether there's a next page */
+  hasNext: boolean;
+  /** Whether there's a previous page */
+  hasPrev: boolean;
+  /** Next page cursor (for cursor-based pagination) */
+  nextCursor?: string;
+  /** Previous page cursor (for cursor-based pagination) */
+  prevCursor?: string;
+}
+
+/**
+ * Rate limiting information
+ */
+export interface RateLimitInfo {
+  /** Maximum requests allowed */
+  limit: number;
+  /** Remaining requests */
+  remaining: number;
+  /** Reset timestamp (Unix timestamp) */
+  resetAt: number;
+  /** Reset time in ISO format */
+  resetTime?: string;
+  /** Retry after seconds */
+  retryAfter?: number;
+  /** Request window in seconds */
+  window?: number;
+}
+
+// ============================================================================
+// ZOD SCHEMAS
+// ============================================================================
+
+export const PaginationInfoSchema = z.object({
+  page: z.number().min(1),
+  limit: z.number().min(1).max(100),
+  total: z.number().min(0),
+  totalPages: z.number().min(0),
+  hasNext: z.boolean(),
+  hasPrev: z.boolean(),
+  nextCursor: z.string().optional(),
+  prevCursor: z.string().optional(),
+});
+
+export const RateLimitInfoSchema = z.object({
+  limit: z.number().min(1),
+  remaining: z.number().min(0),
+  resetAt: z.number().min(0),
+  resetTime: z.string().optional(),
+  retryAfter: z.number().optional(),
+  window: z.number().optional(),
+});
+
+export const ApiErrorSchema = z.object({
+  code: z.string(),
+  message: z.string(),
+  statusCode: z.number().optional(),
+  type: z.enum([
+    'validation',
+    'authentication',
+    'authorization',
+    'not_found',
+    'conflict',
+    'rate_limit',
+    'server_error',
+    'network',
+    'timeout',
+  ]),
+  description: z.string().optional(),
+  fieldErrors: z.record(z.array(z.string())).optional(),
+  stack: z.string().optional(),
+  context: z.record(z.unknown()).optional(),
+  suggestions: z.array(z.string()).optional(),
+});
+
+export const ApiResponseSchema = z.object({
+  success: z.boolean(),
+  data: z.unknown().optional(),
+  message: z.string().optional(),
+  metadata: z
+    .object({
+      timestamp: z.string(),
+      requestId: z.string().optional(),
+      version: z.string().optional(),
+      responseTime: z.number().optional(),
+      pagination: PaginationInfoSchema.optional(),
+      rateLimit: RateLimitInfoSchema.optional(),
+    })
+    .optional(),
+  error: ApiErrorSchema.optional(),
+});
+
+export const HttpResponseSchema = z.object({
+  data: z.unknown(),
+  status: z.number(),
+  statusText: z.string(),
+  headers: z.record(z.string()),
+  metadata: z
+    .object({
+      timestamp: z.string(),
+      requestId: z.string().optional(),
+      responseTime: z.number().optional(),
+      size: z.number().optional(),
+      fromCache: z.boolean().optional(),
+    })
+    .optional(),
+});

package/src/types/api/websockets.ts

@@ -0,0 +1,85 @@
+import { z } from 'zod';
+
+// ============================================================================
+// WEBSOCKET INTERFACES
+// ============================================================================
+
+/**
+ * WebSocket message structure
+ */
+export interface WebSocketMessage<T = unknown> {
+  /** Message type for routing */
+  type: string;
+  /** Message payload */
+  payload: T;
+  /** Message ID for correlation */
+  id?: string;
+  /** Timestamp when message was created */
+  timestamp: string;
+  /** Message metadata */
+  metadata?: {
+    /** Sender ID */
+    senderId?: string;
+    /** Recipient ID (for direct messages) */
+    recipientId?: string;
+    /** Room or channel ID */
+    room?: string;
+    /** Message version for compatibility */
+    version?: string;
+    /** Whether message requires acknowledgment */
+    requiresAck?: boolean;
+    /** Message priority */
+    priority?: 'low' | 'normal' | 'high';
+  };
+}
+
+/**
+ * WebSocket connection status
+ */
+export interface WebSocketConnectionStatus {
+  /** Connection state */
+  status: 'connecting' | 'connected' | 'disconnected' | 'error' | 'reconnecting';
+  /** Connection ID */
+  connectionId?: string;
+  /** URL of connected server */
+  url?: string;
+  /** Connection timestamp */
+  connectedAt?: string;
+  /** Last activity timestamp */
+  lastActivity?: string;
+  /** Number of reconnection attempts */
+  retryCount?: number;
+  /** Connection error (if any) */
+  error?: string;
+}
+
+// ============================================================================
+// ZOD SCHEMAS
+// ============================================================================
+
+export const WebSocketMessageSchema = z.object({
+  type: z.string(),
+  payload: z.unknown(),
+  id: z.string().optional(),
+  timestamp: z.string(),
+  metadata: z
+    .object({
+      senderId: z.string().optional(),
+      recipientId: z.string().optional(),
+      room: z.string().optional(),
+      version: z.string().optional(),
+      requiresAck: z.boolean().optional(),
+      priority: z.enum(['low', 'normal', 'high']).optional(),
+    })
+    .optional(),
+});
+
+export const WebSocketConnectionStatusSchema = z.object({
+  status: z.enum(['connecting', 'connected', 'disconnected', 'error', 'reconnecting']),
+  connectionId: z.string().optional(),
+  url: z.string().optional(),
+  connectedAt: z.string().optional(),
+  lastActivity: z.string().optional(),
+  retryCount: z.number().min(0).optional(),
+  error: z.string().optional(),
+});

package/src/types/api.types.ts

@@ -0,0 +1,9 @@
+/**
+ * Backward compatibility layer for API types
+ * Re-exports from the organized API types module
+ *
+ * @deprecated Import from './types/api' instead
+ */
+
+// Re-export everything from the organized API types module
+export * from './types/api/index.js';

package/src/types/benchmark.ts

@@ -0,0 +1,49 @@
+export interface BenchmarkCommandOptions {
+  agents?: string;
+  task?: string;
+  output?: string;
+  context?: string;
+  evaluate?: boolean;
+  report?: string;
+  concurrency?: number;
+  delay?: number;
+  timeout?: number;
+  quiet?: boolean;
+}
+
+export type AgentStatus = 'idle' | 'running' | 'completed' | 'error';
+
+export interface AgentData {
+  status: AgentStatus;
+  output: string[];
+  startTime?: number;
+  endTime?: number;
+  pid?: number;
+}
+
+export interface InitialInfo {
+  agentCount: number;
+  concurrency: number;
+  delay: number;
+  taskFile: string;
+  outputDir: string;
+}
+
+export interface AgentWork {
+  [key: string]: string;
+}
+
+export interface AgentTimings {
+  [key: string]: {
+    startTime?: number;
+    endTime?: number;
+    duration?: number;
+  };
+}
+
+export interface TimingData {
+  endTime: number;
+  exitCode: number;
+  stdoutLength: number;
+  stderrLength: number;
+}

package/src/types/cli.types.ts

@@ -0,0 +1,87 @@
+/**
+ * CLI-specific type definitions
+ * Types for command-line interface operations
+ */
+
+/**
+ * Application-specific options that extend Commander's built-in parsing
+ * Aggregates all possible CLI options across different commands
+ */
+export interface CommandOptions {
+  // Common CLI options
+  target?: string;
+  verbose?: boolean;
+  dryRun?: boolean;
+  clear?: boolean;
+  mcp?: string[] | null | boolean;
+  servers?: string[];
+  server?: string;
+  all?: boolean;
+
+  // Init command skip flags (--no-X sets to false)
+  // Note: 'agents' and 'rules' may also be strings in other commands
+  rules?: boolean | string;
+  outputStyles?: boolean;
+  hooks?: boolean;
+
+  // Memory command options
+  namespace?: string;
+  limit?: number;
+  pattern?: string;
+  key?: string;
+  confirm?: boolean;
+
+  // Benchmark-specific options
+  agents?: string | boolean; // boolean for init command --no-agents
+  task?: string;
+  output?: string;
+  context?: string;
+  evaluate?: boolean;
+  report?: string;
+  concurrency?: number;
+  delay?: number;
+
+  // Codebase command options
+  includeContent?: boolean;
+  extensions?: string[];
+  path?: string;
+  exclude?: string[];
+  query?: string;
+
+  // Knowledge command options
+  category?: string;
+  uri?: string;
+
+  // Allow dynamic properties - Commander.js already handles this
+  [key: string]: unknown;
+}
+
+/**
+ * Command configuration interface
+ */
+export interface CommandConfig {
+  name: string;
+  description: string;
+  handler: CommandHandler;
+  options?: Record<string, any>;
+}
+
+/**
+ * Command handler function type
+ * All CLI commands implement this signature
+ */
+export type CommandHandler = (options: CommandOptions) => Promise<void>;
+
+/**
+ * Options for executing commands on targets (Claude Code, OpenCode)
+ */
+export interface RunCommandOptions {
+  target?: string;
+  verbose?: boolean;
+  dryRun?: boolean;
+  agent?: string;
+  agentFile?: string;
+  prompt?: string;
+  print?: boolean;      // Headless print mode
+  continue?: boolean;   // Continue previous conversation
+}

package/src/types/common.types.ts

@@ -0,0 +1,35 @@
+/**
+ * Common types shared across modules
+ * Reusable types for cross-cutting concerns
+ */
+
+/**
+ * Type for resolvable values
+ * Can be a static value, sync function, or async function
+ * Enables lazy evaluation and dynamic configuration
+ */
+export type Resolvable<T> = T | (() => Promise<T>) | (() => T);
+
+/**
+ * Common options shared across commands and operations
+ */
+export interface CommonOptions {
+  target?: string;
+  verbose?: boolean;
+  dryRun?: boolean;
+  clear?: boolean;
+  mcp?: string[] | null | boolean;
+  quiet?: boolean;
+  agent?: string;
+}
+
+/**
+ * Standardized result from setup methods
+ * Used for consistent UI feedback across different setup operations
+ */
+export interface SetupResult {
+  /** Number of items processed (servers, agents, files, etc.) */
+  count: number;
+  /** Optional detailed message */
+  message?: string;
+}