@weavelogic/knowledge-graph-agent 0.3.0 → 0.6.0

package/dist/dashboard-server/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","sources":["../../src/dashboard-server/server.ts"],"sourcesContent":["/**\n * Dashboard Server\n *\n * Server integration for the Knowledge Graph Dashboard.\n * Supports running Next.js in development and production modes,\n * with programmatic control and concurrent server support.\n *\n * @module dashboard/server\n */\n\nimport { EventEmitter } from 'events';\nimport { spawn, ChildProcess, exec } from 'child_process';\nimport { createServer, Server as HTTPServer, IncomingMessage, ServerResponse } from 'http';\nimport { join, dirname } from 'path';\nimport { existsSync, readFileSync, statSync } from 'fs';\nimport { fileURLToPath } from 'url';\nimport { createLogger } from '../utils/index.js';\nimport {\n  DEFAULT_DASHBOARD_PORT,\n  DEFAULT_GRAPHQL_PORT,\n} from '../server/types.js';\n\n/**\n * Execute a command asynchronously\n */\nfunction execAsync(command: string, options?: { cwd?: string; env?: NodeJS.ProcessEnv }): Promise<{ stdout: string; stderr: string }> {\n  return new Promise((resolve, reject) => {\n    exec(command, options, (error, stdout, stderr) => {\n      if (error) {\n        reject(error);\n      } else {\n        resolve({ stdout: stdout.toString(), stderr: stderr.toString() });\n      }\n    });\n  });\n}\nconst logger = createLogger('dashboard-server');\n\n// ============================================================================\n// Types\n// ============================================================================\n\n/**\n * Dashboard server mode\n */\nexport type DashboardMode = 'development' | 'production';\n\n/**\n * Dashboard server configuration\n */\nexport interface DashboardConfig {\n  /** Project root directory */\n  projectRoot: string;\n  /** Port to listen on */\n  port: number;\n  /** GraphQL server endpoint URL */\n  graphqlEndpoint: string;\n  /** Server mode (development or production) */\n  mode: DashboardMode;\n  /** Output directory for production build */\n  outputDir?: string;\n  /** Enable verbose logging */\n  verbose?: boolean;\n  /** Path to dashboard source (defaults to dashboard/ in project) */\n  dashboardPath?: string;\n}\n\n/**\n * Dashboard server status\n */\nexport type DashboardStatus = 'stopped' | 'starting' | 'running' | 'stopping' | 'error';\n\n/**\n * Dashboard server state\n */\nexport interface DashboardState {\n  /** Current status */\n  status: DashboardStatus;\n  /** Port the server is listening on */\n  port?: number;\n  /** GraphQL endpoint being used */\n  graphqlEndpoint?: string;\n  /** When the server started */\n  startedAt?: Date;\n  /** Error message if status is 'error' */\n  error?: string;\n  /** Server mode */\n  mode?: DashboardMode;\n  /** Whether GraphQL connection is established */\n  graphqlConnected?: boolean;\n}\n\n/**\n * Dashboard server event types\n */\nexport type DashboardEventType =\n  | 'starting'\n  | 'started'\n  | 'stopping'\n  | 'stopped'\n  | 'error'\n  | 'build:started'\n  | 'build:completed'\n  | 'build:failed'\n  | 'graphql:connected'\n  | 'graphql:disconnected';\n\n/**\n * Dashboard server interface\n */\nexport interface IDashboardServer {\n  /** Start the dashboard server */\n  start(): Promise<void>;\n  /** Stop the dashboard server */\n  stop(): Promise<void>;\n  /** Build the dashboard for production */\n  build(): Promise<void>;\n  /** Get current server state */\n  getState(): DashboardState;\n  /** Check GraphQL connection */\n  checkGraphQLConnection(): Promise<boolean>;\n  /** Wait for the server to shutdown (blocks until stopped) */\n  waitForShutdown(): Promise<void>;\n  /** Subscribe to events */\n  on(event: DashboardEventType, listener: (...args: unknown[]) => void): void;\n  /** Unsubscribe from events */\n  off(event: DashboardEventType, listener: (...args: unknown[]) => void): void;\n}\n\n// ============================================================================\n// Constants\n// ============================================================================\n\nconst STARTUP_TIMEOUT = 30000; // 30 seconds\nconst SHUTDOWN_TIMEOUT = 10000; // 10 seconds\nconst GRAPHQL_CHECK_INTERVAL = 5000; // 5 seconds\nconst RECONNECT_DELAY = 3000; // 3 seconds\n\n// MIME types for static file serving\nconst MIME_TYPES: Record<string, string> = {\n  '.html': 'text/html',\n  '.js': 'application/javascript',\n  '.css': 'text/css',\n  '.json': 'application/json',\n  '.png': 'image/png',\n  '.jpg': 'image/jpeg',\n  '.jpeg': 'image/jpeg',\n  '.gif': 'image/gif',\n  '.svg': 'image/svg+xml',\n  '.ico': 'image/x-icon',\n  '.woff': 'font/woff',\n  '.woff2': 'font/woff2',\n  '.ttf': 'font/ttf',\n  '.eot': 'application/vnd.ms-fontobject',\n};\n\n// ============================================================================\n// Dashboard Server Implementation\n// ============================================================================\n\n/**\n * DashboardServer\n *\n * Manages the Knowledge Graph Dashboard web interface.\n * Supports both development (with hot reload) and production modes.\n *\n * @example\n * ```typescript\n * const server = new DashboardServer({\n *   projectRoot: process.cwd(),\n *   port: 3000,\n *   graphqlEndpoint: 'http://localhost:4000/graphql',\n *   mode: 'development',\n * });\n *\n * await server.start();\n *\n * // Later...\n * await server.stop();\n * ```\n */\nexport class DashboardServer implements IDashboardServer {\n  private config: DashboardConfig;\n  private state: DashboardState;\n  private eventEmitter: EventEmitter;\n  private childProcess: ChildProcess | null = null;\n  private httpServer: HTTPServer | null = null;\n  private graphqlCheckInterval: NodeJS.Timeout | null = null;\n  private shutdownPromise: Promise<void> | null = null;\n  private shutdownResolve: (() => void) | null = null;\n\n  constructor(config: DashboardConfig) {\n    this.config = {\n      ...config,\n      dashboardPath: config.dashboardPath ?? this.detectDashboardPath(config.projectRoot),\n    };\n\n    this.state = {\n      status: 'stopped',\n    };\n\n    this.eventEmitter = new EventEmitter();\n    this.eventEmitter.setMaxListeners(50);\n\n    logger.debug('DashboardServer created', {\n      port: config.port,\n      mode: config.mode,\n      graphqlEndpoint: config.graphqlEndpoint,\n    });\n  }\n\n  // ============================================================================\n  // Path Detection\n  // ============================================================================\n\n  /**\n   * Detect the dashboard path\n   */\n  private detectDashboardPath(projectRoot: string): string {\n    // Check common locations\n    const candidates = [\n      join(projectRoot, 'dashboard'),\n      join(projectRoot, 'src', 'dashboard'),\n      join(projectRoot, 'packages', 'dashboard'),\n      join(projectRoot, '..', 'dashboard'),\n    ];\n\n    for (const candidate of candidates) {\n      if (existsSync(join(candidate, 'package.json'))) {\n        logger.debug('Found dashboard at', { path: candidate });\n        return candidate;\n      }\n    }\n\n    // Default to projectRoot/dashboard (will be created if needed)\n    return join(projectRoot, 'dashboard');\n  }\n\n  /**\n   * Check if dashboard is installed\n   */\n  private isDashboardInstalled(): boolean {\n    const dashboardPath = this.config.dashboardPath!;\n    return existsSync(join(dashboardPath, 'package.json'));\n  }\n\n  // ============================================================================\n  // Server Lifecycle\n  // ============================================================================\n\n  /**\n   * Start the dashboard server\n   */\n  async start(): Promise<void> {\n    if (this.state.status === 'running') {\n      logger.warn('Dashboard server already running');\n      return;\n    }\n\n    this.state.status = 'starting';\n    this.emit('starting');\n\n    try {\n      if (this.config.mode === 'development') {\n        await this.startDevelopmentServer();\n      } else {\n        await this.startProductionServer();\n      }\n\n      this.state.status = 'running';\n      this.state.port = this.config.port;\n      this.state.graphqlEndpoint = this.config.graphqlEndpoint;\n      this.state.mode = this.config.mode;\n      this.state.startedAt = new Date();\n\n      this.emit('started');\n\n      // Start GraphQL connection monitoring\n      this.startGraphQLMonitoring();\n\n      // Setup shutdown promise\n      this.shutdownPromise = new Promise((resolve) => {\n        this.shutdownResolve = resolve;\n      });\n\n      logger.info('Dashboard server started', {\n        port: this.config.port,\n        mode: this.config.mode,\n      });\n    } catch (error) {\n      this.state.status = 'error';\n      this.state.error = error instanceof Error ? error.message : String(error);\n      this.emit('error', error);\n      throw error;\n    }\n  }\n\n  /**\n   * Start the development server (Next.js dev)\n   */\n  private async startDevelopmentServer(): Promise<void> {\n    const dashboardPath = this.config.dashboardPath!;\n\n    // Check if dashboard is installed\n    if (!this.isDashboardInstalled()) {\n      // For now, we'll use a fallback static server\n      logger.warn('Dashboard not installed, using fallback static server');\n      await this.startFallbackServer();\n      return;\n    }\n\n    // Set environment variables for the dashboard\n    const env = {\n      ...process.env,\n      PORT: String(this.config.port),\n      NEXT_PUBLIC_GRAPHQL_ENDPOINT: this.config.graphqlEndpoint,\n      NEXT_PUBLIC_API_URL: this.config.graphqlEndpoint.replace('/graphql', ''),\n    };\n\n    // Start Next.js dev server\n    return new Promise((resolve, reject) => {\n      const timeout = setTimeout(() => {\n        reject(new Error(`Dashboard startup timed out after ${STARTUP_TIMEOUT}ms`));\n      }, STARTUP_TIMEOUT);\n\n      this.childProcess = spawn('npm', ['run', 'dev'], {\n        cwd: dashboardPath,\n        env,\n        stdio: this.config.verbose ? 'inherit' : 'pipe',\n        shell: true,\n      });\n\n      this.childProcess.on('error', (error) => {\n        clearTimeout(timeout);\n        reject(error);\n      });\n\n      this.childProcess.on('exit', (code) => {\n        if (code !== 0 && this.state.status === 'starting') {\n          clearTimeout(timeout);\n          reject(new Error(`Dashboard process exited with code ${code}`));\n        }\n      });\n\n      if (this.childProcess.stdout && !this.config.verbose) {\n        this.childProcess.stdout.on('data', (data: Buffer) => {\n          const output = data.toString();\n          if (output.includes('Ready') || output.includes('started')) {\n            clearTimeout(timeout);\n            resolve();\n          }\n          if (this.config.verbose) {\n            process.stdout.write(data);\n          }\n        });\n      }\n\n      // For verbose mode or fallback, resolve after a delay\n      if (this.config.verbose || !this.childProcess.stdout) {\n        setTimeout(() => {\n          clearTimeout(timeout);\n          resolve();\n        }, 3000);\n      }\n    });\n  }\n\n  /**\n   * Start the production server (Next.js start or static file server)\n   */\n  private async startProductionServer(): Promise<void> {\n    const dashboardPath = this.config.dashboardPath!;\n    const buildPath = join(dashboardPath, '.next');\n\n    // Check if production build exists\n    if (!existsSync(buildPath)) {\n      logger.warn('Production build not found, using fallback server');\n      await this.startFallbackServer();\n      return;\n    }\n\n    // Set environment variables\n    const env = {\n      ...process.env,\n      PORT: String(this.config.port),\n      NEXT_PUBLIC_GRAPHQL_ENDPOINT: this.config.graphqlEndpoint,\n      NODE_ENV: 'production',\n    };\n\n    // Start Next.js production server\n    return new Promise((resolve, reject) => {\n      const timeout = setTimeout(() => {\n        reject(new Error(`Dashboard startup timed out after ${STARTUP_TIMEOUT}ms`));\n      }, STARTUP_TIMEOUT);\n\n      this.childProcess = spawn('npm', ['run', 'start'], {\n        cwd: dashboardPath,\n        env,\n        stdio: this.config.verbose ? 'inherit' : 'pipe',\n        shell: true,\n      });\n\n      this.childProcess.on('error', (error) => {\n        clearTimeout(timeout);\n        reject(error);\n      });\n\n      if (this.childProcess.stdout && !this.config.verbose) {\n        this.childProcess.stdout.on('data', (data: Buffer) => {\n          const output = data.toString();\n          if (output.includes('Ready') || output.includes('started')) {\n            clearTimeout(timeout);\n            resolve();\n          }\n        });\n      }\n\n      // Fallback resolve after delay\n      setTimeout(() => {\n        clearTimeout(timeout);\n        resolve();\n      }, 3000);\n    });\n  }\n\n  /**\n   * Start a fallback static server when dashboard is not installed\n   */\n  private async startFallbackServer(): Promise<void> {\n    return new Promise((resolve, reject) => {\n      this.httpServer = createServer((req: IncomingMessage, res: ServerResponse) => {\n        this.handleFallbackRequest(req, res);\n      });\n\n      this.httpServer.on('error', (error: NodeJS.ErrnoException) => {\n        if (error.code === 'EADDRINUSE') {\n          reject(new Error(`Port ${this.config.port} is already in use`));\n        } else {\n          reject(error);\n        }\n      });\n\n      this.httpServer.listen(this.config.port, () => {\n        logger.info('Fallback dashboard server started', { port: this.config.port });\n        resolve();\n      });\n    });\n  }\n\n  /**\n   * Handle requests to the fallback server\n   */\n  private handleFallbackRequest(req: IncomingMessage, res: ServerResponse): void {\n    const url = req.url ?? '/';\n\n    // API endpoints\n    if (url === '/api/health') {\n      res.writeHead(200, { 'Content-Type': 'application/json' });\n      res.end(JSON.stringify({\n        status: 'ok',\n        server: 'dashboard',\n        mode: this.config.mode,\n        graphqlEndpoint: this.config.graphqlEndpoint,\n        graphqlConnected: this.state.graphqlConnected ?? false,\n      }));\n      return;\n    }\n\n    if (url === '/api/status') {\n      res.writeHead(200, { 'Content-Type': 'application/json' });\n      res.end(JSON.stringify(this.getState()));\n      return;\n    }\n\n    if (url === '/api/config') {\n      res.writeHead(200, { 'Content-Type': 'application/json' });\n      res.end(JSON.stringify({\n        graphqlEndpoint: this.config.graphqlEndpoint,\n        port: this.config.port,\n        mode: this.config.mode,\n      }));\n      return;\n    }\n\n    // Serve fallback HTML page\n    res.writeHead(200, { 'Content-Type': 'text/html' });\n    res.end(this.getFallbackHTML());\n  }\n\n  /**\n   * Get fallback HTML when dashboard is not fully installed\n   */\n  private getFallbackHTML(): string {\n    const graphqlEndpoint = this.config.graphqlEndpoint;\n    const mode = this.config.mode;\n\n    return `<!DOCTYPE html>\n<html lang=\"en\">\n<head>\n  <meta charset=\"UTF-8\">\n  <meta name=\"viewport\" content=\"width=device-width, initial-scale=1.0\">\n  <title>Knowledge Graph Dashboard</title>\n  <style>\n    * { margin: 0; padding: 0; box-sizing: border-box; }\n    body {\n      font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;\n      background: linear-gradient(135deg, #1a1a2e 0%, #16213e 100%);\n      color: #e0e0e0;\n      min-height: 100vh;\n      display: flex;\n      flex-direction: column;\n      align-items: center;\n      justify-content: center;\n    }\n    .container { text-align: center; padding: 2rem; max-width: 600px; }\n    h1 { font-size: 2.5rem; margin-bottom: 1rem; color: #00d4ff; }\n    p { font-size: 1.1rem; margin-bottom: 1.5rem; opacity: 0.8; line-height: 1.6; }\n    .status {\n      display: flex;\n      gap: 1.5rem;\n      justify-content: center;\n      flex-wrap: wrap;\n      margin: 2rem 0;\n    }\n    .card {\n      background: rgba(255,255,255,0.05);\n      border: 1px solid rgba(255,255,255,0.1);\n      border-radius: 12px;\n      padding: 1.5rem;\n      min-width: 180px;\n      transition: transform 0.2s, border-color 0.2s;\n    }\n    .card:hover {\n      transform: translateY(-2px);\n      border-color: rgba(0, 212, 255, 0.3);\n    }\n    .card h3 { color: #00d4ff; font-size: 0.85rem; text-transform: uppercase; letter-spacing: 0.05em; margin-bottom: 0.75rem; }\n    .card .value { font-size: 1.4rem; font-weight: 600; }\n    .connected { color: #00ff88; }\n    .disconnected { color: #ff6b6b; }\n    .mode-dev { color: #ffcc00; }\n    .mode-prod { color: #00d4ff; }\n    .indicator {\n      display: inline-block;\n      width: 10px;\n      height: 10px;\n      border-radius: 50%;\n      margin-right: 8px;\n      animation: pulse 2s infinite;\n    }\n    .indicator.connected { background: #00ff88; }\n    .indicator.disconnected { background: #ff6b6b; }\n    @keyframes pulse {\n      0%, 100% { opacity: 1; }\n      50% { opacity: 0.5; }\n    }\n    .actions {\n      margin-top: 2rem;\n      padding-top: 2rem;\n      border-top: 1px solid rgba(255,255,255,0.1);\n    }\n    .actions a {\n      display: inline-block;\n      padding: 0.75rem 1.5rem;\n      background: linear-gradient(135deg, #00d4ff 0%, #0066ff 100%);\n      color: white;\n      text-decoration: none;\n      border-radius: 8px;\n      font-weight: 500;\n      margin: 0.5rem;\n      transition: transform 0.2s, box-shadow 0.2s;\n    }\n    .actions a:hover {\n      transform: translateY(-2px);\n      box-shadow: 0 4px 20px rgba(0, 212, 255, 0.3);\n    }\n    .info {\n      margin-top: 2rem;\n      font-size: 0.9rem;\n      opacity: 0.6;\n    }\n    code {\n      background: rgba(255,255,255,0.1);\n      padding: 0.2rem 0.5rem;\n      border-radius: 4px;\n      font-size: 0.85em;\n    }\n  </style>\n</head>\n<body>\n  <div class=\"container\">\n    <h1>Knowledge Graph Dashboard</h1>\n    <p>The dashboard server is running. Connect to explore your knowledge graph visually.</p>\n\n    <div class=\"status\" id=\"status\">\n      <div class=\"card\">\n        <h3>GraphQL Server</h3>\n        <div class=\"value\" id=\"graphql-status\">\n          <span class=\"indicator disconnected\" id=\"graphql-indicator\"></span>\n          <span id=\"graphql-text\">Checking...</span>\n        </div>\n      </div>\n      <div class=\"card\">\n        <h3>Dashboard Mode</h3>\n        <div class=\"value ${mode === 'development' ? 'mode-dev' : 'mode-prod'}\">${mode}</div>\n      </div>\n      <div class=\"card\">\n        <h3>Endpoint</h3>\n        <div class=\"value\" style=\"font-size: 0.9rem; word-break: break-all;\">${graphqlEndpoint}</div>\n      </div>\n    </div>\n\n    <div class=\"actions\">\n      <a href=\"${graphqlEndpoint.replace('/graphql', '/graphql')}\" target=\"_blank\">GraphQL Playground</a>\n      <a href=\"/api/health\">Health Check</a>\n    </div>\n\n    <div class=\"info\">\n      <p>For the full dashboard experience, install the dashboard package:</p>\n      <p><code>npm run dashboard:install</code></p>\n    </div>\n  </div>\n\n  <script>\n    async function checkGraphQL() {\n      const indicator = document.getElementById('graphql-indicator');\n      const text = document.getElementById('graphql-text');\n\n      try {\n        const res = await fetch('${graphqlEndpoint}', {\n          method: 'POST',\n          headers: { 'Content-Type': 'application/json' },\n          body: JSON.stringify({ query: '{ __typename }' }),\n        });\n\n        if (res.ok) {\n          indicator.className = 'indicator connected';\n          text.textContent = 'Connected';\n          text.className = 'connected';\n        } else {\n          throw new Error('Not OK');\n        }\n      } catch (e) {\n        indicator.className = 'indicator disconnected';\n        text.textContent = 'Disconnected';\n        text.className = 'disconnected';\n      }\n    }\n\n    // Initial check\n    checkGraphQL();\n\n    // Check every 5 seconds\n    setInterval(checkGraphQL, 5000);\n  </script>\n</body>\n</html>`;\n  }\n\n  /**\n   * Stop the dashboard server\n   */\n  async stop(): Promise<void> {\n    if (this.state.status === 'stopped') {\n      logger.debug('Dashboard server already stopped');\n      return;\n    }\n\n    this.state.status = 'stopping';\n    this.emit('stopping');\n\n    try {\n      // Stop GraphQL monitoring\n      this.stopGraphQLMonitoring();\n\n      // Stop child process (Next.js server)\n      if (this.childProcess) {\n        await this.killChildProcess();\n        this.childProcess = null;\n      }\n\n      // Stop HTTP server (fallback server)\n      if (this.httpServer) {\n        await this.closeHttpServer();\n        this.httpServer = null;\n      }\n\n      this.state.status = 'stopped';\n      this.state.port = undefined;\n      this.state.startedAt = undefined;\n      this.state.graphqlConnected = undefined;\n\n      this.emit('stopped');\n\n      // Resolve shutdown promise\n      if (this.shutdownResolve) {\n        this.shutdownResolve();\n        this.shutdownResolve = null;\n        this.shutdownPromise = null;\n      }\n\n      logger.info('Dashboard server stopped');\n    } catch (error) {\n      this.state.status = 'error';\n      this.state.error = error instanceof Error ? error.message : String(error);\n      this.emit('error', error);\n      throw error;\n    }\n  }\n\n  /**\n   * Kill the child process\n   */\n  private async killChildProcess(): Promise<void> {\n    if (!this.childProcess) return;\n\n    return new Promise((resolve) => {\n      const timeout = setTimeout(() => {\n        // Force kill if graceful shutdown fails\n        this.childProcess?.kill('SIGKILL');\n        resolve();\n      }, SHUTDOWN_TIMEOUT);\n\n      this.childProcess?.on('exit', () => {\n        clearTimeout(timeout);\n        resolve();\n      });\n\n      // Send SIGTERM for graceful shutdown\n      this.childProcess?.kill('SIGTERM');\n    });\n  }\n\n  /**\n   * Close the HTTP server\n   */\n  private async closeHttpServer(): Promise<void> {\n    if (!this.httpServer) return;\n\n    return new Promise((resolve, reject) => {\n      this.httpServer!.close((err) => {\n        if (err) {\n          reject(err);\n        } else {\n          resolve();\n        }\n      });\n    });\n  }\n\n  // ============================================================================\n  // Build\n  // ============================================================================\n\n  /**\n   * Build the dashboard for production\n   */\n  async build(): Promise<void> {\n    const dashboardPath = this.config.dashboardPath!;\n\n    if (!this.isDashboardInstalled()) {\n      throw new Error('Dashboard not installed. Run npm run dashboard:install first.');\n    }\n\n    this.emit('build:started');\n\n    try {\n      // Set environment variables\n      const env = {\n        ...process.env,\n        NEXT_PUBLIC_GRAPHQL_ENDPOINT: this.config.graphqlEndpoint,\n        NODE_ENV: 'production',\n      };\n\n      // Run build command\n      await execAsync('npm run build', {\n        cwd: dashboardPath,\n        env,\n      });\n\n      this.emit('build:completed');\n      logger.info('Dashboard build completed');\n    } catch (error) {\n      this.emit('build:failed', error);\n      throw error;\n    }\n  }\n\n  // ============================================================================\n  // GraphQL Connection Monitoring\n  // ============================================================================\n\n  /**\n   * Start GraphQL connection monitoring\n   */\n  private startGraphQLMonitoring(): void {\n    // Initial check\n    this.checkGraphQLConnection().then((connected) => {\n      this.state.graphqlConnected = connected;\n      if (connected) {\n        this.emit('graphql:connected');\n      } else {\n        this.emit('graphql:disconnected');\n      }\n    });\n\n    // Periodic checks\n    this.graphqlCheckInterval = setInterval(async () => {\n      const wasConnected = this.state.graphqlConnected;\n      const isConnected = await this.checkGraphQLConnection();\n\n      if (wasConnected !== isConnected) {\n        this.state.graphqlConnected = isConnected;\n        if (isConnected) {\n          this.emit('graphql:connected');\n          logger.info('GraphQL connection established');\n        } else {\n          this.emit('graphql:disconnected');\n          logger.warn('GraphQL connection lost');\n        }\n      }\n    }, GRAPHQL_CHECK_INTERVAL);\n  }\n\n  /**\n   * Stop GraphQL connection monitoring\n   */\n  private stopGraphQLMonitoring(): void {\n    if (this.graphqlCheckInterval) {\n      clearInterval(this.graphqlCheckInterval);\n      this.graphqlCheckInterval = null;\n    }\n  }\n\n  /**\n   * Check if GraphQL connection is available\n   */\n  async checkGraphQLConnection(): Promise<boolean> {\n    try {\n      const controller = new AbortController();\n      const timeout = setTimeout(() => controller.abort(), 3000);\n\n      const response = await fetch(this.config.graphqlEndpoint, {\n        method: 'POST',\n        headers: { 'Content-Type': 'application/json' },\n        body: JSON.stringify({ query: '{ __typename }' }),\n        signal: controller.signal,\n      });\n\n      clearTimeout(timeout);\n      return response.ok;\n    } catch {\n      return false;\n    }\n  }\n\n  // ============================================================================\n  // State & Events\n  // ============================================================================\n\n  /**\n   * Get current server state\n   */\n  getState(): DashboardState {\n    return { ...this.state };\n  }\n\n  /**\n   * Wait for the server to shutdown\n   */\n  async waitForShutdown(): Promise<void> {\n    if (this.shutdownPromise) {\n      return this.shutdownPromise;\n    }\n\n    // If not running, resolve immediately\n    if (this.state.status === 'stopped') {\n      return Promise.resolve();\n    }\n\n    // Create new promise if somehow missing\n    return new Promise((resolve) => {\n      this.shutdownResolve = resolve;\n    });\n  }\n\n  /**\n   * Emit an event\n   */\n  private emit(event: DashboardEventType, data?: unknown): void {\n    this.eventEmitter.emit(event, data);\n  }\n\n  /**\n   * Subscribe to events\n   */\n  on(event: DashboardEventType, listener: (...args: unknown[]) => void): void {\n    this.eventEmitter.on(event, listener);\n  }\n\n  /**\n   * Unsubscribe from events\n   */\n  off(event: DashboardEventType, listener: (...args: unknown[]) => void): void {\n    this.eventEmitter.off(event, listener);\n  }\n\n  /**\n   * Subscribe to an event once\n   */\n  once(event: DashboardEventType, listener: (...args: unknown[]) => void): void {\n    this.eventEmitter.once(event, listener);\n  }\n}\n\n// ============================================================================\n// Factory Functions\n// ============================================================================\n\n/**\n * Create a new dashboard server instance\n */\nexport function createDashboardServer(config: DashboardConfig): DashboardServer {\n  return new DashboardServer(config);\n}\n\n/**\n * Create dashboard configuration with defaults\n */\nexport function createDashboardConfig(\n  projectRoot: string,\n  overrides?: Partial<DashboardConfig>\n): DashboardConfig {\n  return {\n    projectRoot,\n    port: DEFAULT_DASHBOARD_PORT,\n    graphqlEndpoint: `http://localhost:${DEFAULT_GRAPHQL_PORT}/graphql`,\n    mode: process.env.NODE_ENV === 'production' ? 'production' : 'development',\n    ...overrides,\n  };\n}\n"],"names":[],"mappings":"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"}

package/dist/database/schemas/index.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Database Schemas
+ *
+ * Exports SQL schema definitions for PostgreSQL integration.
+ * Provides utilities for loading and managing RuVector and Exochain schemas.
+ *
+ * @module database/schemas
+ */
+/**
+ * Schema names supported by the system
+ */
+export type SchemaName = 'ruvector' | 'exochain';
+/**
+ * Load a SQL schema file from disk
+ *
+ * @param name - The schema name to load ('ruvector' or 'exochain')
+ * @returns The SQL schema content as a string
+ * @throws Error if the schema file cannot be read
+ *
+ * @example
+ * ```typescript
+ * const ruvectorSchema = loadSchema('ruvector');
+ * await pgClient.query(ruvectorSchema);
+ * ```
+ */
+export declare function loadSchema(name: SchemaName): string;
+/**
+ * Get all available schemas
+ *
+ * @returns A record mapping schema names to their SQL content
+ *
+ * @example
+ * ```typescript
+ * const schemas = getAllSchemas();
+ * for (const [name, sql] of Object.entries(schemas)) {
+ *   console.log(`Loading schema: ${name}`);
+ *   await pgClient.query(sql);
+ * }
+ * ```
+ */
+export declare function getAllSchemas(): Record<SchemaName, string>;
+/**
+ * Check if a schema name is valid
+ *
+ * @param name - The schema name to validate
+ * @returns True if the schema name is valid
+ *
+ * @example
+ * ```typescript
+ * if (isValidSchemaName('ruvector')) {
+ *   const schema = loadSchema('ruvector');
+ * }
+ * ```
+ */
+export declare function isValidSchemaName(name: string): name is SchemaName;
+/**
+ * Get the list of available schema names
+ *
+ * @returns Array of available schema names
+ *
+ * @example
+ * ```typescript
+ * const names = getSchemaNames(); // ['ruvector', 'exochain']
+ * ```
+ */
+export declare function getSchemaNames(): SchemaName[];
+/**
+ * RuVector schema SQL (inline for bundled distribution)
+ *
+ * This constant provides a minimal inline version of the RuVector schema
+ * for use cases where file system access is not available (e.g., bundled builds).
+ *
+ * For the full schema with all functions and triggers, use loadSchema('ruvector').
+ */
+export declare const RUVECTOR_SCHEMA = "\n-- Inline RuVector schema for bundled distribution\nCREATE SCHEMA IF NOT EXISTS ruvector;\n\nCREATE TABLE IF NOT EXISTS ruvector.embeddings (\n  id TEXT PRIMARY KEY,\n  node_type TEXT NOT NULL,\n  embedding REAL[] NOT NULL,\n  dimensions INTEGER NOT NULL,\n  metadata JSONB DEFAULT '{}',\n  created_at TIMESTAMPTZ DEFAULT NOW(),\n  updated_at TIMESTAMPTZ DEFAULT NOW()\n);\n\nCREATE INDEX IF NOT EXISTS idx_embeddings_node_type\nON ruvector.embeddings(node_type);\n\nCREATE INDEX IF NOT EXISTS idx_embeddings_metadata\nON ruvector.embeddings USING GIN (metadata);\n\nCREATE TABLE IF NOT EXISTS ruvector.trajectories (\n  id TEXT PRIMARY KEY,\n  agent_id TEXT NOT NULL,\n  workflow_id TEXT,\n  steps JSONB DEFAULT '[]',\n  started_at TIMESTAMPTZ NOT NULL,\n  completed_at TIMESTAMPTZ,\n  success BOOLEAN DEFAULT FALSE,\n  total_duration INTEGER DEFAULT 0,\n  metadata JSONB DEFAULT '{}'\n);\n\nCREATE INDEX IF NOT EXISTS idx_trajectories_agent_id\nON ruvector.trajectories(agent_id);\n\nCREATE INDEX IF NOT EXISTS idx_trajectories_workflow_id\nON ruvector.trajectories(workflow_id);\n\nCREATE INDEX IF NOT EXISTS idx_trajectories_success\nON ruvector.trajectories(success);\n\nCREATE TABLE IF NOT EXISTS ruvector.patterns (\n  id TEXT PRIMARY KEY,\n  pattern_type TEXT NOT NULL,\n  actions TEXT[] NOT NULL,\n  frequency INTEGER DEFAULT 1,\n  avg_duration REAL DEFAULT 0,\n  success_rate REAL DEFAULT 0,\n  confidence REAL DEFAULT 0,\n  metadata JSONB DEFAULT '{}',\n  created_at TIMESTAMPTZ DEFAULT NOW(),\n  updated_at TIMESTAMPTZ DEFAULT NOW()\n);\n\nCREATE INDEX IF NOT EXISTS idx_patterns_type\nON ruvector.patterns(pattern_type);\n\nCREATE INDEX IF NOT EXISTS idx_patterns_confidence\nON ruvector.patterns(confidence);\n\nCREATE TABLE IF NOT EXISTS ruvector.learning_records (\n  id SERIAL PRIMARY KEY,\n  trajectory_id TEXT NOT NULL REFERENCES ruvector.trajectories(id),\n  pattern_id TEXT NOT NULL REFERENCES ruvector.patterns(id),\n  pattern_type TEXT NOT NULL,\n  confidence REAL NOT NULL,\n  learned_at TIMESTAMPTZ DEFAULT NOW(),\n  applied_count INTEGER DEFAULT 0\n);\n\nCREATE INDEX IF NOT EXISTS idx_learning_records_pattern\nON ruvector.learning_records(pattern_id);\n\nCREATE TABLE IF NOT EXISTS ruvector.graph_nodes (\n  id TEXT PRIMARY KEY,\n  node_type TEXT NOT NULL,\n  properties JSONB DEFAULT '{}',\n  embedding_id TEXT REFERENCES ruvector.embeddings(id),\n  created_at TIMESTAMPTZ DEFAULT NOW(),\n  updated_at TIMESTAMPTZ DEFAULT NOW()\n);\n\nCREATE INDEX IF NOT EXISTS idx_graph_nodes_type\nON ruvector.graph_nodes(node_type);\n\nCREATE INDEX IF NOT EXISTS idx_graph_nodes_properties\nON ruvector.graph_nodes USING GIN (properties);\n\nCREATE TABLE IF NOT EXISTS ruvector.graph_edges (\n  id TEXT PRIMARY KEY,\n  source_id TEXT NOT NULL REFERENCES ruvector.graph_nodes(id),\n  target_id TEXT NOT NULL REFERENCES ruvector.graph_nodes(id),\n  edge_type TEXT NOT NULL,\n  properties JSONB DEFAULT '{}',\n  created_at TIMESTAMPTZ DEFAULT NOW()\n);\n\nCREATE INDEX IF NOT EXISTS idx_graph_edges_source\nON ruvector.graph_edges(source_id);\n\nCREATE INDEX IF NOT EXISTS idx_graph_edges_target\nON ruvector.graph_edges(target_id);\n\nCREATE INDEX IF NOT EXISTS idx_graph_edges_type\nON ruvector.graph_edges(edge_type);\n";
+/**
+ * Exochain schema SQL (inline for bundled distribution)
+ *
+ * This constant provides a minimal inline version of the Exochain schema
+ * for use cases where file system access is not available (e.g., bundled builds).
+ *
+ * For the full schema with all functions and triggers, use loadSchema('exochain').
+ */
+export declare const EXOCHAIN_SCHEMA = "\n-- Inline Exochain schema for bundled distribution\nCREATE SCHEMA IF NOT EXISTS exochain;\n\nCREATE TABLE IF NOT EXISTS exochain.events (\n  id TEXT PRIMARY KEY,\n  parents TEXT[] DEFAULT '{}',\n  hlc_physical_ms BIGINT NOT NULL,\n  hlc_logical INTEGER NOT NULL,\n  author TEXT NOT NULL,\n  payload_type TEXT NOT NULL,\n  payload JSONB NOT NULL,\n  signature TEXT NOT NULL,\n  created_at TIMESTAMPTZ DEFAULT NOW()\n);\n\nCREATE INDEX IF NOT EXISTS idx_events_author\nON exochain.events(author);\n\nCREATE INDEX IF NOT EXISTS idx_events_payload_type\nON exochain.events(payload_type);\n\nCREATE INDEX IF NOT EXISTS idx_events_hlc\nON exochain.events(hlc_physical_ms, hlc_logical);\n\nCREATE INDEX IF NOT EXISTS idx_events_parents\nON exochain.events USING GIN (parents);\n\nCREATE TABLE IF NOT EXISTS exochain.checkpoints (\n  height INTEGER PRIMARY KEY,\n  event_root TEXT NOT NULL,\n  state_root TEXT NOT NULL,\n  timestamp TIMESTAMPTZ NOT NULL,\n  created_at TIMESTAMPTZ DEFAULT NOW()\n);\n\nCREATE TABLE IF NOT EXISTS exochain.checkpoint_signatures (\n  id SERIAL PRIMARY KEY,\n  checkpoint_height INTEGER NOT NULL REFERENCES exochain.checkpoints(height),\n  validator_did TEXT NOT NULL,\n  signature TEXT NOT NULL,\n  signed_at TIMESTAMPTZ DEFAULT NOW(),\n  UNIQUE(checkpoint_height, validator_did)\n);\n\nCREATE INDEX IF NOT EXISTS idx_checkpoint_signatures_height\nON exochain.checkpoint_signatures(checkpoint_height);\n\nCREATE TABLE IF NOT EXISTS exochain.tips (\n  event_id TEXT PRIMARY KEY REFERENCES exochain.events(id),\n  added_at TIMESTAMPTZ DEFAULT NOW()\n);\n\nCREATE TABLE IF NOT EXISTS exochain.peers (\n  id TEXT PRIMARY KEY,\n  endpoint TEXT NOT NULL UNIQUE,\n  did TEXT,\n  status TEXT DEFAULT 'disconnected',\n  last_sync_time TIMESTAMPTZ,\n  last_checkpoint_height INTEGER,\n  events_received INTEGER DEFAULT 0,\n  events_sent INTEGER DEFAULT 0,\n  errors INTEGER DEFAULT 0,\n  created_at TIMESTAMPTZ DEFAULT NOW(),\n  updated_at TIMESTAMPTZ DEFAULT NOW()\n);\n\nCREATE INDEX IF NOT EXISTS idx_peers_status\nON exochain.peers(status);\n\nCREATE TABLE IF NOT EXISTS exochain.sync_log (\n  id SERIAL PRIMARY KEY,\n  peer_id TEXT NOT NULL,\n  direction TEXT NOT NULL,\n  events_transferred INTEGER DEFAULT 0,\n  duration_ms INTEGER,\n  success BOOLEAN DEFAULT FALSE,\n  error_message TEXT,\n  started_at TIMESTAMPTZ NOT NULL,\n  completed_at TIMESTAMPTZ\n);\n\nCREATE INDEX IF NOT EXISTS idx_sync_log_peer\nON exochain.sync_log(peer_id);\n\nCREATE INDEX IF NOT EXISTS idx_sync_log_started_at\nON exochain.sync_log(started_at);\n";
+//# sourceMappingURL=index.d.ts.map

package/dist/database/schemas/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/database/schemas/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAYH;;GAEG;AACH,MAAM,MAAM,UAAU,GAAG,UAAU,GAAG,UAAU,CAAC;AAUjD;;;;;;;;;;;;GAYG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,CAenD;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,aAAa,IAAI,MAAM,CAAC,UAAU,EAAE,MAAM,CAAC,CAK1D;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,IAAI,UAAU,CAElE;AAED;;;;;;;;;GASG;AACH,wBAAgB,cAAc,IAAI,UAAU,EAAE,CAE7C;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,eAAe,0qGAyG3B,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,eAAe,2/EAuF3B,CAAC"}

package/dist/graphql/context.d.ts

@@ -0,0 +1,154 @@
+/**
+ * GraphQL Request Context
+ *
+ * Provides request-scoped context for GraphQL resolvers including
+ * database access, caching, service management, and authentication.
+ *
+ * @module graphql/context
+ */
+import type { KnowledgeGraphDatabase } from '../core/database.js';
+import type { AdvancedCache } from '../caching/lru-cache.js';
+import type { ServiceManager } from '../services/index.js';
+/**
+ * Authentication result from API key validation
+ */
+export interface AuthResult {
+    /** Whether authentication succeeded */
+    authenticated: boolean;
+    /** User or service identifier */
+    userId?: string;
+    /** Permission scopes granted */
+    scopes: string[];
+    /** Error message if authentication failed */
+    error?: string;
+}
+/**
+ * Request metadata extracted from HTTP request
+ */
+export interface RequestMeta {
+    /** Request ID for tracing */
+    requestId: string;
+    /** Request start timestamp */
+    startTime: number;
+    /** Client IP address */
+    clientIp: string;
+    /** User agent string */
+    userAgent: string;
+    /** Request path */
+    path: string;
+}
+/**
+ * Request-scoped utilities
+ */
+export interface RequestUtils {
+    /**
+     * Generate a unique ID
+     */
+    generateId(): string;
+    /**
+     * Log with request context
+     */
+    log(level: 'debug' | 'info' | 'warn' | 'error', message: string, data?: Record<string, unknown>): void;
+    /**
+     * Get elapsed time since request start
+     */
+    getElapsedMs(): number;
+    /**
+     * Create a cache key with request-scoped prefix
+     */
+    cacheKey(key: string): string;
+}
+/**
+ * Service layer interfaces for resolvers
+ */
+export interface Services {
+    /** Knowledge graph database */
+    database: KnowledgeGraphDatabase;
+    /** Request-scoped cache */
+    cache: AdvancedCache<unknown>;
+    /** Service manager for background services */
+    serviceManager: ServiceManager;
+}
+/**
+ * GraphQL request context provided to all resolvers
+ */
+export interface GraphQLContext {
+    /** Authentication result */
+    auth: AuthResult;
+    /** Request metadata */
+    request: RequestMeta;
+    /** Service layer */
+    services: Services;
+    /** Request-scoped utilities */
+    utils: RequestUtils;
+}
+/**
+ * Configuration for context factory
+ */
+export interface ContextFactoryConfig {
+    /** Knowledge graph database instance */
+    database: KnowledgeGraphDatabase;
+    /** Cache instance */
+    cache: AdvancedCache<unknown>;
+    /** Service manager instance */
+    serviceManager: ServiceManager;
+    /** API key for authentication (optional) */
+    apiKey?: string;
+    /** Whether to require authentication */
+    requireAuth?: boolean;
+    /** Custom authentication function */
+    authenticate?: (token: string | undefined) => AuthResult | Promise<AuthResult>;
+}
+/**
+ * Create a context factory function for graphql-yoga
+ *
+ * @param config - Context factory configuration
+ * @returns Function that creates request-scoped context
+ *
+ * @example
+ * ```typescript
+ * const contextFactory = createContextFactory({
+ *   database,
+ *   cache,
+ *   serviceManager,
+ *   apiKey: process.env.API_KEY,
+ *   requireAuth: true,
+ * });
+ *
+ * const yoga = createYoga({
+ *   context: contextFactory,
+ *   // ... other config
+ * });
+ * ```
+ */
+export declare function createContextFactory(config: ContextFactoryConfig): (request: {
+    request: Request;
+}) => Promise<GraphQLContext>;
+/**
+ * Check if context has a specific permission scope
+ *
+ * @param context - GraphQL context
+ * @param scope - Required permission scope
+ * @returns True if scope is present
+ */
+export declare function hasScope(context: GraphQLContext, scope: string): boolean;
+/**
+ * Require authentication, throwing if not authenticated
+ *
+ * @param context - GraphQL context
+ * @throws Error if not authenticated
+ */
+export declare function requireAuth(context: GraphQLContext): void;
+/**
+ * Require a specific permission scope, throwing if not present
+ *
+ * @param context - GraphQL context
+ * @param scope - Required permission scope
+ * @throws Error if scope is not present
+ */
+export declare function requireScope(context: GraphQLContext, scope: string): void;
+/**
+ * Type guard to check if value is a valid GraphQL context
+ */
+export declare function isGraphQLContext(value: unknown): value is GraphQLContext;
+//# sourceMappingURL=context.d.ts.map

package/dist/graphql/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../src/graphql/context.ts"],"names":[],"mappings":"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"}

package/dist/graphql/context.js

@@ -0,0 +1,168 @@
+import { createLogger } from "../utils/logger.js";
+const logger = createLogger("graphql-context");
+function createContextFactory(config) {
+  const {
+    database,
+    cache,
+    serviceManager,
+    apiKey,
+    requireAuth: requireAuth2 = false,
+    authenticate
+  } = config;
+  return async ({ request }) => {
+    const startTime = Date.now();
+    const requestId = generateRequestId();
+    const requestMeta = {
+      requestId,
+      startTime,
+      clientIp: extractClientIp(request),
+      userAgent: request.headers.get("user-agent") ?? "unknown",
+      path: new URL(request.url).pathname
+    };
+    const authHeader = request.headers.get("authorization");
+    const token = extractBearerToken(authHeader);
+    let auth;
+    if (authenticate) {
+      auth = await authenticate(token);
+    } else if (apiKey) {
+      auth = validateApiKey(token, apiKey);
+    } else {
+      auth = {
+        authenticated: true,
+        scopes: ["read", "write"]
+      };
+    }
+    if (requireAuth2 && !auth.authenticated) {
+      logger.warn("Unauthenticated request rejected", {
+        requestId,
+        path: requestMeta.path,
+        error: auth.error
+      });
+    }
+    const utils = {
+      generateId: () => generateRequestId(),
+      log: (level, message, data) => {
+        const logData = { ...data, requestId };
+        switch (level) {
+          case "debug":
+            logger.debug(message, logData);
+            break;
+          case "info":
+            logger.info(message, logData);
+            break;
+          case "warn":
+            logger.warn(message, logData);
+            break;
+          case "error":
+            logger.error(message, void 0, logData);
+            break;
+        }
+      },
+      getElapsedMs: () => Date.now() - startTime,
+      cacheKey: (key) => `req:${requestId}:${key}`
+    };
+    const services = {
+      database,
+      cache,
+      serviceManager
+    };
+    logger.debug("GraphQL context created", {
+      requestId,
+      authenticated: auth.authenticated,
+      scopes: auth.scopes
+    });
+    return {
+      auth,
+      request: requestMeta,
+      services,
+      utils
+    };
+  };
+}
+function extractBearerToken(header) {
+  if (!header) {
+    return void 0;
+  }
+  const parts = header.split(" ");
+  if (parts.length !== 2 || parts[0].toLowerCase() !== "bearer") {
+    return void 0;
+  }
+  return parts[1];
+}
+function validateApiKey(token, apiKey) {
+  if (!token) {
+    return {
+      authenticated: false,
+      scopes: [],
+      error: "No authentication token provided"
+    };
+  }
+  if (!constantTimeEqual(token, apiKey)) {
+    return {
+      authenticated: false,
+      scopes: [],
+      error: "Invalid API key"
+    };
+  }
+  return {
+    authenticated: true,
+    userId: "api-key-user",
+    scopes: ["read", "write", "admin"]
+  };
+}
+function constantTimeEqual(a, b) {
+  if (a.length !== b.length) {
+    return false;
+  }
+  let result = 0;
+  for (let i = 0; i < a.length; i++) {
+    result |= a.charCodeAt(i) ^ b.charCodeAt(i);
+  }
+  return result === 0;
+}
+function generateRequestId() {
+  const timestamp = Date.now().toString(36);
+  const random = Math.random().toString(36).substring(2, 10);
+  return `${timestamp}-${random}`;
+}
+function extractClientIp(request) {
+  const forwarded = request.headers.get("x-forwarded-for");
+  if (forwarded) {
+    const ips = forwarded.split(",").map((ip) => ip.trim());
+    return ips[0] || "unknown";
+  }
+  const realIp = request.headers.get("x-real-ip");
+  if (realIp) {
+    return realIp;
+  }
+  return "unknown";
+}
+function hasScope(context, scope) {
+  return context.auth.scopes.includes(scope);
+}
+function requireAuth(context) {
+  if (!context.auth.authenticated) {
+    throw new Error(context.auth.error ?? "Authentication required");
+  }
+}
+function requireScope(context, scope) {
+  requireAuth(context);
+  if (!hasScope(context, scope)) {
+    throw new Error(`Permission denied: requires '${scope}' scope`);
+  }
+}
+function isGraphQLContext(value) {
+  if (typeof value !== "object" || value === null) {
+    return false;
+  }
+  const obj = value;
+  return typeof obj.auth === "object" && typeof obj.request === "object" && typeof obj.services === "object" && typeof obj.utils === "object";
+}
+export {
+  createContextFactory,
+  hasScope,
+  isGraphQLContext,
+  requireAuth,
+  requireScope
+};
+//# sourceMappingURL=context.js.map

package/dist/graphql/context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.js","sources":["../../src/graphql/context.ts"],"sourcesContent":["/**\n * GraphQL Request Context\n *\n * Provides request-scoped context for GraphQL resolvers including\n * database access, caching, service management, and authentication.\n *\n * @module graphql/context\n */\n\nimport type { IncomingMessage } from 'http';\nimport type { KnowledgeGraphDatabase } from '../core/database.js';\nimport type { AdvancedCache } from '../caching/lru-cache.js';\nimport type { ServiceManager } from '../services/index.js';\nimport { createLogger } from '../utils/index.js';\n\nconst logger = createLogger('graphql-context');\n\n// ============================================================================\n// Types\n// ============================================================================\n\n/**\n * Authentication result from API key validation\n */\nexport interface AuthResult {\n  /** Whether authentication succeeded */\n  authenticated: boolean;\n  /** User or service identifier */\n  userId?: string;\n  /** Permission scopes granted */\n  scopes: string[];\n  /** Error message if authentication failed */\n  error?: string;\n}\n\n/**\n * Request metadata extracted from HTTP request\n */\nexport interface RequestMeta {\n  /** Request ID for tracing */\n  requestId: string;\n  /** Request start timestamp */\n  startTime: number;\n  /** Client IP address */\n  clientIp: string;\n  /** User agent string */\n  userAgent: string;\n  /** Request path */\n  path: string;\n}\n\n/**\n * Request-scoped utilities\n */\nexport interface RequestUtils {\n  /**\n   * Generate a unique ID\n   */\n  generateId(): string;\n\n  /**\n   * Log with request context\n   */\n  log(level: 'debug' | 'info' | 'warn' | 'error', message: string, data?: Record<string, unknown>): void;\n\n  /**\n   * Get elapsed time since request start\n   */\n  getElapsedMs(): number;\n\n  /**\n   * Create a cache key with request-scoped prefix\n   */\n  cacheKey(key: string): string;\n}\n\n/**\n * Service layer interfaces for resolvers\n */\nexport interface Services {\n  /** Knowledge graph database */\n  database: KnowledgeGraphDatabase;\n  /** Request-scoped cache */\n  cache: AdvancedCache<unknown>;\n  /** Service manager for background services */\n  serviceManager: ServiceManager;\n}\n\n/**\n * GraphQL request context provided to all resolvers\n */\nexport interface GraphQLContext {\n  /** Authentication result */\n  auth: AuthResult;\n  /** Request metadata */\n  request: RequestMeta;\n  /** Service layer */\n  services: Services;\n  /** Request-scoped utilities */\n  utils: RequestUtils;\n}\n\n// ============================================================================\n// Context Factory Configuration\n// ============================================================================\n\n/**\n * Configuration for context factory\n */\nexport interface ContextFactoryConfig {\n  /** Knowledge graph database instance */\n  database: KnowledgeGraphDatabase;\n  /** Cache instance */\n  cache: AdvancedCache<unknown>;\n  /** Service manager instance */\n  serviceManager: ServiceManager;\n  /** API key for authentication (optional) */\n  apiKey?: string;\n  /** Whether to require authentication */\n  requireAuth?: boolean;\n  /** Custom authentication function */\n  authenticate?: (token: string | undefined) => AuthResult | Promise<AuthResult>;\n}\n\n// ============================================================================\n// Context Factory\n// ============================================================================\n\n/**\n * Create a context factory function for graphql-yoga\n *\n * @param config - Context factory configuration\n * @returns Function that creates request-scoped context\n *\n * @example\n * ```typescript\n * const contextFactory = createContextFactory({\n *   database,\n *   cache,\n *   serviceManager,\n *   apiKey: process.env.API_KEY,\n *   requireAuth: true,\n * });\n *\n * const yoga = createYoga({\n *   context: contextFactory,\n *   // ... other config\n * });\n * ```\n */\nexport function createContextFactory(\n  config: ContextFactoryConfig\n): (request: { request: Request }) => Promise<GraphQLContext> {\n  const {\n    database,\n    cache,\n    serviceManager,\n    apiKey,\n    requireAuth = false,\n    authenticate,\n  } = config;\n\n  return async ({ request }: { request: Request }): Promise<GraphQLContext> => {\n    const startTime = Date.now();\n    const requestId = generateRequestId();\n\n    // Extract request metadata\n    const requestMeta: RequestMeta = {\n      requestId,\n      startTime,\n      clientIp: extractClientIp(request),\n      userAgent: request.headers.get('user-agent') ?? 'unknown',\n      path: new URL(request.url).pathname,\n    };\n\n    // Authenticate request\n    const authHeader = request.headers.get('authorization');\n    const token = extractBearerToken(authHeader);\n\n    let auth: AuthResult;\n\n    if (authenticate) {\n      // Use custom authentication function\n      auth = await authenticate(token);\n    } else if (apiKey) {\n      // Use simple API key authentication\n      auth = validateApiKey(token, apiKey);\n    } else {\n      // No authentication configured\n      auth = {\n        authenticated: true,\n        scopes: ['read', 'write'],\n      };\n    }\n\n    // Check if authentication is required\n    if (requireAuth && !auth.authenticated) {\n      logger.warn('Unauthenticated request rejected', {\n        requestId,\n        path: requestMeta.path,\n        error: auth.error,\n      });\n    }\n\n    // Create request-scoped utilities\n    const utils: RequestUtils = {\n      generateId: () => generateRequestId(),\n      log: (level, message, data) => {\n        const logData = { ...data, requestId };\n        switch (level) {\n          case 'debug':\n            logger.debug(message, logData);\n            break;\n          case 'info':\n            logger.info(message, logData);\n            break;\n          case 'warn':\n            logger.warn(message, logData);\n            break;\n          case 'error':\n            logger.error(message, undefined, logData);\n            break;\n        }\n      },\n      getElapsedMs: () => Date.now() - startTime,\n      cacheKey: (key) => `req:${requestId}:${key}`,\n    };\n\n    // Create services reference\n    const services: Services = {\n      database,\n      cache,\n      serviceManager,\n    };\n\n    logger.debug('GraphQL context created', {\n      requestId,\n      authenticated: auth.authenticated,\n      scopes: auth.scopes,\n    });\n\n    return {\n      auth,\n      request: requestMeta,\n      services,\n      utils,\n    };\n  };\n}\n\n// ============================================================================\n// Authentication Helpers\n// ============================================================================\n\n/**\n * Extract Bearer token from Authorization header\n */\nfunction extractBearerToken(header: string | null): string | undefined {\n  if (!header) {\n    return undefined;\n  }\n\n  const parts = header.split(' ');\n  if (parts.length !== 2 || parts[0].toLowerCase() !== 'bearer') {\n    return undefined;\n  }\n\n  return parts[1];\n}\n\n/**\n * Validate API key (simple comparison)\n */\nfunction validateApiKey(token: string | undefined, apiKey: string): AuthResult {\n  if (!token) {\n    return {\n      authenticated: false,\n      scopes: [],\n      error: 'No authentication token provided',\n    };\n  }\n\n  // Constant-time comparison to prevent timing attacks\n  if (!constantTimeEqual(token, apiKey)) {\n    return {\n      authenticated: false,\n      scopes: [],\n      error: 'Invalid API key',\n    };\n  }\n\n  return {\n    authenticated: true,\n    userId: 'api-key-user',\n    scopes: ['read', 'write', 'admin'],\n  };\n}\n\n/**\n * Constant-time string comparison to prevent timing attacks\n */\nfunction constantTimeEqual(a: string, b: string): boolean {\n  if (a.length !== b.length) {\n    return false;\n  }\n\n  let result = 0;\n  for (let i = 0; i < a.length; i++) {\n    result |= a.charCodeAt(i) ^ b.charCodeAt(i);\n  }\n\n  return result === 0;\n}\n\n// ============================================================================\n// Request Utilities\n// ============================================================================\n\n/**\n * Generate a unique request ID\n */\nfunction generateRequestId(): string {\n  const timestamp = Date.now().toString(36);\n  const random = Math.random().toString(36).substring(2, 10);\n  return `${timestamp}-${random}`;\n}\n\n/**\n * Extract client IP from request headers\n */\nfunction extractClientIp(request: Request): string {\n  // Check forwarded headers (reverse proxy)\n  const forwarded = request.headers.get('x-forwarded-for');\n  if (forwarded) {\n    const ips = forwarded.split(',').map((ip) => ip.trim());\n    return ips[0] || 'unknown';\n  }\n\n  const realIp = request.headers.get('x-real-ip');\n  if (realIp) {\n    return realIp;\n  }\n\n  return 'unknown';\n}\n\n// ============================================================================\n// Authorization Helpers\n// ============================================================================\n\n/**\n * Check if context has a specific permission scope\n *\n * @param context - GraphQL context\n * @param scope - Required permission scope\n * @returns True if scope is present\n */\nexport function hasScope(context: GraphQLContext, scope: string): boolean {\n  return context.auth.scopes.includes(scope);\n}\n\n/**\n * Require authentication, throwing if not authenticated\n *\n * @param context - GraphQL context\n * @throws Error if not authenticated\n */\nexport function requireAuth(context: GraphQLContext): void {\n  if (!context.auth.authenticated) {\n    throw new Error(context.auth.error ?? 'Authentication required');\n  }\n}\n\n/**\n * Require a specific permission scope, throwing if not present\n *\n * @param context - GraphQL context\n * @param scope - Required permission scope\n * @throws Error if scope is not present\n */\nexport function requireScope(context: GraphQLContext, scope: string): void {\n  requireAuth(context);\n  if (!hasScope(context, scope)) {\n    throw new Error(`Permission denied: requires '${scope}' scope`);\n  }\n}\n\n// ============================================================================\n// Type Guards\n// ============================================================================\n\n/**\n * Type guard to check if value is a valid GraphQL context\n */\nexport function isGraphQLContext(value: unknown): value is GraphQLContext {\n  if (typeof value !== 'object' || value === null) {\n    return false;\n  }\n\n  const obj = value as Record<string, unknown>;\n  return (\n    typeof obj.auth === 'object' &&\n    typeof obj.request === 'object' &&\n    typeof obj.services === 'object' &&\n    typeof obj.utils === 'object'\n  );\n}\n"],"names":["requireAuth"],"mappings":"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"}

package/dist/graphql/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * GraphQL Module
+ *
+ * Exports GraphQL server setup, context, and custom scalars for the
+ * Knowledge Graph Agent API.
+ *
+ * @module graphql
+ */
+export { createGraphQLServer, type GraphQLServerConfig, type GraphQLServerInstance, type CorsConfig, type HealthCheckResponse, } from './server.js';
+export { createContextFactory, hasScope, requireAuth, requireScope, isGraphQLContext, type GraphQLContext, type AuthResult, type RequestMeta, type RequestUtils, type Services, type ContextFactoryConfig, } from './context.js';
+export { DateTimeScalar, JSONScalar, UUIDScalar, FilePathScalar, customScalars, scalarTypeDefs, } from './scalars.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/graphql/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/graphql/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAMH,OAAO,EACL,mBAAmB,EACnB,KAAK,mBAAmB,EACxB,KAAK,qBAAqB,EAC1B,KAAK,UAAU,EACf,KAAK,mBAAmB,GACzB,MAAM,aAAa,CAAC;AAMrB,OAAO,EACL,oBAAoB,EACpB,QAAQ,EACR,WAAW,EACX,YAAY,EACZ,gBAAgB,EAChB,KAAK,cAAc,EACnB,KAAK,UAAU,EACf,KAAK,WAAW,EAChB,KAAK,YAAY,EACjB,KAAK,QAAQ,EACb,KAAK,oBAAoB,GAC1B,MAAM,cAAc,CAAC;AAMtB,OAAO,EACL,cAAc,EACd,UAAU,EACV,UAAU,EACV,cAAc,EACd,aAAa,EACb,cAAc,GACf,MAAM,cAAc,CAAC"}