ai-control-center 1.15.2

package/lib/config.js

@@ -0,0 +1,243 @@
+/**
+ * Config loader for ai-control-center.
+ *
+ * Finds and loads `aicc.config.js` from the project root.
+ * Provides a singleton via getConfig() and env-var helper via env().
+ */
+import { existsSync, readFileSync } from 'fs';
+import { dirname, resolve } from 'path';
+import { pathToFileURL } from 'url';
+
+let _config = null;
+
+const DEFAULTS = {
+  workflowDir: '.ai-workflow',
+  skillsDir: '.claude/skills',
+  envPrefix: 'AICC',
+  stages: {
+    idle:                    { label: 'Idle',              color: 'gray' },
+    inbox:                   { label: 'Feature Submitted', color: 'yellow' },
+    spec_complete:           { label: 'PM Spec Ready',     color: 'cyan' },
+    arch_complete:           { label: 'Arch Ready',        color: 'blue' },
+    implementation_complete: { label: 'Code Done',         color: 'magenta' },
+    review_complete:         { label: 'Review Ready',      color: 'green' },
+    approved:                { label: 'Approved',          color: 'green' },
+    rejected:                { label: 'Rejected',          color: 'red' },
+    deployed:                { label: 'Deployed',          color: 'green' },
+  },
+  deploy: { command: null, options: [] },
+  review: { extensions: ['.js', '.ts', '.py', '.go'], sourceDir: 'src/' },
+  ai: { system: 'You are a concise DevOps assistant.', roleFile: null },
+  feature: { placeholder: 'Describe the feature you want to build...' },
+  queries: [],
+  debug: { commands: [] },
+  web: { port: 3847 },
+  plugins: [],
+
+  // ─── Pipeline — Stage × AI Model Configuration ──────────────────────────
+  // Each entry defines ONE stage: which AI provider runs it and which model.
+  // To switch a model, just change the `model` value for that stage.
+  //
+  // provider: 'openclaw' | 'copilot' | 'claude' | 'gemini' | 'ollama'
+  // model:    the AI model name (copilot uses period format, claude uses hyphen)
+  // fallbacks: ordered list of backup 'provider:model' pairs (optional)
+  //
+  // Env var overrides (applied at runtime, take precedence over config):
+  //   GEMINI_MODEL, CLAUDE_MODEL, COPILOT_MODEL, OLLAMA_MODEL
+  pipeline: [
+    { stage: 'chat',      provider: 'claude',   model: 'claude-haiku-4-5',   fallbacks: ['gemini:gemini-2.5-flash', 'copilot:claude-haiku-4.5', 'ollama'] },
+    { stage: 'pm',        provider: 'copilot',  model: 'claude-sonnet-4.6',  fallbacks: ['gemini:gemini-2.5-pro', 'ollama']         },
+    { stage: 'architect', provider: 'copilot',  model: 'claude-sonnet-4.6',  fallbacks: ['gemini:gemini-2.5-pro', 'ollama']         },
+    { stage: 'implement', provider: 'claude',   model: 'claude-sonnet-4-6',  fallbacks: ['copilot:claude-sonnet-4.6', 'ollama']     },
+    { stage: 'review',    provider: 'copilot',  model: 'claude-sonnet-4.6',  fallbacks: ['gemini:gemini-2.5-pro', 'ollama']         },
+    { stage: 'deploy',    provider: 'copilot',  model: 'claude-sonnet-4.6',  fallbacks: ['gemini:gemini-2.5-pro', 'ollama']         },
+  ],
+
+  // Ollama local fallback settings
+  ollama: { model: 'llama3.1', baseUrl: 'http://localhost:11434' },
+
+  roleplay: {
+    enabled: true,
+    verbosity: 'normal',
+    pmPersonality: 'professional',
+    agentChat: true,
+    progressUpdates: true,
+    progressInterval: 60000,
+    maxReviewCycles: 3,
+    autoDeployOnApproval: false,
+    openclawBridge: true, // Enable OpenClaw bridge for multi-channel communication
+  },
+};
+
+/**
+ * Walk up from `startDir` to find aicc.config.js.
+ */
+function findProjectRoot(startDir) {
+  let dir = startDir;
+  while (true) {
+    if (existsSync(resolve(dir, 'aicc.config.js'))) return dir;
+    const parent = dirname(dir);
+    if (parent === dir) return null; // reached filesystem root
+    dir = parent;
+  }
+}
+
+/**
+ * Load the project config. Must be called once before getConfig().
+ */
+export async function loadConfig(cwd) {
+  if (_config) return _config;
+
+  const root = findProjectRoot(cwd || process.cwd());
+  if (!root) {
+    throw new Error(
+      'No aicc.config.js found.\n' +
+      'Run "aicc init" to create one, or ensure you\'re in the project directory.'
+    );
+  }
+
+  // Load .env file if present (does NOT override existing env vars)
+  const envFilePath = resolve(root, '.env');
+  if (existsSync(envFilePath)) {
+    try {
+      const envContent = readFileSync(envFilePath, 'utf8');
+      for (const line of envContent.split('\n')) {
+        const trimmed = line.trim();
+        if (!trimmed || trimmed.startsWith('#')) continue;
+        const eqIdx = trimmed.indexOf('=');
+        if (eqIdx === -1) continue;
+        const key = trimmed.slice(0, eqIdx).trim();
+        const val = trimmed.slice(eqIdx + 1).trim();
+        if (key && !(key in process.env)) {
+          process.env[key] = val;
+        }
+      }
+    } catch { /* ignore .env read errors */ }
+  }
+
+  const configPath = resolve(root, 'aicc.config.js');
+  const mod = await import(pathToFileURL(configPath).href);
+  const userConfig = mod.default || mod;
+
+  // ── Backward compat: convert old `models` config → new `pipeline` format ──
+  let pipeline = userConfig.pipeline || null;
+  if (!pipeline && userConfig.models) {
+    pipeline = _migrateModelsToPipeline(userConfig.models);
+  }
+
+  // Merge with defaults
+  _config = {
+    ...DEFAULTS,
+    ...userConfig,
+    stages: { ...DEFAULTS.stages, ...(userConfig.stages || {}) },
+    deploy: { ...DEFAULTS.deploy, ...(userConfig.deploy || {}) },
+    review: { ...DEFAULTS.review, ...(userConfig.review || {}) },
+    ai: { ...DEFAULTS.ai, ...(userConfig.ai || {}) },
+    feature: { ...DEFAULTS.feature, ...(userConfig.feature || {}) },
+    debug: { ...DEFAULTS.debug, ...(userConfig.debug || {}) },
+    web: { ...DEFAULTS.web, ...(userConfig.web || {}) },
+    pipeline: pipeline || DEFAULTS.pipeline,
+    ollama: { ...DEFAULTS.ollama, ...(userConfig.ollama || {}) },
+    roleplay: { ...DEFAULTS.roleplay, ...(userConfig.roleplay || {}) },
+    // Resolved absolute paths
+    _root: root,
+    _workflowDir: resolve(root, userConfig.workflowDir || DEFAULTS.workflowDir),
+    _statusFile: resolve(root, userConfig.workflowDir || DEFAULTS.workflowDir, 'status.json'),
+    _configPath: configPath,
+  };
+
+  return _config;
+}
+
+/**
+ * Get the loaded config. Throws if loadConfig() hasn't been called.
+ */
+export function getConfig() {
+  if (!_config) {
+    throw new Error('Config not loaded. Call loadConfig() first.');
+  }
+  return _config;
+}
+
+/**
+ * Get an environment variable using the configured prefix.
+ * env('TELEGRAM_TOKEN') → process.env.XCONN_TELEGRAM_TOKEN (if envPrefix is 'XCONN')
+ * Falls back to AICC_ prefix.
+ */
+export function env(suffix) {
+  const prefix = _config ? _config.envPrefix : 'AICC';
+  return process.env[`${prefix}_${suffix}`] || process.env[`AICC_${suffix}`];
+}
+
+/**
+ * Get the pipeline entry for a given stage.
+ * Returns { stage, provider, model, fallbacks } or a sensible default.
+ */
+export function getPipelineStage(stage) {
+  const cfg = _config || DEFAULTS;
+  const pipeline = cfg.pipeline || DEFAULTS.pipeline;
+  const entry = pipeline.find(e => e.stage === stage);
+  if (entry) return entry;
+  // Fallback: use 'default' entry or first non-chat entry
+  const defaultEntry = pipeline.find(e => e.stage === 'default');
+  if (defaultEntry) return { ...defaultEntry, stage };
+  return { stage, provider: 'copilot', model: 'claude-sonnet-4.6', fallbacks: ['gemini:gemini-2.5-pro', 'ollama'] };
+}
+
+/**
+ * Get the Ollama config.
+ */
+export function getOllamaConfig() {
+  const cfg = _config || DEFAULTS;
+  return cfg.ollama || DEFAULTS.ollama;
+}
+
+/**
+ * Backward compat: convert old `models` config to new `pipeline[]` format.
+ */
+function _migrateModelsToPipeline(models) {
+  const sp = models.stageProviders || {};
+  const chatModel = models.chatModel || 'claude-haiku-4.5';
+  const crossModel = models.copilotCrossAiModel || 'claude-sonnet-4.6';
+  const claudeModel = (models.claudeChain || ['claude-sonnet-4-6'])[0];
+  const copilotModel = (models.copilotChain || ['claude-sonnet-4.6'])[0];
+  const geminiModel = (models.geminiChain || ['gemini-2.5-pro'])[0];
+
+  function buildEntry(stage) {
+    const providers = sp[stage] || sp.default || ['copilot', 'gemini', 'ollama'];
+    const primary = providers[0];
+    let model;
+    switch (primary) {
+      case 'claude':  model = claudeModel; break;
+      case 'gemini':  model = (models.stages?.[stage]?.geminiChain || [geminiModel])[0]; break;
+      case 'copilot': model = stage === 'implement' ? copilotModel : crossModel; break;
+      default:        model = models.ollamaModel || 'llama3.1';
+    }
+    const fallbacks = providers.slice(1).map(p => {
+      switch (p) {
+        case 'gemini':  return `gemini:${geminiModel}`;
+        case 'claude':  return `claude:${claudeModel}`;
+        case 'copilot': return `copilot:${copilotModel}`;
+        case 'ollama':  return 'ollama';
+        default:        return p;
+      }
+    });
+    return { stage, provider: primary, model, fallbacks };
+  }
+
+  return [
+    { stage: 'chat', provider: 'copilot', model: chatModel },
+    buildEntry('pm'),
+    buildEntry('architect'),
+    buildEntry('implement'),
+    buildEntry('review'),
+    buildEntry('deploy'),
+  ];
+}
+
+/**
+ * Reset config (for testing).
+ */
+export function resetConfig() {
+  _config = null;
+}

package/lib/hub/hub-server.js

@@ -0,0 +1,440 @@
+/**
+ * Hub Server — Multi-project aggregator for AI Control Center.
+ *
+ * Polls each registered project's /api/status and /api/health,
+ * aggregates state, and broadcasts changes via WebSocket.
+ *
+ * Uses native http.createServer with simple request routing (no Express).
+ *
+ * Usage:  aicc hub
+ */
+import { createServer } from 'http';
+import { existsSync, readFileSync } from 'fs';
+import { dirname, extname, join, resolve } from 'path';
+import { fileURLToPath } from 'url';
+import WebSocket, { WebSocketServer } from 'ws';
+import { getConfig } from '../config.js';
+import { aggregateStates, detectChanges } from './state-aggregator.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+// ─── Helpers ───────────────────────────────────────────────────────────────────
+
+const sleep = (ms) => new Promise(r => setTimeout(r, ms));
+
+/** Parse JSON body from an IncomingMessage */
+function parseBody(req) {
+  return new Promise((resolve, reject) => {
+    const chunks = [];
+    req.on('data', (c) => chunks.push(c));
+    req.on('end', () => {
+      try { resolve(chunks.length ? JSON.parse(Buffer.concat(chunks).toString()) : {}); }
+      catch (e) { reject(e); }
+    });
+    req.on('error', reject);
+  });
+}
+
+/** Send a JSON response */
+function json(res, data, status = 200) {
+  const body = JSON.stringify(data);
+  res.writeHead(status, { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(body) });
+  res.end(body);
+}
+
+/** Simple URL path matcher — returns params or null */
+function matchRoute(method, url, pattern, expectedMethod) {
+  if (method !== expectedMethod) return null;
+  const urlPath = url.split('?')[0];
+  const patternParts = pattern.split('/');
+  const urlParts = urlPath.split('/');
+  if (patternParts.length !== urlParts.length) return null;
+  const params = {};
+  for (let i = 0; i < patternParts.length; i++) {
+    if (patternParts[i].startsWith(':')) {
+      params[patternParts[i].slice(1)] = decodeURIComponent(urlParts[i]);
+    } else if (patternParts[i] !== urlParts[i]) {
+      return null;
+    }
+  }
+  return params;
+}
+
+// ─── HubServer class ───────────────────────────────────────────────────────────
+
+/**
+ * Multi-project hub that aggregates status from multiple AICC instances.
+ *
+ * @example
+ *   const hub = new HubServer({ port: 3850, pollInterval: 3000, projects: [...] });
+ *   await hub.start();
+ */
+export class HubServer {
+  /**
+   * @param {object} config — hub configuration
+   * @param {number} [config.port=3850] — HTTP port
+   * @param {number} [config.pollInterval=3000] — polling interval in ms
+   * @param {Array<{name:string, url:string, color?:string, icon?:string}>} config.projects
+   */
+  constructor(config = {}) {
+    this._port = config.port || 3850;
+    this._pollInterval = config.pollInterval || 30000; // health poll only, slow
+    this._projects = config.projects || [];
+    this._server = null;
+    this._wss = null;
+    this._pollTimer = null;
+    this._state = null;
+    this._running = false;
+    this._projectWs = new Map();      // project name → WebSocket client
+    this._projectStatus = new Map();   // project name → latest status
+    this._projectHealth = new Map();   // project name → latest health
+    this._projectOnline = new Map();   // project name → boolean
+    this._reconnectTimers = new Map(); // project name → reconnect timer
+  }
+
+  /** Start HTTP server + WebSocket, begin polling */
+  async start() {
+    this._server = createServer((req, res) => this._handleRequest(req, res));
+    this._wss = new WebSocketServer({ server: this._server, path: '/ws' });
+
+    this._wss.on('connection', (ws) => {
+      // Send current state on connect
+      if (this._state) {
+        try { ws.send(JSON.stringify({ type: 'state', ...this._state })); } catch { /* skip */ }
+      }
+    });
+
+    this._running = true;
+    // Subscribe to each project's WebSocket for real-time updates
+    for (const project of this._projects) {
+      this._subscribeToProject(project);
+    }
+    // Initial poll to get health data and bootstrap state
+    await this._pollProjects();
+    // Slow poll for health checks only (status comes via WebSocket)
+    this._schedulePoll();
+
+    return new Promise((resolve) => {
+      this._server.listen(this._port, () => {
+        console.log(`\n  🏢 AI Hub Server`);
+        console.log(`  ─────────────────────────────────────`);
+        console.log(`  API:        http://localhost:${this._port}/api/projects`);
+        console.log(`  Health:     http://localhost:${this._port}/api/health`);
+        console.log(`  WebSocket:  ws://localhost:${this._port}/ws`);
+        console.log(`  Projects:`);
+        for (const p of this._projects) {
+          console.log(`    • ${p.icon || '📦'} ${p.name} → ${p.url}`);
+        }
+        console.log();
+        resolve();
+      });
+    });
+  }
+
+  /** Gracefully shut down */
+  async stop() {
+    this._running = false;
+    if (this._pollTimer) { clearTimeout(this._pollTimer); this._pollTimer = null; }
+    // Close all project WebSocket subscriptions
+    for (const [name, ws] of this._projectWs) {
+      try { ws.close(); } catch { /* ignore */ }
+    }
+    this._projectWs.clear();
+    for (const timer of this._reconnectTimers.values()) clearTimeout(timer);
+    this._reconnectTimers.clear();
+    if (this._wss) { this._wss.close(); this._wss = null; }
+    if (this._server) {
+      await new Promise((resolve) => this._server.close(resolve));
+      this._server = null;
+    }
+  }
+
+  /** Returns the current aggregated project states */
+  getProjectStates() {
+    return this._state;
+  }
+
+  // ── Real-time WebSocket subscriptions ───────────────────────────────────────
+
+  /** Subscribe to a project's WebSocket for instant status updates */
+  _subscribeToProject(project) {
+    if (!this._running) return;
+    const wsUrl = project.url.replace(/^http/, 'ws') + '/ws';
+    try {
+      const ws = new WebSocket(wsUrl);
+      ws.on('open', () => {
+        this._projectOnline.set(project.name, true);
+        this._projectWs.set(project.name, ws);
+        // Clear reconnect timer
+        const rt = this._reconnectTimers.get(project.name);
+        if (rt) { clearTimeout(rt); this._reconnectTimers.delete(project.name); }
+      });
+      ws.on('message', (raw) => {
+        try {
+          const msg = JSON.parse(raw.toString());
+          if (msg.type === 'status' && msg.data) {
+            this._projectStatus.set(project.name, msg.data.status || msg.data);
+            this._projectOnline.set(project.name, true);
+            this._rebuildAndBroadcast();
+          }
+        } catch { /* ignore non-JSON */ }
+      });
+      ws.on('close', () => {
+        this._projectWs.delete(project.name);
+        this._projectOnline.set(project.name, false);
+        this._rebuildAndBroadcast();
+        this._scheduleReconnect(project);
+      });
+      ws.on('error', () => {
+        this._projectOnline.set(project.name, false);
+        try { ws.close(); } catch { /* ignore */ }
+      });
+    } catch {
+      this._scheduleReconnect(project);
+    }
+  }
+
+  /** Reconnect to a project's WebSocket after a delay */
+  _scheduleReconnect(project) {
+    if (!this._running) return;
+    if (this._reconnectTimers.has(project.name)) return;
+    const timer = setTimeout(() => {
+      this._reconnectTimers.delete(project.name);
+      this._subscribeToProject(project);
+    }, 5000);
+    this._reconnectTimers.set(project.name, timer);
+  }
+
+  /** Rebuild aggregated state from cached data and broadcast */
+  _rebuildAndBroadcast() {
+    const responses = this._projects.map((project) => ({
+      name: project.name,
+      status: this._projectStatus.get(project.name) || null,
+      health: this._projectHealth.get(project.name) || null,
+      online: this._projectOnline.get(project.name) || false,
+    }));
+
+    const oldState = this._state;
+    this._state = aggregateStates(this._projects, responses);
+
+    const changes = oldState ? detectChanges(oldState, this._state) : [];
+    if (!oldState || changes.length > 0) {
+      if (changes.length > 0) {
+        for (const c of changes) {
+          console.log(`[Hub] Change: ${c.project} ${c.type} ${c.from} → ${c.to}`);
+        }
+      }
+      this._broadcastState();
+    }
+  }
+
+  // ── Polling (health checks only) ──────────────────────────────────────────
+
+  /** Poll each project's /api/status and /api/health — updates cache maps */
+  async _pollProjects() {
+    await Promise.all(
+      this._projects.map(async (project) => {
+        try {
+          const [statusRes, healthRes] = await Promise.all([
+            fetch(`${project.url}/api/status`, { signal: AbortSignal.timeout(5000) }),
+            fetch(`${project.url}/api/health`, { signal: AbortSignal.timeout(5000) }),
+          ]);
+          if (statusRes.ok) this._projectStatus.set(project.name, await statusRes.json());
+          if (healthRes.ok) this._projectHealth.set(project.name, await healthRes.json());
+          this._projectOnline.set(project.name, statusRes.ok);
+        } catch {
+          // Only mark offline if no WebSocket is connected
+          if (!this._projectWs.has(project.name)) {
+            this._projectOnline.set(project.name, false);
+          }
+        }
+      }),
+    );
+    this._rebuildAndBroadcast();
+  }
+
+  /** Schedule the next poll */
+  _schedulePoll() {
+    if (!this._running) return;
+    this._pollTimer = setTimeout(async () => {
+      await this._pollProjects();
+      this._schedulePoll();
+    }, this._pollInterval);
+  }
+
+  /** Broadcast current state to all connected WebSocket clients */
+  _broadcastState() {
+    if (!this._wss || !this._state) return;
+    const msg = JSON.stringify({ type: 'state', ...this._state });
+    for (const ws of this._wss.clients) {
+      if (ws.readyState === 1) {
+        try { ws.send(msg); } catch { /* skip dead connections */ }
+      }
+    }
+  }
+
+  // ── HTTP request routing ─────────────────────────────────────────────────────
+
+  async _handleRequest(req, res) {
+    const { method, url } = req;
+    let params;
+
+    // CORS headers for dashboard access
+    res.setHeader('Access-Control-Allow-Origin', '*');
+    res.setHeader('Access-Control-Allow-Methods', 'GET, POST, OPTIONS');
+    res.setHeader('Access-Control-Allow-Headers', 'Content-Type');
+    if (method === 'OPTIONS') { res.writeHead(204); return res.end(); }
+
+    try {
+      // GET /api/projects — all projects with current state
+      if (method === 'GET' && url.split('?')[0] === '/api/projects') {
+        const state = this._state || { projects: {}, summary: {} };
+        return json(res, {
+          projects: Object.values(state.projects),
+          summary: state.summary,
+          hub: { port: this._port, pollInterval: this._pollInterval },
+        });
+      }
+
+      // GET /api/projects/:name — single project detail
+      if ((params = matchRoute(method, url, '/api/projects/:name', 'GET'))) {
+        const state = this._state || { projects: {} };
+        const project = state.projects[params.name];
+        if (!project) return json(res, { error: 'Project not found' }, 404);
+        return json(res, project);
+      }
+
+      // POST /api/projects/:name/feature — forward feature submission
+      if ((params = matchRoute(method, url, '/api/projects/:name/feature', 'POST'))) {
+        const projectCfg = this._projects.find(p => p.name === params.name);
+        if (!projectCfg) return json(res, { error: 'Project not found' }, 404);
+        const body = await parseBody(req);
+        try {
+          const r = await fetch(`${projectCfg.url}/api/feature`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify(body),
+          });
+          return json(res, await r.json(), r.status);
+        } catch (e) {
+          return json(res, { error: `Cannot reach ${projectCfg.name}: ${e.message}` }, 502);
+        }
+      }
+
+      // POST /api/projects/:name/action/:action — forward any pipeline action
+      if (method === 'POST') {
+        const actionMatch = url.split('?')[0].match(/^\/api\/projects\/([^/]+)\/action\/([^/]+)$/);
+        if (actionMatch) {
+          const projectName = decodeURIComponent(actionMatch[1]);
+          const action = decodeURIComponent(actionMatch[2]);
+          const projectCfg = this._projects.find(p => p.name === projectName);
+          if (!projectCfg) return json(res, { error: 'Project not found' }, 404);
+          const body = await parseBody(req);
+          try {
+            const r = await fetch(`${projectCfg.url}/api/${action}`, {
+              method: 'POST',
+              headers: { 'Content-Type': 'application/json' },
+              body: JSON.stringify(body),
+              signal: AbortSignal.timeout(30000),
+            });
+            return json(res, await r.json(), r.status);
+          } catch (e) {
+            return json(res, { error: `Cannot reach ${projectCfg.name}: ${e.message}` }, 502);
+          }
+        }
+      }
+
+      // GET /api/health — hub health + all project health
+      if (method === 'GET' && url.split('?')[0] === '/api/health') {
+        const state = this._state || { projects: {}, summary: { total: 0, active: 0, idle: 0, offline: 0 } };
+        return json(res, {
+          hub: 'ok',
+          uptime: process.uptime(),
+          projectCount: state.summary.total,
+          onlineCount: state.summary.total - state.summary.offline,
+          projects: Object.values(state.projects).map(p => ({
+            name: p.name,
+            online: p.online,
+            health: p.health,
+          })),
+        });
+      }
+
+      // Serve /office/ static files (pixel art RPG visualizer)
+      const urlPath = url.split('?')[0];
+      if (method === 'GET' && urlPath.startsWith('/office')) {
+        const officeDir = resolve(__dirname, '../web/public/office');
+        let filePath = urlPath === '/office' || urlPath === '/office/'
+          ? join(officeDir, 'index.html')
+          : join(officeDir, urlPath.replace('/office/', ''));
+
+        if (existsSync(filePath)) {
+          const MIME = {
+            '.html': 'text/html', '.css': 'text/css', '.js': 'application/javascript',
+            '.json': 'application/json', '.png': 'image/png', '.svg': 'image/svg+xml',
+            '.woff2': 'font/woff2', '.woff': 'font/woff',
+          };
+          const ext = extname(filePath);
+          const content = readFileSync(filePath);
+          res.writeHead(200, {
+            'Content-Type': MIME[ext] || 'application/octet-stream',
+            'Cache-Control': 'no-cache',
+          });
+          return res.end(content);
+        }
+      }
+
+      // 404 fallback
+      json(res, { error: 'Not found' }, 404);
+    } catch (e) {
+      json(res, { error: e.message }, 500);
+    }
+  }
+}
+
+// ─── Convenience starter ───────────────────────────────────────────────────────
+
+/**
+ * Start the hub server with the given options or from loaded config.
+ *
+ * @param {object} [options]
+ * @param {number} [options.port] — override port (default from config or 3850)
+ * @returns {{ server: import('http').Server, wss: WebSocketServer }}
+ */
+export async function startHub(options = {}) {
+  let hubConfig;
+  try {
+    const cfg = getConfig();
+    hubConfig = cfg.hub || {};
+  } catch {
+    hubConfig = {};
+  }
+
+  const config = {
+    port: options.port || hubConfig.port || 3850,
+    pollInterval: hubConfig.pollInterval || 3000,
+    projects: hubConfig.projects || [],
+  };
+
+  if (config.projects.length === 0) {
+    console.error('  ✗  No projects configured for hub.');
+    console.error('     Add hub.projects to aicc.config.js');
+    console.error('     Example:');
+    console.error('       hub: {');
+    console.error('         projects: [');
+    console.error('           { name: "MyProject", url: "http://localhost:3847" }');
+    console.error('         ]');
+    console.error('       }');
+    process.exit(1);
+  }
+
+  const hub = new HubServer(config);
+  await hub.start();
+
+  // Graceful shutdown
+  const shutdown = () => { hub.stop().then(() => process.exit(0)); };
+  process.on('SIGINT', shutdown);
+  process.on('SIGTERM', shutdown);
+
+  return { server: hub._server, wss: hub._wss };
+}