Type Definitions

TypeScript type definitions and interfaces used throughout Orchestre.

Core Types

Project Types

// Project metadata
export interface Project {
  name: string;
  template: TemplateType;
  path: string;
  created: Date;
  version: string;
  description?: string;
  author?: string;
  repository?: string;
}

// Template types
export type TemplateType = 
  | "cloudflare-hono"
  | "makerkit-nextjs"
  | "react-native-expo";

// Project configuration
export interface ProjectConfig {
  version: string;
  project: {
    name: string;
    template: TemplateType;
    description?: string;
    created?: string;
    author?: string;
    repository?: string;
  };
  settings?: ProjectSettings;
  llm?: LLMConfig;
  features?: Record<string, any>;
  deployment?: DeploymentConfig;
}

// Project settings
export interface ProjectSettings {
  parallelAgents?: number;
  autoReview?: boolean;
  knowledgeBase?: boolean;
  debugMode?: boolean;
  customCommands?: boolean;
  patternLibrary?: boolean;
  distributedMemory?: boolean;
}

Analysis Types

// Technology stack
export interface Technology {
  name: string;
  purpose: string;
  version?: string;
  required: boolean;
}

// Risk assessment
export interface Risk {
  type: "technical" | "business" | "security" | "performance";
  description: string;
  mitigation: string;
  severity: "low" | "medium" | "high";
  probability?: "low" | "medium" | "high";
}

// Project analysis result
export interface ProjectAnalysis {
  complexity: "simple" | "moderate" | "complex";
  estimatedHours: number;
  technologies: Technology[];
  risks: Risk[];
  opportunities?: string[];
  constraints?: string[];
  recommendations?: string[];
  metadata?: {
    analyzedAt: string;
    model: string;
    confidence: number;
  };
}

Planning Types

// Task definition
export interface Task {
  id: string;
  title: string;
  description?: string;
  estimatedHours: number;
  dependencies?: string[];
  assignee?: string;
  status?: "pending" | "in_progress" | "completed" | "blocked";
  priority?: "low" | "medium" | "high";
}

// Project phase
export interface Phase {
  id: string;
  name: string;
  description?: string;
  tasks: Task[];
  estimatedDays?: number;
  dependencies?: string[];
  deliverables?: string[];
}

// Implementation plan
export interface ImplementationPlan {
  title: string;
  description?: string;
  phases: Phase[];
  totalEstimatedHours: number;
  criticalPath?: string[];
  parallelWorkstreams?: WorkStream[];
  milestones?: Milestone[];
}

// Parallel work stream
export interface WorkStream {
  id: string;
  name: string;
  tasks: string[]; // Task IDs
  assignee?: string;
}

// Project milestone
export interface Milestone {
  id: string;
  name: string;
  date?: string;
  criteria: string[];
  phase: string; // Phase ID
}

Review Types

// Code finding
export interface Finding {
  type: "bug" | "security" | "performance" | "style" | "improvement";
  severity: "info" | "warning" | "error" | "critical";
  file: string;
  line?: number;
  column?: number;
  description: string;
  suggestion?: string;
  codeSnippet?: string;
  rule?: string;
}

// Review summary
export interface ReviewSummary {
  score: number; // 0-100
  strengths: string[];
  improvements: string[];
  criticalIssues: number;
  totalFindings: number;
  recommendation: "approve" | "conditional" | "reject";
}

// Model review
export interface ModelReview {
  model: string;
  findings: Finding[];
  summary: string;
  confidence: number;
}

// Multi-LLM review result
export interface MultiLLMReview {
  consensus: ReviewSummary;
  reviews: ModelReview[];
  findings: Finding[];
  disagreements?: Finding[];
  metadata: {
    reviewedAt: string;
    duration: number;
    models: string[];
  };
}

LLM Configuration Types

// LLM provider
export type LLMProvider = "anthropic" | "openai" | "google";

// Model configuration
export interface LLMConfig {
  primary?: string;
  planning?: string;
  review?: string[];
  parameters?: ModelParameters;
  providers?: Record<LLMProvider, ProviderConfig>;
}

// Model parameters
export interface ModelParameters {
  temperature?: number;
  maxTokens?: number;
  topP?: number;
  frequencyPenalty?: number;
  presencePenalty?: number;
}

// Provider configuration
export interface ProviderConfig {
  apiKey?: string;
  apiBase?: string;
  organization?: string;
  headers?: Record<string, string>;
  timeout?: number;
  maxRetries?: number;
}

MCP Protocol Types

// MCP tool definition
export interface MCPTool {
  name: string;
  description: string;
  inputSchema: {
    type: "object";
    properties: Record<string, any>;
    required?: string[];
    additionalProperties?: boolean;
  };
}

// MCP request
export interface MCPRequest {
  jsonrpc: "2.0";
  id: string | number;
  method: string;
  params?: any;
}

// MCP response
export interface MCPResponse {
  jsonrpc: "2.0";
  id: string | number;
  result?: any;
  error?: MCPError;
}

// MCP error
export interface MCPError {
  code: number;
  message: string;
  data?: any;
}

// Tool response
export interface ToolResponse {
  content: Array<{
    type: "text" | "image" | "binary";
    text?: string;
    data?: any;
    mimeType?: string;
  }>;
  isError?: boolean;
}

State Management Types

// Distributed state entry
export interface StateEntry {
  path: string;
  content: string;
  type: "feature" | "api" | "architecture" | "decision";
  created: string;
  updated: string;
  tags?: string[];
}

// Memory template
export interface MemoryTemplate {
  name: string;
  description: string;
  sections: Array<{
    heading: string;
    prompt: string;
    required: boolean;
  }>;
  examples?: string[];
}

// Knowledge base
export interface KnowledgeBase {
  entries: StateEntry[];
  index: Map<string, string[]>; // tag -> paths
  lastUpdated: string;
}

Command Types

// Command definition
export interface Command {
  name: string;
  description: string;
  category: "core" | "parallel" | "meta" | "specialized" | "template";
  parameters?: CommandParameter[];
  examples: string[];
  templateSpecific?: boolean;
}

// Command parameter
export interface CommandParameter {
  name: string;
  type: "string" | "number" | "boolean" | "array" | "object";
  description: string;
  required: boolean;
  default?: any;
  enum?: string[];
}

// Command result
export interface CommandResult {
  success: boolean;
  message?: string;
  data?: any;
  nextSteps?: string[];
  artifacts?: string[]; // Created file paths
}

Deployment Types

// Deployment target
export type DeploymentTarget = 
  | "vercel"
  | "cloudflare-workers"
  | "aws-lambda"
  | "docker"
  | "kubernetes";

// Deployment configuration
export interface DeploymentConfig {
  target: DeploymentTarget;
  region?: string | string[];
  environment?: Record<string, EnvironmentConfig>;
  domains?: DomainConfig[];
  scaling?: ScalingConfig;
}

// Environment configuration
export interface EnvironmentConfig {
  variables: Record<string, string>;
  secrets?: string[];
  features?: Record<string, boolean>;
}

// Domain configuration
export interface DomainConfig {
  domain: string;
  environment: string;
  ssl: boolean;
  cdn?: boolean;
}

// Scaling configuration
export interface ScalingConfig {
  min: number;
  max: number;
  targetCPU?: number;
  targetMemory?: number;
}

Utility Types

Generic Helpers

// Partial deep
export type DeepPartial<T> = {
  [P in keyof T]?: T[P] extends object ? DeepPartial<T[P]> : T[P];
};

// Required keys
export type RequiredKeys<T, K extends keyof T> = T & Required<Pick<T, K>>;

// Omit deep
export type DeepOmit<T, K> = T extends object
  ? { [P in Exclude<keyof T, K>]: DeepOmit<T[P], K> }
  : T;

// String literal union
export type StringLiteral<T> = T extends string ? T : never;

// Array element type
export type ArrayElement<T> = T extends readonly (infer U)[] ? U : never;

Result Types

// Success result
export interface Success<T> {
  success: true;
  data: T;
  metadata?: Record<string, any>;
}

// Error result
export interface Failure {
  success: false;
  error: string;
  code?: string;
  details?: any;
}

// Result union
export type Result<T> = Success<T> | Failure;

// Async result
export type AsyncResult<T> = Promise<Result<T>>;

Event Types

// Event base
export interface Event {
  id: string;
  type: string;
  timestamp: string;
  source: string;
}

// Tool event
export interface ToolEvent extends Event {
  type: "tool.started" | "tool.completed" | "tool.failed";
  tool: string;
  params?: any;
  result?: any;
  error?: any;
  duration?: number;
}

// Command event
export interface CommandEvent extends Event {
  type: "command.executed" | "command.failed";
  command: string;
  args?: string[];
  result?: CommandResult;
  error?: any;
}

Type Guards

// Check if value is Success
export function isSuccess<T>(result: Result<T>): result is Success<T> {
  return result.success === true;
}

// Check if value is Failure
export function isFailure<T>(result: Result<T>): result is Failure {
  return result.success === false;
}

// Check if value is MCPError
export function isMCPError(value: any): value is MCPError {
  return value && 
    typeof value.code === "number" &&
    typeof value.message === "string";
}

// Check if value is Finding
export function isFinding(value: any): value is Finding {
  return value &&
    ["bug", "security", "performance", "style", "improvement"].includes(value.type) &&
    ["info", "warning", "error", "critical"].includes(value.severity) &&
    typeof value.description === "string";
}

Usage Examples

Type-Safe Tool Implementation

import { ProjectAnalysis, Result } from '../types';

export async function analyzeProject(
  requirements: string
): Promise<Result<ProjectAnalysis>> {
  try {
    const analysis: ProjectAnalysis = {
      complexity: "moderate",
      estimatedHours: 80,
      technologies: [
        { name: "Next.js", purpose: "Frontend", required: true }
      ],
      risks: []
    };
    
    return {
      success: true,
      data: analysis
    };
  } catch (error) {
    return {
      success: false,
      error: error.message,
      code: "ANALYSIS_FAILED"
    };
  }
}

Type-Safe Configuration

import { ProjectConfig } from '../types';

const config: ProjectConfig = {
  version: "3.0.0",
  project: {
    name: "my-app",
    template: "makerkit-nextjs"
  },
  settings: {
    parallelAgents: 3,
    autoReview: true
  },
  llm: {
    primary: "claude-3-opus",
    review: ["gpt-4o", "claude-3-sonnet"]
  }
};

See Also

• API Reference
• Tool Schemas
• Configuration Reference
• TypeScript Documentation