forge-server 0.1.0

package/src/util/types.ts

@@ -0,0 +1,710 @@
+// Core domain types for the dk-forge-server.
+// These are the canonical entity interfaces shared across the storage, knowledge,
+// and pipeline layers. Every field is explicit — no `any`, no implicit optionals.
+
+// ---------------------------------------------------------------------------
+// Pipeline state types
+// ---------------------------------------------------------------------------
+
+export type PipelinePhase =
+  | 'idle'
+  | 'strategist'
+  | 'product-manager'
+  | 'architect'
+  | 'designer'
+  | 'qa-strategist'
+  | 'backend-specialist'
+  | 'frontend-specialist'
+  | 'data-specialist'
+  | 'platform-engineer'
+  | 'inspector'
+  | 'knowledge-keeper'
+  | 'complete'
+  | 'failed';
+
+export type PipelineTier = 'full' | 'abbreviated' | 'trivial';
+
+export type ProjectStatus = 'active' | 'paused' | 'complete' | 'archived';
+
+export type RepoSharing = 'private' | 'team' | 'public';
+
+export type TrajectoryStatus = 'active' | 'complete' | 'failed' | 'abandoned';
+
+export type ClaimStatus = 'claimed' | 'complete' | 'failed' | 'stealable';
+
+export type EventType =
+  | 'phase_transition'
+  | 'agent_started'
+  | 'agent_completed'
+  | 'agent_failed'
+  | 'project_created'
+  | 'project_paused'
+  | 'project_resumed'
+  | 'project_completed'
+  | 'claim_created'
+  | 'claim_completed'
+  | 'claim_failed'
+  | 'agent_broadcast';
+
+// ---------------------------------------------------------------------------
+// Row types — these mirror the SQLite table columns exactly.
+// Timestamps are stored as INTEGER (Unix ms). JSON columns are TEXT in SQLite
+// but deserialized to typed objects by the query helpers.
+// ---------------------------------------------------------------------------
+
+export interface RepoRow {
+  id: string;
+  name: string;
+  path: string;
+  remote: string | null;
+  stack: string; // JSON array of strings: e.g. '["nestjs","drizzle"]'
+  sharing: RepoSharing;
+  org: string | null;
+  registered_at: number;
+  last_seen_at: number;
+  manifest_hash: string | null;
+}
+
+export interface ProjectRow {
+  id: string;
+  repo_id: string;
+  name: string;
+  description: string | null;
+  current_phase: PipelinePhase;
+  tier: PipelineTier;
+  status: ProjectStatus;
+  created_at: number;
+  updated_at: number;
+  metadata: string; // JSON object
+}
+
+export interface PipelineEventRow {
+  id: number;
+  project_id: string;
+  event_type: EventType;
+  from_phase: PipelinePhase | null;
+  to_phase: PipelinePhase | null;
+  agent: string | null;
+  payload: string; // JSON object
+  created_at: number;
+}
+
+export interface PhaseOutputRow {
+  id: number;
+  project_id: string;
+  phase: PipelinePhase;
+  output_type: string;
+  content: string;
+  file_path: string | null;
+  created_at: number;
+}
+
+export interface TrajectoryRow {
+  id: string;
+  project_id: string;
+  phase: PipelinePhase;
+  agent: string;
+  status: TrajectoryStatus;
+  started_at: number;
+  completed_at: number | null;
+  success: number | null; // SQLite INTEGER: 0 = false, 1 = true, NULL = not yet determined
+  feedback: string | null;
+}
+
+export interface TrajectoryStepRow {
+  id: number;
+  trajectory_id: string;
+  action: string;
+  result: string | null;
+  quality_score: number | null;
+  metadata: string; // JSON object
+  created_at: number;
+}
+
+export interface SessionRow {
+  id: string;
+  project_id: string | null;
+  repo_id: string | null;
+  started_at: number;
+  ended_at: number | null;
+  state: string; // JSON object
+  observation_count: number;
+}
+
+export interface ClaimRow {
+  id: string;
+  project_id: string;
+  module_name: string;
+  agent: string;
+  branch: string | null;
+  status: ClaimStatus;
+  claimed_at: number;
+  completed_at: number | null;
+  result: string | null;
+}
+
+// ---------------------------------------------------------------------------
+// Deserialized domain objects — produced by service-layer queries that parse
+// JSON columns. These are what callers above the storage layer work with.
+// ---------------------------------------------------------------------------
+
+export interface Repo {
+  id: string;
+  name: string;
+  path: string;
+  remote: string | null;
+  stack: string[];
+  sharing: RepoSharing;
+  org: string | null;
+  registeredAt: number;
+  lastSeenAt: number;
+  manifestHash: string | null;
+}
+
+export interface ProjectMetadata {
+  planPath?: string;
+  worktreePaths?: Record<string, string>;
+  interviewTranscript?: string;
+  tags?: string[];
+  [key: string]: unknown;
+}
+
+export interface Project {
+  id: string;
+  repoId: string;
+  name: string;
+  description: string | null;
+  currentPhase: PipelinePhase;
+  tier: PipelineTier;
+  status: ProjectStatus;
+  createdAt: number;
+  updatedAt: number;
+  metadata: ProjectMetadata;
+}
+
+export interface PipelineEventPayload {
+  message?: string;
+  error?: string;
+  duration?: number;
+  output?: string;
+  [key: string]: unknown;
+}
+
+export interface PipelineEvent {
+  id: number;
+  projectId: string;
+  eventType: EventType;
+  fromPhase: PipelinePhase | null;
+  toPhase: PipelinePhase | null;
+  agent: string | null;
+  payload: PipelineEventPayload;
+  createdAt: number;
+}
+
+export interface PhaseOutput {
+  id: number;
+  projectId: string;
+  phase: PipelinePhase;
+  outputType: string;
+  content: string;
+  filePath: string | null;
+  createdAt: number;
+}
+
+export interface Trajectory {
+  id: string;
+  projectId: string;
+  phase: PipelinePhase;
+  agent: string;
+  status: TrajectoryStatus;
+  startedAt: number;
+  completedAt: number | null;
+  success: boolean | null;
+  feedback: string | null;
+}
+
+export interface TrajectoryStepMetadata {
+  toolName?: string;
+  filePath?: string;
+  lineCount?: number;
+  [key: string]: unknown;
+}
+
+export interface TrajectoryStep {
+  id: number;
+  trajectoryId: string;
+  action: string;
+  result: string | null;
+  qualityScore: number | null;
+  metadata: TrajectoryStepMetadata;
+  createdAt: number;
+}
+
+export interface SessionState {
+  currentTask?: string;
+  context?: Record<string, unknown>;
+  [key: string]: unknown;
+}
+
+export interface Session {
+  id: string;
+  projectId: string | null;
+  repoId: string | null;
+  startedAt: number;
+  endedAt: number | null;
+  state: SessionState;
+  observationCount: number;
+}
+
+export interface Claim {
+  id: string;
+  projectId: string;
+  moduleName: string;
+  agent: string;
+  branch: string | null;
+  status: ClaimStatus;
+  claimedAt: number;
+  completedAt: number | null;
+  result: string | null;
+}
+
+// ---------------------------------------------------------------------------
+// Knowledge types — used by both the YAML store and the Qdrant vector layer.
+// KnowledgeCategory is exported here so store.ts can import it cleanly.
+// ---------------------------------------------------------------------------
+
+export type KnowledgeCategory = 'gotcha' | 'pattern' | 'decision' | 'convention';
+
+export interface KnowledgeItem {
+  id: string;
+  title: string;
+  content: string;
+  stack_tags: string[];
+  confidence: number;
+  source: 'migration' | 'manual' | 'agent' | 'inspector';
+  source_phase: PipelinePhase | null;
+  source_agent: string | null;
+  created_at: number;
+  updated_at: number;
+}
+
+// ---------------------------------------------------------------------------
+// forge-graph-rag types — needed by storage, ingestion, query, and memory
+// modules merged from forge-graph-rag. These live alongside the pipeline
+// types above so that a single import covers both domains.
+// ---------------------------------------------------------------------------
+
+// Phase type as used by the knowledge/trajectory modules (pipeline-specific).
+// Maps to the pipeline execution phases tracked in KnowledgeItem and trajectories.
+export type Phase =
+  | 'idle'
+  | 'interview'
+  | 'requirements'
+  | 'architecture'
+  | 'design'
+  | 'qa_strategy'
+  | 'implementation'
+  | 'inspection'
+  | 'knowledge_collection'
+  | 'completed';
+
+export type SharingMode = 'team' | 'private' | 'public';
+
+export interface ForgeManifest {
+  name: string;
+  stack: string[];
+  sharing: SharingMode;
+  org?: string;
+  repo_id_override?: string | null;
+}
+
+export interface KnowledgePayload {
+  id: string;
+  repo_id: string;
+  category: string;
+  title: string;
+  content: string;
+  stack_tags: string[];
+  confidence: number;
+  source: string;
+  source_phase: string | null;
+  source_agent: string | null;
+  sharing: string;
+  created_at: number;
+  updated_at: number;
+  accessed_at: number;
+  access_count: number;
+}
+
+// ============================================================
+// Configuration Types (forge-graph-rag)
+// ============================================================
+
+export interface RepoConfig {
+  id: string;
+  path: string;
+  remote?: string;
+  ownership: 'owned' | 'external';
+  watch: boolean;
+  languages: string[];
+  retrieval?: RepoRetrievalDefaults;
+}
+
+export interface AppConfig {
+  server: {
+    name: string;
+    version: string;
+    transport: string;
+  };
+  embedding: {
+    model: string;
+    dimension: number;
+    batch_size: number;
+  };
+  cache: {
+    max_size_mb: number;
+    max_entries: number;
+    ttl_minutes: number;
+  };
+  watcher: {
+    debounce_ms: number;
+    ignored_patterns: string[];
+    watched_extensions: string[];
+  };
+  indexing: {
+    max_file_size_kb: number;
+    chunk_max_tokens: number;
+    chunk_overlap_tokens: number;
+    git_history_depth: number;
+  };
+  graph: {
+    name: string;
+    query_timeout_ms: number;
+  };
+  vector: {
+    code_chunks_collection: string;
+    observations_collection: string;
+    hnsw_m: number;
+    hnsw_ef_construct: number;
+    on_disk_payload: boolean;
+  };
+  knowledge_routing: {
+    default_ownership: 'owned' | 'external';
+  };
+  repos: RepoConfig[];
+}
+
+// ============================================================
+// Entity / Graph Types (forge-graph-rag)
+// ============================================================
+
+export type EntityType =
+  | 'function'
+  | 'class'
+  | 'interface'
+  | 'type_alias'
+  | 'variable'
+  | 'module'
+  | 'file';
+
+export interface ParsedEntity {
+  name: string;
+  type: EntityType;
+  filePath: string;
+  repoId: string;
+  startLine: number;
+  endLine: number;
+  isExported: boolean;
+  isAsync?: boolean;
+  params?: string;
+  isConst?: boolean;
+  isDefault?: boolean;
+  sourceText: string;
+}
+
+export interface ParsedImport {
+  fromPath: string;    // module specifier (e.g. './auth.service')
+  specifiers: string;  // comma-joined import names
+  isDefault: boolean;
+}
+
+export interface ParseResult {
+  entities: ParsedEntity[];
+  imports: ParsedImport[];
+  filePath: string;
+  language: string;
+  success: boolean;
+  error?: string;
+}
+
+// ============================================================
+// Chunk Types (forge-graph-rag)
+// ============================================================
+
+export type ChunkType =
+  | 'function'
+  | 'class'
+  | 'interface'
+  | 'type_alias'
+  | 'variable'
+  | 'file_level'
+  | 'markdown'
+  | 'config';
+
+export interface CodeChunk {
+  id: string;              // UUID for Qdrant point ID
+  repoId: string;
+  filePath: string;
+  entityName: string | null;
+  entityType: ChunkType;
+  startLine: number;
+  endLine: number;
+  language: string;
+  contentHash: string;     // SHA-256 of content for cache invalidation
+  content: string;         // Full chunk text (with header comment)
+  contentPreview: string;  // First 200 chars
+  indexedAt: number;       // Unix timestamp ms
+}
+
+// ============================================================
+// Vector Store Types (forge-graph-rag)
+// ============================================================
+
+export interface CodeChunkPayload {
+  repo_id: string;
+  file_path: string;
+  entity_name: string | null;
+  entity_type: ChunkType;
+  start_line: number;
+  end_line: number;
+  language: string;
+  content_hash: string;
+  content_preview: string;
+  indexed_at: number;
+}
+
+export interface ObservationPayload {
+  id: string;
+  repo_id: string | null;
+  session_id: string;
+  content: string;
+  type: 'episodic' | 'semantic' | 'procedural' | 'working';
+  category: string | null;
+  tags: string[];
+  importance: number;
+  created_at: number;
+  accessed_at: number;
+  access_count: number;
+  is_stale: boolean;
+  linked_symbols: string[];
+  source: 'forge' | 'claude-flow' | 'ruflo';
+  metadata: Record<string, unknown>;
+  key: string | null;
+  namespace: string;
+}
+
+export interface VectorSearchResult {
+  id: string;
+  score: number;
+  payload: CodeChunkPayload | ObservationPayload;
+}
+
+// ============================================================
+// Query Types (forge-graph-rag)
+// ============================================================
+
+export type QueryIntent = 'read' | 'modify' | 'debug' | 'refactor';
+
+export interface GraphHybridSearchResult {
+  filePath: string;
+  repoId: string;
+  vectorScore: number;
+  graphScore: number;
+  recencyScore: number;
+  finalScore: number;
+  entityName: string | null;
+  entityType: ChunkType;
+  startLine: number;
+  endLine: number;
+  matchReason: string;
+}
+
+// ============================================================
+// Graph Node/Edge Types (forge-graph-rag)
+// ============================================================
+
+export interface GraphNode {
+  id?: string;
+  label: string;
+  properties: Record<string, unknown>;
+}
+
+export interface GraphEdge {
+  type: string;
+  from: string;  // node identifier
+  to: string;    // node identifier
+  properties?: Record<string, unknown>;
+}
+
+export interface GraphQueryResult {
+  nodes: GraphNode[];
+  edges: GraphEdge[];
+  raw?: unknown[];
+}
+
+// ============================================================
+// Cache Types (forge-graph-rag)
+// ============================================================
+
+export interface CacheEntry {
+  content: string;
+  contentHash: string;
+  cachedAt: number;
+  accessCount: number;
+  sizeBytes: number;
+}
+
+export interface CacheStats {
+  entries: number;
+  memoryUsageMb: number;
+  hitRate: number;
+  evictionCount: number;
+  oldestEntryAgeSeconds: number;
+}
+
+// ============================================================
+// Index Status Types (forge-graph-rag)
+// ============================================================
+
+export interface RepoIndexStatus {
+  repoId: string;
+  path: string;
+  filesIndexed: number;
+  filesTotal: number;
+  lastIndexedAt: number;
+  staleFiles: number;
+}
+
+// ============================================================
+// MCP Tool Input/Output Types (forge-graph-rag)
+// ============================================================
+
+export type DetailLevel = 'full' | 'skeleton' | 'paths';
+
+export interface GetContextInput {
+  query: string;
+  repo_id?: string;
+  include_tests?: boolean;
+  max_tokens?: number;
+  pivot_depth?: number;
+  detail?: DetailLevel;
+  max_results?: number;
+  min_score?: number;
+}
+
+/**
+ * Per-repo retrieval defaults. Applied when repo_id matches, overridden by per-call params.
+ */
+export interface RepoRetrievalDefaults {
+  detail?: DetailLevel;
+  max_results?: number;
+  max_tokens?: number;
+  pivot_depth?: number;
+  min_score?: number;
+  include_tests?: boolean;
+}
+
+export interface TokenBreakdown {
+  pivots: number;
+  skeletons: number;
+  memories: number;
+  overhead: number;
+}
+
+export interface GetContextOutput {
+  pivot_files: Array<{
+    file_path: string;
+    content: string;
+    relevance_score: number;
+    match_reason: string;
+  }>;
+  supporting_skeletons: Array<{
+    file_path: string;
+    skeleton: string;
+    relevance_score: number;
+  }>;
+  related_memories: Array<{
+    content: string;
+    created_at: number;
+    relevance_score: number;
+  }>;
+  query_intent: QueryIntent;
+  token_count: number;
+  token_breakdown: TokenBreakdown;
+  cache_hits: number;
+  execution_time_ms: number;
+}
+
+export interface GetSkeletonInput {
+  path: string;
+  repo_id?: string;
+  detail?: 'minimal' | 'standard' | 'detailed';
+}
+
+export interface GetSkeletonOutput {
+  path: string;
+  type: 'file' | 'directory';
+  skeleton: string;
+  token_count: number;
+}
+
+export interface IndexStatusInput {
+  repo_id?: string;
+}
+
+export interface IndexStatusOutput {
+  repos: RepoIndexStatus[];
+  graph: {
+    total_nodes: number;
+    total_edges: number;
+    node_counts: Record<string, number>;
+  };
+  vector: {
+    code_chunks_count: number;
+    observations_count: number;
+  };
+  cache: CacheStats;
+  health: 'healthy' | 'degraded' | 'unavailable';
+  embedding_model: string;
+  uptime_seconds: number;
+}
+
+// ============================================================
+// Git History Types (Phase 3 - git enrichment)
+// ============================================================
+
+export interface FileChangeStats {
+  commitCount: number;
+  stabilityScore: number;    // 0-1, higher = more stable (fewer recent changes)
+  changeVelocity: number;    // -1 to +1, positive = accelerating changes
+  lastCommitHash: string;
+  lastCommitTs: number;
+  recentMessages: string[];  // Last N commit messages touching this file
+}
+
+export interface CommitRecord {
+  hash: string;
+  message: string;
+  author: string;
+  timestamp: number;         // Unix ms
+  files: string[];
+}
+
+export interface GitCommitPayload {
+  repo_id: string;
+  commit_hash: string;
+  message: string;
+  author: string;
+  timestamp: number;
+  file_paths: string[];
+}