tracelattice 1.2.5

package/dist/metrics/metrics.impl.d.ts

@@ -0,0 +1,252 @@
+/**
+ * Prometheus-compatible metrics collection.
+ *
+ * This module provides metrics collection and export in Prometheus text format.
+ * Supports counters, gauges, and histograms for observability.
+ *
+ * @module metrics
+ */
+/**
+ * Metric types supported by the metrics collector.
+ */
+export declare enum MetricType {
+    /** Counter - a cumulative metric that only increases */
+    Counter = "counter",
+    /** Gauge - a metric that can go up and down */
+    Gauge = "gauge",
+    /** Histogram - a metric for sampling observations */
+    Histogram = "histogram"
+}
+/**
+ * A collected metric with its value and labels.
+ */
+export interface Metric {
+    /** Name of the metric */
+    name: string;
+    /** Type of metric (counter, gauge, histogram) */
+    type: MetricType;
+    /** Current value */
+    value: number;
+    /** Labels for the metric */
+    labels: Record<string, string>;
+    /** Help text describing the metric */
+    help?: string;
+    /** Timestamp when metric was recorded (Unix epoch) */
+    timestamp?: number;
+}
+/**
+ * Prometheus-compatible metrics collector.
+ *
+ * Collects and exports metrics in Prometheus text format for scraping.
+ * Thread-safe and supports counters, gauges, and histograms.
+ *
+ * @remarks
+ * **Metric Types:**
+ * - **Counter**: Cumulative value that only increases (e.g., request counts)
+ * - **Gauge**: Value that can go up or down (e.g., active connections)
+ * - **Histogram**: Sampling observations (e.g., request latency)
+ *
+ * **Labels:**
+ * Metrics can have labels for dimensional data:
+ * ```typescript
+ * counter('http_requests_total', { method: 'GET', status: '200' });
+ * ```
+ *
+ * **Export Format:**
+ * Metrics are exported in Prometheus text format:
+ * ```
+ * # HELP http_requests_total Total HTTP requests
+ * # TYPE http_requests_total counter
+ * http_requests_total{method="GET",status="200"} 1234
+ * ```
+ *
+ * @example
+ * ```typescript
+ * const metrics = new Metrics({ prefix: 'mcp_server' });
+ *
+ * // Count requests
+ * metrics.counter('requests_total', { method: 'GET' }).inc();
+ *
+ * // Track active connections
+ * const activeConnections = metrics.gauge('active_connections');
+ * activeConnections.set(5);
+ * activeConnections.dec();
+ *
+ * // Record latency
+ * metrics.histogram('request_duration_seconds').observe(0.023);
+ *
+ * // Export for Prometheus
+ * const prometheusText = metrics.export();
+ * ```
+ */
+export declare class Metrics {
+    /** Metrics storage indexed by name and label hash */
+    private _metrics;
+    /** Histogram samples */
+    private _histograms;
+    /** Prefix for all metric names */
+    private _prefix;
+    /** Default labels to apply to all metrics */
+    private _defaultLabels;
+    /** Counter for metric collection operations */
+    private _operationsCounter;
+    /**
+     * Creates a new Metrics instance.
+     *
+     * @param options - Configuration options
+     *
+     * @example
+     * ```typescript
+     * const metrics = new Metrics({ prefix: 'mcp_server' });
+     * ```
+     */
+    constructor(options?: {
+        prefix?: string;
+        defaultLabels?: Record<string, string>;
+    });
+    /**
+     * Creates a counter metric.
+     *
+     * @param name - Metric name
+     * @param value - Increment value (default: 1)
+     * @param labels - Optional labels
+     * @param help - Help text
+     *
+     * @example
+     * ```typescript
+     * metrics.counter('requests_total', 1, { method: 'GET' });
+     * metrics.counter('errors_total', 1, { type: 'timeout' });
+     * ```
+     */
+    counter(name: string, value?: number, labels?: Record<string, string>, help?: string): void;
+    /**
+     * Creates a gauge metric.
+     *
+     * @param name - Metric name
+     * @param value - Current value
+     * @param labels - Optional labels
+     * @param help - Help text
+     *
+     * @example
+     * ```typescript
+     * const activeConnections = metrics.gauge('active_connections');
+     * activeConnections.set(5);
+     * activeConnections.dec();
+     * ```
+     */
+    gauge(name: string, value: number, labels?: Record<string, string>, help?: string): void;
+    /**
+     * Records a histogram observation.
+     *
+     * @param name - Histogram name
+     * @param value - Observed value
+     * @param labels - Optional labels
+     * @param help - Help text
+     * @param buckets - Custom bucket boundaries
+     *
+     * @example
+     * ```typescript
+     * metrics.histogram('request_duration_seconds').observe(0.023);
+     * metrics.histogram('thought_processing_ms').observe(45);
+     * ```
+     */
+    histogram(name: string, value: number, labels?: Record<string, string>, buckets?: number[]): void;
+    /**
+     * Gets the current value of a metric.
+     *
+     * @param name - Metric name
+     * @param labels - Labels
+     * @returns Current value or undefined if not found
+     *
+     * @example
+     * ```typescript
+     * const count = metrics.get('requests_total', { method: 'GET' });
+     * ```
+     */
+    get(name: string, labels?: Record<string, string>): number | undefined;
+    /**
+     * Increments a counter by 1.
+     *
+     * @param name - Metric name
+     * @param labels - Optional labels
+     *
+     * @example
+     * ```typescript
+     * metrics.inc('requests_total', { method: 'GET' });
+     * ```
+     */
+    inc(name: string, labels?: Record<string, string>): void;
+    /**
+     * Decrements a gauge by 1.
+     *
+     * @param name - Metric name
+     * @param labels - Optional labels
+     *
+     * @example
+     * ```typescript
+     * metrics.dec('active_connections');
+     * ```
+     */
+    dec(name: string, labels?: Record<string, string>): void;
+    /**
+     * Resets all metrics to zero.
+     * Useful for testing or on server restart.
+     *
+     * @example
+     * ```typescript
+     * metrics.reset();
+     * ```
+     */
+    reset(): void;
+    /**
+     * Gets the number of metric operations performed.
+     * Useful for testing.
+     *
+     * @returns Operation count
+     *
+     * @example
+     * ```typescript
+     * const ops = metrics.getOperationCount();
+     * ```
+     */
+    getOperationCount(): number;
+    /**
+     * Exports metrics in Prometheus text format.
+     *
+     * @returns Prometheus text format string
+     *
+     * @example
+     * ```typescript
+     * const prometheusText = metrics.export();
+     * console.log(prometheusText);
+     * // Output:
+     * // # HELP http_requests_total Total HTTP requests
+     * // # TYPE http_requests_total counter
+     * // http_requests_total{method="GET",status="200"} 1234
+     * ```
+     */
+    export(): string;
+    /**
+     * Gets metric name with prefix.
+     * @param name - Metric name
+     * @returns Full metric name
+     * @private
+     */
+    private _fullName;
+    /**
+     * Creates a unique key for a metric with labels.
+     * @param name - Metric name
+     * @param labels - Labels
+     * @returns Unique key
+     * @private
+     */
+    private _metricKey;
+    /**
+     * Parses a metric key back into name and labels.
+     * @param key - Metric key
+     * @returns Name and labels
+     * @private
+     */
+    private _parseMetricKey;
+}
+//# sourceMappingURL=metrics.impl.d.ts.map

package/dist/metrics/metrics.impl.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metrics.impl.d.ts","sourceRoot":"","sources":["../../src/metrics/metrics.impl.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH;;GAEG;AACH,oBAAY,UAAU;IACrB,wDAAwD;IACxD,OAAO,YAAY;IAEnB,+CAA+C;IAC/C,KAAK,UAAU;IAEf,qDAAqD;IACrD,SAAS,cAAc;CACvB;AAED;;GAEG;AACH,MAAM,WAAW,MAAM;IACtB,yBAAyB;IACzB,IAAI,EAAE,MAAM,CAAC;IAEb,iDAAiD;IACjD,IAAI,EAAE,UAAU,CAAC;IAEjB,oBAAoB;IACpB,KAAK,EAAE,MAAM,CAAC;IAEd,4BAA4B;IAC5B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAE/B,sCAAsC;IACtC,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd,sDAAsD;IACtD,SAAS,CAAC,EAAE,MAAM,CAAC;CACnB;AAOD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,qBAAa,OAAO;IACnB,qDAAqD;IACrD,OAAO,CAAC,QAAQ,CAAsB;IAEtC,wBAAwB;IACxB,OAAO,CAAC,WAAW,CAA4E;IAE/F,kCAAkC;IAClC,OAAO,CAAC,OAAO,CAAS;IAExB,6CAA6C;IAC7C,OAAO,CAAC,cAAc,CAAyB;IAE/C,+CAA+C;IAC/C,OAAO,CAAC,kBAAkB,CAAa;IAEvC;;;;;;;;;OASG;gBACS,OAAO,GAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;KAAO;IAOrF;;;;;;;;;;;;;OAaG;IACH,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,SAAI,EAAE,MAAM,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI;IAuB1F;;;;;;;;;;;;;;OAcG;IACH,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI;IAe5F;;;;;;;;;;;;;;OAcG;IACH,SAAS,CACR,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,EACb,MAAM,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAM,EACnC,OAAO,WAAkB,GACvB,IAAI;IAgCP;;;;;;;;;;;OAWG;IACH,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAM,GAAG,MAAM,GAAG,SAAS;IAO1E;;;;;;;;;;OAUG;IACH,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI;IAIxD;;;;;;;;;;OAUG;IACH,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI;IAKxD;;;;;;;;OAQG;IACH,KAAK,IAAI,IAAI;IAMb;;;;;;;;;;OAUG;IACH,iBAAiB,IAAI,MAAM;IAI3B;;;;;;;;;;;;;;OAcG;IACH,MAAM,IAAI,MAAM;IAiEhB;;;;;OAKG;IACH,OAAO,CAAC,SAAS;IASjB;;;;;;OAMG;IACH,OAAO,CAAC,UAAU;IAQlB;;;;;OAKG;IACH,OAAO,CAAC,eAAe;CAyBvB"}

package/dist/metrics/metrics.impl.js

@@ -0,0 +1,197 @@
+var metrics_impl_MetricType = /*#__PURE__*/ function(MetricType) {
+    MetricType["Counter"] = "counter";
+    MetricType["Gauge"] = "gauge";
+    MetricType["Histogram"] = "histogram";
+    return MetricType;
+}({});
+const DEFAULT_BUCKETS = [
+    0.005,
+    0.01,
+    0.025,
+    0.05,
+    0.1,
+    0.25,
+    0.5,
+    1,
+    2.5,
+    5,
+    10
+];
+class Metrics {
+    _metrics;
+    _histograms;
+    _prefix;
+    _defaultLabels;
+    _operationsCounter = 0;
+    constructor(options = {}){
+        this._metrics = new Map();
+        this._histograms = new Map();
+        this._prefix = options.prefix ?? '';
+        this._defaultLabels = options.defaultLabels ?? {};
+    }
+    counter(name, value = 1, labels = {}, help) {
+        const fullName = this._fullName(name);
+        const allLabels = {
+            ...this._defaultLabels,
+            ...labels
+        };
+        const key = this._metricKey(fullName, allLabels);
+        const existing = this._metrics.get(key);
+        if (existing) {
+            existing.value += value;
+            if (help && !existing.help) existing.help = help;
+        } else this._metrics.set(key, {
+            name: fullName,
+            type: "counter",
+            value,
+            labels: allLabels,
+            help
+        });
+        this._operationsCounter++;
+    }
+    gauge(name, value, labels = {}, help) {
+        const fullName = this._fullName(name);
+        const allLabels = {
+            ...this._defaultLabels,
+            ...labels
+        };
+        const key = this._metricKey(fullName, allLabels);
+        const existing = this._metrics.get(key);
+        this._metrics.set(key, {
+            name: fullName,
+            type: "gauge",
+            value,
+            labels: allLabels,
+            help: help ?? existing?.help
+        });
+        this._operationsCounter++;
+    }
+    histogram(name, value, labels = {}, buckets = DEFAULT_BUCKETS) {
+        const fullName = this._fullName(name);
+        const allLabels = {
+            ...this._defaultLabels,
+            ...labels
+        };
+        const key = this._metricKey(fullName, allLabels);
+        const histogram = this._histograms.get(key);
+        if (histogram) {
+            histogram.sum += value;
+            histogram.count += 1;
+            for (const boundary of buckets)if (value <= boundary) histogram.buckets.set(boundary, (histogram.buckets.get(boundary) ?? 0) + 1);
+            else histogram.buckets.set(boundary, histogram.buckets.get(boundary) ?? 0);
+            histogram.buckets.set(1 / 0, (histogram.buckets.get(1 / 0) ?? 0) + 1);
+        } else {
+            const histogramData = {
+                sum: value,
+                count: 1,
+                buckets: new Map()
+            };
+            for (const boundary of buckets)histogramData.buckets.set(boundary, value <= boundary ? 1 : 0);
+            histogramData.buckets.set(1 / 0, 1);
+            this._histograms.set(key, histogramData);
+        }
+        this._operationsCounter++;
+    }
+    get(name, labels = {}) {
+        const fullName = this._fullName(name);
+        const allLabels = {
+            ...this._defaultLabels,
+            ...labels
+        };
+        const key = this._metricKey(fullName, allLabels);
+        return this._metrics.get(key)?.value;
+    }
+    inc(name, labels) {
+        this.counter(name, 1, labels);
+    }
+    dec(name, labels) {
+        const value = this.get(name, labels) ?? 0;
+        this.gauge(name, value - 1, labels);
+    }
+    reset() {
+        this._metrics.clear();
+        this._histograms.clear();
+        this._operationsCounter = 0;
+    }
+    getOperationCount() {
+        return this._operationsCounter;
+    }
+    export() {
+        const lines = [];
+        const metrics = Array.from(this._metrics.values());
+        const histograms = Array.from(this._histograms.entries());
+        const helpEntries = new Map();
+        const typeEntries = new Map();
+        for (const metric of metrics){
+            if (!helpEntries.has(metric.name)) {
+                const helpText = metric.help ?? `${metric.name} metric`;
+                lines.push(`# HELP ${metric.name} ${helpText}`);
+                helpEntries.set(metric.name, helpText);
+            }
+            if (!typeEntries.has(metric.name)) {
+                lines.push(`# TYPE ${metric.name} ${metric.type}`);
+                typeEntries.set(metric.name, metric.type);
+            }
+            const labelStr = Object.entries(metric.labels).map(([k, v])=>`${k}="${v}"`).join(',');
+            lines.push(`${metric.name}{${labelStr}} ${metric.value}`);
+        }
+        for (const [key, histogram] of histograms){
+            const { name: fullName, labels } = this._parseMetricKey(key);
+            if (histogram.count > 0) {
+                if (!typeEntries.has(fullName)) {
+                    lines.push(`# TYPE ${fullName} histogram`);
+                    typeEntries.set(fullName, "histogram");
+                }
+                const labelStr = Object.entries(labels).map(([k, v])=>`${k}="${v}"`).join(',');
+                const formatMetricLine = (suffix, value)=>{
+                    if (0 === labelStr.length) return `${fullName}${suffix} ${value}`;
+                    return `${fullName}${suffix}{${labelStr}} ${value}`;
+                };
+                lines.push(formatMetricLine('_sum', histogram.sum));
+                lines.push(formatMetricLine('_count', histogram.count));
+                for (const [boundary, count] of histogram.buckets.entries()){
+                    const boundaryLabel = boundary === 1 / 0 ? '+Inf' : Number.isFinite(boundary) ? String(boundary) : String(boundary);
+                    const bucketLabels = 0 === labelStr.length ? `le="${boundaryLabel}"` : `${labelStr},le="${boundaryLabel}"`;
+                    lines.push(`${fullName}_bucket{${bucketLabels}} ${count}`);
+                }
+            }
+        }
+        return lines.join('\n');
+    }
+    _fullName(name) {
+        if (!this._prefix) return name;
+        const prefix = `${this._prefix}_`;
+        return name.startsWith(prefix) ? name : `${prefix}${name}`;
+    }
+    _metricKey(name, labels) {
+        const sortedLabels = Object.entries(labels).sort(([a], [b])=>a.localeCompare(b)).map(([k, v])=>`${k}=${v}`).join(',');
+        return `${name}{${sortedLabels}}`;
+    }
+    _parseMetricKey(key) {
+        const match = key.match(/^([^{}]+)\{([^{}]*)\}$/);
+        if (!match) return {
+            name: key,
+            labels: {}
+        };
+        const [, name, labelsPart] = match;
+        if (!labelsPart) return {
+            name,
+            labels: {}
+        };
+        const labels = {};
+        for (const label of labelsPart.split(',')){
+            const separatorIndex = label.indexOf('=');
+            if (separatorIndex <= 0) continue;
+            const labelKey = label.slice(0, separatorIndex);
+            const labelValue = label.slice(separatorIndex + 1);
+            labels[labelKey] = labelValue;
+        }
+        return {
+            name,
+            labels
+        };
+    }
+}
+export { Metrics, metrics_impl_MetricType as MetricType };
+
+//# sourceMappingURL=metrics.impl.js.map

package/dist/metrics/metrics.impl.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"metrics/metrics.impl.js","sources":["../../src/metrics/metrics.impl.ts"],"sourcesContent":["/**\n * Prometheus-compatible metrics collection.\n *\n * This module provides metrics collection and export in Prometheus text format.\n * Supports counters, gauges, and histograms for observability.\n *\n * @module metrics\n */\n\n/**\n * Metric types supported by the metrics collector.\n */\nexport enum MetricType {\n\t/** Counter - a cumulative metric that only increases */\n\tCounter = 'counter',\n\n\t/** Gauge - a metric that can go up and down */\n\tGauge = 'gauge',\n\n\t/** Histogram - a metric for sampling observations */\n\tHistogram = 'histogram',\n}\n\n/**\n * A collected metric with its value and labels.\n */\nexport interface Metric {\n\t/** Name of the metric */\n\tname: string;\n\n\t/** Type of metric (counter, gauge, histogram) */\n\ttype: MetricType;\n\n\t/** Current value */\n\tvalue: number;\n\n\t/** Labels for the metric */\n\tlabels: Record<string, string>;\n\n\t/** Help text describing the metric */\n\thelp?: string;\n\n\t/** Timestamp when metric was recorded (Unix epoch) */\n\ttimestamp?: number;\n}\n\n/**\n * Histogram bucket boundaries for latency tracking.\n */\nconst DEFAULT_BUCKETS = [0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10];\n\n/**\n * Prometheus-compatible metrics collector.\n *\n * Collects and exports metrics in Prometheus text format for scraping.\n * Thread-safe and supports counters, gauges, and histograms.\n *\n * @remarks\n * **Metric Types:**\n * - **Counter**: Cumulative value that only increases (e.g., request counts)\n * - **Gauge**: Value that can go up or down (e.g., active connections)\n * - **Histogram**: Sampling observations (e.g., request latency)\n *\n * **Labels:**\n * Metrics can have labels for dimensional data:\n * ```typescript\n * counter('http_requests_total', { method: 'GET', status: '200' });\n * ```\n *\n * **Export Format:**\n * Metrics are exported in Prometheus text format:\n * ```\n * # HELP http_requests_total Total HTTP requests\n * # TYPE http_requests_total counter\n * http_requests_total{method=\"GET\",status=\"200\"} 1234\n * ```\n *\n * @example\n * ```typescript\n * const metrics = new Metrics({ prefix: 'mcp_server' });\n *\n * // Count requests\n * metrics.counter('requests_total', { method: 'GET' }).inc();\n *\n * // Track active connections\n * const activeConnections = metrics.gauge('active_connections');\n * activeConnections.set(5);\n * activeConnections.dec();\n *\n * // Record latency\n * metrics.histogram('request_duration_seconds').observe(0.023);\n *\n * // Export for Prometheus\n * const prometheusText = metrics.export();\n * ```\n */\nexport class Metrics {\n\t/** Metrics storage indexed by name and label hash */\n\tprivate _metrics: Map<string, Metric>;\n\n\t/** Histogram samples */\n\tprivate _histograms: Map<string, { sum: number; count: number; buckets: Map<number, number> }>;\n\n\t/** Prefix for all metric names */\n\tprivate _prefix: string;\n\n\t/** Default labels to apply to all metrics */\n\tprivate _defaultLabels: Record<string, string>;\n\n\t/** Counter for metric collection operations */\n\tprivate _operationsCounter: number = 0;\n\n\t/**\n\t * Creates a new Metrics instance.\n\t *\n\t * @param options - Configuration options\n\t *\n\t * @example\n\t * ```typescript\n\t * const metrics = new Metrics({ prefix: 'mcp_server' });\n\t * ```\n\t */\n\tconstructor(options: { prefix?: string; defaultLabels?: Record<string, string> } = {}) {\n\t\tthis._metrics = new Map();\n\t\tthis._histograms = new Map();\n\t\tthis._prefix = options.prefix ?? '';\n\t\tthis._defaultLabels = options.defaultLabels ?? {};\n\t}\n\n\t/**\n\t * Creates a counter metric.\n\t *\n\t * @param name - Metric name\n\t * @param value - Increment value (default: 1)\n\t * @param labels - Optional labels\n\t * @param help - Help text\n\t *\n\t * @example\n\t * ```typescript\n\t * metrics.counter('requests_total', 1, { method: 'GET' });\n\t * metrics.counter('errors_total', 1, { type: 'timeout' });\n\t * ```\n\t */\n\tcounter(name: string, value = 1, labels: Record<string, string> = {}, help?: string): void {\n\t\tconst fullName = this._fullName(name);\n\t\tconst allLabels = { ...this._defaultLabels, ...labels };\n\t\tconst key = this._metricKey(fullName, allLabels);\n\t\tconst existing = this._metrics.get(key);\n\n\t\tif (existing) {\n\t\t\texisting.value += value;\n\t\t\tif (help && !existing.help) {\n\t\t\t\texisting.help = help;\n\t\t\t}\n\t\t} else {\n\t\t\tthis._metrics.set(key, {\n\t\t\t\tname: fullName,\n\t\t\t\ttype: MetricType.Counter,\n\t\t\t\tvalue,\n\t\t\t\tlabels: allLabels,\n\t\t\t\thelp,\n\t\t\t});\n\t\t}\n\t\tthis._operationsCounter++;\n\t}\n\n\t/**\n\t * Creates a gauge metric.\n\t *\n\t * @param name - Metric name\n\t * @param value - Current value\n\t * @param labels - Optional labels\n\t * @param help - Help text\n\t *\n\t * @example\n\t * ```typescript\n\t * const activeConnections = metrics.gauge('active_connections');\n\t * activeConnections.set(5);\n\t * activeConnections.dec();\n\t * ```\n\t */\n\tgauge(name: string, value: number, labels: Record<string, string> = {}, help?: string): void {\n\t\tconst fullName = this._fullName(name);\n\t\tconst allLabels = { ...this._defaultLabels, ...labels };\n\t\tconst key = this._metricKey(fullName, allLabels);\n\t\tconst existing = this._metrics.get(key);\n\t\tthis._metrics.set(key, {\n\t\t\tname: fullName,\n\t\t\ttype: MetricType.Gauge,\n\t\t\tvalue,\n\t\t\tlabels: allLabels,\n\t\t\thelp: help ?? existing?.help,\n\t\t});\n\t\tthis._operationsCounter++;\n\t}\n\n\t/**\n\t * Records a histogram observation.\n\t *\n\t * @param name - Histogram name\n\t * @param value - Observed value\n\t * @param labels - Optional labels\n\t * @param help - Help text\n\t * @param buckets - Custom bucket boundaries\n\t *\n\t * @example\n\t * ```typescript\n\t * metrics.histogram('request_duration_seconds').observe(0.023);\n\t * metrics.histogram('thought_processing_ms').observe(45);\n\t * ```\n\t */\n\thistogram(\n\t\tname: string,\n\t\tvalue: number,\n\t\tlabels: Record<string, string> = {},\n\t\tbuckets = DEFAULT_BUCKETS\n\t): void {\n\t\tconst fullName = this._fullName(name);\n\t\tconst allLabels = { ...this._defaultLabels, ...labels };\n\t\tconst key = this._metricKey(fullName, allLabels);\n\t\tconst histogram = this._histograms.get(key);\n\n\t\tif (histogram) {\n\t\t\thistogram.sum += value;\n\t\t\thistogram.count += 1;\n\t\t\tfor (const boundary of buckets) {\n\t\t\t\tif (value <= boundary) {\n\t\t\t\t\thistogram.buckets.set(boundary, (histogram.buckets.get(boundary) ?? 0) + 1);\n\t\t\t\t} else {\n\t\t\t\t\thistogram.buckets.set(boundary, histogram.buckets.get(boundary) ?? 0);\n\t\t\t\t}\n\t\t\t}\n\t\t\thistogram.buckets.set(Infinity, (histogram.buckets.get(Infinity) ?? 0) + 1);\n\t\t} else {\n\t\t\tconst histogramData = {\n\t\t\t\tsum: value,\n\t\t\t\tcount: 1,\n\t\t\t\tbuckets: new Map<number, number>(),\n\t\t\t};\n\t\t\tfor (const boundary of buckets) {\n\t\t\t\thistogramData.buckets.set(boundary, value <= boundary ? 1 : 0);\n\t\t\t}\n\t\t\thistogramData.buckets.set(Infinity, 1);\n\t\t\tthis._histograms.set(key, histogramData);\n\t\t}\n\t\tthis._operationsCounter++;\n\t}\n\n\t/**\n\t * Gets the current value of a metric.\n\t *\n\t * @param name - Metric name\n\t * @param labels - Labels\n\t * @returns Current value or undefined if not found\n\t *\n\t * @example\n\t * ```typescript\n\t * const count = metrics.get('requests_total', { method: 'GET' });\n\t * ```\n\t */\n\tget(name: string, labels: Record<string, string> = {}): number | undefined {\n\t\tconst fullName = this._fullName(name);\n\t\tconst allLabels = { ...this._defaultLabels, ...labels };\n\t\tconst key = this._metricKey(fullName, allLabels);\n\t\treturn this._metrics.get(key)?.value;\n\t}\n\n\t/**\n\t * Increments a counter by 1.\n\t *\n\t * @param name - Metric name\n\t * @param labels - Optional labels\n\t *\n\t * @example\n\t * ```typescript\n\t * metrics.inc('requests_total', { method: 'GET' });\n\t * ```\n\t */\n\tinc(name: string, labels?: Record<string, string>): void {\n\t\tthis.counter(name, 1, labels);\n\t}\n\n\t/**\n\t * Decrements a gauge by 1.\n\t *\n\t * @param name - Metric name\n\t * @param labels - Optional labels\n\t *\n\t * @example\n\t * ```typescript\n\t * metrics.dec('active_connections');\n\t * ```\n\t */\n\tdec(name: string, labels?: Record<string, string>): void {\n\t\tconst value = this.get(name, labels) ?? 0;\n\t\tthis.gauge(name, value - 1, labels);\n\t}\n\n\t/**\n\t * Resets all metrics to zero.\n\t * Useful for testing or on server restart.\n\t *\n\t * @example\n\t * ```typescript\n\t * metrics.reset();\n\t * ```\n\t */\n\treset(): void {\n\t\tthis._metrics.clear();\n\t\tthis._histograms.clear();\n\t\tthis._operationsCounter = 0;\n\t}\n\n\t/**\n\t * Gets the number of metric operations performed.\n\t * Useful for testing.\n\t *\n\t * @returns Operation count\n\t *\n\t * @example\n\t * ```typescript\n\t * const ops = metrics.getOperationCount();\n\t * ```\n\t */\n\tgetOperationCount(): number {\n\t\treturn this._operationsCounter;\n\t}\n\n\t/**\n\t * Exports metrics in Prometheus text format.\n\t *\n\t * @returns Prometheus text format string\n\t *\n\t * @example\n\t * ```typescript\n\t * const prometheusText = metrics.export();\n\t * console.log(prometheusText);\n\t * // Output:\n\t * // # HELP http_requests_total Total HTTP requests\n\t * // # TYPE http_requests_total counter\n\t * // http_requests_total{method=\"GET\",status=\"200\"} 1234\n\t * ```\n\t */\n\texport(): string {\n\t\tconst lines: string[] = [];\n\n\t\tconst metrics = Array.from(this._metrics.values());\n\t\tconst histograms = Array.from(this._histograms.entries());\n\n\t\tconst helpEntries = new Map<string, string>();\n\t\tconst typeEntries = new Map<string, MetricType>();\n\n\t\tfor (const metric of metrics) {\n\t\t\tif (!helpEntries.has(metric.name)) {\n\t\t\t\tconst helpText = metric.help ?? `${metric.name} metric`;\n\t\t\t\tlines.push(`# HELP ${metric.name} ${helpText}`);\n\t\t\t\thelpEntries.set(metric.name, helpText);\n\t\t\t}\n\t\t\tif (!typeEntries.has(metric.name)) {\n\t\t\t\tlines.push(`# TYPE ${metric.name} ${metric.type}`);\n\t\t\t\ttypeEntries.set(metric.name, metric.type);\n\t\t\t}\n\n\t\t\tconst labelStr = Object.entries(metric.labels)\n\t\t\t\t.map(([k, v]) => `${k}=\"${v}\"`)\n\t\t\t\t.join(',');\n\t\t\tlines.push(`${metric.name}{${labelStr}} ${metric.value}`);\n\t\t}\n\n\t\tfor (const [key, histogram] of histograms) {\n\t\t\tconst { name: fullName, labels } = this._parseMetricKey(key);\n\t\t\tif (histogram.count > 0) {\n\t\t\t\tif (!typeEntries.has(fullName)) {\n\t\t\t\t\tlines.push(`# TYPE ${fullName} histogram`);\n\t\t\t\t\ttypeEntries.set(fullName, MetricType.Histogram);\n\t\t\t\t}\n\n\t\t\t\tconst labelStr = Object.entries(labels)\n\t\t\t\t\t.map(([k, v]) => `${k}=\"${v}\"`)\n\t\t\t\t\t.join(',');\n\t\t\t\tconst formatMetricLine = (suffix: string, value: number): string => {\n\t\t\t\t\tif (labelStr.length === 0) {\n\t\t\t\t\t\treturn `${fullName}${suffix} ${value}`;\n\t\t\t\t\t}\n\n\t\t\t\t\treturn `${fullName}${suffix}{${labelStr}} ${value}`;\n\t\t\t\t};\n\n\t\t\t\tlines.push(formatMetricLine('_sum', histogram.sum));\n\t\t\t\tlines.push(formatMetricLine('_count', histogram.count));\n\n\t\t\t\tfor (const [boundary, count] of histogram.buckets.entries()) {\n\t\t\t\t\tconst boundaryLabel =\n\t\t\t\t\t\tboundary === Infinity\n\t\t\t\t\t\t\t? '+Inf'\n\t\t\t\t\t\t\t: Number.isFinite(boundary)\n\t\t\t\t\t\t\t\t? String(boundary)\n\t\t\t\t\t\t\t\t: String(boundary);\n\t\t\t\t\tconst bucketLabels =\n\t\t\t\t\t\tlabelStr.length === 0 ? `le=\"${boundaryLabel}\"` : `${labelStr},le=\"${boundaryLabel}\"`;\n\t\t\t\t\tlines.push(`${fullName}_bucket{${bucketLabels}} ${count}`);\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\n\t\treturn lines.join('\\n');\n\t}\n\n\t/**\n\t * Gets metric name with prefix.\n\t * @param name - Metric name\n\t * @returns Full metric name\n\t * @private\n\t */\n\tprivate _fullName(name: string): string {\n\t\tif (!this._prefix) {\n\t\t\treturn name;\n\t\t}\n\n\t\tconst prefix = `${this._prefix}_`;\n\t\treturn name.startsWith(prefix) ? name : `${prefix}${name}`;\n\t}\n\n\t/**\n\t * Creates a unique key for a metric with labels.\n\t * @param name - Metric name\n\t * @param labels - Labels\n\t * @returns Unique key\n\t * @private\n\t */\n\tprivate _metricKey(name: string, labels: Record<string, string>): string {\n\t\tconst sortedLabels = Object.entries(labels)\n\t\t\t.sort(([a], [b]) => a.localeCompare(b))\n\t\t\t.map(([k, v]) => `${k}=${v}`)\n\t\t\t.join(',');\n\t\treturn `${name}{${sortedLabels}}`;\n\t}\n\n\t/**\n\t * Parses a metric key back into name and labels.\n\t * @param key - Metric key\n\t * @returns Name and labels\n\t * @private\n\t */\n\tprivate _parseMetricKey(key: string): { name: string; labels: Record<string, string> } {\n\t\tconst match = key.match(/^([^{}]+)\\{([^{}]*)\\}$/);\n\t\tif (!match) {\n\t\t\treturn { name: key, labels: {} };\n\t\t}\n\n\t\tconst [, name, labelsPart] = match as [string, string, string | undefined];\n\t\tif (!labelsPart) {\n\t\t\treturn { name, labels: {} };\n\t\t}\n\n\t\tconst labels: Record<string, string> = {};\n\t\tfor (const label of labelsPart.split(',')) {\n\t\t\tconst separatorIndex = label.indexOf('=');\n\t\t\tif (separatorIndex <= 0) {\n\t\t\t\tcontinue;\n\t\t\t}\n\n\t\t\tconst labelKey = label.slice(0, separatorIndex);\n\t\t\tconst labelValue = label.slice(separatorIndex + 1);\n\t\t\tlabels[labelKey] = labelValue;\n\t\t}\n\n\t\treturn { name, labels };\n\t}\n}\n"],"names":["MetricType","DEFAULT_BUCKETS","Metrics","options","Map","name","value","labels","help","fullName","allLabels","key","existing","buckets","histogram","boundary","Infinity","histogramData","lines","metrics","Array","histograms","helpEntries","typeEntries","metric","helpText","labelStr","Object","k","v","formatMetricLine","suffix","count","boundaryLabel","Number","String","bucketLabels","prefix","sortedLabels","a","b","match","labelsPart","label","separatorIndex","labelKey","labelValue"],"mappings":"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"}

package/dist/persistence/FilePersistence.d.ts

@@ -0,0 +1,66 @@
+import type { IMetrics } from '../contracts/index.js';
+import type { ThoughtData } from '../core/thought.js';
+import type { PersistenceBackend, PersistenceConfig } from './PersistenceBackend.js';
+/**
+ * File-based persistence backend using JSON files.
+ *
+ * Stores thoughts and branches as JSON files in a configured directory.
+ * Simple and reliable, with no external dependencies.
+ *
+ * File structure:
+ * ```
+ * dataDir/
+ *   history.json          # Main thought history
+ *   branches/
+ *     <branch-id>.json    # Individual branch files
+ * ```
+ */
+export declare class FilePersistence implements PersistenceBackend {
+    private _dataDir;
+    private _historyPath;
+    private _branchesDir;
+    private _maxHistorySize;
+    private _persistBranches;
+    private _metrics?;
+    constructor(options?: PersistenceConfig['options'] & {
+        metrics?: IMetrics;
+    });
+    private _recordOperationDuration;
+    /**
+     * Initialize the persistence directory structure.
+     */
+    private _ensureDirectories;
+    /**
+     * Validates branch ID format and resolves the path safely.
+     *
+     * This method provides defense-in-depth security by:
+     * 1. Validating the branch ID format (alphanumeric, hyphens, underscores only)
+     * 2. Preventing path traversal attacks
+     *
+     * @param branchId - The branch ID to validate and resolve
+     * @returns The safe, resolved branch file path
+     * @throws Error if branch ID is invalid or path traversal is detected
+     */
+    private _safeBranchPath;
+    saveThought(thought: ThoughtData): Promise<void>;
+    loadHistory(): Promise<ThoughtData[]>;
+    saveBranch(branchId: string, thoughts: ThoughtData[]): Promise<void>;
+    loadBranch(branchId: string): Promise<ThoughtData[] | undefined>;
+    listBranches(): Promise<string[]>;
+    clear(): Promise<void>;
+    healthy(): Promise<boolean>;
+    /**
+     * Get the data directory path.
+     */
+    getDataDir(): string;
+    /**
+     * Get all branch IDs that are persisted.
+     */
+    getBranchIds(): Promise<string[]>;
+    /**
+     * Close the backend and release resources.
+     * No resources to release for file backend.
+     */
+    close(): Promise<void>;
+}
+//# sourceMappingURL=FilePersistence.d.ts.map

package/dist/persistence/FilePersistence.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FilePersistence.d.ts","sourceRoot":"","sources":["../../src/persistence/FilePersistence.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AACtD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,KAAK,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAErF;;;;;;;;;;;;;GAaG;AACH,qBAAa,eAAgB,YAAW,kBAAkB;IACzD,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,YAAY,CAAS;IAC7B,OAAO,CAAC,YAAY,CAAS;IAC7B,OAAO,CAAC,eAAe,CAAS;IAChC,OAAO,CAAC,gBAAgB,CAAU;IAClC,OAAO,CAAC,QAAQ,CAAC,CAAW;gBAEhB,OAAO,CAAC,EAAE,iBAAiB,CAAC,SAAS,CAAC,GAAG;QAAE,OAAO,CAAC,EAAE,QAAQ,CAAA;KAAE;IAa3E,OAAO,CAAC,wBAAwB;IAKhC;;OAEG;YACW,kBAAkB;IAShC;;;;;;;;;;OAUG;IACH,OAAO,CAAC,eAAe;IAoBV,WAAW,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAkBhD,WAAW,IAAI,OAAO,CAAC,WAAW,EAAE,CAAC;IAoBrC,UAAU,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,WAAW,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAgBpE,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,EAAE,GAAG,SAAS,CAAC;IA0BhE,YAAY,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;IAIjC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAqBtB,OAAO,IAAI,OAAO,CAAC,OAAO,CAAC;IASxC;;OAEG;IACI,UAAU,IAAI,MAAM;IAI3B;;OAEG;IACU,YAAY,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;IAa9C;;;OAGG;IACU,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAGnC"}