@varveai/adit-core 0.2.1

package/dist/perf/perf-log.js

@@ -0,0 +1,280 @@
+/**
+ * Performance logging for time-sensitive operations.
+ *
+ * Records call timing for hook handlers, git operations, network calls,
+ * and other time-sensitive operations. Logs are stored as daily JSONL files
+ * in .adit/perf-logs/ and auto-pruned after 7 days.
+ */
+import { mkdirSync, appendFileSync, readdirSync, readFileSync, unlinkSync, existsSync, } from "node:fs";
+import { join } from "node:path";
+import { performance } from "node:perf_hooks";
+const RETENTION_DAYS = 7;
+const PERF_LOG_DIR = "perf-logs";
+/** Get the perf log directory path */
+function getPerfLogDir(dataDir) {
+    return join(dataDir, PERF_LOG_DIR);
+}
+/** Get today's date string (YYYY-MM-DD) */
+function todayDateStr() {
+    return new Date().toISOString().slice(0, 10);
+}
+/** Get the log file path for a given date */
+function logFilePath(dataDir, dateStr) {
+    return join(getPerfLogDir(dataDir), `${dateStr}.jsonl`);
+}
+/**
+ * Prune log files older than the retention period.
+ * Called on each write to keep the directory clean.
+ */
+export function pruneOldLogs(dataDir) {
+    const dir = getPerfLogDir(dataDir);
+    if (!existsSync(dir))
+        return;
+    const cutoff = new Date();
+    cutoff.setDate(cutoff.getDate() - RETENTION_DAYS);
+    const cutoffStr = cutoff.toISOString().slice(0, 10);
+    try {
+        const files = readdirSync(dir);
+        for (const file of files) {
+            if (!file.endsWith(".jsonl"))
+                continue;
+            const dateStr = file.replace(".jsonl", "");
+            if (dateStr < cutoffStr) {
+                try {
+                    unlinkSync(join(dir, file));
+                }
+                catch {
+                    // Best effort
+                }
+            }
+        }
+    }
+    catch {
+        // Best effort
+    }
+}
+/**
+ * Record a performance log entry.
+ *
+ * @param dataDir - The ADIT data directory (.adit/)
+ * @param entry - The performance entry to record
+ */
+export function recordPerf(dataDir, entry) {
+    try {
+        const dir = getPerfLogDir(dataDir);
+        mkdirSync(dir, { recursive: true });
+        const filePath = logFilePath(dataDir, todayDateStr());
+        const line = JSON.stringify(entry) + "\n";
+        appendFileSync(filePath, line, "utf-8");
+        // Prune old logs (best effort, non-blocking)
+        pruneOldLogs(dataDir);
+    }
+    catch {
+        // Fail-open: never let perf logging break the application
+    }
+}
+/**
+ * Wrap an async function with performance logging.
+ *
+ * @param dataDir - The ADIT data directory (.adit/)
+ * @param category - Category of the operation
+ * @param operation - Name of the operation
+ * @param fn - The async function to measure
+ * @returns The result of the function
+ */
+export async function withPerf(dataDir, category, operation, fn) {
+    const start = performance.now();
+    const timestamp = new Date().toISOString();
+    try {
+        const result = await fn();
+        recordPerf(dataDir, {
+            timestamp,
+            category,
+            operation,
+            durationMs: Math.round((performance.now() - start) * 100) / 100,
+            success: true,
+        });
+        return result;
+    }
+    catch (err) {
+        recordPerf(dataDir, {
+            timestamp,
+            category,
+            operation,
+            durationMs: Math.round((performance.now() - start) * 100) / 100,
+            success: false,
+            error: err instanceof Error ? err.message : String(err),
+        });
+        throw err;
+    }
+}
+/**
+ * Wrap a sync function with performance logging.
+ */
+export function withPerfSync(dataDir, category, operation, fn) {
+    const start = performance.now();
+    const timestamp = new Date().toISOString();
+    try {
+        const result = fn();
+        recordPerf(dataDir, {
+            timestamp,
+            category,
+            operation,
+            durationMs: Math.round((performance.now() - start) * 100) / 100,
+            success: true,
+        });
+        return result;
+    }
+    catch (err) {
+        recordPerf(dataDir, {
+            timestamp,
+            category,
+            operation,
+            durationMs: Math.round((performance.now() - start) * 100) / 100,
+            success: false,
+            error: err instanceof Error ? err.message : String(err),
+        });
+        throw err;
+    }
+}
+/**
+ * Read all perf log entries within the retention window.
+ *
+ * @param dataDir - The ADIT data directory (.adit/)
+ * @param fromDate - Optional start date (YYYY-MM-DD). Defaults to 7 days ago.
+ * @param toDate - Optional end date (YYYY-MM-DD). Defaults to today.
+ * @returns Array of perf entries
+ */
+export function readPerfLogs(dataDir, fromDate, toDate) {
+    const dir = getPerfLogDir(dataDir);
+    if (!existsSync(dir))
+        return [];
+    const today = todayDateStr();
+    const defaultFrom = new Date();
+    defaultFrom.setDate(defaultFrom.getDate() - RETENTION_DAYS);
+    const from = fromDate ?? defaultFrom.toISOString().slice(0, 10);
+    const to = toDate ?? today;
+    const entries = [];
+    try {
+        const files = readdirSync(dir).filter((f) => f.endsWith(".jsonl")).sort();
+        for (const file of files) {
+            const dateStr = file.replace(".jsonl", "");
+            if (dateStr < from || dateStr > to)
+                continue;
+            const content = readFileSync(join(dir, file), "utf-8");
+            for (const line of content.split("\n")) {
+                if (!line.trim())
+                    continue;
+                try {
+                    entries.push(JSON.parse(line));
+                }
+                catch {
+                    // Skip malformed lines
+                }
+            }
+        }
+    }
+    catch {
+        // Return whatever we collected
+    }
+    return entries;
+}
+/**
+ * Generate a stats report from perf log entries.
+ *
+ * @param entries - Array of perf entries to analyze
+ * @returns Stats report with per-operation aggregations
+ */
+export function generatePerfStats(entries) {
+    const now = new Date().toISOString();
+    if (entries.length === 0) {
+        return {
+            generatedAt: now,
+            fromDate: "",
+            toDate: "",
+            totalEntries: 0,
+            operations: [],
+        };
+    }
+    // Find date range
+    const timestamps = entries.map((e) => e.timestamp).sort();
+    const fromDate = timestamps[0].slice(0, 10);
+    const toDate = timestamps[timestamps.length - 1].slice(0, 10);
+    // Group by category:operation
+    const groups = new Map();
+    for (const entry of entries) {
+        const key = `${entry.category}:${entry.operation}`;
+        const group = groups.get(key);
+        if (group) {
+            group.push(entry);
+        }
+        else {
+            groups.set(key, [entry]);
+        }
+    }
+    // Compute per-operation stats
+    const operations = [];
+    for (const [, group] of groups) {
+        const durations = group.map((e) => e.durationMs).sort((a, b) => a - b);
+        const totalMs = durations.reduce((sum, d) => sum + d, 0);
+        const avgMs = totalMs / group.length;
+        const p95Index = Math.min(Math.ceil(durations.length * 0.95) - 1, durations.length - 1);
+        // Standard deviation
+        const variance = group.length > 1
+            ? durations.reduce((sum, d) => sum + (d - avgMs) ** 2, 0) /
+                (group.length - 1)
+            : 0;
+        const stddevMs = Math.round(Math.sqrt(variance) * 100) / 100;
+        operations.push({
+            category: group[0].category,
+            operation: group[0].operation,
+            count: group.length,
+            avgMs: Math.round(avgMs * 100) / 100,
+            minMs: durations[0],
+            maxMs: durations[durations.length - 1],
+            p95Ms: durations[p95Index],
+            stddevMs,
+            failures: group.filter((e) => !e.success).length,
+        });
+    }
+    // Sort by call count descending
+    operations.sort((a, b) => b.count - a.count);
+    return {
+        generatedAt: now,
+        fromDate,
+        toDate,
+        totalEntries: entries.length,
+        operations,
+    };
+}
+/**
+ * Clear all performance logs.
+ *
+ * @param dataDir - The ADIT data directory (.adit/)
+ * @returns Number of files deleted
+ */
+export function clearPerfLogs(dataDir) {
+    const dir = getPerfLogDir(dataDir);
+    if (!existsSync(dir))
+        return 0;
+    let count = 0;
+    try {
+        const files = readdirSync(dir);
+        for (const file of files) {
+            if (!file.endsWith(".jsonl"))
+                continue;
+            try {
+                unlinkSync(join(dir, file));
+                count++;
+            }
+            catch {
+                // Best effort
+            }
+        }
+    }
+    catch {
+        // Best effort
+    }
+    return count;
+}
+//# sourceMappingURL=perf-log.js.map

package/dist/perf/perf-log.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"perf-log.js","sourceRoot":"","sources":["../../src/perf/perf-log.ts"],"names":[],"mappings":"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"}

package/dist/security/content-redaction.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Content-aware secret redaction.
+ *
+ * Scans text content for secrets using two complementary techniques:
+ * 1. Shannon entropy scoring — flags high-entropy strings that look like
+ *    randomly generated secrets (API keys, tokens, passwords).
+ * 2. Pattern matching — regex-based detection of known secret formats
+ *    (AWS keys, GitHub tokens, JWTs, private keys, etc.).
+ *
+ * Inspired by gitleaks/trufflehog approaches. Designed to run on transcript
+ * data (prompts, responses, tool I/O) before writing to the database.
+ */
+/** Result of scanning a single string for secrets */
+export interface RedactionResult {
+    /** The redacted text with secrets replaced */
+    redacted: string;
+    /** Number of secrets found and replaced */
+    secretsFound: number;
+    /** Details of each detection for logging/debugging */
+    detections: SecretDetection[];
+}
+export interface SecretDetection {
+    /** What triggered the detection */
+    method: "entropy" | "pattern";
+    /** Name of the matched pattern (if pattern-based) */
+    patternName?: string;
+    /** Character offset in the original string */
+    offset: number;
+    /** Length of the matched secret */
+    length: number;
+}
+/** Configuration for the content redaction pipeline */
+export interface RedactionConfig {
+    /** Shannon entropy threshold (default: 4.5) */
+    entropyThreshold?: number;
+    /** Minimum token length to check for entropy (default: 8) */
+    minTokenLength?: number;
+    /** Maximum token length to check for entropy (default: 256) */
+    maxTokenLength?: number;
+    /** Replacement string for detected secrets (default: "[REDACTED]") */
+    replacement?: string;
+    /** Additional custom patterns to match */
+    customPatterns?: SecretPattern[];
+    /** Field names to skip scanning (e.g., "id", "signature") */
+    skipFields?: string[];
+}
+export interface SecretPattern {
+    /** Human-readable name for this pattern */
+    name: string;
+    /** Regex to match the secret */
+    pattern: RegExp;
+}
+/**
+ * Built-in secret patterns based on common formats.
+ * Covers major cloud providers, VCS platforms, payment processors,
+ * communication tools, and generic credential formats.
+ */
+export declare const builtinPatterns: SecretPattern[];
+/**
+ * Default field names to skip when scanning structured data.
+ * These commonly contain high-entropy but non-secret data.
+ */
+export declare const defaultSkipFields: string[];
+/**
+ * Compute Shannon entropy for a string.
+ *
+ * Shannon entropy measures the randomness/information density of a string.
+ * Random strings (like API keys) typically have entropy > 4.5 bits per character,
+ * while natural language text is usually below 4.0.
+ *
+ * @param s - The string to analyze
+ * @returns Entropy in bits per character (0 to log2(charset_size))
+ */
+export declare function shannonEntropy(s: string): number;
+/**
+ * Redact secrets from a text string.
+ *
+ * Combines entropy-based and pattern-based scanning to detect
+ * and replace secrets with a configurable placeholder.
+ *
+ * @param text - The text to scan and redact
+ * @param config - Optional configuration overrides
+ * @returns The redacted text and detection details
+ */
+export declare function redactContent(text: string, config?: RedactionConfig): RedactionResult;
+/**
+ * Check if a field name should be skipped during structured data scanning.
+ *
+ * Fields like "id", "signature", "hash" etc. often contain high-entropy
+ * strings that are not secrets.
+ */
+export declare function shouldSkipField(fieldName: string, skipFields?: string[]): boolean;
+/**
+ * Recursively redact secrets from a structured object.
+ *
+ * Walks through all string values in the object tree and applies
+ * content-aware redaction. Skips fields that commonly contain
+ * non-secret high-entropy data (IDs, signatures, hashes).
+ *
+ * @param obj - The object to scan
+ * @param config - Optional redaction configuration
+ * @returns A new object with secrets redacted
+ */
+export declare function redactObject(obj: unknown, config?: RedactionConfig): unknown;
+//# sourceMappingURL=content-redaction.d.ts.map

package/dist/security/content-redaction.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"content-redaction.d.ts","sourceRoot":"","sources":["../../src/security/content-redaction.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,qDAAqD;AACrD,MAAM,WAAW,eAAe;IAC9B,8CAA8C;IAC9C,QAAQ,EAAE,MAAM,CAAC;IACjB,2CAA2C;IAC3C,YAAY,EAAE,MAAM,CAAC;IACrB,sDAAsD;IACtD,UAAU,EAAE,eAAe,EAAE,CAAC;CAC/B;AAED,MAAM,WAAW,eAAe;IAC9B,mCAAmC;IACnC,MAAM,EAAE,SAAS,GAAG,SAAS,CAAC;IAC9B,qDAAqD;IACrD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,8CAA8C;IAC9C,MAAM,EAAE,MAAM,CAAC;IACf,mCAAmC;IACnC,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,uDAAuD;AACvD,MAAM,WAAW,eAAe;IAC9B,+CAA+C;IAC/C,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,6DAA6D;IAC7D,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,+DAA+D;IAC/D,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,sEAAsE;IACtE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,0CAA0C;IAC1C,cAAc,CAAC,EAAE,aAAa,EAAE,CAAC;IACjC,6DAA6D;IAC7D,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;CACvB;AAED,MAAM,WAAW,aAAa;IAC5B,2CAA2C;IAC3C,IAAI,EAAE,MAAM,CAAC;IACb,gCAAgC;IAChC,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;GAIG;AACH,eAAO,MAAM,eAAe,EAAE,aAAa,EA0E1C,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,iBAAiB,UAU7B,CAAC;AAEF;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAiBhD;AAsKD;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAC3B,IAAI,EAAE,MAAM,EACZ,MAAM,GAAE,eAAoB,GAC3B,eAAe,CAwCjB;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAC7B,SAAS,EAAE,MAAM,EACjB,UAAU,CAAC,EAAE,MAAM,EAAE,GACpB,OAAO,CAcT;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,YAAY,CAC1B,GAAG,EAAE,OAAO,EACZ,MAAM,GAAE,eAAoB,GAC3B,OAAO,CAiCT"}