doc2vec 2.10.5 → 2.11.0

package/README.md

@@ -52,6 +52,7 @@ The primary goal is to prepare documentation content for Retrieval-Augmented Gen
 *   **Incremental Updates:** For GitHub and Zendesk sources, tracks the last run date to only fetch new or updated issues/tickets.
 *   **Cleanup:** Removes obsolete chunks from the database corresponding to pages or files that are no longer found during processing.
 *   **Configuration:** Driven by a YAML configuration file (`config.yaml`) specifying sites, repositories, local directories, Zendesk instances, database types, metadata, and other parameters.
+*   **[Controller Mode](#controller-mode):** Optionally runs as a long-lived controller that schedules sync jobs from multiple config files (cron `schedule` field), persists run history and statistics in Postgres, and serves a web UI with live log streaming — read-only (configs from files/ConfigMap) or read-write (create/edit configs from the UI).
 *   **Structured Logging:** Uses a custom logger (`logger.ts`) with levels, timestamps, colors, progress bars, and child loggers for clear execution monitoring.
 
 ## Chunk Metadata & Page Reconstruction
@@ -437,6 +438,103 @@ The script will then:
 7.  Cleanup obsolete chunks.
 8.  Output detailed logs.
 
+## Controller Mode
+
+Besides the one-shot sync, doc2vec can run as a **long-lived controller** that schedules sync jobs, records run history and statistics in Postgres, and serves a web UI for monitoring and managing configs:
+
+```bash
+doc2vec controller --database-url postgres://user:pass@host:5432/doc2vec ./configs/
+```
+
+Open http://localhost:8080 to see the dashboard: configs with their schedule and next run, run history with per-source statistics, and live log streaming for running jobs.
+
+### Scheduling
+
+Add a top-level cron `schedule` (and optionally a display `name`) to a config file, and the controller runs it automatically:
+
+```yaml
+name: product-docs
+schedule: "0 2 * * *"   # every day at 02:00
+sources:
+  - type: website
+    ...
+```
+
+Configs without a `schedule` are still listed in the UI and can be triggered manually with **Run now**. Each run executes `doc2vec run <config.yaml>` as a child process; overlapping runs of the same config are skipped, and `--max-parallel` (default 1) caps how many sync jobs run at once — keep it low, since website sources launch a headless Chromium.
+
+### Flags
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--database-url <url>` | `DATABASE_URL` env | Postgres connection string (required) |
+| `--port <n>` | `8080` (or `PORT`) | HTTP port for the API and UI |
+| `--read-write` | off (read-only) | Allow creating/editing/deleting configs from the UI |
+| `--config-dir <dir>` | — | Where UI-created configs are written (required with `--read-write`) |
+| `--max-parallel <n>` | `1` | Max concurrent sync jobs |
+| `--reload-interval <s>` | `30` | How often config files are re-read for changes |
+| `--log-retention-days <n>` | `14` | Run logs older than this are pruned (run history is kept) |
+| `--slack-webhook-url <url>` | `SLACK_WEBHOOK_URL` env | Slack incoming webhook — post a message when a run finishes |
+| `--slack-notify <mode>` | `all` | `all` or `failures` (failures also covers canceled runs) |
+| `--public-url <url>` | `PUBLIC_URL` env | Externally reachable base URL, used for "view run" links in notifications |
+
+Positional arguments are config files and/or directories (directories are scanned for `*.yaml`/`*.yml`, and re-scanned on every reload).
+
+### Slack notifications
+
+With `--slack-webhook-url` (or `SLACK_WEBHOOK_URL`) set, the controller posts to a [Slack incoming webhook](https://api.slack.com/messaging/webhooks) whenever a run reaches a terminal state — ✅ succeeded, ❌ failed (naming the failing sources and their errors), or ⚠️ canceled. Overlap-`skipped` runs are not notified. Set `--slack-notify failures` to silence successes, and `--public-url https://doc2vec.example.com` to get clickable "view run" links.
+
+### Read-only vs read-write
+
+- **Read-only** (default): configs come solely from the files passed on the command line — ideal for Kubernetes, where they live in a ConfigMap. The UI can view configs, trigger runs, and browse history/stats, but not modify anything. ConfigMap updates are picked up automatically via content-hash polling.
+- **Read-write** (`--read-write --config-dir ./configs`): the UI can also create, edit, and delete config YAML files. Files stay the source of truth on disk; concurrent edits are protected by a content-hash check.
+
+In both modes the UI always shows raw YAML: `${ENV_VAR}` secret placeholders are **never** resolved outside the sync job itself.
+
+### Kubernetes example
+
+```yaml
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: doc2vec-controller
+spec:
+  replicas: 1        # keep a single replica: the scheduler is not distributed
+  selector:
+    matchLabels: { app: doc2vec-controller }
+  template:
+    metadata:
+      labels: { app: doc2vec-controller }
+    spec:
+      containers:
+        - name: controller
+          image: ghcr.io/kagent-dev/doc2vec:latest
+          command: ["node", "dist/doc2vec.js", "controller", "/etc/doc2vec"]
+          ports:
+            - containerPort: 8080
+          env:
+            - name: DATABASE_URL
+              valueFrom:
+                secretKeyRef: { name: doc2vec-secrets, key: database-url }
+            - name: OPENAI_API_KEY
+              valueFrom:
+                secretKeyRef: { name: doc2vec-secrets, key: openai-api-key }
+          volumeMounts:
+            - name: configs
+              mountPath: /etc/doc2vec
+          resources:
+            requests: { memory: 1Gi }
+            limits: { memory: 4Gi }   # website sources launch headless Chromium
+      volumes:
+        - name: configs
+          configMap: { name: doc2vec-configs }
+```
+
+The controller detects ConfigMap updates without a restart. Health endpoint: `GET /api/health`.
+
+### API
+
+The UI is backed by a small REST API you can also use directly: `GET /api/configs`, `POST /api/configs/:id/run`, `GET /api/runs?configId=`, `GET /api/runs/:id/logs`, `POST /api/runs/:id/cancel`, `GET /api/configs/:id/stats?days=30`, plus server-sent events at `GET /api/events` and `GET /api/runs/:id/logs/stream`.
+
 ## Database Options
 
 ### SQLite (`database_config.type: 'sqlite'`)

package/dist/content-processor.js

@@ -36,7 +36,8 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ContentProcessor = void 0;
+exports.ContentProcessor = exports.BrowserLaunchError = void 0;
+exports.resolveBrowserExecutablePath = resolveBrowserExecutablePath;
 const readability_1 = require("@mozilla/readability");
 const axios_1 = __importDefault(require("axios"));
 const cheerio_1 = require("cheerio");
@@ -48,6 +49,97 @@ const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 const utils_1 = require("./utils");
 const code_chunker_1 = require("./code-chunker");
+/**
+ * Thrown when the browser cannot be launched at all (even after a retry).
+ * Without a browser no page in the crawl can be processed, so this aborts the
+ * whole website source — the run is then reported as failed instead of
+ * "succeeding" with an error on every URL.
+ */
+class BrowserLaunchError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'BrowserLaunchError';
+    }
+}
+exports.BrowserLaunchError = BrowserLaunchError;
+/**
+ * Resolve which browser binary to launch, in order of preference:
+ *  1. PUPPETEER_EXECUTABLE_PATH (explicit override)
+ *  2. Puppeteer's own downloaded Chrome for Testing (version-matched, the
+ *     reliable choice — Debian's chromium package has shipped builds that
+ *     crash at startup in containers, e.g. 150.0.7871 SIGTRAPs immediately)
+ *  3. A system chromium, as the fallback (also covers linux/arm64, where
+ *     Chrome for Testing is not published)
+ *  4. undefined — let puppeteer decide
+ */
+function resolveBrowserExecutablePath() {
+    const override = process.env.PUPPETEER_EXECUTABLE_PATH;
+    if (override)
+        return override;
+    try {
+        const bundled = puppeteer_1.default.executablePath();
+        if (bundled && fs.existsSync(bundled))
+            return bundled;
+    }
+    catch {
+        // no browser downloaded for this platform
+    }
+    if (fs.existsSync('/usr/bin/chromium'))
+        return '/usr/bin/chromium';
+    if (fs.existsSync('/usr/bin/chromium-browser'))
+        return '/usr/bin/chromium-browser';
+    return undefined;
+}
+/**
+ * Best-effort snapshot of process + container memory, for diagnosing browser
+ * launch failures (the usual cause in Kubernetes is the pod's memory cgroup —
+ * Chromium forks, then its renderers are immediately OOM-killed).
+ */
+function memoryDiagnostics() {
+    const gib = (bytes) => `${(bytes / 1024 ** 3).toFixed(2)}GiB`;
+    const parts = [`node rss ${gib(process.memoryUsage().rss)}`];
+    try {
+        // cgroup v2, else v1 — absent entirely outside Linux/containers
+        let current;
+        let max;
+        if (fs.existsSync('/sys/fs/cgroup/memory.current')) {
+            current = fs.readFileSync('/sys/fs/cgroup/memory.current', 'utf8').trim();
+            max = fs.readFileSync('/sys/fs/cgroup/memory.max', 'utf8').trim();
+        }
+        else if (fs.existsSync('/sys/fs/cgroup/memory/memory.usage_in_bytes')) {
+            current = fs.readFileSync('/sys/fs/cgroup/memory/memory.usage_in_bytes', 'utf8').trim();
+            max = fs.readFileSync('/sys/fs/cgroup/memory/memory.limit_in_bytes', 'utf8').trim();
+        }
+        if (current !== undefined && max !== undefined) {
+            const unlimited = max === 'max' || Number(max) > 2 ** 60;
+            parts.push(`cgroup ${gib(Number(current))} used / ${unlimited ? 'no limit' : gib(Number(max))}`);
+        }
+    }
+    catch {
+        // diagnostics only — never fail because of them
+    }
+    try {
+        // /proc/meminfo reflects the NODE in Kubernetes — catches host-level pressure
+        const meminfo = fs.readFileSync('/proc/meminfo', 'utf8');
+        const available = meminfo.match(/^MemAvailable:\s+(\d+) kB/m);
+        if (available) {
+            parts.push(`node available ${gib(Number(available[1]) * 1024)}`);
+        }
+    }
+    catch {
+        // not Linux
+    }
+    try {
+        // Chromium writes its profile and (with --disable-dev-shm-usage) its
+        // shared memory under /tmp — a full disk breaks launches
+        const stat = fs.statfsSync('/tmp');
+        parts.push(`/tmp free ${gib(stat.bavail * stat.bsize)}`);
+    }
+    catch {
+        // statfs unavailable
+    }
+    return parts.join(', ');
+}
 class ContentProcessor {
     constructor(logger) {
         this.logger = logger;
@@ -329,16 +421,8 @@ class ContentProcessor {
         let browser = null;
         let page = null;
         const launchBrowser = async () => {
-            let executablePath = process.env.PUPPETEER_EXECUTABLE_PATH;
-            if (!executablePath) {
-                if (fs.existsSync('/usr/bin/chromium')) {
-                    executablePath = '/usr/bin/chromium';
-                }
-                else if (fs.existsSync('/usr/bin/chromium-browser')) {
-                    executablePath = '/usr/bin/chromium-browser';
-                }
-            }
-            const b = await puppeteer_1.default.launch({
+            const executablePath = resolveBrowserExecutablePath();
+            const launchOptions = {
                 executablePath,
                 args: [
                     '--no-sandbox',
@@ -348,7 +432,25 @@ class ContentProcessor {
                     '--disable-extensions',
                 ],
                 protocolTimeout: 60000,
-            });
+            };
+            let b;
+            try {
+                b = await puppeteer_1.default.launch(launchOptions);
+            }
+            catch (firstError) {
+                // One retry after a pause — the failure may be transient (e.g.
+                // memory pressure from a page that just closed). If the browser
+                // cannot launch at all, no page in this crawl can be processed,
+                // so escalate as fatal instead of failing every URL one by one.
+                logger.warn(`Browser launch failed (${memoryDiagnostics()}), retrying once in 5s...`, firstError);
+                await new Promise(resolve => setTimeout(resolve, 5000));
+                try {
+                    b = await puppeteer_1.default.launch(launchOptions);
+                }
+                catch (secondError) {
+                    throw new BrowserLaunchError(`browser failed to launch twice (${memoryDiagnostics()}): ${secondError instanceof Error ? secondError.message : String(secondError)}`);
+                }
+            }
             const p = await b.newPage();
             return { browser: b, page: p };
         };
@@ -682,6 +784,13 @@ class ContentProcessor {
                     }
                 }
                 catch (error) {
+                    // A browser that cannot launch is fatal for the whole crawl —
+                    // rethrow so the source (and the run) is reported as failed
+                    // rather than logging an error per URL and finishing "green".
+                    if (error instanceof BrowserLaunchError) {
+                        logger.error(`Aborting crawl of ${baseUrl}: ${error.message}`);
+                        throw error;
+                    }
                     const status = this.getHttpStatus(error);
                     // ── Handle 429 (Too Many Requests) with retry ──
                     if (status === 429) {
@@ -846,17 +955,8 @@ class ContentProcessor {
             }
             else {
                 // Standalone mode: launch a browser for this single page
-                let executablePath = process.env.PUPPETEER_EXECUTABLE_PATH;
-                if (!executablePath) {
-                    if (fs.existsSync('/usr/bin/chromium')) {
-                        executablePath = '/usr/bin/chromium';
-                    }
-                    else if (fs.existsSync('/usr/bin/chromium-browser')) {
-                        executablePath = '/usr/bin/chromium-browser';
-                    }
-                }
                 browser = await puppeteer_1.default.launch({
-                    executablePath,
+                    executablePath: resolveBrowserExecutablePath(),
                     args: [
                         '--no-sandbox',
                         '--disable-setuid-sandbox',

package/dist/controller/config-registry.js

@@ -0,0 +1,277 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ConfigRegistry = void 0;
+exports.parseConfigMeta = parseConfigMeta;
+exports.isValidCron = isValidCron;
+exports.hashContent = hashContent;
+const crypto = __importStar(require("crypto"));
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const yaml = __importStar(require("js-yaml"));
+const croner_1 = require("croner");
+const types_1 = require("./types");
+/**
+ * Parse raw config YAML WITHOUT ${ENV} substitution (secrets stay as placeholders)
+ * and without Doc2Vec.loadConfig()'s process.exit() behavior — invalid files are
+ * reported, never fatal.
+ */
+function parseConfigMeta(content, filePath) {
+    const fallbackName = path.basename(filePath).replace(/\.ya?ml$/i, '');
+    try {
+        const parsed = yaml.load(content);
+        if (!parsed || typeof parsed !== 'object') {
+            return { name: fallbackName, schedule: null, sourceSummary: [], parseError: 'config is empty or not a YAML mapping' };
+        }
+        if (!Array.isArray(parsed.sources) || parsed.sources.length === 0) {
+            return { name: parsed.name || fallbackName, schedule: null, sourceSummary: [], parseError: 'config has no sources' };
+        }
+        const sourceSummary = parsed.sources.map((s) => ({
+            type: String(s?.type ?? 'unknown'),
+            product_name: String(s?.product_name ?? 'unknown'),
+            ...(s?.version !== undefined && { version: String(s.version) }),
+        }));
+        let schedule = null;
+        let parseError = null;
+        if (parsed.schedule !== undefined && parsed.schedule !== null) {
+            schedule = String(parsed.schedule);
+            if (!isValidCron(schedule)) {
+                parseError = `invalid cron expression: ${schedule}`;
+                schedule = null;
+            }
+        }
+        return { name: String(parsed.name || fallbackName), schedule, sourceSummary, parseError };
+    }
+    catch (err) {
+        return {
+            name: fallbackName,
+            schedule: null,
+            sourceSummary: [],
+            parseError: err instanceof Error ? err.message : String(err),
+        };
+    }
+}
+function isValidCron(expr) {
+    try {
+        new croner_1.Cron(expr, { paused: true }).stop();
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function hashContent(content) {
+    return crypto.createHash('sha256').update(content).digest('hex');
+}
+/**
+ * Watches the config files/directories passed on the CLI (plus --config-dir in
+ * read-write mode), keeps the d2v_configs table in sync, and — in read-write mode —
+ * persists UI edits back to YAML files on disk. Disk is the source of truth.
+ *
+ * Change detection is content-hash polling rather than fs.watch: Kubernetes
+ * ConfigMap updates arrive as atomic symlink swaps that fs.watch misses.
+ */
+class ConfigRegistry {
+    constructor(opts, store, events, logger) {
+        this.opts = opts;
+        this.store = store;
+        this.events = events;
+        this.logger = logger;
+        this.byPath = new Map();
+        this.timer = null;
+        this.syncing = false;
+    }
+    async start() {
+        await this.sync();
+        this.timer = setInterval(() => {
+            this.sync().catch(err => this.logger.error('Config re-sync failed:', err));
+        }, Math.max(this.opts.reloadIntervalSec, 5) * 1000);
+        this.timer.unref();
+    }
+    stop() {
+        if (this.timer)
+            clearInterval(this.timer);
+        this.timer = null;
+    }
+    list() {
+        return [...this.byPath.values()].sort((a, b) => a.name.localeCompare(b.name));
+    }
+    get(id) {
+        return [...this.byPath.values()].find(c => c.id === id);
+    }
+    /** Expand CLI args (files and directories) into the current set of config files. */
+    discoverFiles() {
+        const files = new Set();
+        const addDir = (dir) => {
+            for (const entry of fs.readdirSync(dir)) {
+                if (/\.ya?ml$/i.test(entry) && !entry.startsWith('.')) {
+                    const full = path.join(dir, entry);
+                    if (fs.statSync(full).isFile())
+                        files.add(full);
+                }
+            }
+        };
+        for (const arg of this.opts.configArgs) {
+            const abs = path.resolve(arg);
+            if (!fs.existsSync(abs)) {
+                this.logger.warn(`Config path does not exist: ${abs}`);
+                continue;
+            }
+            if (fs.statSync(abs).isDirectory()) {
+                addDir(abs);
+            }
+            else {
+                files.add(abs);
+            }
+        }
+        if (this.opts.readWrite && this.opts.configDir && fs.existsSync(this.opts.configDir)) {
+            addDir(path.resolve(this.opts.configDir));
+        }
+        return [...files];
+    }
+    async sync() {
+        if (this.syncing)
+            return;
+        this.syncing = true;
+        try {
+            const files = this.discoverFiles();
+            const seen = new Set();
+            let changed = false;
+            for (const file of files) {
+                seen.add(file);
+                let content;
+                try {
+                    content = fs.readFileSync(file, 'utf8');
+                }
+                catch (err) {
+                    this.logger.warn(`Failed to read config ${file}:`, err);
+                    continue;
+                }
+                const contentHash = hashContent(content);
+                const existing = this.byPath.get(file);
+                if (existing && existing.content_hash === contentHash)
+                    continue;
+                const meta = parseConfigMeta(content, file);
+                if (meta.parseError) {
+                    this.logger.warn(`Config ${file} has a problem: ${meta.parseError}`);
+                }
+                const record = await this.store.upsertConfig({
+                    path: file,
+                    name: meta.name,
+                    content,
+                    contentHash,
+                    schedule: meta.schedule,
+                    sourceSummary: meta.sourceSummary,
+                    parseError: meta.parseError,
+                });
+                this.byPath.set(file, record);
+                changed = true;
+                this.logger.info(`${existing ? 'Reloaded' : 'Loaded'} config '${record.name}' from ${file}` +
+                    (record.schedule ? ` (schedule: ${record.schedule})` : ' (manual runs only)'));
+            }
+            for (const [file] of this.byPath) {
+                if (!seen.has(file)) {
+                    this.logger.info(`Config file removed: ${file}`);
+                    await this.store.markConfigDeleted(file);
+                    this.byPath.delete(file);
+                    changed = true;
+                }
+            }
+            if (changed)
+                this.events.emitConfigUpdate();
+        }
+        finally {
+            this.syncing = false;
+        }
+    }
+    // ------------------------------------------------------------- read-write mode
+    /** Validate content for create/update: must parse and declare sources; cron must be valid. */
+    validateForWrite(content, filePath) {
+        const meta = parseConfigMeta(content, filePath);
+        if (meta.parseError) {
+            throw new types_1.ValidationError(meta.parseError);
+        }
+        return meta;
+    }
+    atomicWrite(target, content) {
+        const tmp = `${target}.tmp-${process.pid}`;
+        fs.writeFileSync(tmp, content, 'utf8');
+        fs.renameSync(tmp, target);
+    }
+    async create(filename, content) {
+        if (!this.opts.configDir) {
+            throw new types_1.ValidationError('no --config-dir configured');
+        }
+        if (!/^[A-Za-z0-9][A-Za-z0-9._-]*\.ya?ml$/.test(filename)) {
+            throw new types_1.ValidationError('filename must be a plain name ending in .yaml or .yml');
+        }
+        const target = path.join(path.resolve(this.opts.configDir), filename);
+        if (fs.existsSync(target)) {
+            throw new types_1.ConflictError(`config file ${filename} already exists`);
+        }
+        this.validateForWrite(content, target);
+        this.atomicWrite(target, content);
+        await this.sync();
+        const record = this.byPath.get(target);
+        if (!record)
+            throw new Error('config was written but failed to load');
+        return record;
+    }
+    async update(id, content, baseHash) {
+        const existing = this.get(id);
+        if (!existing)
+            throw new types_1.NotFoundError(`config ${id} not found`);
+        if (existing.content_hash !== baseHash) {
+            throw new types_1.ConflictError('config changed on disk since you loaded it — reload and reapply your edits');
+        }
+        this.validateForWrite(content, existing.path);
+        this.atomicWrite(existing.path, content);
+        await this.sync();
+        const record = this.byPath.get(existing.path);
+        if (!record)
+            throw new Error('config was written but failed to load');
+        return record;
+    }
+    async delete(id) {
+        const existing = this.get(id);
+        if (!existing)
+            throw new types_1.NotFoundError(`config ${id} not found`);
+        fs.unlinkSync(existing.path);
+        await this.store.markConfigDeleted(existing.path);
+        this.byPath.delete(existing.path);
+        this.events.emitConfigUpdate();
+    }
+}
+exports.ConfigRegistry = ConfigRegistry;

package/dist/controller/events.js

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ControllerEvents = void 0;
+const events_1 = require("events");
+/**
+ * In-process event bus connecting the job runner / config registry to SSE clients.
+ *
+ * Events:
+ *  - 'run:update'    (run: RunRecord)                     — a run was created or changed status
+ *  - 'run:log'       ({ runId: number, lines: LogRow[] }) — new log lines for a running job
+ *  - 'config:update' ()                                   — the set of configs changed on disk
+ */
+class ControllerEvents extends events_1.EventEmitter {
+    constructor() {
+        super();
+        // Every SSE client adds a listener per event; don't warn at the default 10
+        this.setMaxListeners(1000);
+    }
+    emitRunUpdate(run) {
+        this.emit('run:update', run);
+    }
+    emitRunLogs(runId, lines) {
+        this.emit('run:log', { runId, lines });
+    }
+    emitConfigUpdate() {
+        this.emit('config:update');
+    }
+}
+exports.ControllerEvents = ControllerEvents;