mergen-server 1.4.0

package/dist/sensor/ci-gate-history.js

@@ -0,0 +1,70 @@
+import fs from "fs";
+import { randomUUID, randomBytes } from "crypto";
+import { DATA_DIR, CI_GATE_HISTORY_FILE, zeroRetentionMode } from "./paths.js";
+import logger from "./logger.js";
+import { lockAndExecute } from "./file-lock.js";
+const MAX_GATE_HISTORY = (() => {
+  const v = parseInt(process.env.MERGEN_MAX_GATE_HISTORY ?? "2000", 10);
+  return Number.isFinite(v) && v > 0 ? Math.min(v, 5e4) : 2e3;
+})();
+let _entries = [];
+let _loaded = false;
+let _testingMode = false;
+function load(force = false) {
+  if (_testingMode) return;
+  if (_loaded && !force) return;
+  _loaded = true;
+  if (!fs.existsSync(CI_GATE_HISTORY_FILE)) {
+    _entries = [];
+    return;
+  }
+  try {
+    const raw = JSON.parse(fs.readFileSync(CI_GATE_HISTORY_FILE, "utf8"));
+    _entries = raw?.version === 1 && Array.isArray(raw.entries) ? raw.entries : [];
+  } catch {
+    _entries = [];
+  }
+}
+function persist() {
+  if (zeroRetentionMode()) return;
+  try {
+    fs.mkdirSync(DATA_DIR, { recursive: true, mode: 448 });
+    const tmp = `${CI_GATE_HISTORY_FILE}.tmp.${process.pid}.${randomBytes(4).toString("hex")}`;
+    const contents = JSON.stringify({ version: 1, entries: _entries });
+    fs.writeFileSync(tmp, contents, "utf8");
+    fs.renameSync(tmp, CI_GATE_HISTORY_FILE);
+  } catch (err) {
+    logger.warn({ err }, "ci-gate-history: persist failed");
+  }
+}
+function _resetForTesting() {
+  _entries = [];
+  _loaded = true;
+  _testingMode = true;
+}
+function recordGateEvaluation(entry) {
+  lockAndExecute(`${CI_GATE_HISTORY_FILE}.lock`, () => {
+    load(true);
+    const id = entry.id ?? randomUUID();
+    if (_entries.some((e) => e.id === id)) return;
+    _entries.push({ ...entry, id, recordedAt: entry.recordedAt ?? Date.now() });
+    if (_entries.length > MAX_GATE_HISTORY) _entries = _entries.slice(-MAX_GATE_HISTORY);
+    persist();
+  });
+}
+function getGateHistoryForPR(prNumber, repo) {
+  load(true);
+  return _entries.filter((e) => e.prNumber === prNumber && (!repo || e.repo === repo));
+}
+function getGateHistory(opts) {
+  load(true);
+  const sorted = [..._entries].sort((a, b) => b.recordedAt - a.recordedAt);
+  return opts?.limit ? sorted.slice(0, opts.limit) : sorted;
+}
+export {
+  MAX_GATE_HISTORY,
+  _resetForTesting,
+  getGateHistory,
+  getGateHistoryForPR,
+  recordGateEvaluation
+};

package/dist/sensor/cloud-auth.js

@@ -0,0 +1,183 @@
+import fs from "fs";
+import path from "path";
+import crypto from "crypto";
+import { DATA_DIR } from "./paths.js";
+import logger from "./logger.js";
+const API_KEYS_FILE = path.join(DATA_DIR, "api-keys.json");
+let _keys = [];
+let _loaded = false;
+function load() {
+  if (_loaded) return;
+  _loaded = true;
+  if (!fs.existsSync(API_KEYS_FILE)) return;
+  try {
+    const parsed = JSON.parse(fs.readFileSync(API_KEYS_FILE, "utf8"));
+    if (parsed?.version === 1 && Array.isArray(parsed.keys)) _keys = parsed.keys;
+  } catch (err) {
+    logger.warn({ err }, "cloud-auth: failed to load api-keys file");
+  }
+}
+function persist() {
+  try {
+    fs.mkdirSync(DATA_DIR, { recursive: true });
+    const tmp = `${API_KEYS_FILE}.tmp.${process.pid}.${Date.now()}`;
+    fs.writeFileSync(tmp, JSON.stringify({ version: 1, keys: _keys }, null, 2), "utf8");
+    fs.renameSync(tmp, API_KEYS_FILE);
+  } catch (err) {
+    logger.warn({ err }, "cloud-auth: failed to persist api-keys to file");
+  }
+}
+async function upsertKeyToPg(key) {
+  const { getSql } = await import("../storage/pg/pg-client.js");
+  const sql = getSql();
+  await sql`
+    INSERT INTO api_keys (id, tenant_id, label, key_hash, rate_limit, scope, expires_at, created_at, last_used_at, created_by)
+    VALUES (
+      ${key.id}, ${key.tenantId}, ${key.label}, ${key.keyHash}, ${key.rateLimit},
+      ${JSON.stringify(key.scope ?? [])}, ${key.expiresAt ?? null}, ${key.createdAt},
+      ${key.lastUsedAt ?? null}, ${key.createdBy ?? "api-admin"}
+    )
+    ON CONFLICT (id) DO UPDATE SET
+      label        = EXCLUDED.label,
+      rate_limit   = EXCLUDED.rate_limit,
+      scope        = EXCLUDED.scope,
+      expires_at   = EXCLUDED.expires_at,
+      last_used_at = EXCLUDED.last_used_at
+  `;
+}
+async function deleteKeyFromPg(id) {
+  const { getSql } = await import("../storage/pg/pg-client.js");
+  const sql = getSql();
+  await sql`DELETE FROM api_keys WHERE id = ${id}`;
+}
+async function initCloudApiKeys() {
+  if (!CLOUD_MODE) return;
+  try {
+    const { getSql } = await import("../storage/pg/pg-client.js");
+    const sql = getSql();
+    const rows = await sql`SELECT * FROM api_keys ORDER BY created_at ASC`;
+    _keys = rows.map((row) => ({
+      id: String(row["id"]),
+      tenantId: String(row["tenant_id"]),
+      label: String(row["label"]),
+      keyHash: String(row["key_hash"]),
+      rateLimit: Number(row["rate_limit"]),
+      createdAt: Number(row["created_at"]),
+      ...row["last_used_at"] != null ? { lastUsedAt: Number(row["last_used_at"]) } : {},
+      ...Array.isArray(row["scope"]) && row["scope"].length > 0 ? { scope: row["scope"] } : {},
+      ...row["expires_at"] != null ? { expiresAt: String(row["expires_at"]) } : {},
+      ...row["created_by"] != null ? { createdBy: String(row["created_by"]) } : {}
+    }));
+    _loaded = true;
+    logger.info({ count: _keys.length }, "cloud-auth: loaded api keys from postgres");
+  } catch (err) {
+    logger.error({ err }, "cloud-auth: failed to load api keys from postgres \u2014 falling back to file");
+    load();
+  }
+}
+function hashKey(plain) {
+  return crypto.createHash("sha256").update(plain).digest("hex");
+}
+const _rateBuckets = /* @__PURE__ */ new Map();
+const WINDOW_MS = 6e4;
+function checkRateLimit(keyId, limit) {
+  const now = Date.now();
+  const bucket = _rateBuckets.get(keyId);
+  if (!bucket || now - bucket.windowStart > WINDOW_MS) {
+    _rateBuckets.set(keyId, { count: 1, windowStart: now });
+    return true;
+  }
+  bucket.count += 1;
+  return bucket.count <= limit;
+}
+function createApiKey(opts) {
+  load();
+  const plain = crypto.randomBytes(32).toString("hex");
+  const entry = {
+    id: `key-${Date.now().toString(36)}-${crypto.randomBytes(4).toString("hex")}`,
+    tenantId: opts.tenantId,
+    label: opts.label,
+    keyHash: hashKey(plain),
+    createdAt: Date.now(),
+    rateLimit: opts.rateLimit ?? 1e3,
+    ...opts.scope ? { scope: opts.scope } : {},
+    ...opts.expiresAt ? { expiresAt: opts.expiresAt } : {},
+    ...opts.createdBy ? { createdBy: opts.createdBy } : {}
+  };
+  _keys.push(entry);
+  persist();
+  if (CLOUD_MODE) {
+    upsertKeyToPg(entry).catch((err) => logger.warn({ err, id: entry.id }, "cloud-auth: failed to persist new key to postgres"));
+  }
+  logger.info({ id: entry.id, tenantId: entry.tenantId, label: entry.label, createdBy: entry.createdBy }, "cloud-auth: api key created");
+  return {
+    id: entry.id,
+    tenantId: entry.tenantId,
+    label: entry.label,
+    key: plain,
+    rateLimit: entry.rateLimit,
+    createdAt: entry.createdAt,
+    ...entry.scope ? { scope: entry.scope } : {},
+    ...entry.expiresAt ? { expiresAt: entry.expiresAt } : {},
+    ...entry.createdBy ? { createdBy: entry.createdBy } : {}
+  };
+}
+function listApiKeys() {
+  load();
+  return _keys.map(({ keyHash: _h, ...rest }) => rest);
+}
+function revokeApiKey(id) {
+  load();
+  const before = _keys.length;
+  _keys = _keys.filter((k) => k.id !== id);
+  if (_keys.length === before) return false;
+  _rateBuckets.delete(id);
+  persist();
+  if (CLOUD_MODE) {
+    deleteKeyFromPg(id).catch((err) => logger.warn({ err, id }, "cloud-auth: failed to delete key from postgres"));
+  }
+  logger.info({ id }, "cloud-auth: api key revoked");
+  return true;
+}
+const CLOUD_MODE = process.env.MERGEN_CLOUD_MODE === "true";
+function cloudAuthMiddleware(req, res, next) {
+  if (!CLOUD_MODE) {
+    next();
+    return;
+  }
+  const plain = req.headers["x-api-key"];
+  if (!plain || typeof plain !== "string") {
+    res.status(401).json({ error: "x-api-key header required in cloud mode" });
+    return;
+  }
+  load();
+  const hash = hashKey(plain);
+  const key = _keys.find((k) => k.keyHash === hash);
+  if (!key) {
+    res.status(401).json({ error: "invalid api key" });
+    return;
+  }
+  if (key.expiresAt && new Date(key.expiresAt) < /* @__PURE__ */ new Date()) {
+    res.status(401).json({ error: "api key expired", expiredAt: key.expiresAt });
+    return;
+  }
+  if (!checkRateLimit(key.id, key.rateLimit)) {
+    res.status(429).json({ error: "rate limit exceeded", limit: key.rateLimit, windowMs: WINDOW_MS });
+    return;
+  }
+  key.lastUsedAt = Date.now();
+  req.tenantId = key.tenantId;
+  if (CLOUD_MODE) {
+    upsertKeyToPg(key).catch(() => {
+    });
+  }
+  next();
+}
+export {
+  CLOUD_MODE,
+  cloudAuthMiddleware,
+  createApiKey,
+  initCloudApiKeys,
+  listApiKeys,
+  revokeApiKey
+};

package/dist/sensor/commit-context-store.js

@@ -0,0 +1,235 @@
+import initSqlJs from "sql.js";
+import fs from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+import { createRequire } from "module";
+import { DATA_DIR } from "./paths.js";
+import logger from "./logger.js";
+const CONTEXT_DB = path.join(DATA_DIR, "commit-contexts.db");
+function extractLinkedIssues(body) {
+  const issues = [];
+  const seen = /* @__PURE__ */ new Set();
+  const ghRe = /(?:fix(?:es|ed)?|clos(?:es|ed)?|resolv(?:es|ed)?|ref(?:erences?)?|relates?\s+to)\s+([a-z0-9_.-]+\/[a-z0-9_.-]+)?#(\d+)/gi;
+  let m;
+  while ((m = ghRe.exec(body)) !== null) {
+    const ref = m[1] ? `${m[1]}#${m[2]}` : `#${m[2]}`;
+    if (!seen.has(ref)) {
+      seen.add(ref);
+      issues.push({ ref });
+    }
+  }
+  const plainRe = /#(\d+)\b/g;
+  while ((m = plainRe.exec(body)) !== null) {
+    const ref = `#${m[1]}`;
+    if (!seen.has(ref)) {
+      seen.add(ref);
+      issues.push({ ref });
+    }
+  }
+  const jiraRe = /\b([A-Z][A-Z0-9]+-\d+)\b/g;
+  while ((m = jiraRe.exec(body)) !== null) {
+    const ref = m[1];
+    if (!seen.has(ref)) {
+      seen.add(ref);
+      issues.push({ ref });
+    }
+  }
+  return issues.slice(0, 20);
+}
+class CommitContextStore {
+  db = null;
+  resolveWasmPath() {
+    if (process.env.MERGEN_WASM_PATH) return process.env.MERGEN_WASM_PATH;
+    const moduleDir = path.dirname(fileURLToPath(import.meta.url));
+    const fromModule = path.resolve(moduleDir, "../../node_modules/sql.js/dist/sql-wasm.wasm");
+    if (fs.existsSync(fromModule)) return fromModule;
+    try {
+      const req = createRequire(import.meta.url);
+      const resolved = path.join(path.dirname(req.resolve("sql.js")), "sql-wasm.wasm");
+      if (fs.existsSync(resolved)) return resolved;
+    } catch {
+    }
+    return fromModule;
+  }
+  async init() {
+    try {
+      const wasmBinary = fs.readFileSync(this.resolveWasmPath());
+      const SQL = await initSqlJs({ wasmBinary });
+      fs.mkdirSync(DATA_DIR, { recursive: true });
+      let fileBuffer;
+      if (fs.existsSync(CONTEXT_DB)) {
+        try {
+          fileBuffer = fs.readFileSync(CONTEXT_DB);
+        } catch {
+        }
+      }
+      this.db = fileBuffer ? new SQL.Database(fileBuffer) : new SQL.Database();
+      this.db.run(`
+        CREATE TABLE IF NOT EXISTS commit_contexts (
+          sha            TEXT PRIMARY KEY,
+          repo           TEXT NOT NULL DEFAULT '',
+          branch         TEXT,
+          pr_number      INTEGER,
+          pr_title       TEXT,
+          pr_body        TEXT,
+          author         TEXT,
+          approvers      TEXT NOT NULL DEFAULT '[]',
+          linked_issues  TEXT NOT NULL DEFAULT '[]',
+          ai_generated   INTEGER NOT NULL DEFAULT 0,
+          ai_tool        TEXT,
+          files_changed  TEXT NOT NULL DEFAULT '[]',
+          captured_at    INTEGER NOT NULL,
+          merged_at      INTEGER
+        );
+        CREATE INDEX IF NOT EXISTS idx_cc_repo ON commit_contexts(repo);
+        CREATE INDEX IF NOT EXISTS idx_cc_captured ON commit_contexts(captured_at DESC);
+      `);
+      this._flush();
+      logger.info({ path: CONTEXT_DB }, "commit context store initialised");
+    } catch (err) {
+      logger.warn({ err }, "commit context store failed to init \u2014 running without persistence");
+    }
+  }
+  _flush() {
+    if (!this.db) return;
+    try {
+      const data = this.db.export();
+      fs.writeFileSync(CONTEXT_DB, Buffer.from(data));
+    } catch (err) {
+      logger.warn({ err }, "commit context store flush failed");
+    }
+  }
+  _row(cols, vals) {
+    const row = {};
+    cols.forEach((c, i) => {
+      row[c] = vals[i];
+    });
+    const parse = (key, fallback) => {
+      try {
+        return JSON.parse(String(row[key] ?? "[]"));
+      } catch {
+        return fallback;
+      }
+    };
+    return {
+      sha: String(row.sha ?? ""),
+      repo: String(row.repo ?? ""),
+      branch: row.branch ? String(row.branch) : null,
+      prNumber: row.pr_number != null ? Number(row.pr_number) : null,
+      prTitle: row.pr_title ? String(row.pr_title) : null,
+      prBody: row.pr_body ? String(row.pr_body) : null,
+      author: row.author ? String(row.author) : null,
+      approvers: parse("approvers", []),
+      linkedIssues: parse("linked_issues", []),
+      aiGenerated: Boolean(row.ai_generated),
+      aiTool: row.ai_tool ? String(row.ai_tool) : null,
+      filesChanged: parse("files_changed", []),
+      capturedAt: Number(row.captured_at ?? 0),
+      mergedAt: row.merged_at != null ? Number(row.merged_at) : null
+    };
+  }
+  upsert(ctx) {
+    if (!this.db) return;
+    try {
+      this.db.run(
+        `INSERT INTO commit_contexts
+           (sha, repo, branch, pr_number, pr_title, pr_body, author, approvers, linked_issues,
+            ai_generated, ai_tool, files_changed, captured_at, merged_at)
+         VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?)
+         ON CONFLICT(sha) DO UPDATE SET
+           repo=excluded.repo, branch=excluded.branch, pr_number=excluded.pr_number,
+           pr_title=excluded.pr_title, pr_body=excluded.pr_body, author=excluded.author,
+           approvers=excluded.approvers, linked_issues=excluded.linked_issues,
+           ai_generated=excluded.ai_generated, ai_tool=excluded.ai_tool,
+           files_changed=excluded.files_changed, merged_at=excluded.merged_at`,
+        [
+          ctx.sha,
+          ctx.repo,
+          ctx.branch,
+          ctx.prNumber,
+          ctx.prTitle,
+          ctx.prBody ? ctx.prBody.slice(0, 2e3) : null,
+          ctx.author,
+          JSON.stringify(ctx.approvers),
+          JSON.stringify(ctx.linkedIssues),
+          ctx.aiGenerated ? 1 : 0,
+          ctx.aiTool,
+          JSON.stringify(ctx.filesChanged.slice(0, 100)),
+          ctx.capturedAt,
+          ctx.mergedAt ?? null
+        ]
+      );
+      this._flush();
+    } catch (err) {
+      logger.warn({ err, sha: ctx.sha }, "commit context upsert failed");
+    }
+  }
+  getBySha(sha) {
+    if (!this.db) return null;
+    try {
+      const res = this.db.exec(
+        `SELECT * FROM commit_contexts WHERE sha=? OR sha LIKE ? LIMIT 1`,
+        [sha, `${sha.slice(0, 7)}%`]
+      );
+      if (!res[0]?.values?.length) return null;
+      return this._row(res[0].columns, res[0].values[0]);
+    } catch {
+      return null;
+    }
+  }
+  /** Returns contexts for a repo or service name, newest first. */
+  listByRepo(repo, limit = 20) {
+    if (!this.db) return [];
+    try {
+      const res = this.db.exec(
+        `SELECT * FROM commit_contexts WHERE repo LIKE ? ORDER BY captured_at DESC LIMIT ?`,
+        [`%${repo}%`, limit]
+      );
+      if (!res[0]?.values) return [];
+      return res[0].values.map((v) => this._row(res[0].columns, v));
+    } catch {
+      return [];
+    }
+  }
+  /** Returns contexts where the given relative file path appears in files_changed, newest first. */
+  listByFile(relPath, repo, limit = 10) {
+    if (!this.db) return [];
+    try {
+      const pattern = `%${relPath}%`;
+      const sql = repo ? `SELECT * FROM commit_contexts WHERE files_changed LIKE ? AND repo LIKE ? ORDER BY captured_at DESC LIMIT ?` : `SELECT * FROM commit_contexts WHERE files_changed LIKE ? ORDER BY captured_at DESC LIMIT ?`;
+      const params = repo ? [pattern, `%${repo}%`, limit] : [pattern, limit];
+      const res = this.db.exec(sql, params);
+      if (!res[0]?.values) return [];
+      return res[0].values.map((v) => this._row(res[0].columns, v));
+    } catch {
+      return [];
+    }
+  }
+  /** Returns contexts in a time window, optionally filtered by repo. */
+  listByWindow(since, until, repo, limit = 50) {
+    if (!this.db) return [];
+    try {
+      const sql = repo ? `SELECT * FROM commit_contexts WHERE captured_at BETWEEN ? AND ? AND repo LIKE ? ORDER BY captured_at DESC LIMIT ?` : `SELECT * FROM commit_contexts WHERE captured_at BETWEEN ? AND ? ORDER BY captured_at DESC LIMIT ?`;
+      const params = repo ? [since, until, `%${repo}%`, limit] : [since, until, limit];
+      const res = this.db.exec(sql, params);
+      if (!res[0]?.values) return [];
+      return res[0].values.map((v) => this._row(res[0].columns, v));
+    } catch {
+      return [];
+    }
+  }
+  count() {
+    if (!this.db) return 0;
+    try {
+      const res = this.db.exec("SELECT COUNT(*) FROM commit_contexts");
+      return Number(res[0]?.values?.[0]?.[0] ?? 0);
+    } catch {
+      return 0;
+    }
+  }
+}
+const commitContextStore = new CommitContextStore();
+export {
+  commitContextStore,
+  extractLinkedIssues
+};

package/dist/sensor/docker-log-stream.js

@@ -0,0 +1,164 @@
+import { spawn } from "child_process";
+import { store } from "./buffer.js";
+import logger from "./logger.js";
+const MAX_LINES_PER_SEC = 30;
+const RATE_WINDOW_MS = 1e3;
+const MAX_LINE_LENGTH = 2e3;
+const TAIL_LINES = 50;
+const _streams = /* @__PURE__ */ new Map();
+let _eventProc = null;
+let _active = false;
+function pushLine(stream, raw) {
+  const now = Date.now();
+  if (now - stream.windowStart > RATE_WINDOW_MS) {
+    stream.lineCount = 0;
+    stream.windowStart = now;
+  }
+  if (stream.lineCount >= MAX_LINES_PER_SEC) return;
+  stream.lineCount++;
+  const event = {
+    type: "terminal",
+    terminalName: `docker:${stream.name}`,
+    data: raw.slice(0, MAX_LINE_LENGTH),
+    timestamp: Date.now()
+  };
+  try {
+    store.push(event);
+  } catch {
+  }
+}
+function streamContainer(id, name) {
+  if (_streams.has(id)) return;
+  let proc;
+  try {
+    proc = spawn("docker", ["logs", "--follow", `--tail=${TAIL_LINES}`, id], {
+      stdio: ["ignore", "pipe", "pipe"]
+    });
+  } catch {
+    return;
+  }
+  const stream = {
+    id,
+    name,
+    kill: () => {
+      try {
+        proc.kill();
+      } catch {
+      }
+    },
+    lineCount: 0,
+    windowStart: Date.now()
+  };
+  _streams.set(id, stream);
+  function handleChunk(chunk, prefix) {
+    const text = chunk.toString("utf8");
+    for (const line of text.split("\n")) {
+      const trimmed = (prefix ? `[${prefix}] ` : "") + line.trim();
+      if (trimmed) pushLine(stream, trimmed);
+    }
+  }
+  if (proc.stdout) proc.stdout.on("data", (c) => handleChunk(c, ""));
+  if (proc.stderr) proc.stderr.on("data", (c) => handleChunk(c, "stderr"));
+  proc.on("close", () => {
+    _streams.delete(id);
+  });
+  proc.on("error", () => {
+    _streams.delete(id);
+  });
+  logger.info({ containerId: id.slice(0, 12), name }, "docker-log-stream: streaming");
+}
+async function enumerateContainers() {
+  return new Promise((resolve) => {
+    let out = "";
+    let proc;
+    try {
+      proc = spawn("docker", ["ps", "--format", "{{json .}}"], { stdio: ["ignore", "pipe", "ignore"] });
+    } catch {
+      resolve();
+      return;
+    }
+    if (proc.stdout) proc.stdout.on("data", (c) => {
+      out += c.toString();
+    });
+    proc.on("close", () => {
+      for (const line of out.split("\n")) {
+        const trimmed = line.trim();
+        if (!trimmed) continue;
+        try {
+          const obj = JSON.parse(trimmed);
+          const id = obj.ID ?? "";
+          const name = (obj.Names ?? obj.ID ?? "unknown").replace(/^\//, "");
+          if (id) streamContainer(id, name);
+        } catch {
+        }
+      }
+      resolve();
+    });
+    proc.on("error", () => resolve());
+  });
+}
+function subscribeToDockerEvents() {
+  try {
+    _eventProc = spawn(
+      "docker",
+      ["events", "--filter", "type=container", "--filter", "event=start", "--filter", "event=die", "--format", "{{json .}}"],
+      { stdio: ["ignore", "pipe", "ignore"] }
+    );
+  } catch {
+    return;
+  }
+  if (!_eventProc.stdout) return;
+  let buf = "";
+  _eventProc.stdout.on("data", (chunk) => {
+    buf += chunk.toString();
+    const lines = buf.split("\n");
+    buf = lines.pop() ?? "";
+    for (const line of lines) {
+      const trimmed = line.trim();
+      if (!trimmed) continue;
+      try {
+        const ev = JSON.parse(trimmed);
+        const id = ev.Actor?.ID ?? "";
+        const name = ev.Actor?.Attributes?.name ?? id.slice(0, 12);
+        if (ev.Action === "start" && id) {
+          streamContainer(id, name);
+        } else if (ev.Action === "die" && id) {
+          _streams.get(id)?.kill();
+          _streams.delete(id);
+        }
+      } catch {
+      }
+    }
+  });
+  _eventProc.on("error", () => {
+    _eventProc = null;
+  });
+  _eventProc.on("exit", () => {
+    _eventProc = null;
+  });
+}
+async function startDockerLogStream() {
+  if (_active) return;
+  _active = true;
+  await enumerateContainers();
+  subscribeToDockerEvents();
+  logger.info({ containers: _streams.size }, "docker-log-stream: started");
+}
+function stopDockerLogStream() {
+  _active = false;
+  for (const s of _streams.values()) s.kill();
+  _streams.clear();
+  try {
+    _eventProc?.kill();
+  } catch {
+  }
+  _eventProc = null;
+}
+function listStreamedContainers() {
+  return [..._streams.values()].map((s) => `${s.name} (${s.id.slice(0, 12)})`);
+}
+export {
+  listStreamedContainers,
+  startDockerLogStream,
+  stopDockerLogStream
+};