profclaw 0.0.1-beta.1

package/dist/diagnostics/exporters.js

@@ -0,0 +1,138 @@
+/**
+ * Span Exporters
+ *
+ * Pluggable export targets for collected spans.
+ * Ready for OTEL collector integration.
+ */
+import { writeFile, mkdir } from 'fs/promises';
+import { existsSync } from 'fs';
+import path from 'path';
+import { logger } from '../utils/logger.js';
+/**
+ * Console exporter - writes spans to the structured logger at debug level
+ */
+export function createConsoleExporter() {
+    return {
+        export: async (spans) => {
+            for (const span of spans) {
+                logger.debug('[Trace]', {
+                    traceId: span.traceId,
+                    spanId: span.spanId,
+                    name: span.name,
+                    durationMs: span.endTime !== undefined ? span.endTime - span.startTime : undefined,
+                    status: span.status,
+                });
+            }
+        },
+    };
+}
+/**
+ * File exporter - appends spans as JSONL to a date-stamped file
+ */
+export function createFileExporter(outputDir) {
+    const dir = outputDir ?? path.resolve(process.cwd(), 'data', 'traces');
+    return {
+        export: async (spans) => {
+            if (!existsSync(dir)) {
+                await mkdir(dir, { recursive: true });
+            }
+            const date = new Date().toISOString().split('T')[0];
+            const filePath = path.join(dir, `traces-${date}.jsonl`);
+            const lines = spans.map(s => JSON.stringify(s)).join('\n') + '\n';
+            await writeFile(filePath, lines, { flag: 'a' });
+            logger.debug('[Trace] Exported to file', { file: filePath, count: spans.length });
+        },
+    };
+}
+function toOTLPValue(v) {
+    if (typeof v === 'string')
+        return { stringValue: v };
+    if (typeof v === 'number')
+        return { intValue: String(v) };
+    return { boolValue: v };
+}
+function spanKindToOTLP(kind) {
+    const map = {
+        server: 2,
+        client: 3,
+        producer: 4,
+        consumer: 5,
+        internal: 1,
+    };
+    return map[kind] ?? 1;
+}
+function spanStatusToOTLP(status) {
+    if (status === 'error')
+        return 2;
+    if (status === 'ok')
+        return 1;
+    return 0;
+}
+/**
+ * OTLP HTTP exporter - sends spans to an OpenTelemetry collector endpoint.
+ * Uses a 5-second abort timeout so export failures do not block the process.
+ */
+export function createOTLPExporter(endpoint) {
+    return {
+        export: async (spans) => {
+            try {
+                const response = await fetch(endpoint, {
+                    method: 'POST',
+                    headers: { 'Content-Type': 'application/json' },
+                    body: JSON.stringify({
+                        resourceSpans: [
+                            {
+                                resource: {
+                                    attributes: [
+                                        { key: 'service.name', value: { stringValue: 'profclaw' } },
+                                        { key: 'service.version', value: { stringValue: '2.0.0' } },
+                                    ],
+                                },
+                                scopeSpans: [
+                                    {
+                                        spans: spans.map(s => ({
+                                            traceId: s.traceId,
+                                            spanId: s.spanId,
+                                            parentSpanId: s.parentSpanId,
+                                            name: s.name,
+                                            kind: spanKindToOTLP(s.kind),
+                                            startTimeUnixNano: BigInt(s.startTime * 1_000_000).toString(),
+                                            endTimeUnixNano: s.endTime !== undefined
+                                                ? BigInt(s.endTime * 1_000_000).toString()
+                                                : undefined,
+                                            status: { code: spanStatusToOTLP(s.status) },
+                                            attributes: Object.entries(s.attributes).map(([k, v]) => ({
+                                                key: k,
+                                                value: toOTLPValue(v),
+                                            })),
+                                            events: s.events.map(e => ({
+                                                name: e.name,
+                                                timeUnixNano: BigInt(e.timestamp * 1_000_000).toString(),
+                                                attributes: e.attributes
+                                                    ? Object.entries(e.attributes).map(([k, v]) => ({
+                                                        key: k,
+                                                        value: toOTLPValue(v),
+                                                    }))
+                                                    : [],
+                                            })),
+                                        })),
+                                    },
+                                ],
+                            },
+                        ],
+                    }),
+                    signal: AbortSignal.timeout(5000),
+                });
+                if (!response.ok) {
+                    logger.warn('[OTLP] Export failed', { status: response.status });
+                }
+            }
+            catch (err) {
+                logger.warn('[OTLP] Export error', {
+                    error: err instanceof Error ? err.message : String(err),
+                });
+            }
+        },
+    };
+}
+//# sourceMappingURL=exporters.js.map

package/dist/diagnostics/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Diagnostics Module
+ *
+ * Lightweight OpenTelemetry-compatible tracing and metrics.
+ */
+export { startSpan, endSpan, addSpanEvent, setSpanAttribute, trace, recordMetric, incrementCounter, getDiagnostics, getTraceSpans, configureDiagnostics, stopDiagnostics, parseTraceparent, formatTraceparent, } from './tracer.js';
+export type { Span, SpanEvent, SpanKind, SpanStatus, TraceContext, MetricPoint, SpanExporter, DiagnosticsConfig, MetricSummary, DiagnosticsSnapshot, } from './tracer.js';
+export { tracingMiddleware } from './middleware.js';
+export { createConsoleExporter, createFileExporter, createOTLPExporter, } from './exporters.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/diagnostics/index.js

@@ -0,0 +1,9 @@
+/**
+ * Diagnostics Module
+ *
+ * Lightweight OpenTelemetry-compatible tracing and metrics.
+ */
+export { startSpan, endSpan, addSpanEvent, setSpanAttribute, trace, recordMetric, incrementCounter, getDiagnostics, getTraceSpans, configureDiagnostics, stopDiagnostics, parseTraceparent, formatTraceparent, } from './tracer.js';
+export { tracingMiddleware } from './middleware.js';
+export { createConsoleExporter, createFileExporter, createOTLPExporter, } from './exporters.js';
+//# sourceMappingURL=index.js.map

package/dist/diagnostics/middleware.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Diagnostics Middleware for Hono
+ *
+ * Automatically traces HTTP requests and propagates W3C traceparent context.
+ */
+import type { Context, Next } from 'hono';
+/**
+ * Request tracing middleware.
+ * Adds a server span to every request and propagates W3C traceparent.
+ */
+export declare function tracingMiddleware(c: Context, next: Next): Promise<void>;
+//# sourceMappingURL=middleware.d.ts.map

package/dist/diagnostics/middleware.js

@@ -0,0 +1,58 @@
+/**
+ * Diagnostics Middleware for Hono
+ *
+ * Automatically traces HTTP requests and propagates W3C traceparent context.
+ */
+import { startSpan, endSpan, setSpanAttribute, parseTraceparent, formatTraceparent, incrementCounter, recordMetric, } from './tracer.js';
+/**
+ * Request tracing middleware.
+ * Adds a server span to every request and propagates W3C traceparent.
+ */
+export async function tracingMiddleware(c, next) {
+    // Parse incoming traceparent to continue an existing trace
+    const traceparentHeader = c.req.header('traceparent');
+    const parentContext = traceparentHeader ? parseTraceparent(traceparentHeader) : null;
+    const spanKind = 'server';
+    const span = startSpan(`${c.req.method} ${c.req.routePath || c.req.path}`, {
+        kind: spanKind,
+        traceId: parentContext?.traceId,
+        parentSpanId: parentContext?.spanId,
+        attributes: {
+            'http.method': c.req.method,
+            'http.url': c.req.path,
+            'http.user_agent': c.req.header('User-Agent') ?? 'unknown',
+        },
+    });
+    // Propagate trace context to the response so callers can correlate
+    c.header('traceparent', formatTraceparent({
+        traceId: span.traceId,
+        spanId: span.spanId,
+        traceFlags: 1,
+    }));
+    // Store span in Hono context variables for downstream handlers
+    c.set('span', span);
+    incrementCounter('http.requests', {
+        method: c.req.method,
+        path: c.req.routePath || c.req.path,
+    });
+    const startTime = Date.now();
+    try {
+        await next();
+        const status = c.res.status;
+        setSpanAttribute(span, 'http.status_code', status);
+        const durationMs = Date.now() - startTime;
+        recordMetric('http.response_time_ms', durationMs, {
+            method: c.req.method,
+            path: c.req.routePath || c.req.path,
+            status: String(status),
+        });
+        endSpan(span, status >= 400 ? 'error' : 'ok');
+    }
+    catch (error) {
+        setSpanAttribute(span, 'error', true);
+        setSpanAttribute(span, 'error.message', error instanceof Error ? error.message : String(error));
+        endSpan(span, 'error');
+        throw error;
+    }
+}
+//# sourceMappingURL=middleware.js.map

package/dist/diagnostics/tracer.d.ts

@@ -0,0 +1,133 @@
+/**
+ * Lightweight Tracing / Diagnostics
+ *
+ * OpenTelemetry-compatible trace context without the full SDK.
+ * Provides:
+ * - Span creation and nesting
+ * - Trace context propagation (W3C traceparent)
+ * - Performance metrics collection
+ * - Export interface for future OTEL integration
+ */
+export interface Span {
+    traceId: string;
+    spanId: string;
+    parentSpanId?: string;
+    name: string;
+    kind: SpanKind;
+    startTime: number;
+    endTime?: number;
+    status: SpanStatus;
+    attributes: Record<string, string | number | boolean>;
+    events: SpanEvent[];
+}
+export interface SpanEvent {
+    name: string;
+    timestamp: number;
+    attributes?: Record<string, string | number | boolean>;
+}
+export type SpanKind = 'internal' | 'server' | 'client' | 'producer' | 'consumer';
+export type SpanStatus = 'unset' | 'ok' | 'error';
+export interface TraceContext {
+    traceId: string;
+    spanId: string;
+    traceFlags: number;
+}
+export interface MetricPoint {
+    name: string;
+    value: number;
+    labels: Record<string, string>;
+    timestamp: number;
+}
+export interface SpanExporter {
+    export: (spans: Span[]) => Promise<void>;
+}
+export interface DiagnosticsConfig {
+    enabled: boolean;
+    sampleRate: number;
+    maxSpans: number;
+    exportIntervalMs: number;
+    exporter?: SpanExporter;
+}
+/**
+ * Parse W3C traceparent header.
+ * Format: version-traceId-parentId-traceFlags
+ * Example: 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01
+ */
+export declare function parseTraceparent(header: string): TraceContext | null;
+/**
+ * Format W3C traceparent header
+ */
+export declare function formatTraceparent(ctx: TraceContext): string;
+/**
+ * Start a new span
+ */
+export declare function startSpan(name: string, options?: {
+    kind?: SpanKind;
+    parentSpanId?: string;
+    traceId?: string;
+    attributes?: Record<string, string | number | boolean>;
+}): Span;
+/**
+ * End a span and record its duration
+ */
+export declare function endSpan(span: Span, status?: SpanStatus): void;
+/**
+ * Add an event to a span
+ */
+export declare function addSpanEvent(span: Span, name: string, attributes?: Record<string, string | number | boolean>): void;
+/**
+ * Set a span attribute
+ */
+export declare function setSpanAttribute(span: Span, key: string, value: string | number | boolean): void;
+/**
+ * Convenience: trace an async function execution as a span
+ */
+export declare function trace<T>(name: string, fn: (span: Span) => Promise<T>, options?: {
+    kind?: SpanKind;
+    attributes?: Record<string, string | number | boolean>;
+}): Promise<T>;
+/**
+ * Record a metric point
+ */
+export declare function recordMetric(name: string, value: number, labels?: Record<string, string>): void;
+/**
+ * Increment a counter metric by 1
+ */
+export declare function incrementCounter(name: string, labels?: Record<string, string>): void;
+export interface MetricSummary {
+    count: number;
+    avg: number;
+    min: number;
+    max: number;
+}
+export interface DiagnosticsSnapshot {
+    activeSpans: number;
+    completedSpans: number;
+    metricsCount: number;
+    config: Omit<DiagnosticsConfig, 'exporter'>;
+    recentSpans: Array<{
+        name: string;
+        durationMs: number;
+        status: SpanStatus;
+        traceId: string;
+    }>;
+    metricsSummary: Record<string, MetricSummary>;
+}
+/**
+ * Get a snapshot of current diagnostics state
+ */
+export declare function getDiagnostics(): DiagnosticsSnapshot;
+/**
+ * Get all completed spans belonging to a specific trace
+ */
+export declare function getTraceSpans(traceId: string): Span[];
+/**
+ * Configure the diagnostics system.
+ * Restarts the export interval if the interval or exporter changed.
+ */
+export declare function configureDiagnostics(newConfig: Partial<DiagnosticsConfig>): void;
+/**
+ * Stop the diagnostics system and clear all buffers
+ */
+export declare function stopDiagnostics(): void;
+//# sourceMappingURL=tracer.d.ts.map

package/dist/diagnostics/tracer.js

@@ -0,0 +1,257 @@
+/**
+ * Lightweight Tracing / Diagnostics
+ *
+ * OpenTelemetry-compatible trace context without the full SDK.
+ * Provides:
+ * - Span creation and nesting
+ * - Trace context propagation (W3C traceparent)
+ * - Performance metrics collection
+ * - Export interface for future OTEL integration
+ */
+import { randomBytes } from 'crypto';
+import { logger } from '../utils/logger.js';
+// --- State ---
+const DEFAULT_CONFIG = {
+    enabled: true,
+    sampleRate: 1.0,
+    maxSpans: 1000,
+    exportIntervalMs: 30_000,
+};
+let config = { ...DEFAULT_CONFIG };
+const activeSpans = new Map();
+const completedSpans = [];
+const metrics = [];
+let exportInterval = null;
+/** Null trace ID sentinel for unsampled spans */
+const NULL_TRACE_ID = '0'.repeat(32);
+// --- Trace Context (W3C traceparent) ---
+/**
+ * Generate a new trace ID (32 hex chars)
+ */
+function generateTraceId() {
+    return randomBytes(16).toString('hex');
+}
+/**
+ * Generate a new span ID (16 hex chars)
+ */
+function generateSpanId() {
+    return randomBytes(8).toString('hex');
+}
+/**
+ * Parse W3C traceparent header.
+ * Format: version-traceId-parentId-traceFlags
+ * Example: 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01
+ */
+export function parseTraceparent(header) {
+    const parts = header.split('-');
+    if (parts.length !== 4)
+        return null;
+    if (parts[0] !== '00')
+        return null; // Only version 00
+    if (parts[1].length !== 32 || parts[2].length !== 16)
+        return null;
+    return {
+        traceId: parts[1],
+        spanId: parts[2],
+        traceFlags: parseInt(parts[3], 16),
+    };
+}
+/**
+ * Format W3C traceparent header
+ */
+export function formatTraceparent(ctx) {
+    return `00-${ctx.traceId}-${ctx.spanId}-${ctx.traceFlags.toString(16).padStart(2, '0')}`;
+}
+// --- Span Operations ---
+/**
+ * Start a new span
+ */
+export function startSpan(name, options = {}) {
+    // Return a no-op span when disabled or not sampled
+    if (!config.enabled || Math.random() > config.sampleRate) {
+        return {
+            traceId: NULL_TRACE_ID,
+            spanId: '0'.repeat(16),
+            name,
+            kind: 'internal',
+            startTime: Date.now(),
+            status: 'unset',
+            attributes: {},
+            events: [],
+        };
+    }
+    const span = {
+        traceId: options.traceId ?? generateTraceId(),
+        spanId: generateSpanId(),
+        parentSpanId: options.parentSpanId,
+        name,
+        kind: options.kind ?? 'internal',
+        startTime: Date.now(),
+        status: 'unset',
+        attributes: options.attributes ?? {},
+        events: [],
+    };
+    activeSpans.set(span.spanId, span);
+    return span;
+}
+/**
+ * End a span and record its duration
+ */
+export function endSpan(span, status) {
+    span.endTime = Date.now();
+    span.status = status ?? 'ok';
+    activeSpans.delete(span.spanId);
+    // Only store sampled spans
+    if (span.traceId !== NULL_TRACE_ID) {
+        completedSpans.push(span);
+        // Evict oldest if buffer full
+        while (completedSpans.length > config.maxSpans) {
+            completedSpans.shift();
+        }
+        // Record duration metric
+        recordMetric('span.duration_ms', span.endTime - span.startTime, {
+            name: span.name,
+            kind: span.kind,
+            status: span.status,
+        });
+    }
+}
+/**
+ * Add an event to a span
+ */
+export function addSpanEvent(span, name, attributes) {
+    span.events.push({ name, timestamp: Date.now(), attributes });
+}
+/**
+ * Set a span attribute
+ */
+export function setSpanAttribute(span, key, value) {
+    span.attributes[key] = value;
+}
+/**
+ * Convenience: trace an async function execution as a span
+ */
+export async function trace(name, fn, options) {
+    const span = startSpan(name, options);
+    try {
+        const result = await fn(span);
+        endSpan(span, 'ok');
+        return result;
+    }
+    catch (error) {
+        span.attributes['error.message'] = error instanceof Error ? error.message : String(error);
+        span.attributes['error.type'] = error instanceof Error ? error.constructor.name : 'unknown';
+        endSpan(span, 'error');
+        throw error;
+    }
+}
+// --- Metrics ---
+/**
+ * Record a metric point
+ */
+export function recordMetric(name, value, labels = {}) {
+    if (!config.enabled)
+        return;
+    metrics.push({ name, value, labels, timestamp: Date.now() });
+    // Evict old metrics (keep last 5000)
+    while (metrics.length > 5000) {
+        metrics.shift();
+    }
+}
+/**
+ * Increment a counter metric by 1
+ */
+export function incrementCounter(name, labels = {}) {
+    recordMetric(name, 1, labels);
+}
+/**
+ * Get a snapshot of current diagnostics state
+ */
+export function getDiagnostics() {
+    // Summarize the 20 most recent completed spans
+    const recentSpans = completedSpans.slice(-20).map(s => ({
+        name: s.name,
+        durationMs: (s.endTime ?? Date.now()) - s.startTime,
+        status: s.status,
+        traceId: s.traceId,
+    }));
+    // Aggregate metrics by name
+    const metricsSummary = {};
+    for (const m of metrics) {
+        if (!metricsSummary[m.name]) {
+            metricsSummary[m.name] = { count: 0, avg: 0, min: Infinity, max: -Infinity };
+        }
+        const s = metricsSummary[m.name];
+        s.avg = (s.avg * s.count + m.value) / (s.count + 1);
+        s.count += 1;
+        s.min = Math.min(s.min, m.value);
+        s.max = Math.max(s.max, m.value);
+    }
+    // Omit exporter (not serialisable) from config snapshot
+    const { exporter: _exporter, ...configWithoutExporter } = config;
+    return {
+        activeSpans: activeSpans.size,
+        completedSpans: completedSpans.length,
+        metricsCount: metrics.length,
+        config: configWithoutExporter,
+        recentSpans,
+        metricsSummary,
+    };
+}
+/**
+ * Get all completed spans belonging to a specific trace
+ */
+export function getTraceSpans(traceId) {
+    return completedSpans.filter(s => s.traceId === traceId);
+}
+// --- Configuration ---
+/**
+ * Configure the diagnostics system.
+ * Restarts the export interval if the interval or exporter changed.
+ */
+export function configureDiagnostics(newConfig) {
+    config = { ...config, ...newConfig };
+    // Restart export interval
+    if (exportInterval) {
+        clearInterval(exportInterval);
+        exportInterval = null;
+    }
+    if (config.enabled && config.exporter) {
+        exportInterval = setInterval(() => {
+            exportSpans().catch((err) => {
+                logger.warn('[Diagnostics] Export failed', {
+                    error: err instanceof Error ? err.message : String(err),
+                });
+            });
+        }, config.exportIntervalMs);
+    }
+    logger.info('[Diagnostics] Configuration updated', {
+        enabled: config.enabled,
+        sampleRate: config.sampleRate,
+        maxSpans: config.maxSpans,
+    });
+}
+/**
+ * Flush and export all completed spans via the configured exporter
+ */
+async function exportSpans() {
+    if (!config.exporter || completedSpans.length === 0)
+        return;
+    const toExport = completedSpans.splice(0, completedSpans.length);
+    await config.exporter.export(toExport);
+    logger.debug('[Diagnostics] Exported spans', { count: toExport.length });
+}
+/**
+ * Stop the diagnostics system and clear all buffers
+ */
+export function stopDiagnostics() {
+    if (exportInterval) {
+        clearInterval(exportInterval);
+        exportInterval = null;
+    }
+    activeSpans.clear();
+    completedSpans.length = 0;
+    metrics.length = 0;
+    logger.info('[Diagnostics] Stopped');
+}
+//# sourceMappingURL=tracer.js.map

package/dist/discovery/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Discovery Module
+ *
+ * LAN-based node discovery for profClaw instances.
+ */
+export { startMDNS, stopMDNS, getDiscoveredNodes, isMDNSRunning } from './mdns.js';
+export type { MDNSConfig } from './mdns.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/discovery/index.js

@@ -0,0 +1,7 @@
+/**
+ * Discovery Module
+ *
+ * LAN-based node discovery for profClaw instances.
+ */
+export { startMDNS, stopMDNS, getDiscoveredNodes, isMDNSRunning } from './mdns.js';
+//# sourceMappingURL=index.js.map

package/dist/discovery/mdns.d.ts

@@ -0,0 +1,40 @@
+/**
+ * mDNS/DNS-SD Local Discovery
+ *
+ * Announces profClaw instance on the local network using multicast DNS.
+ * Enables automatic discovery of profClaw nodes on the LAN.
+ * Uses Node.js dgram (UDP) - no external dependencies.
+ */
+export interface MDNSConfig {
+    serviceName?: string;
+    serviceType?: string;
+    port: number;
+    instanceName?: string;
+    txtRecords?: Record<string, string>;
+}
+interface DiscoveredNode {
+    name: string;
+    host: string;
+    port: number;
+    addresses: string[];
+    txt: Record<string, string>;
+    lastSeen: number;
+}
+/**
+ * Start mDNS announcement
+ */
+export declare function startMDNS(config: MDNSConfig): void;
+/**
+ * Stop mDNS announcement
+ */
+export declare function stopMDNS(): void;
+/**
+ * Get list of discovered profClaw nodes on the network
+ */
+export declare function getDiscoveredNodes(): DiscoveredNode[];
+/**
+ * Check if mDNS is currently running
+ */
+export declare function isMDNSRunning(): boolean;
+export {};
+//# sourceMappingURL=mdns.d.ts.map