@caracalai/core 0.1.2 → 0.1.4-rc.1

package/dist/logging.js

@@ -2,22 +2,307 @@
 // Caracal, a product of Garudex Labs
 //
 // Structured JSON logger for TypeScript services.
-const ORDER = ['debug', 'info', 'warn', 'error'];
-function shouldLog(msgLevel, configLevel) {
-    return ORDER.indexOf(msgLevel) >= ORDER.indexOf(configLevel);
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { hostname } from 'node:os';
+const LEVEL_VALUE = { debug: 10, info: 20, warn: 30, error: 40, fatal: 50 };
+/**
+ * Field names whose values must never appear in dev logs. Mirror this list in
+ * packages/core/go/logging/redact.go and packages/core/python/caracalai_core/logging.py.
+ */
+export const SECRET_KEYS = Object.freeze([
+    'password',
+    'secret',
+    'token',
+    'access_token',
+    'refresh_token',
+    'id_token',
+    'api_key',
+    'client_secret',
+    'private_key',
+    'session',
+    'assertion',
+    'authorization',
+    'cookie',
+    'set_cookie',
+    'set-cookie',
+    'hmac',
+    'signature',
+]);
+export const REDACT_VALUE = '***';
+const PINO_REDACT_CONTAINERS = Object.freeze([
+    'req.headers',
+    'request.headers',
+    'res.headers',
+    'response.headers',
+    'req.body',
+    'request.body',
+    'req.query',
+    'request.query',
+]);
+const BEARER_PATTERN = /bearer\s+[A-Za-z0-9._\-+/=]{8,}/gi;
+const JWT_PATTERN = /eyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}/g;
+const AWS_AKIA = /AKIA[0-9A-Z]{16}/g;
+const AWS_ASIA = /ASIA[0-9A-Z]{16}/g;
+const GCP_KEY = /AIza[0-9A-Za-z_-]{35}/g;
+const GITHUB_PAT = /gh[pousr]_[A-Za-z0-9]{36,255}/g;
+const SLACK_TOKEN = /xox[abprs]-[A-Za-z0-9-]{10,}/g;
+const PEM_BEGIN = '-----BEGIN ';
+const PEM_END = '-----END ';
+const PEM_TAIL = '-----';
+export const MAX_FIELD_BYTES = (() => {
+    const v = process.env.CARACAL_LOG_MAX_FIELD_BYTES;
+    if (v) {
+        const n = Number.parseInt(v, 10);
+        if (Number.isFinite(n))
+            return n;
+    }
+    return 8192;
+})();
+export function isSecretKey(name) {
+    const lower = name.toLowerCase();
+    return SECRET_KEYS.some((k) => lower.includes(k));
 }
-export function createLogger(service, level = 'info') {
+export function buildPinoRedactPaths() {
+    const paths = new Set();
+    for (const k of SECRET_KEYS) {
+        for (const c of PINO_REDACT_CONTAINERS) {
+            paths.add(`${c}["${k}"]`);
+            paths.add(`${c}["${k.toUpperCase()}"]`);
+        }
+    }
+    return Array.from(paths);
+}
+/**
+ * Scrub Bearer tokens, JWT-shaped substrings, and common cloud secret patterns
+ * (AWS, GCP, GitHub, Slack, PEM keys) from a string. Cheap on the common path.
+ */
+export function redactString(s) {
+    if (s.length < 16)
+        return s;
+    let out = redactPemBlocks(s);
+    out = out.replace(BEARER_PATTERN, `Bearer ${REDACT_VALUE}`);
+    out = out.replace(JWT_PATTERN, REDACT_VALUE);
+    out = out.replace(AWS_AKIA, REDACT_VALUE);
+    out = out.replace(AWS_ASIA, REDACT_VALUE);
+    out = out.replace(GCP_KEY, REDACT_VALUE);
+    out = out.replace(GITHUB_PAT, REDACT_VALUE);
+    out = out.replace(SLACK_TOKEN, REDACT_VALUE);
+    return out;
+}
+function redactPemBlocks(s) {
+    let copyStart = 0;
+    let pendingBegin = -1;
+    let begin = s.indexOf(PEM_BEGIN);
+    let end = s.indexOf(PEM_END);
+    const chunks = [];
+    while (begin !== -1 || end !== -1) {
+        if (begin !== -1 && (end === -1 || begin < end)) {
+            const label = readPemLabel(s, begin + PEM_BEGIN.length);
+            if (label && isPrivateKeyPemLabel(label.value) && pendingBegin === -1)
+                pendingBegin = begin;
+            begin = s.indexOf(PEM_BEGIN, label?.end ?? begin + PEM_BEGIN.length);
+            continue;
+        }
+        const label = readPemLabel(s, end + PEM_END.length);
+        if (label && isPrivateKeyPemLabel(label.value) && pendingBegin !== -1) {
+            chunks.push(s.slice(copyStart, pendingBegin), REDACT_VALUE);
+            copyStart = label.end;
+            pendingBegin = -1;
+        }
+        end = s.indexOf(PEM_END, label?.end ?? end + PEM_END.length);
+    }
+    if (chunks.length === 0)
+        return s;
+    chunks.push(s.slice(copyStart));
+    return chunks.join('');
+}
+function readPemLabel(s, start) {
+    const end = s.indexOf(PEM_TAIL, start);
+    if (end === -1)
+        return null;
+    return { value: s.slice(start, end), end: end + PEM_TAIL.length };
+}
+function isPrivateKeyPemLabel(label) {
+    if (!label.endsWith('PRIVATE KEY'))
+        return false;
+    for (let i = 0; i < label.length; i++) {
+        const code = label.charCodeAt(i);
+        if (code !== 32 && (code < 65 || code > 90))
+            return false;
+    }
+    return true;
+}
+export function truncateString(s) {
+    if (MAX_FIELD_BYTES <= 0 || s.length <= MAX_FIELD_BYTES)
+        return s;
+    return s.slice(0, MAX_FIELD_BYTES) + '…[truncated]';
+}
+function serializeError(err) {
+    const out = { name: err.name, message: err.message };
+    if (err.stack)
+        out.stack = err.stack;
+    const code = err.code;
+    if (code !== undefined)
+        out.code = code;
+    const cause = err.cause;
+    if (cause !== undefined)
+        out.cause = cause instanceof Error ? serializeError(cause) : cause;
+    return out;
+}
+/**
+ * Returns a deep copy of `value` with any field whose key matches SECRET_KEYS
+ * replaced with REDACT_VALUE, string values scrubbed of token-like patterns
+ * and truncated to MAX_FIELD_BYTES, and Error instances flattened to plain
+ * JSON-friendly objects.
+ */
+export function redact(value) {
+    if (value === null || value === undefined)
+        return value;
+    if (typeof value === 'string')
+        return truncateString(redactString(value));
+    if (value instanceof Error)
+        return serializeError(value);
+    if (Array.isArray(value))
+        return value.map(redact);
+    if (typeof value !== 'object')
+        return value;
+    const out = {};
+    for (const [k, v] of Object.entries(value)) {
+        out[k] = isSecretKey(k) ? REDACT_VALUE : redact(v);
+    }
+    return out;
+}
+const traceStore = new AsyncLocalStorage();
+/** Run `fn` with the provided trace context bound to the async chain. */
+export function runWithTrace(tc, fn) {
+    return traceStore.run(tc, fn);
+}
+/** Enter a trace context for the remainder of the current async chain. */
+export function bindTrace(tc) {
+    traceStore.enterWith(tc);
+}
+/** Returns the trace context bound to the current async chain, or undefined. */
+export function getTraceContext() {
+    return traceStore.getStore();
+}
+/** Parse a W3C traceparent header (`version-traceid-spanid-flags`). */
+export function parseTraceparent(h) {
+    if (!h)
+        return {};
+    const parts = h.split('-');
+    if (parts.length < 4)
+        return {};
+    if (parts[1].length !== 32 || parts[2].length !== 16)
+        return {};
+    return { traceId: parts[1], spanId: parts[2] };
+}
+/** Returns a pino-compatible mixin function that injects trace fields. */
+export function traceMixin() {
+    return () => {
+        const tc = getTraceContext();
+        const out = {};
+        if (tc?.traceId)
+            out.trace_id = tc.traceId;
+        if (tc?.spanId)
+            out.span_id = tc.spanId;
+        return out;
+    };
+}
+const metricsState = { emitted: 0, dropped: 0, sampled: 0 };
+export function devLogMetrics() {
+    return { ...metricsState };
+}
+const DEBUG_SAMPLE_N = (() => {
+    const v = process.env.CARACAL_LOG_SAMPLE_DEBUG;
+    if (v) {
+        const n = Number.parseInt(v, 10);
+        if (Number.isFinite(n) && n > 0)
+            return n;
+    }
+    return 1;
+})();
+let debugCounter = 0;
+let cachedHostname = null;
+function host() {
+    if (cachedHostname === null) {
+        try {
+            cachedHostname = hostname();
+        }
+        catch {
+            cachedHostname = 'unknown';
+        }
+    }
+    return cachedHostname;
+}
+function processBaseFields() {
+    return {
+        hostname: host(),
+        pid: process.pid,
+        version: process.env.CARACAL_VERSION || process.env.npm_package_version || 'dev',
+        env: process.env.CARACAL_ENV || process.env.NODE_ENV || 'development',
+    };
+}
+function envLevel() {
+    const raw = (process.env.CARACAL_LOG_LEVEL || process.env.LOG_LEVEL || '').toLowerCase();
+    if (raw === 'debug' || raw === 'info' || raw === 'warn' || raw === 'error' || raw === 'fatal')
+        return raw;
+    return 'info';
+}
+export function createLogger(service, levelOrOpts) {
+    const opts = typeof levelOrOpts === 'string' ? { level: levelOrOpts } : (levelOrOpts ?? {});
+    const level = opts.level ?? envLevel();
+    const baseFields = {
+        service,
+        ...processBaseFields(),
+        ...(opts.hostname !== undefined ? { hostname: opts.hostname } : {}),
+        ...(opts.pid !== undefined ? { pid: opts.pid } : {}),
+        ...(opts.version !== undefined ? { version: opts.version } : {}),
+        ...(opts.env !== undefined ? { env: opts.env } : {}),
+    };
+    return makeLogger(baseFields, level, opts.stream ?? process.stderr);
+}
+function makeLogger(bound, level, stream) {
+    const threshold = LEVEL_VALUE[level];
     const emit = (msgLevel, msg, fields) => {
-        if (!shouldLog(msgLevel, level))
+        if (LEVEL_VALUE[msgLevel] < threshold)
             return;
-        process.stderr.write(JSON.stringify({ level: msgLevel, service, msg, time: new Date().toISOString(), ...fields }) +
-            '\n');
+        if (msgLevel === 'debug' && DEBUG_SAMPLE_N > 1) {
+            debugCounter = (debugCounter + 1) >>> 0;
+            if (debugCounter % DEBUG_SAMPLE_N !== 0) {
+                metricsState.sampled++;
+                return;
+            }
+        }
+        const tc = getTraceContext();
+        const traceFields = {};
+        if (tc?.traceId)
+            traceFields.trace_id = tc.traceId;
+        if (tc?.spanId)
+            traceFields.span_id = tc.spanId;
+        const safe = fields ? redact(fields) : undefined;
+        const line = JSON.stringify({
+            level: msgLevel,
+            time: new Date().toISOString(),
+            ...bound,
+            ...traceFields,
+            msg,
+            ...safe,
+        }) + '\n';
+        const ok = stream.write(line);
+        if (ok)
+            metricsState.emitted++;
+        else
+            metricsState.dropped++;
     };
     return {
+        level,
         debug: (msg, fields) => emit('debug', msg, fields),
         info: (msg, fields) => emit('info', msg, fields),
         warn: (msg, fields) => emit('warn', msg, fields),
         error: (msg, fields) => emit('error', msg, fields),
+        fatal: (msg, fields) => emit('fatal', msg, fields),
+        with: (fields) => makeLogger({ ...bound, ...redact(fields) }, level, stream),
+        metrics: () => devLogMetrics(),
     };
 }
 //# sourceMappingURL=logging.js.map

package/dist/logging.js.map

@@ -1 +1 @@
-{"version":3,"file":"logging.js","sourceRoot":"","sources":["../src/logging.ts"],"names":[],"mappings":"AAAA,yDAAyD;AACzD,qCAAqC;AACrC,EAAE;AACF,kDAAkD;AAIlD,MAAM,KAAK,GAAY,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC;AAE1D,SAAS,SAAS,CAAC,QAAe,EAAE,WAAkB;IACpD,OAAO,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,IAAI,KAAK,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC;AAC/D,CAAC;AAID,MAAM,UAAU,YAAY,CAAC,OAAe,EAAE,QAAe,MAAM;IACjE,MAAM,IAAI,GAAG,CAAC,QAAe,EAAE,GAAW,EAAE,MAAgC,EAAE,EAAE;QAC9E,IAAI,CAAC,SAAS,CAAC,QAAQ,EAAE,KAAK,CAAC;YAAE,OAAO;QACxC,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,IAAI,CAAC,SAAS,CAAC,EAAE,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE,GAAG,EAAE,IAAI,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,EAAE,GAAG,MAAM,EAAE,CAAC;YAC1F,IAAI,CACP,CAAC;IACJ,CAAC,CAAC;IACF,OAAO;QACL,KAAK,EAAE,CAAC,GAAW,EAAE,MAAgC,EAAE,EAAE,CAAC,IAAI,CAAC,OAAO,EAAE,GAAG,EAAE,MAAM,CAAC;QACpF,IAAI,EAAE,CAAC,GAAW,EAAE,MAAgC,EAAE,EAAE,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,EAAE,MAAM,CAAC;QAClF,IAAI,EAAE,CAAC,GAAW,EAAE,MAAgC,EAAE,EAAE,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,EAAE,MAAM,CAAC;QAClF,KAAK,EAAE,CAAC,GAAW,EAAE,MAAgC,EAAE,EAAE,CAAC,IAAI,CAAC,OAAO,EAAE,GAAG,EAAE,MAAM,CAAC;KACrF,CAAC;AACJ,CAAC"}
+{"version":3,"file":"logging.js","sourceRoot":"","sources":["../src/logging.ts"],"names":[],"mappings":"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"}

package/dist/metrics.d.ts

@@ -0,0 +1,4 @@
+import type { AuditClient } from './audit.js';
+/** Render dev-log + (optional) audit counters in Prometheus text format. */
+export declare function renderObservabilityMetrics(audit?: AuditClient): string;
+//# sourceMappingURL=metrics.d.ts.map

package/dist/metrics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metrics.d.ts","sourceRoot":"","sources":["../src/metrics.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAwB9C,4EAA4E;AAC5E,wBAAgB,0BAA0B,CAAC,KAAK,CAAC,EAAE,WAAW,GAAG,MAAM,CAuBtE"}

package/dist/metrics.js

@@ -0,0 +1,43 @@
+// Copyright (C) 2026 Garudex Labs.  All Rights Reserved.
+// Caracal, a product of Garudex Labs
+//
+// Prometheus text-format renderer for Caracal counter snapshots.
+import { devLogMetrics } from './logging.js';
+function renderCounters(counters) {
+    const lines = [];
+    for (const c of counters) {
+        lines.push(`# HELP ${c.name} ${c.help}`);
+        lines.push(`# TYPE ${c.name} counter`);
+        lines.push(`${c.name} ${c.value}`);
+    }
+    return lines.join('\n') + '\n';
+}
+function renderGauges(gauges) {
+    const lines = [];
+    for (const g of gauges) {
+        lines.push(`# HELP ${g.name} ${g.help}`);
+        lines.push(`# TYPE ${g.name} gauge`);
+        lines.push(`${g.name} ${g.value}`);
+    }
+    return lines.join('\n') + '\n';
+}
+/** Render dev-log + (optional) audit counters in Prometheus text format. */
+export function renderObservabilityMetrics(audit) {
+    const log = devLogMetrics();
+    const counters = [
+        { name: 'caracal_log_emitted_total', help: 'Dev log records emitted', value: log.emitted },
+        { name: 'caracal_log_dropped_total', help: 'Dev log records dropped due to backpressure', value: log.dropped },
+        { name: 'caracal_log_sampled_total', help: 'Debug log records dropped by sampler', value: log.sampled },
+    ];
+    if (audit) {
+        const a = audit.snapshot();
+        counters.push({ name: 'caracal_audit_emitted_total', help: 'Audit events accepted into buffer', value: a.emitted }, { name: 'caracal_audit_dropped_total', help: 'Audit events dropped due to full buffer', value: a.dropped }, { name: 'caracal_audit_persisted_total', help: 'Audit events spilled to disk for later replay', value: a.persisted }, { name: 'caracal_audit_drained_total', help: 'Audit events replayed from disk', value: a.drained }, { name: 'caracal_audit_sink_errors_total', help: 'Audit sink (XADD) errors', value: a.sink_errors });
+        const gauges = [
+            { name: 'caracal_audit_queue_depth', help: 'Audit buffer depth', value: a.queue_depth },
+            { name: 'caracal_audit_queue_cap', help: 'Audit buffer capacity', value: a.queue_cap },
+        ];
+        return renderCounters(counters) + renderGauges(gauges);
+    }
+    return renderCounters(counters);
+}
+//# sourceMappingURL=metrics.js.map

package/dist/metrics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"metrics.js","sourceRoot":"","sources":["../src/metrics.ts"],"names":[],"mappings":"AAAA,yDAAyD;AACzD,qCAAqC;AACrC,EAAE;AACF,iEAAiE;AAEjE,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAK7C,SAAS,cAAc,CAAC,QAAmB;IACzC,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,KAAK,MAAM,CAAC,IAAI,QAAQ,EAAE,CAAC;QACzB,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;QACzC,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,IAAI,UAAU,CAAC,CAAC;QACvC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC;IACrC,CAAC;IACD,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;AACjC,CAAC;AAED,SAAS,YAAY,CAAC,MAAiB;IACrC,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,KAAK,MAAM,CAAC,IAAI,MAAM,EAAE,CAAC;QACvB,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;QACzC,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,IAAI,QAAQ,CAAC,CAAC;QACrC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC;IACrC,CAAC;IACD,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;AACjC,CAAC;AAED,4EAA4E;AAC5E,MAAM,UAAU,0BAA0B,CAAC,KAAmB;IAC5D,MAAM,GAAG,GAAG,aAAa,EAAE,CAAC;IAC5B,MAAM,QAAQ,GAAc;QAC1B,EAAE,IAAI,EAAE,2BAA2B,EAAE,IAAI,EAAE,yBAAyB,EAAE,KAAK,EAAE,GAAG,CAAC,OAAO,EAAE;QAC1F,EAAE,IAAI,EAAE,2BAA2B,EAAE,IAAI,EAAE,6CAA6C,EAAE,KAAK,EAAE,GAAG,CAAC,OAAO,EAAE;QAC9G,EAAE,IAAI,EAAE,2BAA2B,EAAE,IAAI,EAAE,sCAAsC,EAAE,KAAK,EAAE,GAAG,CAAC,OAAO,EAAE;KACxG,CAAC;IACF,IAAI,KAAK,EAAE,CAAC;QACV,MAAM,CAAC,GAAG,KAAK,CAAC,QAAQ,EAAE,CAAC;QAC3B,QAAQ,CAAC,IAAI,CACX,EAAE,IAAI,EAAE,6BAA6B,EAAE,IAAI,EAAE,mCAAmC,EAAE,KAAK,EAAE,CAAC,CAAC,OAAO,EAAE,EACpG,EAAE,IAAI,EAAE,6BAA6B,EAAE,IAAI,EAAE,yCAAyC,EAAE,KAAK,EAAE,CAAC,CAAC,OAAO,EAAE,EAC1G,EAAE,IAAI,EAAE,+BAA+B,EAAE,IAAI,EAAE,+CAA+C,EAAE,KAAK,EAAE,CAAC,CAAC,SAAS,EAAE,EACpH,EAAE,IAAI,EAAE,6BAA6B,EAAE,IAAI,EAAE,iCAAiC,EAAE,KAAK,EAAE,CAAC,CAAC,OAAO,EAAE,EAClG,EAAE,IAAI,EAAE,iCAAiC,EAAE,IAAI,EAAE,0BAA0B,EAAE,KAAK,EAAE,CAAC,CAAC,WAAW,EAAE,CACpG,CAAC;QACF,MAAM,MAAM,GAAc;YACxB,EAAE,IAAI,EAAE,2BAA2B,EAAE,IAAI,EAAE,oBAAoB,EAAE,KAAK,EAAE,CAAC,CAAC,WAAW,EAAE;YACvF,EAAE,IAAI,EAAE,yBAAyB,EAAE,IAAI,EAAE,uBAAuB,EAAE,KAAK,EAAE,CAAC,CAAC,SAAS,EAAE;SACvF,CAAC;QACF,OAAO,cAAc,CAAC,QAAQ,CAAC,GAAG,YAAY,CAAC,MAAM,CAAC,CAAC;IACzD,CAAC;IACD,OAAO,cAAc,CAAC,QAAQ,CAAC,CAAC;AAClC,CAAC"}

package/dist/telemetry.d.ts

@@ -0,0 +1,10 @@
+type Log = {
+    error?: (msg: string, meta?: Record<string, unknown>) => void;
+};
+type FastifyLike = {
+    addHook: (name: string, handler: (...args: unknown[]) => unknown) => void;
+};
+export declare function initNodeTelemetry(serviceName: string, log?: Log): () => Promise<void>;
+export declare function instrumentFastifyApp(app: FastifyLike, serviceName: string): void;
+export {};
+//# sourceMappingURL=telemetry.d.ts.map

package/dist/telemetry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"telemetry.d.ts","sourceRoot":"","sources":["../src/telemetry.ts"],"names":[],"mappings":"AAWA,KAAK,GAAG,GAAG;IAAE,KAAK,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAA;CAAE,CAAA;AAC5E,KAAK,WAAW,GAAG;IACjB,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,KAAK,IAAI,CAAA;CAC1E,CAAA;AAID,wBAAgB,iBAAiB,CAAC,WAAW,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,GAAG,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC,CAmBrF;AAED,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,GAAG,IAAI,CAyChF"}

package/dist/telemetry.js

@@ -0,0 +1,98 @@
+// Copyright (C) 2026 Garudex Labs.  All Rights Reserved.
+// Caracal, a product of Garudex Labs
+//
+// OpenTelemetry bootstrap helpers for Node.js services.
+import { context, propagation, SpanKind, SpanStatusCode, trace } from '@opentelemetry/api';
+import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';
+import { resourceFromAttributes } from '@opentelemetry/resources';
+import { BatchSpanProcessor } from '@opentelemetry/sdk-trace-base';
+import { NodeTracerProvider } from '@opentelemetry/sdk-trace-node';
+const spanKey = Symbol('caracal.otel.span');
+export function initNodeTelemetry(serviceName, log) {
+    const endpoint = process.env.OTEL_EXPORTER_OTLP_ENDPOINT?.trim();
+    if (!endpoint)
+        return async () => { };
+    const protocol = process.env.OTEL_EXPORTER_OTLP_PROTOCOL?.trim();
+    if (protocol && protocol !== 'http/protobuf') {
+        throw new Error(`unsupported OTEL_EXPORTER_OTLP_PROTOCOL ${protocol}`);
+    }
+    const provider = new NodeTracerProvider({
+        resource: resourceFromAttributes(resourceAttributes(serviceName)),
+        spanProcessors: [new BatchSpanProcessor(new OTLPTraceExporter({ url: traceUrl(endpoint) }))],
+    });
+    provider.register();
+    return async () => {
+        try {
+            await provider.shutdown();
+        }
+        catch (err) {
+            log?.error?.('telemetry shutdown failed', { err });
+        }
+    };
+}
+export function instrumentFastifyApp(app, serviceName) {
+    const tracer = trace.getTracer(serviceName);
+    app.addHook('onRequest', async (req) => {
+        const request = req;
+        const method = request.method ?? 'GET';
+        const path = String(request.url ?? '/').split('?')[0] || '/';
+        const parent = propagation.extract(context.active(), normalizeHeaders(request.headers ?? {}));
+        request[spanKey] = tracer.startSpan(`${method} ${path}`, {
+            kind: SpanKind.SERVER,
+            attributes: {
+                'http.request.method': method,
+                'url.path': path,
+            },
+        }, parent);
+    });
+    app.addHook('onResponse', async (req, reply) => {
+        const request = req;
+        const response = reply;
+        const span = request[spanKey];
+        if (!span)
+            return;
+        const statusCode = response.statusCode ?? 200;
+        span.setAttribute('http.response.status_code', statusCode);
+        if (statusCode >= 500) {
+            span.setStatus({ code: SpanStatusCode.ERROR });
+        }
+        span.end();
+    });
+    app.addHook('onError', async (req, _reply, err) => {
+        const request = req;
+        const span = request[spanKey];
+        if (!span)
+            return;
+        if (err instanceof Error) {
+            span.recordException(err);
+        }
+        span.setStatus({ code: SpanStatusCode.ERROR });
+    });
+}
+function traceUrl(endpoint) {
+    const trimmed = endpoint.replace(/\/+$/, '');
+    return trimmed.endsWith('/v1/traces') ? trimmed : `${trimmed}/v1/traces`;
+}
+function normalizeHeaders(headers) {
+    const out = {};
+    for (const [key, value] of Object.entries(headers)) {
+        if (Array.isArray(value)) {
+            out[key] = value.join(',');
+        }
+        else if (typeof value === 'string') {
+            out[key] = value;
+        }
+    }
+    return out;
+}
+function resourceAttributes(serviceName) {
+    const attrs = { 'service.name': serviceName };
+    for (const raw of (process.env.OTEL_RESOURCE_ATTRIBUTES ?? '').split(',')) {
+        const [key, value] = raw.split('=', 2);
+        if (key?.trim() && value?.trim()) {
+            attrs[key.trim()] = value.trim();
+        }
+    }
+    return attrs;
+}
+//# sourceMappingURL=telemetry.js.map

package/dist/telemetry.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@caracalai/core",
-  "version": "0.1.2",
+  "version": "0.1.4-rc.1",
   "description": "Caracal SDK foundation: logging, config, errors.",
   "license": "Apache-2.0",
   "homepage": "https://github.com/Garudex-Labs/caracal",
@@ -22,30 +22,34 @@
     ".": {
       "import": "./dist/index.js",
       "types": "./dist/index.d.ts"
-    },
-    "./cli": {
-      "import": "./dist/cliconfig.js",
-      "types": "./dist/cliconfig.d.ts"
     }
   },
   "files": [
     "dist",
-    "README.md",
     "LICENSE"
   ],
   "publishConfig": {
     "access": "public"
   },
   "scripts": {
+    "clean": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\"",
+    "prebuild": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\"",
     "build": "tsc",
     "dev": "tsc --watch",
     "typecheck": "tsc --noEmit",
-    "test": "vitest run --root ../../.. tests/typescript/unit/shared",
-    "prepublishOnly": "tsc"
+    "test": "vitest run --root ../../.. tests/typescript/unit/shared tests/typescript/contract/interoperability",
+    "prepublishOnly": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\" && tsc"
   },
   "devDependencies": {
     "@types/node": "^24.12.2",
     "typescript": "^6.0.3",
     "vitest": "^4.1.6"
+  },
+  "dependencies": {
+    "@opentelemetry/api": "^1.9.1",
+    "@opentelemetry/exporter-trace-otlp-http": "^0.218.0",
+    "@opentelemetry/resources": "^2.7.1",
+    "@opentelemetry/sdk-trace-base": "^2.7.1",
+    "@opentelemetry/sdk-trace-node": "^2.7.1"
   }
 }

package/dist/cliconfig.d.ts

@@ -1,31 +0,0 @@
-import { CaracalError } from './errors.js';
-export declare const DEFAULT_API_URL = "http://localhost:3000";
-export declare const DEFAULT_COORDINATOR_URL = "http://localhost:4000";
-export interface Credential {
-    env: string;
-    resource: string;
-}
-export interface OptionalCredential extends Credential {
-    on_failure: 'warn' | 'error';
-}
-export interface McpGovernance {
-    mode: 'block' | 'log';
-}
-export interface CliConfig {
-    zone_url: string;
-    zone_id: string;
-    application_id: string;
-    app_client_secret: string;
-    continue_on_failure?: boolean;
-    credentials?: Credential[];
-    optional_credentials?: OptionalCredential[];
-    mcp_governance?: McpGovernance;
-}
-export declare function resolveCliConfigPath(env?: NodeJS.ProcessEnv): string | undefined;
-export declare class ServiceUrlMissingError extends CaracalError {
-    readonly envKey: string;
-    readonly nodeEnv: string;
-    constructor(envKey: string, nodeEnv: string);
-}
-export declare function resolveServiceUrl(envKey: string, devDefault: string): string;
-//# sourceMappingURL=cliconfig.d.ts.map

package/dist/cliconfig.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"cliconfig.d.ts","sourceRoot":"","sources":["../src/cliconfig.ts"],"names":[],"mappings":"AAQA,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE3C,eAAO,MAAM,eAAe,0BAA0B,CAAC;AACvD,eAAO,MAAM,uBAAuB,0BAA0B,CAAC;AAE/D,MAAM,WAAW,UAAU;IACzB,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,kBAAmB,SAAQ,UAAU;IACpD,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC;CAC9B;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,OAAO,GAAG,KAAK,CAAC;CACvB;AAED,MAAM,WAAW,SAAS;IACxB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,cAAc,EAAE,MAAM,CAAC;IACvB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAC9B,WAAW,CAAC,EAAE,UAAU,EAAE,CAAC;IAC3B,oBAAoB,CAAC,EAAE,kBAAkB,EAAE,CAAC;IAC5C,cAAc,CAAC,EAAE,aAAa,CAAC;CAChC;AAKD,wBAAgB,oBAAoB,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,MAAM,GAAG,SAAS,CAc7F;AAED,qBAAa,sBAAuB,SAAQ,YAAY;IACtD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;gBACb,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM;CAQ5C;AAID,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CAQ5E"}