@a-company/sentinel 0.2.0 → 3.5.0

package/dist/chunk-VQ3SIN7S.js

@@ -0,0 +1,422 @@
+// src/client.ts
+import { v4 as uuidv4 } from "uuid";
+var DEFAULTS = {
+  url: "http://localhost:3838",
+  batchSize: 50,
+  flushIntervalMs: 5e3,
+  maxBufferSize: 1e3,
+  maxRetries: 3,
+  retryBackoffMs: 1e3
+};
+var SentinelClient = class {
+  url;
+  service;
+  version;
+  environment;
+  token;
+  batchSize;
+  maxBufferSize;
+  maxRetries;
+  retryBackoffMs;
+  onDrop;
+  onError;
+  sessionId;
+  logBuffer = [];
+  metricsBuffer = [];
+  flushTimer = null;
+  closed = false;
+  beforeUnloadHandler = null;
+  constructor(options) {
+    this.url = (options.url ?? DEFAULTS.url).replace(/\/+$/, "");
+    this.service = options.service;
+    this.version = options.version;
+    this.environment = options.environment;
+    this.token = options.token;
+    this.batchSize = options.batchSize ?? DEFAULTS.batchSize;
+    this.maxBufferSize = options.maxBufferSize ?? DEFAULTS.maxBufferSize;
+    this.maxRetries = options.maxRetries ?? DEFAULTS.maxRetries;
+    this.retryBackoffMs = options.retryBackoffMs ?? DEFAULTS.retryBackoffMs;
+    this.onDrop = options.onDrop;
+    this.onError = options.onError;
+    this.sessionId = uuidv4();
+    const intervalMs = options.flushIntervalMs ?? DEFAULTS.flushIntervalMs;
+    this.flushTimer = setInterval(() => {
+      this.flush().catch((err) => {
+        this.handleError(err);
+      });
+    }, intervalMs);
+    if (this.flushTimer && typeof this.flushTimer === "object" && "unref" in this.flushTimer) {
+      this.flushTimer.unref();
+    }
+    if (typeof globalThis !== "undefined" && typeof globalThis.addEventListener === "function") {
+      this.beforeUnloadHandler = () => {
+        this.flushSync();
+      };
+      globalThis.addEventListener("beforeunload", this.beforeUnloadHandler);
+    }
+    this.registerService();
+  }
+  // ── Logging Methods ──────────────────────────────────────────────
+  /** Log a debug-level message */
+  debug(symbol, message, data) {
+    this.log("debug", symbol, message, data);
+  }
+  /** Log an info-level message */
+  info(symbol, message, data) {
+    this.log("info", symbol, message, data);
+  }
+  /** Log a warn-level message */
+  warn(symbol, message, data) {
+    this.log("warn", symbol, message, data);
+  }
+  /** Log an error-level message */
+  error(symbol, message, data) {
+    this.log("error", symbol, message, data);
+  }
+  /** Log a message at the specified level */
+  log(level, symbol, message, data) {
+    if (this.closed) return;
+    const entry = {
+      level,
+      symbol,
+      message,
+      service: this.service,
+      sessionId: this.sessionId,
+      environment: this.environment,
+      data
+    };
+    this.pushToLogBuffer(entry);
+  }
+  // ── Metrics Methods ──────────────────────────────────────────────
+  /** Record a counter metric (increments) */
+  counter(name, value, tags) {
+    this.metric({ name, type: "counter", value: value ?? 1, tags });
+  }
+  /** Record a gauge metric (current value) */
+  gauge(name, value, tags) {
+    this.metric({ name, type: "gauge", value, tags });
+  }
+  /** Record a histogram metric (distribution) */
+  histogram(name, value, tags) {
+    this.metric({ name, type: "histogram", value, tags });
+  }
+  /** Record a metric of any type */
+  metric(input) {
+    if (this.closed) return;
+    const entry = {
+      ...input,
+      service: this.service,
+      environment: this.environment
+    };
+    this.pushToMetricsBuffer(entry);
+  }
+  // ── State Push ───────────────────────────────────────────────────
+  /** Push an application state snapshot to the server */
+  async pushState(state, activeFlows, activeGates) {
+    if (this.closed) return;
+    await this.post("/api/state", {
+      service: this.service,
+      sessionId: this.sessionId,
+      state,
+      activeFlows,
+      activeGates
+    });
+  }
+  // ── Tracing ──────────────────────────────────────────────────────
+  /** Start a trace span. Call end() on the returned SpanContext when the operation completes. */
+  startSpan(symbol, operation, parentSpanId) {
+    const traceId = parentSpanId ? parentSpanId.split("-")[0] || uuidv4() : uuidv4();
+    const spanId = uuidv4();
+    const startTime = (/* @__PURE__ */ new Date()).toISOString();
+    const startMs = Date.now();
+    const self = this;
+    return {
+      traceId,
+      spanId,
+      async end(status = "ok") {
+        const endTime = (/* @__PURE__ */ new Date()).toISOString();
+        const durationMs = Date.now() - startMs;
+        const span = {
+          traceId,
+          spanId,
+          parentSpanId,
+          service: self.service,
+          symbol,
+          operation,
+          startTime,
+          endTime,
+          durationMs,
+          status
+        };
+        await self.post("/api/traces", span);
+      }
+    };
+  }
+  // ── Buffer Management ────────────────────────────────────────────
+  /** Flush all buffered logs and metrics to the server */
+  async flush() {
+    const logEntries = this.drainLogBuffer();
+    const metricEntries = this.drainMetricsBuffer();
+    const promises = [];
+    if (logEntries.length > 0) {
+      promises.push(this.sendLogs(logEntries));
+    }
+    if (metricEntries.length > 0) {
+      promises.push(this.sendMetrics(metricEntries));
+    }
+    await Promise.allSettled(promises);
+  }
+  // ── Lifecycle ────────────────────────────────────────────────────
+  /** Flush remaining entries and shut down the client */
+  async close() {
+    if (this.closed) return;
+    this.closed = true;
+    if (this.flushTimer !== null) {
+      clearInterval(this.flushTimer);
+      this.flushTimer = null;
+    }
+    if (this.beforeUnloadHandler && typeof globalThis !== "undefined" && typeof globalThis.removeEventListener === "function") {
+      globalThis.removeEventListener("beforeunload", this.beforeUnloadHandler);
+      this.beforeUnloadHandler = null;
+    }
+    try {
+      await this.flush();
+    } catch {
+    }
+  }
+  /** Get the session ID assigned to this client instance */
+  getSessionId() {
+    return this.sessionId;
+  }
+  /**
+   * Synchronous best-effort flush using sendBeacon (browser) or sync XHR fallback.
+   * Used in beforeunload where async is unreliable.
+   */
+  flushSync() {
+    const logEntries = this.drainLogBuffer();
+    const metricEntries = this.drainMetricsBuffer();
+    const sendBeacon = typeof navigator !== "undefined" && typeof navigator.sendBeacon === "function" ? navigator.sendBeacon.bind(navigator) : void 0;
+    if (sendBeacon) {
+      if (logEntries.length > 0) {
+        sendBeacon(`${this.url}/api/logs`, JSON.stringify({ entries: logEntries }));
+      }
+      if (metricEntries.length > 0) {
+        sendBeacon(`${this.url}/api/metrics`, JSON.stringify({ entries: metricEntries }));
+      }
+    }
+  }
+  // ═══════════════════════════════════════════════════════════════════
+  // PRIVATE METHODS
+  // ═══════════════════════════════════════════════════════════════════
+  /** Register this service with the Sentinel server (fire-and-forget) */
+  registerService() {
+    const registration = {
+      name: this.service,
+      version: this.version,
+      pid: typeof process !== "undefined" ? process.pid : void 0,
+      environment: this.environment
+    };
+    this.post("/api/services", registration).catch(() => {
+    });
+  }
+  /** Push a log entry into the ring buffer, enforcing maxBufferSize */
+  pushToLogBuffer(entry) {
+    if (this.logBuffer.length >= this.maxBufferSize) {
+      const dropCount = Math.max(1, Math.floor(this.maxBufferSize * 0.1));
+      this.logBuffer.splice(0, dropCount);
+      if (this.onDrop) {
+        this.onDrop(dropCount);
+      }
+    }
+    this.logBuffer.push(entry);
+    if (this.logBuffer.length >= this.batchSize) {
+      this.flush().catch((err) => {
+        this.handleError(err);
+      });
+    }
+  }
+  /** Push a metric entry into the ring buffer, enforcing maxBufferSize */
+  pushToMetricsBuffer(entry) {
+    if (this.metricsBuffer.length >= this.maxBufferSize) {
+      const dropCount = Math.max(1, Math.floor(this.maxBufferSize * 0.1));
+      this.metricsBuffer.splice(0, dropCount);
+      if (this.onDrop) {
+        this.onDrop(dropCount);
+      }
+    }
+    this.metricsBuffer.push(entry);
+    if (this.metricsBuffer.length >= this.batchSize) {
+      this.flush().catch((err) => {
+        this.handleError(err);
+      });
+    }
+  }
+  /** Drain and return all entries from the log buffer */
+  drainLogBuffer() {
+    const entries = this.logBuffer;
+    this.logBuffer = [];
+    return entries;
+  }
+  /** Drain and return all entries from the metrics buffer */
+  drainMetricsBuffer() {
+    const entries = this.metricsBuffer;
+    this.metricsBuffer = [];
+    return entries;
+  }
+  /** Send log entries to the server with retry */
+  async sendLogs(entries) {
+    try {
+      await this.post("/api/logs", { entries });
+    } catch (err) {
+      const capacity = this.maxBufferSize - this.logBuffer.length;
+      if (capacity > 0) {
+        const toRestore = entries.slice(0, capacity);
+        this.logBuffer.unshift(...toRestore);
+        const dropped = entries.length - toRestore.length;
+        if (dropped > 0 && this.onDrop) {
+          this.onDrop(dropped);
+        }
+      } else if (this.onDrop) {
+        this.onDrop(entries.length);
+      }
+      throw err;
+    }
+  }
+  /** Send metric entries to the server with retry */
+  async sendMetrics(entries) {
+    try {
+      await this.post("/api/metrics", { entries });
+    } catch (err) {
+      const capacity = this.maxBufferSize - this.metricsBuffer.length;
+      if (capacity > 0) {
+        const toRestore = entries.slice(0, capacity);
+        this.metricsBuffer.unshift(...toRestore);
+        const dropped = entries.length - toRestore.length;
+        if (dropped > 0 && this.onDrop) {
+          this.onDrop(dropped);
+        }
+      } else if (this.onDrop) {
+        this.onDrop(entries.length);
+      }
+      throw err;
+    }
+  }
+  /**
+   * POST JSON to the Sentinel server with exponential backoff retry.
+   * Retries on network errors and 5xx responses. Does NOT retry on 4xx.
+   */
+  async post(path, body) {
+    const fetchFn = this.getFetch();
+    if (!fetchFn) {
+      return void 0;
+    }
+    const url = `${this.url}${path}`;
+    const headers = {
+      "Content-Type": "application/json"
+    };
+    if (this.token) {
+      headers["Authorization"] = `Bearer ${this.token}`;
+    }
+    let lastError;
+    for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
+      try {
+        const response = await fetchFn(url, {
+          method: "POST",
+          headers,
+          body: JSON.stringify(body)
+        });
+        if (response.status >= 400 && response.status < 500) {
+          const text = await response.text().catch(() => "");
+          const err = new Error(`Sentinel server returned ${response.status}: ${text}`);
+          this.handleError(err);
+          return void 0;
+        }
+        if (response.status >= 500) {
+          const text = await response.text().catch(() => "");
+          lastError = new Error(`Sentinel server returned ${response.status}: ${text}`);
+          if (attempt < this.maxRetries) {
+            await this.backoff(attempt);
+            continue;
+          }
+          this.handleError(lastError);
+          throw lastError;
+        }
+        const contentType = response.headers.get("content-type") || "";
+        if (contentType.includes("application/json")) {
+          return await response.json();
+        }
+        return void 0;
+      } catch (err) {
+        lastError = err instanceof Error ? err : new Error(String(err));
+        if (attempt < this.maxRetries) {
+          await this.backoff(attempt);
+          continue;
+        }
+        this.handleError(lastError);
+        throw lastError;
+      }
+    }
+    if (lastError) throw lastError;
+    return void 0;
+  }
+  /** Get the fetch function, falling back to globalThis.fetch */
+  getFetch() {
+    if (typeof globalThis !== "undefined" && typeof globalThis.fetch === "function") {
+      return globalThis.fetch;
+    }
+    return void 0;
+  }
+  /** Wait with exponential backoff */
+  backoff(attempt) {
+    const delayMs = this.retryBackoffMs * Math.pow(2, attempt);
+    const jitter = Math.floor(Math.random() * delayMs * 0.25);
+    return new Promise((resolve) => setTimeout(resolve, delayMs + jitter));
+  }
+  /** Handle an error, calling the onError callback if provided */
+  handleError(err) {
+    if (this.onError) {
+      const error = err instanceof Error ? err : new Error(String(err));
+      this.onError(error);
+    }
+  }
+};
+function createSentinelClient(options) {
+  return new SentinelClient(options);
+}
+
+// src/transport.ts
+var SentinelTransport = class {
+  client;
+  constructor(client) {
+    this.client = client;
+  }
+  send(entry) {
+    this.client.log(
+      entry.level,
+      entry.symbol,
+      entry.message,
+      {
+        ...entry.data,
+        symbolType: entry.symbolType,
+        correlationId: entry.correlationId
+      }
+    );
+  }
+};
+function createSentinelTransport(clientOrOptions) {
+  const client = clientOrOptions instanceof SentinelClient ? clientOrOptions : new SentinelClient(clientOrOptions);
+  return new SentinelTransport(client);
+}
+function enableSentinel(logger, clientOrOptions) {
+  const transport = createSentinelTransport(clientOrOptions);
+  logger.addTransport(transport);
+  return transport;
+}
+
+export {
+  SentinelClient,
+  createSentinelClient,
+  SentinelTransport,
+  createSentinelTransport,
+  enableSentinel
+};

package/dist/cli.js

@@ -5,28 +5,28 @@ import { Command } from "commander";
 var program = new Command();
 program.name("sentinel").description("Semantic error monitoring \u2014 errors that speak your language").version("0.2.0");
 program.command("dashboard", { isDefault: true }).description("Launch the Sentinel dashboard").option("-p, --port <port>", "Port number", "3838").option("--no-open", "Don't open browser").action(async (opts) => {
-  const { launchDashboard } = await import("./commands-KIMGFR2I.js");
+  const { launchDashboard } = await import("./commands-7PHRWGOB.js");
   await launchDashboard(opts);
 });
 program.command("init").description("Initialize Sentinel in current project").option("--detect", "Auto-detect symbols from codebase").action(async (opts) => {
-  const { initProject } = await import("./commands-KIMGFR2I.js");
+  const { initProject } = await import("./commands-7PHRWGOB.js");
   await initProject(opts);
 });
 var triage = program.command("triage").description("Incident triage");
 triage.command("list").description("List incidents").option("-s, --status <status>", "Filter by status (open, investigating, resolved, wont-fix)").option("-e, --env <env>", "Filter by environment").option("--symbol <symbol>", "Filter by symbol").option("-n, --limit <n>", "Max results", "10").action(async (opts) => {
-  const { triageList } = await import("./commands-KIMGFR2I.js");
+  const { triageList } = await import("./commands-7PHRWGOB.js");
   await triageList(opts);
 });
 triage.command("show <id>").description("Show incident details").option("--timeline", "Include flow timeline").action(async (id, opts) => {
-  const { triageShow } = await import("./commands-KIMGFR2I.js");
+  const { triageShow } = await import("./commands-7PHRWGOB.js");
   await triageShow(id, opts);
 });
 triage.command("resolve <id>").description("Resolve an incident").option("--pattern <id>", "Pattern that resolved it").option("--commit <hash>", "Fix commit").option("--notes <text>", "Resolution notes").action(async (id, opts) => {
-  const { triageResolve } = await import("./commands-KIMGFR2I.js");
+  const { triageResolve } = await import("./commands-7PHRWGOB.js");
   await triageResolve(id, opts);
 });
 triage.command("stats").description("Show incident statistics").option("-p, --period <period>", "Period (7d, 30d, 90d)", "7d").action(async (opts) => {
-  const { triageStats } = await import("./commands-KIMGFR2I.js");
+  const { triageStats } = await import("./commands-7PHRWGOB.js");
   await triageStats(opts);
 });
 program.parse();