forge-server 0.1.0

package/src/util/circuit-breaker.ts

@@ -0,0 +1,193 @@
+/**
+ * Circuit breaker pattern for external service calls.
+ *
+ * States:
+ *   CLOSED   — normal operation, failures are counted
+ *   OPEN     — failing, all calls rejected immediately after failureThreshold reached
+ *   HALF_OPEN — testing recovery, one probe request allowed
+ *
+ * Transitions:
+ *   CLOSED  → OPEN       after failureThreshold consecutive failures
+ *   OPEN    → HALF_OPEN  after resetTimeoutMs has elapsed
+ *   HALF_OPEN → CLOSED   if the probe request succeeds
+ *   HALF_OPEN → OPEN     if the probe request fails
+ */
+
+import { logger } from './logger.js';
+
+export type CircuitState = 'CLOSED' | 'OPEN' | 'HALF_OPEN';
+
+export interface CircuitBreakerOptions {
+  /** Number of consecutive failures before tripping to OPEN. Default: 5 */
+  failureThreshold?: number;
+  /** Milliseconds to wait in OPEN before transitioning to HALF_OPEN. Default: 30000 */
+  resetTimeoutMs?: number;
+  /** Name for log messages. */
+  name: string;
+}
+
+export class CircuitBreaker {
+  private state: CircuitState = 'CLOSED';
+  private consecutiveFailures = 0;
+  private lastFailureTime = 0;
+  private halfOpenProbeInFlight = false;
+
+  private readonly failureThreshold: number;
+  private readonly resetTimeoutMs: number;
+  private readonly name: string;
+
+  constructor(opts: CircuitBreakerOptions) {
+    this.name = opts.name;
+    this.failureThreshold = opts.failureThreshold ?? 5;
+    this.resetTimeoutMs = opts.resetTimeoutMs ?? 30_000;
+  }
+
+  /**
+   * Current state of the circuit breaker.
+   */
+  getState(): CircuitState {
+    this.maybeTransitionToHalfOpen();
+    return this.state;
+  }
+
+  /**
+   * Returns true when the breaker allows the call to proceed.
+   * Returns false when OPEN (or HALF_OPEN but a probe is already in flight).
+   */
+  isAllowed(): boolean {
+    this.maybeTransitionToHalfOpen();
+
+    if (this.state === 'CLOSED') return true;
+
+    if (this.state === 'HALF_OPEN') {
+      // Allow exactly one probe through
+      if (!this.halfOpenProbeInFlight) {
+        this.halfOpenProbeInFlight = true;
+        return true;
+      }
+      return false;
+    }
+
+    // OPEN — reject
+    return false;
+  }
+
+  /**
+   * Call this when a protected operation succeeds.
+   */
+  recordSuccess(): void {
+    // Ensure state is up to date before evaluating
+    this.maybeTransitionToHalfOpen();
+
+    if (this.state === 'HALF_OPEN') {
+      logger.info(`Circuit breaker [${this.name}] recovered — closing`, {
+        previousFailures: this.consecutiveFailures,
+      });
+      this.transitionTo('CLOSED');
+    }
+    this.consecutiveFailures = 0;
+    this.halfOpenProbeInFlight = false;
+  }
+
+  /**
+   * Call this when a protected operation fails.
+   */
+  recordFailure(): void {
+    // Ensure state is up to date before evaluating
+    this.maybeTransitionToHalfOpen();
+
+    this.consecutiveFailures++;
+    this.lastFailureTime = Date.now();
+    this.halfOpenProbeInFlight = false;
+
+    if (this.state === 'HALF_OPEN') {
+      logger.warn(`Circuit breaker [${this.name}] probe failed — re-opening`, {
+        consecutiveFailures: this.consecutiveFailures,
+      });
+      this.transitionTo('OPEN');
+      return;
+    }
+
+    if (this.state === 'CLOSED' && this.consecutiveFailures >= this.failureThreshold) {
+      logger.warn(`Circuit breaker [${this.name}] tripped OPEN`, {
+        consecutiveFailures: this.consecutiveFailures,
+        failureThreshold: this.failureThreshold,
+        resetTimeoutMs: this.resetTimeoutMs,
+      });
+      this.transitionTo('OPEN');
+    }
+  }
+
+  /**
+   * Execute a function with circuit breaker protection.
+   * Throws CircuitOpenError if the circuit is open.
+   * Automatically records success/failure.
+   */
+  async execute<T>(fn: () => Promise<T>): Promise<T> {
+    if (!this.isAllowed()) {
+      throw new CircuitOpenError(
+        `Circuit breaker [${this.name}] is OPEN — request rejected`
+      );
+    }
+
+    try {
+      const result = await fn();
+      this.recordSuccess();
+      return result;
+    } catch (err) {
+      this.recordFailure();
+      throw err;
+    }
+  }
+
+  /**
+   * Convenience: returns true when the circuit is healthy enough to allow requests.
+   * Equivalent to `isAllowed()` but does not reserve the HALF_OPEN probe slot.
+   */
+  isHealthy(): boolean {
+    this.maybeTransitionToHalfOpen();
+    return this.state === 'CLOSED' || this.state === 'HALF_OPEN';
+  }
+
+  /**
+   * Force-reset the breaker to CLOSED state. Useful for testing or manual recovery.
+   */
+  reset(): void {
+    logger.info(`Circuit breaker [${this.name}] manually reset`);
+    this.transitionTo('CLOSED');
+    this.consecutiveFailures = 0;
+    this.halfOpenProbeInFlight = false;
+  }
+
+  /** Internal: check if we should transition from OPEN to HALF_OPEN due to timeout. */
+  private maybeTransitionToHalfOpen(): void {
+    if (
+      this.state === 'OPEN' &&
+      Date.now() - this.lastFailureTime >= this.resetTimeoutMs
+    ) {
+      logger.info(`Circuit breaker [${this.name}] entering HALF_OPEN — probing`, {
+        elapsed: Date.now() - this.lastFailureTime,
+        resetTimeoutMs: this.resetTimeoutMs,
+      });
+      this.transitionTo('HALF_OPEN');
+    }
+  }
+
+  private transitionTo(next: CircuitState): void {
+    this.state = next;
+    if (next === 'CLOSED') {
+      this.lastFailureTime = 0;
+      this.halfOpenProbeInFlight = false;
+    }
+  }
+}
+
+/**
+ * Thrown when a call is rejected because the circuit is open.
+ */
+export class CircuitOpenError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'CircuitOpenError';
+  }
+}

package/src/util/config.ts

@@ -0,0 +1,177 @@
+/**
+ * Configuration loading from env vars + YAML files.
+ * Priority: env vars > YAML config > hardcoded defaults.
+ */
+
+import { readFileSync, existsSync } from 'fs';
+import { resolve } from 'path';
+import { parse as parseYaml } from 'yaml';
+import type { AppConfig, RepoConfig } from './types.js';
+import { logger } from './logger.js';
+
+const DEFAULT_CONFIG: AppConfig = {
+  server: {
+    name: 'forge-knowledge',
+    version: '0.1.0',
+    transport: 'stdio',
+  },
+  embedding: {
+    model: 'Xenova/all-MiniLM-L6-v2',
+    dimension: 384,
+    batch_size: 32,
+  },
+  cache: {
+    max_size_mb: 100,
+    max_entries: 2000,
+    ttl_minutes: 30,
+  },
+  watcher: {
+    debounce_ms: 500,
+    ignored_patterns: [
+      '**/node_modules/**',
+      '**/.git/**',
+      '**/dist/**',
+      '**/build/**',
+      '**/*.map',
+      '**/package-lock.json',
+    ],
+    watched_extensions: [
+      '.ts', '.tsx', '.js', '.jsx', '.mts', '.cts',
+      '.json', '.yaml', '.yml', '.md', '.graphql', '.sql',
+    ],
+  },
+  indexing: {
+    max_file_size_kb: 500,
+    chunk_max_tokens: 1024,
+    chunk_overlap_tokens: 64,
+    git_history_depth: 500,
+  },
+  graph: {
+    name: 'forge_knowledge',
+    query_timeout_ms: 5000,
+  },
+  vector: {
+    code_chunks_collection: 'code_chunks',
+    observations_collection: 'observations',
+    hnsw_m: 16,
+    hnsw_ef_construct: 100,
+    on_disk_payload: true,
+  },
+  knowledge_routing: {
+    default_ownership: 'external',
+  },
+  repos: [],
+};
+
+let loadedConfig: AppConfig | null = null;
+
+/**
+ * Load and merge configuration from YAML + env vars.
+ * Cached after first load.
+ */
+export function loadConfig(): AppConfig {
+  if (loadedConfig) return loadedConfig;
+
+  let config = { ...DEFAULT_CONFIG };
+
+  // Load YAML config
+  const configPath = process.env.REPOS_CONFIG
+    ? resolve(process.env.REPOS_CONFIG)
+    : resolve('./config/default.yaml');
+
+  const reposPath = process.env.REPOS_CONFIG
+    ? process.env.REPOS_CONFIG
+    : resolve('./config/repos.yaml');
+
+  if (existsSync(configPath)) {
+    try {
+      const yamlContent = readFileSync(configPath, 'utf8');
+      const yamlConfig = parseYaml(yamlContent) as Partial<AppConfig>;
+      config = deepMerge(config, yamlConfig) as AppConfig;
+    } catch (err) {
+      logger.warn(`Failed to load config from ${configPath}`, { error: String(err) });
+    }
+  }
+
+  // Load repos config separately
+  if (existsSync(reposPath)) {
+    try {
+      const reposContent = readFileSync(reposPath, 'utf8');
+      const reposYaml = parseYaml(reposContent) as { repos?: RepoConfig[] };
+      if (reposYaml.repos) {
+        config.repos = reposYaml.repos;
+      }
+    } catch (err) {
+      logger.warn(`Failed to load repos config from ${reposPath}`, { error: String(err) });
+    }
+  }
+
+  // Override with env vars
+  config = applyEnvOverrides(config);
+
+  loadedConfig = config;
+  return config;
+}
+
+/**
+ * Get connection URLs from config/env.
+ */
+export function getConnectionConfig(): {
+  falkordbUrl: string;
+  qdrantUrl: string;
+  graphName: string;
+} {
+  return {
+    falkordbUrl: process.env.FALKORDB_URL ?? 'redis://localhost:6380',
+    qdrantUrl: process.env.QDRANT_URL ?? 'http://localhost:6333',
+    graphName: process.env.GRAPH_NAME ?? 'forge_knowledge',
+  };
+}
+
+/**
+ * Get the default repo ID (first repo in config, or from env).
+ */
+export function getDefaultRepoId(config: AppConfig): string | undefined {
+  const envRepo = process.env.DEFAULT_REPO_ID;
+  if (envRepo) return envRepo;
+  return config.repos[0]?.id;
+}
+
+function applyEnvOverrides(config: AppConfig): AppConfig {
+  if (process.env.LOG_LEVEL) {
+    // Log level handled by logger module
+  }
+  if (process.env.EMBEDDING_MODEL) {
+    config.embedding.model = process.env.EMBEDDING_MODEL;
+  }
+  if (process.env.EMBEDDING_DIMENSION) {
+    config.embedding.dimension = parseInt(process.env.EMBEDDING_DIMENSION, 10);
+  }
+  if (process.env.CACHE_MAX_SIZE_MB) {
+    config.cache.max_size_mb = parseInt(process.env.CACHE_MAX_SIZE_MB, 10);
+  }
+  if (process.env.CACHE_TTL_MINUTES) {
+    config.cache.ttl_minutes = parseInt(process.env.CACHE_TTL_MINUTES, 10);
+  }
+  if (process.env.GRAPH_NAME) {
+    config.graph.name = process.env.GRAPH_NAME;
+  }
+  if (process.env.WATCHER_DEBOUNCE_MS) {
+    config.watcher.debounce_ms = parseInt(process.env.WATCHER_DEBOUNCE_MS, 10);
+  }
+  return config;
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function deepMerge(target: any, source: any): any {
+  if (!source || typeof source !== 'object') return target;
+  const result = { ...target };
+  for (const key of Object.keys(source)) {
+    if (source[key] !== null && typeof source[key] === 'object' && !Array.isArray(source[key])) {
+      result[key] = deepMerge(target[key] ?? {}, source[key]);
+    } else if (source[key] !== undefined) {
+      result[key] = source[key];
+    }
+  }
+  return result;
+}

package/src/util/logger.ts

@@ -0,0 +1,53 @@
+/**
+ * Structured logger for dk-forge-server
+ */
+
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+
+const LOG_LEVELS: Record<LogLevel, number> = {
+  debug: 0,
+  info: 1,
+  warn: 2,
+  error: 3,
+};
+
+let currentLevel: LogLevel = 'info';
+
+export function setLogLevel(level: LogLevel): void {
+  currentLevel = level;
+}
+
+function shouldLog(level: LogLevel): boolean {
+  return LOG_LEVELS[level] >= LOG_LEVELS[currentLevel];
+}
+
+function formatMessage(level: LogLevel, message: string, meta?: unknown): string {
+  const ts = new Date().toISOString();
+  const metaStr = meta !== undefined ? ' ' + JSON.stringify(meta) : '';
+  return `[${ts}] [${level.toUpperCase()}] ${message}${metaStr}`;
+}
+
+export const logger = {
+  debug(message: string, meta?: unknown): void {
+    if (shouldLog('debug')) {
+      process.stderr.write(formatMessage('debug', message, meta) + '\n');
+    }
+  },
+  info(message: string, meta?: unknown): void {
+    if (shouldLog('info')) {
+      process.stderr.write(formatMessage('info', message, meta) + '\n');
+    }
+  },
+  warn(message: string, meta?: unknown): void {
+    if (shouldLog('warn')) {
+      process.stderr.write(formatMessage('warn', message, meta) + '\n');
+    }
+  },
+  error(message: string, meta?: unknown): void {
+    if (shouldLog('error')) {
+      process.stderr.write(formatMessage('error', message, meta) + '\n');
+    }
+  },
+};
+
+export default logger;

package/src/util/token-counter.ts

@@ -0,0 +1,52 @@
+/**
+ * Approximate token counter.
+ * Uses char_count / 4 heuristic - good enough for budget control.
+ * No external dependencies.
+ */
+
+/**
+ * Estimate token count for a string.
+ * Heuristic: ~4 characters per token (GPT-style tokenization average).
+ */
+export function estimateTokens(text: string): number {
+  if (!text) return 0;
+  return Math.ceil(text.length / 4);
+}
+
+/**
+ * Estimate token count for an array of strings (summed).
+ */
+export function estimateTokensForArray(texts: string[]): number {
+  return texts.reduce((sum, text) => sum + estimateTokens(text), 0);
+}
+
+/**
+ * Check if content fits within a token budget.
+ */
+export function fitsInBudget(text: string, budgetTokens: number): boolean {
+  return estimateTokens(text) <= budgetTokens;
+}
+
+/**
+ * Truncate text to approximately fit within a token budget.
+ * Truncates at word boundary when possible.
+ */
+export function truncateToTokenBudget(text: string, maxTokens: number): string {
+  const maxChars = maxTokens * 4;
+  if (text.length <= maxChars) return text;
+
+  // Try to truncate at a newline boundary
+  const truncated = text.slice(0, maxChars);
+  const lastNewline = truncated.lastIndexOf('\n');
+  if (lastNewline > maxChars * 0.8) {
+    return truncated.slice(0, lastNewline) + '\n... [truncated]';
+  }
+
+  // Fall back to word boundary
+  const lastSpace = truncated.lastIndexOf(' ');
+  if (lastSpace > maxChars * 0.8) {
+    return truncated.slice(0, lastSpace) + ' ... [truncated]';
+  }
+
+  return truncated + '... [truncated]';
+}