@cleocode/core 2026.4.48 → 2026.4.50

package/src/telemetry/index.ts

@@ -0,0 +1,341 @@
+/**
+ * Telemetry module — opt-in command telemetry for CLEO self-improvement.
+ *
+ * Entry point for all telemetry operations:
+ *   - Recording events (fire-and-forget)
+ *   - Querying patterns for `cleo diagnostics analyze`
+ *   - Managing the anonymous ID and opt-in state
+ *   - Emitting BRAIN observations from high-signal patterns
+ *
+ * Telemetry is DISABLED by default. Enable with `cleo diagnostics enable`.
+ *
+ * @task T624
+ */
+
+import { randomUUID } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { and, count, desc, gt, sql } from 'drizzle-orm';
+import { getCleoHome } from '../paths.js';
+import { telemetryEvents } from './schema.js';
+import { getTelemetryDb } from './sqlite.js';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/** A single telemetry event to record. */
+export interface TelemetryEvent {
+  /** Canonical domain (e.g. "tasks", "session"). */
+  domain: string;
+  /** CQRS gateway. */
+  gateway: 'query' | 'mutate';
+  /** Operation name (e.g. "show", "add"). */
+  operation: string;
+  /** Wall-clock duration in milliseconds. */
+  durationMs: number;
+  /** LAFS exit code (0 = success). */
+  exitCode: number;
+  /** Machine-readable error code (null on success). */
+  errorCode?: string | null;
+}
+
+/** Aggregated stats for a single command. */
+export interface CommandStats {
+  /** Composed "{domain}.{operation}" command name. */
+  command: string;
+  /** Total invocation count. */
+  count: number;
+  /** Count of invocations that returned exitCode != 0. */
+  failureCount: number;
+  /** Failure rate as a fraction (0..1). */
+  failureRate: number;
+  /** Mean duration in milliseconds. */
+  avgDurationMs: number;
+  /** Max duration in milliseconds. */
+  maxDurationMs: number;
+  /** Most frequent error code, or null if no failures. */
+  topErrorCode: string | null;
+}
+
+/** Aggregated diagnostics summary. */
+export interface DiagnosticsReport {
+  /** Period analyzed (ISO-8601 start and end). */
+  period: { from: string; to: string };
+  /** Total events in period. */
+  totalEvents: number;
+  /** Top 10 commands by failure rate (min 5 invocations). */
+  topFailing: CommandStats[];
+  /** Top 10 slowest commands by average duration. */
+  topSlow: CommandStats[];
+  /** Commands invoked exactly once (potential dead ends). */
+  rareCommands: string[];
+  /** High-signal observations suitable for BRAIN storage. */
+  observations: string[];
+}
+
+/** Global telemetry config stored in ~/.local/share/cleo/telemetry-config.json */
+export interface TelemetryConfig {
+  /** Whether telemetry collection is enabled. */
+  enabled: boolean;
+  /** Anonymous UUID stable across invocations. Generated on first enable. */
+  anonymousId: string;
+}
+
+// ---------------------------------------------------------------------------
+// Config I/O
+// ---------------------------------------------------------------------------
+
+const TELEMETRY_CONFIG_FILENAME = 'telemetry-config.json';
+
+/** Return the path to the telemetry config JSON file. */
+export function getTelemetryConfigPath(): string {
+  return join(getCleoHome(), TELEMETRY_CONFIG_FILENAME);
+}
+
+/** Load telemetry config from disk. Returns default (disabled) config if absent. */
+export function loadTelemetryConfig(): TelemetryConfig {
+  const path = getTelemetryConfigPath();
+  if (!existsSync(path)) {
+    return { enabled: false, anonymousId: '' };
+  }
+  try {
+    return JSON.parse(readFileSync(path, 'utf-8')) as TelemetryConfig;
+  } catch {
+    return { enabled: false, anonymousId: '' };
+  }
+}
+
+/** Persist telemetry config to disk. */
+export function saveTelemetryConfig(config: TelemetryConfig): void {
+  const path = getTelemetryConfigPath();
+  mkdirSync(join(path, '..'), { recursive: true });
+  writeFileSync(path, JSON.stringify(config, null, 2), 'utf-8');
+}
+
+/** Return true if telemetry collection is currently enabled. */
+export function isTelemetryEnabled(): boolean {
+  return loadTelemetryConfig().enabled;
+}
+
+/**
+ * Enable telemetry and generate a stable anonymous ID.
+ * Idempotent — calling again preserves the existing anonymousId.
+ */
+export function enableTelemetry(): TelemetryConfig {
+  const existing = loadTelemetryConfig();
+  const config: TelemetryConfig = {
+    enabled: true,
+    anonymousId: existing.anonymousId || randomUUID(),
+  };
+  saveTelemetryConfig(config);
+  return config;
+}
+
+/**
+ * Disable telemetry collection.
+ * Existing data in telemetry.db is not deleted.
+ */
+export function disableTelemetry(): TelemetryConfig {
+  const existing = loadTelemetryConfig();
+  const config: TelemetryConfig = { ...existing, enabled: false };
+  saveTelemetryConfig(config);
+  return config;
+}
+
+// ---------------------------------------------------------------------------
+// Event recording
+// ---------------------------------------------------------------------------
+
+/**
+ * Record one telemetry event.
+ * Fire-and-forget — errors are swallowed; never blocks the calling command.
+ * No-op when telemetry is disabled.
+ */
+export async function recordTelemetryEvent(event: TelemetryEvent): Promise<void> {
+  const config = loadTelemetryConfig();
+  if (!config.enabled || !config.anonymousId) return;
+
+  try {
+    const db = await getTelemetryDb();
+    const command = `${event.domain}.${event.operation}`;
+    await db
+      .insert(telemetryEvents)
+      .values({
+        id: randomUUID(),
+        anonymousId: config.anonymousId,
+        domain: event.domain,
+        gateway: event.gateway,
+        operation: event.operation,
+        command,
+        exitCode: event.exitCode,
+        durationMs: event.durationMs,
+        errorCode: event.errorCode ?? null,
+        timestamp: new Date().toISOString(),
+      })
+      .run();
+  } catch {
+    // Non-fatal: telemetry must never crash the calling command.
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Analysis
+// ---------------------------------------------------------------------------
+
+/** ISO-8601 timestamp N days ago. */
+function daysAgo(n: number): string {
+  const d = new Date();
+  d.setDate(d.getDate() - n);
+  return d.toISOString();
+}
+
+/**
+ * Build a diagnostics report over the last `days` days (default 30).
+ * Requires telemetry to be enabled; returns null if disabled or no data.
+ */
+export async function buildDiagnosticsReport(days = 30): Promise<DiagnosticsReport | null> {
+  const config = loadTelemetryConfig();
+  if (!config.enabled) return null;
+
+  const db = await getTelemetryDb();
+  const from = daysAgo(days);
+  const to = new Date().toISOString();
+
+  // Total events in window
+  const [totalRow] = await db
+    .select({ n: count(telemetryEvents.id) })
+    .from(telemetryEvents)
+    .where(gt(telemetryEvents.timestamp, from))
+    .all();
+  const totalEvents = totalRow?.n ?? 0;
+
+  if (totalEvents === 0)
+    return {
+      period: { from, to },
+      totalEvents: 0,
+      topFailing: [],
+      topSlow: [],
+      rareCommands: [],
+      observations: [],
+    };
+
+  // Per-command aggregates
+  const rows = await db
+    .select({
+      command: telemetryEvents.command,
+      total: count(telemetryEvents.id),
+      failures: sql<number>`SUM(CASE WHEN ${telemetryEvents.exitCode} != 0 THEN 1 ELSE 0 END)`,
+      avgMs: sql<number>`AVG(${telemetryEvents.durationMs})`,
+      maxMs: sql<number>`MAX(${telemetryEvents.durationMs})`,
+    })
+    .from(telemetryEvents)
+    .where(gt(telemetryEvents.timestamp, from))
+    .groupBy(telemetryEvents.command)
+    .all();
+
+  // Get top error code per command
+  const errorCodeRows = await db
+    .select({
+      command: telemetryEvents.command,
+      errorCode: telemetryEvents.errorCode,
+      n: count(telemetryEvents.id),
+    })
+    .from(telemetryEvents)
+    .where(and(gt(telemetryEvents.timestamp, from), sql`${telemetryEvents.errorCode} IS NOT NULL`))
+    .groupBy(telemetryEvents.command, telemetryEvents.errorCode)
+    .orderBy(desc(count(telemetryEvents.id)))
+    .all();
+
+  // Build a map: command → top error code
+  const topErrorMap = new Map<string, string>();
+  for (const r of errorCodeRows) {
+    if (!topErrorMap.has(r.command)) {
+      topErrorMap.set(r.command, r.errorCode ?? '');
+    }
+  }
+
+  // Build CommandStats
+  const stats: CommandStats[] = rows.map((r) => {
+    const failures = Number(r.failures) || 0;
+    const total = Number(r.total) || 0;
+    return {
+      command: r.command,
+      count: total,
+      failureCount: failures,
+      failureRate: total > 0 ? failures / total : 0,
+      avgDurationMs: Math.round(Number(r.avgMs) || 0),
+      maxDurationMs: Math.round(Number(r.maxMs) || 0),
+      topErrorCode: topErrorMap.get(r.command) ?? null,
+    };
+  });
+
+  // Top failing (min 5 invocations, sorted by failure rate desc)
+  const topFailing = stats
+    .filter((s) => s.count >= 5 && s.failureRate > 0)
+    .sort((a, b) => b.failureRate - a.failureRate)
+    .slice(0, 10);
+
+  // Top slowest (sorted by avgDurationMs desc)
+  const topSlow = [...stats].sort((a, b) => b.avgDurationMs - a.avgDurationMs).slice(0, 10);
+
+  // Rare commands (invoked only once in the window)
+  const rareCommands = stats.filter((s) => s.count === 1).map((s) => s.command);
+
+  // Generate high-signal observations for BRAIN
+  const observations: string[] = [];
+  for (const s of topFailing.slice(0, 5)) {
+    const pct = Math.round(s.failureRate * 100);
+    const errPart = s.topErrorCode ? ` (most common error: ${s.topErrorCode})` : '';
+    observations.push(
+      `Command '${s.command}' fails ${pct}% of the time across ${s.count} invocations${errPart}. Investigate root cause.`,
+    );
+  }
+  // Flag commands 2x slower than median
+  const sortedAvg = stats.map((s) => s.avgDurationMs).sort((a, b) => a - b);
+  const median = sortedAvg[Math.floor(sortedAvg.length / 2)] ?? 0;
+  for (const s of topSlow.slice(0, 5)) {
+    if (median > 0 && s.avgDurationMs > median * 2) {
+      observations.push(
+        `Command '${s.command}' averages ${s.avgDurationMs}ms — ${Math.round(s.avgDurationMs / median)}x slower than the ${median}ms median. Profile for performance improvement.`,
+      );
+    }
+  }
+
+  return { period: { from, to }, totalEvents, topFailing, topSlow, rareCommands, observations };
+}
+
+/**
+ * Export all telemetry events as a JSON array.
+ * Returns empty array when telemetry is disabled or DB is empty.
+ */
+export async function exportTelemetryEvents(days?: number): Promise<TelemetryEvent[]> {
+  const config = loadTelemetryConfig();
+  if (!config.enabled) return [];
+
+  const db = await getTelemetryDb();
+  const rows = days
+    ? await db
+        .select()
+        .from(telemetryEvents)
+        .where(gt(telemetryEvents.timestamp, daysAgo(days)))
+        .orderBy(desc(telemetryEvents.timestamp))
+        .all()
+    : await db.select().from(telemetryEvents).orderBy(desc(telemetryEvents.timestamp)).all();
+
+  return rows.map((r) => ({
+    domain: r.domain,
+    gateway: r.gateway as 'query' | 'mutate',
+    operation: r.operation,
+    durationMs: r.durationMs,
+    exitCode: r.exitCode,
+    errorCode: r.errorCode,
+  }));
+}
+
+// ---------------------------------------------------------------------------
+// Re-exports
+// ---------------------------------------------------------------------------
+
+export * from './schema.js';
+export { getTelemetryDb, getTelemetryDbPath } from './sqlite.js';

package/src/telemetry/schema.ts

@@ -0,0 +1,68 @@
+/**
+ * Drizzle ORM schema for CLEO telemetry.db (SQLite via node:sqlite + sqlite-proxy).
+ *
+ * Tables: telemetry_events, telemetry_schema_meta
+ *
+ * Stores anonymous, opt-in command telemetry for self-improvement analysis.
+ * Tracks which commands run, how fast they are, and whether they succeed.
+ * Telemetry is DISABLED by default; users must run `cleo diagnostics enable`.
+ *
+ * @task T624
+ */
+
+import { sql } from 'drizzle-orm';
+import { index, integer, sqliteTable, text } from 'drizzle-orm/sqlite-core';
+
+// === TELEMETRY_EVENTS TABLE ===
+
+/**
+ * One row per command invocation captured by the telemetry middleware.
+ *
+ * Fields are intentionally minimal — no params, no output, no user data.
+ * Only the shape of what was invoked and its outcome are stored.
+ */
+export const telemetryEvents = sqliteTable(
+  'telemetry_events',
+  {
+    /** UUID primary key. */
+    id: text('id').primaryKey(),
+    /** Anonymous install identifier (UUIDv4, generated once on first enable). */
+    anonymousId: text('anonymous_id').notNull(),
+    /** Canonical domain (e.g. "tasks", "session", "memory", "admin"). */
+    domain: text('domain').notNull(),
+    /** CQRS gateway ("query" or "mutate"). */
+    gateway: text('gateway').notNull(),
+    /** Operation name (e.g. "show", "add", "complete"). */
+    operation: text('operation').notNull(),
+    /** Composed command string "{domain}.{operation}" for easy grouping. */
+    command: text('command').notNull(),
+    /** LAFS exit code (0 = success, non-zero = failure). */
+    exitCode: integer('exit_code').notNull().default(0),
+    /** Wall-clock duration in milliseconds. */
+    durationMs: integer('duration_ms').notNull(),
+    /** Machine-readable error code when exit_code != 0. NULL on success. */
+    errorCode: text('error_code'),
+    /** ISO-8601 timestamp of the invocation. */
+    timestamp: text('timestamp').notNull().default(sql`(datetime('now'))`),
+  },
+  (table) => [
+    index('idx_telemetry_command').on(table.command),
+    index('idx_telemetry_domain').on(table.domain),
+    index('idx_telemetry_exit_code').on(table.exitCode),
+    index('idx_telemetry_timestamp').on(table.timestamp),
+    index('idx_telemetry_duration').on(table.durationMs),
+  ],
+);
+
+// === TELEMETRY_SCHEMA_META TABLE ===
+
+/**
+ * Key-value store for schema version tracking.
+ * Single row with key='schema_version' on first migration.
+ */
+export const telemetrySchemaMeta = sqliteTable('telemetry_schema_meta', {
+  /** Config key. */
+  key: text('key').primaryKey(),
+  /** Config value. */
+  value: text('value').notNull(),
+});

package/src/telemetry/sqlite.ts

@@ -0,0 +1,140 @@
+/**
+ * SQLite store for telemetry.db via drizzle-orm/node-sqlite + node:sqlite.
+ *
+ * Stores opt-in command telemetry in ~/.local/share/cleo/telemetry.db.
+ * Follows the same singleton + WAL + migration pattern as brain-sqlite.ts.
+ * Telemetry is disabled by default — check isTelemetryEnabled() before writing.
+ *
+ * @task T624
+ */
+
+import { mkdirSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import type { DatabaseSync } from 'node:sqlite';
+import { fileURLToPath } from 'node:url';
+import type { NodeSQLiteDatabase } from 'drizzle-orm/node-sqlite';
+import { drizzle } from 'drizzle-orm/node-sqlite';
+import { getCleoHome } from '../paths.js';
+import { ensureColumns, migrateWithRetry, reconcileJournal } from '../store/migration-manager.js';
+import { openNativeDatabase } from '../store/sqlite.js';
+import * as telemetrySchema from './schema.js';
+
+/** Database file name in the global CLEO home directory. */
+const DB_FILENAME = 'telemetry.db';
+
+/** Schema version. Single source of truth. */
+export const TELEMETRY_SCHEMA_VERSION = '1.0.0';
+
+/** Singleton state. */
+let _db: NodeSQLiteDatabase<typeof telemetrySchema> | null = null;
+let _nativeDb: DatabaseSync | null = null;
+let _dbPath: string | null = null;
+let _initPromise: Promise<NodeSQLiteDatabase<typeof telemetrySchema>> | null = null;
+
+/**
+ * Get the absolute path to telemetry.db in the global CLEO home directory.
+ * Linux: ~/.local/share/cleo/telemetry.db
+ */
+export function getTelemetryDbPath(): string {
+  return join(getCleoHome(), DB_FILENAME);
+}
+
+/**
+ * Resolve the drizzle-telemetry migrations folder.
+ * Handles both src/ (dev via tsx) and dist/ (bundled) layouts.
+ */
+export function resolveTelemetryMigrationsFolder(): string {
+  const __filename = fileURLToPath(import.meta.url);
+  const __dir = dirname(__filename);
+  // src/telemetry/ → ../../migrations/drizzle-telemetry
+  // dist/          → ../migrations/drizzle-telemetry
+  const isBundled = __dir.endsWith('/dist') || __dir.endsWith('\\dist');
+  const pkgRoot = isBundled ? join(__dir, '..') : join(__dir, '..', '..');
+  return join(pkgRoot, 'migrations', 'drizzle-telemetry');
+}
+
+/**
+ * Run drizzle migrations to create/update telemetry.db tables.
+ */
+function runTelemetryMigrations(
+  nativeDb: DatabaseSync,
+  db: NodeSQLiteDatabase<typeof telemetrySchema>,
+): void {
+  const migrationsFolder = resolveTelemetryMigrationsFolder();
+
+  reconcileJournal(nativeDb, migrationsFolder, 'telemetry_events', 'telemetry');
+  migrateWithRetry(db, migrationsFolder, nativeDb, 'telemetry_events', 'telemetry');
+
+  // Safety net: ensure core columns exist even if migration was skipped.
+  ensureColumns(
+    nativeDb,
+    'telemetry_events',
+    [
+      { name: 'anonymous_id', ddl: "text NOT NULL DEFAULT ''" },
+      { name: 'domain', ddl: "text NOT NULL DEFAULT ''" },
+      { name: 'gateway', ddl: "text NOT NULL DEFAULT 'query'" },
+      { name: 'operation', ddl: "text NOT NULL DEFAULT ''" },
+      { name: 'command', ddl: "text NOT NULL DEFAULT ''" },
+      { name: 'exit_code', ddl: 'integer NOT NULL DEFAULT 0' },
+      { name: 'duration_ms', ddl: 'integer NOT NULL DEFAULT 0' },
+      { name: 'error_code', ddl: 'text' },
+    ],
+    'telemetry',
+  );
+}
+
+/**
+ * Reset the singleton (used in tests).
+ */
+export function resetTelemetryDbState(): void {
+  try {
+    _nativeDb?.close();
+  } catch {
+    // ignore
+  }
+  _db = null;
+  _nativeDb = null;
+  _dbPath = null;
+  _initPromise = null;
+}
+
+/**
+ * Initialize telemetry.db (lazy singleton).
+ * Creates the file and runs migrations on first call.
+ */
+export async function getTelemetryDb(): Promise<NodeSQLiteDatabase<typeof telemetrySchema>> {
+  const requestedPath = getTelemetryDbPath();
+
+  if (_db && _dbPath !== requestedPath) {
+    resetTelemetryDbState();
+  }
+
+  if (_db) return _db;
+  if (_initPromise) return _initPromise;
+
+  _initPromise = (async () => {
+    const dbPath = requestedPath;
+    _dbPath = dbPath;
+
+    mkdirSync(dirname(dbPath), { recursive: true });
+
+    const nativeDb = openNativeDatabase(dbPath);
+    _nativeDb = nativeDb;
+
+    const db = drizzle({ client: nativeDb, schema: telemetrySchema });
+
+    runTelemetryMigrations(nativeDb, db);
+
+    // Seed schema version (idempotent)
+    nativeDb
+      .prepare(
+        `INSERT OR IGNORE INTO telemetry_schema_meta (key, value) VALUES ('schemaVersion', '${TELEMETRY_SCHEMA_VERSION}')`,
+      )
+      .run();
+
+    _db = db;
+    return db;
+  })();
+
+  return _initPromise;
+}