forge-server 0.1.0

package/src/storage/sqlite.ts

@@ -0,0 +1,168 @@
+// PipelineDB — thin wrapper around better-sqlite3 for the dk-forge-server.
+//
+// Responsibilities:
+// - Opens (or creates) the SQLite file at a configurable path.
+// - Enables WAL journal mode and foreign key enforcement on every connection.
+// - Runs the schema DDL via initialize() — idempotent; safe to call on startup.
+// - Provides run / get / all helpers so callers do not hold raw Statement refs.
+// - Performs an integrity check on open; if the database is corrupt, renames
+//   the file to <name>.corrupt.<timestamp>.db and opens a fresh database.
+//
+// Threading: better-sqlite3 is synchronous. All operations are blocking.
+// This is intentional — the MCP server is single-threaded Node.js; async
+// SQLite wrappers add complexity without benefit for our access patterns.
+
+import Database from 'better-sqlite3';
+import {
+  existsSync,
+  mkdirSync,
+  renameSync,
+} from 'node:fs';
+import { dirname, join } from 'node:path';
+import { homedir } from 'node:os';
+import { SCHEMA_SQL } from './schema.js';
+
+// Default location: ~/.forge/pipeline.db
+const DEFAULT_DB_PATH = join(homedir(), '.forge', 'pipeline.db');
+
+export class PipelineDB {
+  private _db: Database.Database | null = null;
+  private readonly filePath: string;
+
+  constructor(filePath: string = DEFAULT_DB_PATH) {
+    this.filePath = filePath;
+    this._db = this._open();
+  }
+
+  // ---------------------------------------------------------------------------
+  // Lifecycle
+  // ---------------------------------------------------------------------------
+
+  /** Run schema DDL. Idempotent — uses CREATE TABLE IF NOT EXISTS throughout. */
+  initialize(): void {
+    const db = this.db;
+    // Execute all statements in the schema in a single transaction.
+    // We split on ';' and filter empty strings so we can handle multi-statement
+    // schema strings cleanly.
+    db.transaction(() => {
+      const statements = SCHEMA_SQL
+        .split(';')
+        .map((s) => s.trim())
+        .filter((s) => s.length > 0);
+
+      for (const sql of statements) {
+        db.prepare(sql).run();
+      }
+    })();
+  }
+
+  /** Close the database connection. Safe to call multiple times. */
+  close(): void {
+    if (this._db && this._db.open) {
+      this._db.close();
+      this._db = null;
+    }
+  }
+
+  /** Raw better-sqlite3 Database instance. Throws if the connection is closed. */
+  get db(): Database.Database {
+    if (!this._db || !this._db.open) {
+      throw new Error('PipelineDB: database connection is closed');
+    }
+    return this._db;
+  }
+
+  // ---------------------------------------------------------------------------
+  // Query helpers
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Execute a statement that does not return rows (INSERT, UPDATE, DELETE).
+   * Returns the RunResult with lastInsertRowid and changes.
+   */
+  run(
+    sql: string,
+    params: readonly unknown[] | Record<string, unknown> = [],
+  ): Database.RunResult {
+    return this.db.prepare(sql).run(params as never);
+  }
+
+  /**
+   * Return a single row or undefined if no row matches.
+   * The caller supplies the expected row shape via the generic parameter T.
+   */
+  get<T = Record<string, unknown>>(
+    sql: string,
+    params: readonly unknown[] | Record<string, unknown> = [],
+  ): T | undefined {
+    return this.db.prepare(sql).get(params as never) as T | undefined;
+  }
+
+  /**
+   * Return all matching rows as an array.
+   * Returns an empty array when no rows match.
+   */
+  all<T = Record<string, unknown>>(
+    sql: string,
+    params: readonly unknown[] | Record<string, unknown> = [],
+  ): T[] {
+    return this.db.prepare(sql).all(params as never) as T[];
+  }
+
+  // ---------------------------------------------------------------------------
+  // Private helpers
+  // ---------------------------------------------------------------------------
+
+  private _open(): Database.Database {
+    // Ensure the directory exists before attempting to open the file.
+    const dir = dirname(this.filePath);
+    if (!existsSync(dir)) {
+      mkdirSync(dir, { recursive: true });
+    }
+
+    const db = new Database(this.filePath);
+
+    // Enable WAL mode for better concurrent read performance.
+    db.pragma('journal_mode = WAL');
+
+    // Enforce foreign key constraints — SQLite disables them by default.
+    db.pragma('foreign_keys = ON');
+
+    // Integrity check. If the database is corrupt we rename it and open fresh
+    // so the server can still start rather than crashing on every boot.
+    if (!this._integrityCheck(db)) {
+      db.close();
+
+      const timestamp = Date.now();
+      const corruptPath = this.filePath.replace(/\.db$/, '') + `.corrupt.${timestamp}.db`;
+      renameSync(this.filePath, corruptPath);
+      console.error(
+        `PipelineDB: integrity check failed. Corrupt database renamed to:\n  ${corruptPath}\n` +
+        `  A fresh database will be created at:\n  ${this.filePath}`,
+      );
+
+      // Open a fresh database at the original path.
+      const fresh = new Database(this.filePath);
+      fresh.pragma('journal_mode = WAL');
+      fresh.pragma('foreign_keys = ON');
+      return fresh;
+    }
+
+    return db;
+  }
+
+  /**
+   * Runs SQLite's built-in integrity_check pragma.
+   * Returns true if the database passes, false if it is corrupt or the check
+   * itself throws (which happens when the file header is completely invalid).
+   */
+  private _integrityCheck(db: Database.Database): boolean {
+    try {
+      const result = db.pragma('integrity_check') as Array<{ integrity_check: string }>;
+      // integrity_check returns one row with value "ok" when healthy.
+      return result.length === 1 && result[0]?.integrity_check === 'ok';
+    } catch {
+      return false;
+    }
+  }
+}

package/src/tools/collaboration-tools.ts

@@ -0,0 +1,208 @@
+// collaboration-tools.ts — Swarm Learning Phase 5
+// MCP tool handlers for cross-agent collaboration.
+// Tools: broadcast_finding, get_broadcasts
+
+import { z } from 'zod';
+import type { VectorStore, GraphStore } from '../storage/interfaces.js';
+import type { PipelineDB } from '../storage/sqlite.js';
+import { saveObservation } from '../memory/observation-store.js';
+import { getCurrentSessionId } from '../memory/session-tracker.js';
+import { logger } from '../util/logger.js';
+
+// ---------------------------------------------------------------------------
+// Input schemas
+// ---------------------------------------------------------------------------
+
+export const broadcastFindingSchema = z.object({
+  project_id: z.string().min(1, 'project_id is required'),
+  content: z.string().min(1, 'content is required'),
+  severity: z.enum(['info', 'warning', 'critical']).default('info'),
+  target_agents: z.array(z.string()).optional(),
+  symbols: z.array(z.string()).optional(),
+});
+
+export const getBroadcastsSchema = z.object({
+  project_id: z.string().min(1, 'project_id is required'),
+  since: z.number().optional(),
+  severity: z.enum(['info', 'warning', 'critical']).optional(),
+});
+
+// ---------------------------------------------------------------------------
+// Tool factory
+// ---------------------------------------------------------------------------
+
+export function createCollaborationTools(
+  vectorStore: VectorStore | null,
+  graphStore: GraphStore | null,
+  db: PipelineDB,
+) {
+  return {
+    'broadcast_finding': {
+      schema: broadcastFindingSchema,
+      description: 'Broadcast a finding to other agents working on the same project. MANDATORY during implementation — broadcast all interface changes, API contracts, schema changes, and blockers so sibling agents can react. Creates an observation and records in pipeline events.',
+      handler: async (input: z.infer<typeof broadcastFindingSchema>) => {
+        try {
+          let observationId: string | null = null;
+
+          // Save as observation if vector store is available
+          if (vectorStore) {
+            try {
+              const effectiveGraphStore = graphStore ?? createNoOpGraphStore();
+              const result = await saveObservation(
+                {
+                  content: input.content,
+                  symbols: input.symbols,
+                  importance: input.severity === 'critical' ? 0.9 : input.severity === 'warning' ? 0.7 : 0.5,
+                  tags: ['broadcast', 'agent_broadcast', input.project_id, input.severity],
+                  category: 'agent_broadcast',
+                  sessionId: getCurrentSessionId(),
+                  type: 'working',
+                  source: 'forge',
+                  metadata: {
+                    project_id: input.project_id,
+                    severity: input.severity,
+                    target_agents: input.target_agents,
+                  },
+                },
+                vectorStore,
+                effectiveGraphStore,
+                graphStore
+                  ? { writeVector: true, writeGraphNode: true, defaultNamespace: 'default' }
+                  : { writeVector: true, writeGraphNode: false, defaultNamespace: 'default' },
+              );
+              observationId = result.id;
+            } catch (err) {
+              logger.warn('broadcast_finding: observation save failed (non-fatal)', { error: String(err) });
+            }
+          }
+
+          // Record in SQLite pipeline_events
+          try {
+            db.run(
+              `INSERT INTO pipeline_events (project_id, event_type, from_phase, to_phase, agent, payload, created_at)
+               VALUES (?, ?, NULL, NULL, NULL, ?, ?)`,
+              [
+                input.project_id,
+                'agent_broadcast',
+                JSON.stringify({
+                  content: input.content,
+                  severity: input.severity,
+                  target_agents: input.target_agents,
+                  observation_id: observationId,
+                }),
+                Date.now(),
+              ],
+            );
+          } catch (err) {
+            logger.warn('broadcast_finding: event recording failed', { error: String(err) });
+          }
+
+          logger.debug('collaboration-tools.broadcast_finding: completed', {
+            projectId: input.project_id,
+            severity: input.severity,
+            observationId,
+          });
+
+          return {
+            broadcast: true,
+            observation_id: observationId,
+            severity: input.severity,
+            project_id: input.project_id,
+          };
+        } catch (err) {
+          logger.error('collaboration-tools.broadcast_finding: error', { error: String(err) });
+          return {
+            error: 'BROADCAST_FINDING_FAILED',
+            message: String(err),
+            broadcast: false,
+          };
+        }
+      },
+    },
+
+    'get_broadcasts': {
+      schema: getBroadcastsSchema,
+      description: 'Get recent broadcasts for a project. ALWAYS CALL THIS at the start of implementation to see what sibling agents have discovered. Filter by severity or time range.',
+      handler: async (input: z.infer<typeof getBroadcastsSchema>) => {
+        try {
+          // Query from SQLite pipeline_events
+          let query = `SELECT * FROM pipeline_events WHERE project_id = ? AND event_type = 'agent_broadcast'`;
+          const params: unknown[] = [input.project_id];
+
+          if (input.since) {
+            query += ` AND created_at >= ?`;
+            params.push(input.since);
+          }
+
+          query += ` ORDER BY created_at DESC LIMIT 50`;
+
+          const rows = db.all<{
+            id: number;
+            project_id: string;
+            payload: string;
+            created_at: number;
+          }>(query, params);
+
+          let broadcasts = rows.map(row => {
+            let payload: Record<string, unknown> = {};
+            try {
+              payload = JSON.parse(row.payload) as Record<string, unknown>;
+            } catch {}
+
+            return {
+              id: row.id,
+              content: String(payload.content ?? ''),
+              severity: String(payload.severity ?? 'info'),
+              target_agents: (payload.target_agents as string[] | undefined) ?? [],
+              observation_id: payload.observation_id as string | undefined,
+              created_at: row.created_at,
+            };
+          });
+
+          // Filter by severity if specified
+          if (input.severity) {
+            broadcasts = broadcasts.filter(b => b.severity === input.severity);
+          }
+
+          logger.debug('collaboration-tools.get_broadcasts: completed', {
+            projectId: input.project_id,
+            count: broadcasts.length,
+          });
+
+          return {
+            project_id: input.project_id,
+            broadcasts,
+            count: broadcasts.length,
+          };
+        } catch (err) {
+          logger.error('collaboration-tools.get_broadcasts: error', { error: String(err) });
+          return {
+            error: 'GET_BROADCASTS_FAILED',
+            message: String(err),
+            broadcasts: [],
+            count: 0,
+          };
+        }
+      },
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// No-op graph store
+// ---------------------------------------------------------------------------
+
+function createNoOpGraphStore(): GraphStore {
+  return {
+    connect: async () => {},
+    disconnect: async () => {},
+    isHealthy: async () => false,
+    query: async () => ({ nodes: [], edges: [], raw: [] }),
+    upsertNode: async () => {},
+    upsertEdge: async () => {},
+    deleteFile: async () => {},
+    deleteRepo: async () => {},
+    getCounts: async () => ({ totalNodes: 0, totalEdges: 0, byLabel: {} }),
+    ensureIndexes: async () => {},
+  };
+}