forgeos 0.1.0-alpha.0

package/src/forge/runtime/telemetry/context.ts

@@ -0,0 +1,192 @@
+import type { DbAdapter, DbTransaction } from "../db/adapter.ts";
+import { insertTelemetryEvent } from "./buffer.ts";
+import { generateSpanId } from "./correlation.ts";
+import { endTraceSpan, startTraceSpan } from "./spans.ts";
+import type {
+  ForgeTelemetryEnvelope,
+  TelemetryContext,
+  TelemetryEnvironment,
+  TelemetryRuntimeKind,
+} from "./types.ts";
+import { flushPendingTelemetry } from "./flush.ts";
+import { currentReleaseInfo } from "../release/runtime.ts";
+
+export interface CreateTelemetryContextOptions {
+  adapter: DbAdapter;
+  tx?: DbTransaction;
+  traceId: string;
+  requestId?: string;
+  runtime: { kind: TelemetryRuntimeKind; name?: string };
+  workflow?: ForgeTelemetryEnvelope["workflow"];
+  outbox?: ForgeTelemetryEnvelope["outbox"];
+  /** When true, events are written through tx (commands). When false, writes go to adapter immediately. */
+  bufferInTransaction?: boolean;
+  workspaceRoot?: string;
+  /** Sinks to flush when flush() is called */
+  sinks?: string[];
+}
+
+function resolveEnvironment(): TelemetryEnvironment {
+  const raw = process.env.FORGE_ENV ?? process.env.NODE_ENV ?? "dev";
+  if (raw === "production" || raw === "prod") {
+    return "prod";
+  }
+  if (raw === "test") {
+    return "test";
+  }
+  if (raw === "preview") {
+    return "preview";
+  }
+  return "dev";
+}
+
+function writeTarget(options: CreateTelemetryContextOptions): DbTransaction | DbAdapter {
+  if (options.bufferInTransaction && options.tx) {
+    return options.tx;
+  }
+  return options.adapter;
+}
+
+function baseEnvelope(
+  options: CreateTelemetryContextOptions,
+  type: ForgeTelemetryEnvelope["type"],
+): Omit<ForgeTelemetryEnvelope, "event" | "exception" | "log" | "span"> {
+  return {
+    schemaVersion: "0.1",
+    type,
+    traceId: options.traceId,
+    requestId: options.requestId,
+    environment: resolveEnvironment(),
+    runtime: options.runtime,
+    ...(options.workflow ? { workflow: options.workflow } : {}),
+    ...(options.outbox ? { outbox: options.outbox } : {}),
+    release: currentReleaseInfo(),
+    createdAt: new Date().toISOString(),
+  };
+}
+
+export function createTelemetryContext(
+  options: CreateTelemetryContextOptions,
+): TelemetryContext {
+  const target = () => writeTarget(options);
+  let currentSpanId: string | undefined;
+
+  return {
+    traceId: options.traceId,
+    requestId: options.requestId,
+
+    async capture(name, properties = {}) {
+      const envelope: ForgeTelemetryEnvelope = {
+        ...baseEnvelope(options, "event"),
+        event: { name, properties },
+      };
+      await insertTelemetryEvent(target(), envelope);
+    },
+
+    async captureException(error, context = {}) {
+      const message = error instanceof Error ? error.message : String(error);
+      const stack = error instanceof Error ? error.stack : undefined;
+      const errorName = error instanceof Error ? error.name : undefined;
+
+      const envelope: ForgeTelemetryEnvelope = {
+        ...baseEnvelope(options, "exception"),
+        event: undefined,
+        exception: {
+          name: errorName,
+          message,
+          stack,
+        },
+        ...(Object.keys(context).length > 0
+          ? {
+              log: {
+                level: "error",
+                message,
+                fields: context,
+              },
+            }
+          : {}),
+      };
+      await insertTelemetryEvent(target(), envelope);
+    },
+
+    async log(level, message, fields = {}) {
+      const envelope: ForgeTelemetryEnvelope = {
+        ...baseEnvelope(options, "log"),
+        log: { level, message, fields },
+      };
+      await insertTelemetryEvent(target(), envelope);
+    },
+
+    async span(name, attributes = {}) {
+      const spanId = generateSpanId();
+      const parentSpanId = currentSpanId;
+      currentSpanId = spanId;
+
+      await startTraceSpan(target(), {
+        traceId: options.traceId,
+        spanId,
+        parentSpanId,
+        name,
+        kind: options.runtime.kind,
+        attributes,
+      });
+
+      const spanEnvelope: ForgeTelemetryEnvelope = {
+        ...baseEnvelope(options, "span.start"),
+        span: { spanId, parentSpanId, name, attributes },
+      };
+      await insertTelemetryEvent(target(), spanEnvelope);
+
+      return {
+        spanId,
+        end: async (endAttributes = {}) => {
+          await endTraceSpan(target(), {
+            traceId: options.traceId,
+            spanId,
+            attributes: endAttributes,
+          });
+
+          const endEnvelope: ForgeTelemetryEnvelope = {
+            ...baseEnvelope(options, "span.end"),
+            span: { spanId, parentSpanId, name, attributes: endAttributes },
+          };
+          await insertTelemetryEvent(target(), endEnvelope);
+
+          if (currentSpanId === spanId) {
+            currentSpanId = parentSpanId;
+          }
+        },
+      };
+    },
+
+    async flush(sink) {
+      const sinks = sink ? [sink] : (options.sinks ?? ["local"]);
+      for (const sinkName of sinks) {
+        await flushPendingTelemetry(
+          options.adapter,
+          sinkName,
+          options.workspaceRoot ?? process.cwd(),
+        );
+      }
+    },
+  };
+}
+
+export function createNoopTelemetryContext(traceId: string): TelemetryContext {
+  const noop = async () => {
+    /* no-op without db */
+  };
+  const noopSpan = async () => ({
+    spanId: "noop",
+    end: noop,
+  });
+
+  return {
+    traceId,
+    capture: noop,
+    captureException: noop,
+    log: noop,
+    span: noopSpan,
+    flush: noop,
+  };
+}

package/src/forge/runtime/telemetry/correlation.ts

@@ -0,0 +1,13 @@
+import { randomBytes } from "node:crypto";
+
+export function generateTraceId(): string {
+  return randomBytes(16).toString("hex");
+}
+
+export function generateSpanId(): string {
+  return randomBytes(8).toString("hex");
+}
+
+export function generateRequestId(): string {
+  return randomBytes(8).toString("hex");
+}

package/src/forge/runtime/telemetry/flush.ts

@@ -0,0 +1,190 @@
+import { createDiagnostic } from "../../compiler/diagnostics/create.ts";
+import {
+  FORGE_TELEMETRY_SINK_FAILED,
+  FORGE_TELEMETRY_UNKNOWN_SINK,
+} from "../../compiler/diagnostics/codes.ts";
+import type { Diagnostic } from "../../compiler/types/diagnostic.ts";
+import type { DbAdapter } from "../db/adapter.ts";
+import type { ForgeTelemetryEnvelope } from "./types.ts";
+import { writeLocalJsonl } from "./sinks/local-jsonl.ts";
+import { sendToPosthog } from "./sinks/posthog.ts";
+import { sendToSentry } from "./sinks/sentry.ts";
+
+export interface FlushResult {
+  processed: number;
+  failed: number;
+  diagnostics: Diagnostic[];
+}
+
+function parseEnvelope(payload: unknown): ForgeTelemetryEnvelope {
+  if (typeof payload === "string") {
+    return JSON.parse(payload) as ForgeTelemetryEnvelope;
+  }
+  return payload as ForgeTelemetryEnvelope;
+}
+
+async function dispatchToSink(
+  sink: string,
+  envelope: ForgeTelemetryEnvelope,
+  workspaceRoot: string,
+): Promise<void> {
+  switch (sink) {
+    case "local":
+      await writeLocalJsonl(envelope, workspaceRoot);
+      return;
+    case "posthog":
+      await sendToPosthog(envelope, workspaceRoot);
+      return;
+    case "sentry":
+      await sendToSentry(envelope, workspaceRoot);
+      return;
+    default:
+      throw new Error(`unknown telemetry sink '${sink}'`);
+  }
+}
+
+export async function flushPendingTelemetry(
+  adapter: DbAdapter,
+  sink: string,
+  workspaceRoot: string,
+  limit = 100,
+): Promise<FlushResult> {
+  const diagnostics: Diagnostic[] = [];
+  let processed = 0;
+  let failed = 0;
+
+  const pending = await adapter.query(
+    `SELECT id, payload, attempts, max_attempts FROM _forge_telemetry_events
+     WHERE status = 'pending' AND next_attempt_at <= now()
+     ORDER BY id
+     LIMIT $1`,
+    [limit],
+  );
+
+  for (const row of pending.rows) {
+    const id = Number(row.id);
+    const attempts = Number(row.attempts ?? 0);
+    const maxAttempts = Number(row.max_attempts ?? 5);
+
+    try {
+      const envelope = parseEnvelope(row.payload);
+      await dispatchToSink(sink, envelope, workspaceRoot);
+
+      await adapter.query(
+        `UPDATE _forge_telemetry_events
+         SET status = 'processed', sink = $1, processed_at = now(), last_error = NULL
+         WHERE id = $2`,
+        [sink, id],
+      );
+      processed += 1;
+    } catch (error) {
+      const message = error instanceof Error ? error.message : "telemetry sink failed";
+      const nextAttempts = attempts + 1;
+
+      if (message.includes("unknown telemetry sink")) {
+        diagnostics.push(
+          createDiagnostic({
+            severity: "error",
+            code: FORGE_TELEMETRY_UNKNOWN_SINK,
+            message,
+          }),
+        );
+        failed += 1;
+        break;
+      }
+
+      if (nextAttempts >= maxAttempts) {
+        await adapter.query(
+          `UPDATE _forge_telemetry_events
+           SET status = 'failed', sink = $1, attempts = $2, last_error = $3, processed_at = now()
+           WHERE id = $4`,
+          [sink, nextAttempts, message, id],
+        );
+      } else {
+        const nextAttemptAt = new Date(Date.now() + nextAttempts * 1_000).toISOString();
+        await adapter.query(
+          `UPDATE _forge_telemetry_events
+           SET attempts = $1, last_error = $2, next_attempt_at = $3, sink = $4
+           WHERE id = $5`,
+          [nextAttempts, message, nextAttemptAt, sink, id],
+        );
+      }
+
+      diagnostics.push(
+        createDiagnostic({
+          severity: "warning",
+          code: FORGE_TELEMETRY_SINK_FAILED,
+          message: `telemetry sink '${sink}' failed for event ${id}: ${message}`,
+        }),
+      );
+      failed += 1;
+    }
+  }
+
+  return { processed, failed, diagnostics };
+}
+
+export async function getTelemetrySummary(adapter: DbAdapter): Promise<{
+  pending: number;
+  failed: number;
+  processed: number;
+}> {
+  const result = await adapter.query(
+    `SELECT status, COUNT(*)::int AS count FROM _forge_telemetry_events GROUP BY status`,
+  );
+
+  const counts: Record<string, number> = {};
+  for (const row of result.rows) {
+    counts[String(row.status)] = Number(row.count);
+  }
+
+  return {
+    pending: counts.pending ?? 0,
+    failed: counts.failed ?? 0,
+    processed: counts.processed ?? 0,
+  };
+}
+
+export async function listTelemetryEvents(
+  adapter: DbAdapter,
+  limit = 100,
+): Promise<Record<string, unknown>[]> {
+  const result = await adapter.query(
+    `SELECT id, trace_id, event_type, payload, status, sink, attempts, last_error, created_at, processed_at
+     FROM _forge_telemetry_events
+     ORDER BY id DESC
+     LIMIT $1`,
+    [limit],
+  );
+  return result.rows;
+}
+
+export async function inspectTrace(
+  adapter: DbAdapter,
+  traceId: string,
+): Promise<{
+  events: Record<string, unknown>[];
+  spans: Record<string, unknown>[];
+}> {
+  const events = await adapter.query(
+    `SELECT id, trace_id, event_type, payload, status, created_at
+     FROM _forge_telemetry_events WHERE trace_id = $1 ORDER BY id`,
+    [traceId],
+  );
+  const spans = await adapter.query(
+    `SELECT id, trace_id, parent_span_id, span_id, name, kind, attributes, status, started_at, ended_at, error
+     FROM _forge_trace_spans WHERE trace_id = $1 ORDER BY started_at`,
+    [traceId],
+  );
+
+  return {
+    events: events.rows,
+    spans: spans.rows,
+  };
+}
+
+export async function clearTelemetryEvents(adapter: DbAdapter): Promise<number> {
+  const events = await adapter.query(`DELETE FROM _forge_telemetry_events`);
+  await adapter.query(`DELETE FROM _forge_trace_spans`);
+  return events.rowCount;
+}

package/src/forge/runtime/telemetry/process.ts

@@ -0,0 +1,20 @@
+import type { DbAdapter } from "../db/adapter.ts";
+import { flushPendingTelemetry } from "./flush.ts";
+
+export async function processTelemetryBatch(
+  adapter: DbAdapter,
+  workspaceRoot: string,
+  sinks: string[] = ["local"],
+  limit = 50,
+): Promise<{ processed: number; failed: number }> {
+  let processed = 0;
+  let failed = 0;
+
+  for (const sink of sinks) {
+    const result = await flushPendingTelemetry(adapter, sink, workspaceRoot, limit);
+    processed += result.processed;
+    failed += result.failed;
+  }
+
+  return { processed, failed };
+}

package/src/forge/runtime/telemetry/scrubber.ts

@@ -0,0 +1,115 @@
+import { createDiagnostic } from "../../compiler/diagnostics/create.ts";
+import {
+  FORGE_TELEMETRY_PAYLOAD_TRUNCATED,
+  FORGE_TELEMETRY_SECRET_REDACTED,
+} from "../../compiler/diagnostics/codes.ts";
+import type { Diagnostic } from "../../compiler/types/diagnostic.ts";
+
+const SECRET_KEY_PATTERN =
+  /password|secret|token|apikey|authorization|cookie/i;
+
+const MAX_PAYLOAD_BYTES = 8_192;
+const MAX_STACK_BYTES = 4_096;
+
+export interface ScrubResult<T> {
+  value: T;
+  diagnostics: Diagnostic[];
+}
+
+function redactValue(key: string, value: unknown, diagnostics: Diagnostic[]): unknown {
+  if (SECRET_KEY_PATTERN.test(key)) {
+    diagnostics.push(
+      createDiagnostic({
+        severity: "warning",
+        code: FORGE_TELEMETRY_SECRET_REDACTED,
+        message: `redacted telemetry field '${key}'`,
+      }),
+    );
+    return "[REDACTED]";
+  }
+
+  if (value && typeof value === "object" && !Array.isArray(value)) {
+    return scrubObject(value as Record<string, unknown>, diagnostics);
+  }
+
+  if (Array.isArray(value)) {
+    return value.map((item, index) =>
+      redactValue(String(index), item, diagnostics),
+    );
+  }
+
+  return value;
+}
+
+function scrubObject(
+  obj: Record<string, unknown>,
+  diagnostics: Diagnostic[],
+): Record<string, unknown> {
+  const result: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(obj)) {
+    result[key] = redactValue(key, value, diagnostics);
+  }
+  return result;
+}
+
+function truncateString(
+  value: string,
+  maxBytes: number,
+  diagnostics: Diagnostic[],
+  field: string,
+): string {
+  const encoded = Buffer.byteLength(value, "utf8");
+  if (encoded <= maxBytes) {
+    return value;
+  }
+
+  diagnostics.push(
+    createDiagnostic({
+      severity: "warning",
+      code: FORGE_TELEMETRY_PAYLOAD_TRUNCATED,
+      message: `truncated telemetry ${field} from ${encoded} to ${maxBytes} bytes`,
+    }),
+  );
+
+  let truncated = value;
+  while (Buffer.byteLength(truncated, "utf8") > maxBytes && truncated.length > 0) {
+    truncated = truncated.slice(0, Math.floor(truncated.length * 0.9));
+  }
+  return truncated;
+}
+
+export function scrubEnvelopePayload<T extends Record<string, unknown>>(
+  payload: T,
+): ScrubResult<T> {
+  const diagnostics: Diagnostic[] = [];
+  const scrubbed = scrubObject(payload, diagnostics) as T;
+
+  if (typeof scrubbed.exception === "object" && scrubbed.exception !== null) {
+    const exception = scrubbed.exception as Record<string, unknown>;
+    if (typeof exception.stack === "string") {
+      exception.stack = truncateString(
+        exception.stack,
+        MAX_STACK_BYTES,
+        diagnostics,
+        "stack",
+      );
+    }
+  }
+
+  const serialized = JSON.stringify(scrubbed);
+  if (Buffer.byteLength(serialized, "utf8") > MAX_PAYLOAD_BYTES) {
+    diagnostics.push(
+      createDiagnostic({
+        severity: "warning",
+        code: FORGE_TELEMETRY_PAYLOAD_TRUNCATED,
+        message: `truncated telemetry payload to ${MAX_PAYLOAD_BYTES} bytes`,
+      }),
+    );
+    const parsed = JSON.parse(
+      truncateString(serialized, MAX_PAYLOAD_BYTES, diagnostics, "payload"),
+    ) as T;
+    return { value: parsed, diagnostics };
+  }
+
+  return { value: scrubbed, diagnostics };
+}

package/src/forge/runtime/telemetry/sinks/local-jsonl.ts

@@ -0,0 +1,39 @@
+import { join } from "node:path";
+import { nodeFileSystem } from "../../../compiler/fs/index.ts";
+import type { ForgeTelemetryEnvelope } from "../types.ts";
+
+function telemetryDir(workspaceRoot: string): string {
+  return join(workspaceRoot, ".forge", "local", "telemetry");
+}
+
+function fileForType(type: ForgeTelemetryEnvelope["type"], workspaceRoot: string): string {
+  const dir = telemetryDir(workspaceRoot);
+  if (type === "exception") {
+    return join(dir, "exceptions.jsonl");
+  }
+  if (type === "span.start" || type === "span.end") {
+    return join(dir, "spans.jsonl");
+  }
+  return join(dir, "events.jsonl");
+}
+
+export async function writeLocalJsonl(
+  envelope: ForgeTelemetryEnvelope,
+  workspaceRoot: string,
+): Promise<void> {
+  const file = fileForType(envelope.type, workspaceRoot);
+  nodeFileSystem.appendText(file, `${JSON.stringify(envelope)}\n`);
+}
+
+export function localJsonlPaths(workspaceRoot: string): {
+  events: string;
+  exceptions: string;
+  spans: string;
+} {
+  const dir = telemetryDir(workspaceRoot);
+  return {
+    events: join(dir, "events.jsonl"),
+    exceptions: join(dir, "exceptions.jsonl"),
+    spans: join(dir, "spans.jsonl"),
+  };
+}

package/src/forge/runtime/telemetry/sinks/posthog.ts

@@ -0,0 +1,64 @@
+import type { ForgeTelemetryEnvelope } from "../types.ts";
+
+export interface PosthogCaptureFn {
+  (event: string, properties: Record<string, unknown>, distinctId: string): Promise<void> | void;
+}
+
+let injectedCapture: PosthogCaptureFn | null = null;
+
+export function setPosthogCaptureForTests(fn: PosthogCaptureFn | null): void {
+  injectedCapture = fn;
+}
+
+export async function sendToPosthog(
+  envelope: ForgeTelemetryEnvelope,
+  workspaceRoot: string,
+): Promise<void> {
+  if (envelope.type !== "event" || !envelope.event) {
+    return;
+  }
+
+  if (injectedCapture) {
+    await injectedCapture(
+      envelope.event.name,
+      {
+        ...envelope.event.properties,
+        traceId: envelope.traceId,
+        requestId: envelope.requestId,
+        runtime: envelope.runtime,
+      },
+      envelope.traceId,
+    );
+    return;
+  }
+
+  try {
+    const adapterPath = `${workspaceRoot}/src/forge/_generated/packages/posthog.server.ts`.replace(
+      /\\/g,
+      "/",
+    );
+    const mod = (await import(adapterPath)) as {
+      createPosthogServer?: () => { capture: (args: unknown) => void; shutdown: () => Promise<void> };
+    };
+
+    if (typeof mod.createPosthogServer === "function") {
+      const client = mod.createPosthogServer();
+      client.capture({
+        distinctId: envelope.traceId,
+        event: envelope.event.name,
+        properties: {
+          ...envelope.event.properties,
+          traceId: envelope.traceId,
+          requestId: envelope.requestId,
+          runtime: envelope.runtime,
+        },
+      });
+      await client.shutdown();
+      return;
+    }
+  } catch {
+    /* fall through — adapter not installed */
+  }
+
+  throw new Error("posthog adapter not available");
+}

package/src/forge/runtime/telemetry/sinks/sentry.ts

@@ -0,0 +1,60 @@
+import type { ForgeTelemetryEnvelope } from "../types.ts";
+
+export interface SentryCaptureFn {
+  (error: Error, context?: Record<string, unknown>): Promise<void> | void;
+}
+
+let injectedCapture: SentryCaptureFn | null = null;
+
+export function setSentryCaptureForTests(fn: SentryCaptureFn | null): void {
+  injectedCapture = fn;
+}
+
+export async function sendToSentry(
+  envelope: ForgeTelemetryEnvelope,
+  workspaceRoot: string,
+): Promise<void> {
+  if (envelope.type !== "exception" || !envelope.exception) {
+    return;
+  }
+
+  const error = new Error(envelope.exception.message);
+  if (envelope.exception.name) {
+    error.name = envelope.exception.name;
+  }
+  if (envelope.exception.stack) {
+    error.stack = envelope.exception.stack;
+  }
+
+  const context = {
+    traceId: envelope.traceId,
+    requestId: envelope.requestId,
+    runtime: envelope.runtime,
+    workflow: envelope.workflow,
+    outbox: envelope.outbox,
+  };
+
+  if (injectedCapture) {
+    await injectedCapture(error, context);
+    return;
+  }
+
+  try {
+    const adapterPath = `${workspaceRoot}/src/forge/_generated/packages/sentry.server.ts`.replace(
+      /\\/g,
+      "/",
+    );
+    const mod = (await import(adapterPath)) as {
+      captureServerException?: (err: Error, ctx?: Record<string, unknown>) => void;
+    };
+
+    if (typeof mod.captureServerException === "function") {
+      mod.captureServerException(error, context);
+      return;
+    }
+  } catch {
+    /* fall through */
+  }
+
+  throw new Error("sentry adapter not available");
+}