@evo-dev/core 0.0.1-alpha

package/src/observability/index.ts

@@ -0,0 +1,272 @@
+import { mkdir, readFile, readdir, stat, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+
+export type ObservabilityEventType =
+  | "verification.completed"
+  | "workflow.step.planned"
+  | "test-run.completed"
+  | "review.finding";
+
+export interface ObservabilityEvent {
+  version: 1;
+  eventId: string;
+  type: ObservabilityEventType;
+  timestamp: string;
+  scope?: {
+    taskId?: string;
+    workflowId?: string;
+    projectId?: string;
+  };
+  privacy: {
+    classification: "local-private";
+    metadataOnly: true;
+    rawPayloadStored: false;
+    rawOutputStored: false;
+    sourceContentStored: false;
+    promptStored: false;
+  };
+  summary: string;
+  data: Record<string, string | number | boolean | string[]>;
+}
+
+export interface ObservabilityStorePaths {
+  rootDir: string;
+  eventsPath: string;
+}
+
+export interface RetentionDryRunResult {
+  candidates: Array<{ path: string; sizeBytes: number; reason: string }>;
+  totalBytes: number;
+}
+
+const EVENT_TYPE_TO_DIR: Record<ObservabilityEventType, string> = {
+  "verification.completed": "verification",
+  "workflow.step.planned": "workflows",
+  "test-run.completed": "tests",
+  "review.finding": "reviews",
+};
+
+const FORBIDDEN_RAW_KEYS = new Set([
+  "commandoutput",
+  "memorybodies",
+  "memorybody",
+  "promptbody",
+  "prompttext",
+  "rawcommandoutput",
+  "rawoutput",
+  "rawpayload",
+  "secret",
+  "secretvalue",
+  "source",
+  "sourcebody",
+  "sourcecode",
+  "sourcecontent",
+  "sourcetext",
+  "stderr",
+  "stdout",
+  "transcript",
+  "transcriptbody",
+  "transcripttext",
+]);
+const SENSITIVE_TEXT_PATTERN =
+  /https?:\/\/\S+|\b(secret|token|password|passwd|private|internal|api[_-]?key|apikey|credential|credentials|raw log|raw source|raw prompt)\b/i;
+
+export function createObservabilityEvent(input: {
+  eventId: string;
+  type: ObservabilityEventType;
+  summary: string;
+  data?: Record<string, string | number | boolean | string[]>;
+  timestamp?: string;
+  scope?: ObservabilityEvent["scope"];
+}): ObservabilityEvent {
+  const event: ObservabilityEvent = {
+    version: 1,
+    eventId: sanitizeId(input.eventId),
+    type: input.type,
+    timestamp: input.timestamp ?? new Date().toISOString(),
+    scope: input.scope,
+    privacy: {
+      classification: "local-private",
+      metadataOnly: true,
+      rawPayloadStored: false,
+      rawOutputStored: false,
+      sourceContentStored: false,
+      promptStored: false,
+    },
+    summary: sanitizeText(input.summary),
+    data: sanitizeData(input.data ?? {}),
+  };
+  validateObservabilityEvent(event);
+  return event;
+}
+
+export function validateObservabilityEvent(event: ObservabilityEvent): void {
+  if (event.version !== 1) throw new Error("Observability event version must be 1.");
+  if (event.privacy.metadataOnly !== true)
+    throw new Error("Observability event must be metadata-only.");
+  if (
+    event.privacy.rawPayloadStored !== false ||
+    event.privacy.rawOutputStored !== false ||
+    event.privacy.sourceContentStored !== false ||
+    event.privacy.promptStored !== false
+  ) {
+    throw new Error("Observability event cannot store raw payload/output/source/prompt.");
+  }
+  assertNoForbiddenContent(event);
+}
+
+export function resolveObservabilityStorePaths(
+  homeDir: string,
+  type: ObservabilityEventType,
+): ObservabilityStorePaths {
+  const rootDir = join(homeDir, ".evodev", "OBSERVABILITY", EVENT_TYPE_TO_DIR[type]);
+  return { rootDir, eventsPath: join(rootDir, "events.jsonl") };
+}
+
+export async function appendObservabilityEvent(
+  homeDir: string,
+  event: ObservabilityEvent,
+): Promise<string> {
+  validateObservabilityEvent(event);
+  const paths = resolveObservabilityStorePaths(homeDir, event.type);
+  await mkdir(dirname(paths.eventsPath), { recursive: true });
+  await writeFile(paths.eventsPath, `${JSON.stringify(event)}\n`, { encoding: "utf8", flag: "a" });
+  return paths.eventsPath;
+}
+
+export async function listObservabilityEvents(
+  homeDir: string,
+  type?: ObservabilityEventType,
+): Promise<ObservabilityEvent[]> {
+  const eventTypes =
+    type === undefined ? (Object.keys(EVENT_TYPE_TO_DIR) as ObservabilityEventType[]) : [type];
+  const events: ObservabilityEvent[] = [];
+
+  for (const eventType of eventTypes) {
+    const path = resolveObservabilityStorePaths(homeDir, eventType).eventsPath;
+    if (!(await pathExists(path))) continue;
+    const lines = (await readFile(path, "utf8")).split("\n").filter(Boolean);
+    for (const line of lines) {
+      const event = JSON.parse(line) as ObservabilityEvent;
+      validateObservabilityEvent(event);
+      events.push(event);
+    }
+  }
+
+  return events.sort((left, right) => left.timestamp.localeCompare(right.timestamp));
+}
+
+export async function dryRunObservabilityRetentionCleanup(
+  homeDir: string,
+): Promise<RetentionDryRunResult> {
+  const root = join(homeDir, ".evodev", "OBSERVABILITY");
+  const candidates: RetentionDryRunResult["candidates"] = [];
+  if (!(await pathExists(root))) return { candidates, totalBytes: 0 };
+
+  for (const file of await collectJsonlFiles(root)) {
+    const fileStat = await stat(file);
+    candidates.push({ path: file, sizeBytes: fileStat.size, reason: "observability-jsonl" });
+  }
+
+  return {
+    candidates,
+    totalBytes: candidates.reduce((sum, candidate) => sum + candidate.sizeBytes, 0),
+  };
+}
+
+export function formatObservabilityEvents(events: ObservabilityEvent[]): string {
+  return [
+    "EvoDev observability events",
+    "",
+    ...events.map(
+      (event) => `- ${event.timestamp} ${event.type} ${event.eventId}: ${event.summary}`,
+    ),
+  ].join("\n");
+}
+
+export function formatRetentionDryRun(result: RetentionDryRunResult): string {
+  return [
+    "EvoDev observability cleanup dry-run",
+    "",
+    `Candidates: ${result.candidates.length}`,
+    `Total bytes: ${result.totalBytes}`,
+    ...result.candidates.map(
+      (candidate) => `- ${candidate.path} (${candidate.sizeBytes} bytes, ${candidate.reason})`,
+    ),
+  ].join("\n");
+}
+
+function sanitizeData(
+  data: Record<string, string | number | boolean | string[]>,
+): Record<string, string | number | boolean | string[]> {
+  const sanitized: Record<string, string | number | boolean | string[]> = {};
+  for (const [key, value] of Object.entries(data)) {
+    const normalizedKey = normalizeKey(key);
+    if (FORBIDDEN_RAW_KEYS.has(normalizedKey)) {
+      throw new Error(`Observability data contains forbidden raw field: ${key}`);
+    }
+    if (typeof value === "string") sanitized[key] = sanitizeText(value);
+    else if (Array.isArray(value)) sanitized[key] = value.map(sanitizeText);
+    else sanitized[key] = value;
+  }
+  return sanitized;
+}
+
+function assertNoForbiddenContent(value: unknown): void {
+  if (typeof value === "string") {
+    if (value === "local-private") return;
+    if (SENSITIVE_TEXT_PATTERN.test(value))
+      throw new Error("Observability event contains sensitive content.");
+    return;
+  }
+  if (Array.isArray(value)) {
+    for (const item of value) assertNoForbiddenContent(item);
+    return;
+  }
+  if (typeof value !== "object" || value === null) return;
+  for (const [key, child] of Object.entries(value)) {
+    const normalizedKey = normalizeKey(key);
+    if (FORBIDDEN_RAW_KEYS.has(normalizedKey)) {
+      throw new Error(`Observability event contains forbidden raw field: ${key}`);
+    }
+    assertNoForbiddenContent(child);
+  }
+}
+
+async function collectJsonlFiles(root: string): Promise<string[]> {
+  const entries = await readdir(root, { withFileTypes: true });
+  const files: string[] = [];
+  for (const entry of entries) {
+    const path = join(root, entry.name);
+    if (entry.isDirectory()) files.push(...(await collectJsonlFiles(path)));
+    if (entry.isFile() && entry.name.endsWith(".jsonl")) files.push(path);
+  }
+  return files.sort();
+}
+
+async function pathExists(path: string): Promise<boolean> {
+  try {
+    await stat(path);
+    return true;
+  } catch (error) {
+    if (
+      error instanceof Error &&
+      "code" in error &&
+      (error as NodeJS.ErrnoException).code === "ENOENT"
+    )
+      return false;
+    throw error;
+  }
+}
+
+function sanitizeText(value: string): string {
+  return value.replace(SENSITIVE_TEXT_PATTERN, "[redacted]").slice(0, 500);
+}
+
+function sanitizeId(value: string): string {
+  return value.replace(/[^a-zA-Z0-9._-]/g, "-").slice(0, 80) || "event";
+}
+
+function normalizeKey(key: string): string {
+  return key.toLowerCase().replace(/[^a-z0-9]/g, "");
+}