@adjedaini/clockwork-node 0.0.1

package/node_modules/@adjedaini/clockwork-shared/package.json

@@ -0,0 +1,14 @@
+{
+  "name": "@adjedaini/clockwork-shared",
+  "version": "0.0.1",
+  "private": true,
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs --dts"
+  },
+  "devDependencies": {
+    "tsup": "^8.0.0",
+    "typescript": "^5.5.0"
+  }
+}

package/node_modules/@adjedaini/clockwork-shared/src/index.ts

@@ -0,0 +1,96 @@
+/** Shared types for @adjedaini/clockwork-node. Framework-agnostic. */
+
+/** Per-request context (AsyncLocalStorage). Used to correlate logs/queries to the current request. */
+export interface ClockworkContext {
+  requestId: string;
+}
+
+export interface LogData {
+  level: 'debug' | 'info' | 'warning' | 'error';
+  message: string;
+  context?: Record<string, unknown>;
+  time: number;
+  source?: 'native' | 'clockwork';
+}
+
+export interface QueryData {
+  query: string;
+  bindings?: unknown[];
+  duration?: number;
+  connection?: string;
+}
+
+export interface EventData {
+  name: string;
+  description?: string;
+  duration?: number;
+  start?: number;
+  end?: number;
+  data?: Record<string, unknown>;
+  color?: string;
+}
+
+export interface RequestSnapshot {
+  id: string;
+  type: 'http';
+  method: string;
+  uri: string;
+  headers: Record<string, unknown>;
+  getData: Record<string, unknown>;
+  postData?: unknown;
+  responseData?: unknown;
+  cookies?: Record<string, unknown>;
+  responseStatus: number;
+  responseTime: number;
+  responseDuration: number;
+  memoryUsage: number;
+  time: number;
+  log: LogData[];
+  databaseQueries: QueryData[];
+  timelineData: EventData[];
+  controller?: string;
+}
+
+export interface RequestMetadata {
+  id: string;
+  method: string;
+  uri: string;
+  controller?: string;
+  responseStatus: number;
+  responseDuration: number;
+  time: number;
+}
+
+export interface MetricsSpan {
+  interval: number;
+  retention: number;
+  responseTime: number[];
+  rps: number[];
+  statusCodes?: Record<string, number>[];
+}
+
+export interface Snapshot {
+  requests: RequestMetadata[];
+  metrics?: {
+    spans: MetricsSpan[];
+    timestamp: number;
+    os?: { cpu: number; memory: number; heapUsed: number; heapTotal: number; rss: number };
+    process?: { uptime: number; eventLoopDelay?: number };
+  };
+}
+
+/** Storage backend for request snapshots. Implement for Redis, SQLite, file, etc. */
+export interface IRequestStorage {
+  push(id: string, request: RequestSnapshot): void;
+  get(id: string): RequestSnapshot | undefined;
+  getAll(limit: number): RequestSnapshot[];
+  getLatest(): RequestSnapshot | undefined;
+}
+
+export interface CoreConfig {
+  maxRequests?: number;
+  maxBodyDepth?: number;
+  maxBodySize?: number;
+  /** Custom storage backend. Default: in-memory ring buffer. */
+  storage?: IRequestStorage;
+}

package/node_modules/@adjedaini/clockwork-shared/tsconfig.build.json

@@ -0,0 +1,6 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "composite": false
+  }
+}

package/node_modules/@adjedaini/clockwork-shared/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "src",
+    "composite": true
+  },
+  "include": ["src/**/*"]
+}

package/node_modules/@adjedaini/clockwork-shared/tsup.config.ts

@@ -0,0 +1,13 @@
+import path from 'path';
+import { fileURLToPath } from 'url';
+import { defineConfig } from 'tsup';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+export default defineConfig({
+  entry: ['src/index.ts'],
+  format: ['cjs'],
+  dts: true,
+  outDir: 'dist',
+  tsconfig: path.join(__dirname, 'tsconfig.build.json'),
+});

package/node_modules/@adjedaini/clockwork-transport-http/dist/index.d.ts

@@ -0,0 +1,75 @@
+import { MonitorCore } from '@adjedaini/clockwork-core';
+
+/**
+ * Minimal HTTP request/response-like types.
+ * No hard dependency on Express; compatible with Express, Fastify (with adapters), etc.
+ */
+interface ClockworkRequestLike {
+    method: string;
+    url?: string;
+    originalUrl?: string;
+    path?: string;
+    headers: Record<string, string | string[] | undefined>;
+    body?: unknown;
+    /** Parsed query (e.g. from ?foo=bar). */
+    query?: Record<string, unknown>;
+    /** Parsed cookies if available. */
+    cookies?: Record<string, unknown>;
+    /** Route pattern if available (e.g. "/user/:id"). */
+    route?: {
+        path?: string;
+    };
+}
+interface ClockworkResponseLike {
+    setHeader(name: string, value: string | number): void;
+    getHeader?(name: string): string | number | string[] | undefined;
+    statusCode: number;
+    on(event: 'finish', fn: () => void): void;
+    /** Set status and return chainable res (Express-style). */
+    status?(code: number): ClockworkResponseLike;
+    /** Send body (string or Buffer). */
+    send?(body?: unknown): unknown;
+    /** Send JSON. */
+    json?(body?: unknown): unknown;
+    /** End response with optional body. */
+    end?(body?: string): void;
+    headersSent?: boolean;
+}
+type NextLike = (err?: unknown) => void;
+
+/**
+ * @adjedaini/clockwork-transport-http
+ * HTTP adapter: wraps core, exposes middleware + data handler.
+ * No hard dependency on Express types.
+ */
+
+type ContextRunner = (requestId: string, next: NextLike) => void;
+interface HttpAdapterOptions {
+    /** Base path for API and UI (e.g. "/__clockwork"). No trailing slash. */
+    path?: string;
+    /** Run the rest of the request (next) inside this context (e.g. AsyncLocalStorage.run). Enables per-request correlation. */
+    contextRunner?: ContextRunner;
+    /** Max request list returned by snapshot. */
+    snapshotLimit?: number;
+    /** Redact these keys in headers/body. */
+    redactKeys?: string[];
+    /** Max body size to capture (chars). */
+    maxBodySize?: number;
+    /** Max depth when serializing body. */
+    maxBodyDepth?: number;
+    /** Capture request body. */
+    captureRequestBody?: boolean;
+    /** Capture response body. */
+    captureResponseBody?: boolean;
+    /** Skip paths that start with any of these. */
+    ignoreStartsWith?: string[];
+}
+interface HttpAdapter {
+    /** Middleware: capture request, call next(), finalize on res finish. */
+    middleware(req: ClockworkRequestLike, res: ClockworkResponseLike, next: NextLike): void;
+    /** Handler: serve JSON API (snapshot, by id). Call for GET path, path/latest, path/:id. */
+    dataHandler(req: ClockworkRequestLike, res: ClockworkResponseLike): void;
+}
+declare function createHttpAdapter(core: MonitorCore, options?: HttpAdapterOptions): HttpAdapter;
+
+export { type ClockworkRequestLike, type ClockworkResponseLike, type ContextRunner, type HttpAdapter, type HttpAdapterOptions, type NextLike, createHttpAdapter };

package/node_modules/@adjedaini/clockwork-transport-http/dist/index.js

@@ -0,0 +1,306 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  createHttpAdapter: () => createHttpAdapter
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/sanitize.ts
+var DEFAULT_REDACT_KEYS = [
+  "authorization",
+  "cookie",
+  "set-cookie",
+  "x-api-key",
+  "x-auth-token",
+  "password",
+  "passwd",
+  "secret",
+  "token",
+  "access_token",
+  "refresh_token",
+  "api_key",
+  "apikey",
+  "credential",
+  "credentials"
+];
+function redactValue() {
+  return "[REDACTED]";
+}
+function truncate(str, maxLength) {
+  if (typeof str !== "string") return str;
+  if (str.length <= maxLength) return str;
+  return str.slice(0, maxLength) + "...[truncated]";
+}
+function shouldRedact(key, redactKeys) {
+  const lower = key.toLowerCase();
+  return redactKeys.some((k) => lower.includes(k.toLowerCase()) || k.toLowerCase().includes(lower));
+}
+function sanitizeHeaders(obj, options = {}) {
+  if (!obj || typeof obj !== "object") return {};
+  const keys = options.redactKeys ?? DEFAULT_REDACT_KEYS;
+  const maxLen = options.maxValueLength ?? 500;
+  const out = {};
+  for (const [k, v] of Object.entries(obj)) {
+    if (shouldRedact(k, keys)) {
+      out[k] = redactValue();
+    } else if (typeof v === "string") {
+      out[k] = truncate(v, maxLen);
+    } else {
+      out[k] = v;
+    }
+  }
+  return out;
+}
+var DEFAULT_MAX_DEPTH = 10;
+var OMITTED_DEPTH = "[depth exceeded]";
+function sanitizeBodyAtDepth(value, options) {
+  const keys = options.redactKeys ?? DEFAULT_REDACT_KEYS;
+  const maxLength = options.maxLength ?? 1e4;
+  const maxDepth = options.maxDepth ?? DEFAULT_MAX_DEPTH;
+  const depth = options._depth ?? 0;
+  if (value === null || value === void 0) return value;
+  if (typeof value === "string") return truncate(value, maxLength);
+  if (depth >= maxDepth) return OMITTED_DEPTH;
+  const nextOpts = {
+    redactKeys: keys,
+    maxLength,
+    maxDepth,
+    _depth: depth + 1
+  };
+  if (Array.isArray(value)) {
+    return value.slice(0, 50).map((item) => sanitizeBodyAtDepth(item, nextOpts));
+  }
+  if (typeof value === "object") {
+    const out = {};
+    for (const [k, v] of Object.entries(value)) {
+      if (shouldRedact(k, keys)) out[k] = redactValue();
+      else out[k] = sanitizeBodyAtDepth(v, nextOpts);
+    }
+    return out;
+  }
+  return value;
+}
+function sanitizeBody(value, options = {}) {
+  const { _depth, ...opts } = options;
+  return sanitizeBodyAtDepth(value, opts);
+}
+
+// src/index.ts
+var DEFAULT_PATH = "/__clockwork";
+var DEFAULT_REDACT_KEYS2 = [
+  "authorization",
+  "cookie",
+  "set-cookie",
+  "x-api-key",
+  "x-auth-token",
+  "password",
+  "passwd",
+  "secret",
+  "token",
+  "access_token",
+  "refresh_token"
+];
+function getPathPrefix(path) {
+  return path.replace(/\/$/, "") || DEFAULT_PATH;
+}
+function getMethod(req) {
+  return (req.method || "GET").toUpperCase();
+}
+function getUri(req) {
+  return req.originalUrl ?? req.url ?? req.path ?? "/";
+}
+function getPathname(req) {
+  const u = req.originalUrl ?? req.url ?? req.path ?? "/";
+  const q = u.indexOf("?");
+  return q === -1 ? u : u.slice(0, q);
+}
+function createHttpAdapter(core, options = {}) {
+  const pathPrefix = getPathPrefix(options.path ?? DEFAULT_PATH);
+  const contextRunner = options.contextRunner;
+  const snapshotLimit = options.snapshotLimit ?? 50;
+  const redactKeys = options.redactKeys ?? DEFAULT_REDACT_KEYS2;
+  const maxBodySize = options.maxBodySize ?? 1e4;
+  const maxBodyDepth = options.maxBodyDepth ?? 10;
+  const captureRequestBody = options.captureRequestBody ?? true;
+  const captureResponseBody = options.captureResponseBody ?? true;
+  const ignoreStartsWith = options.ignoreStartsWith ?? [];
+  const sanitizeOpts = { redactKeys, maxLength: maxBodySize, maxDepth: maxBodyDepth };
+  function shouldIgnore(pathname) {
+    return ignoreStartsWith.some((p) => pathname.startsWith(p));
+  }
+  function isClockworkPath(pathname) {
+    return pathname === pathPrefix || pathname.startsWith(pathPrefix + "/");
+  }
+  function sendJson(res, body, statusCode) {
+    const payload = JSON.stringify(body);
+    if (statusCode != null && res.status) {
+      const r = res.status(statusCode);
+      if (r.json) r.json(body);
+      else r.end?.(payload);
+    } else if (res.json) {
+      res.json(body);
+    } else {
+      res.setHeader("Content-Type", "application/json");
+      res.end?.(payload);
+    }
+  }
+  const dataHandler = (req, res) => {
+    const pathname = getPathname(req);
+    if (!isClockworkPath(pathname)) {
+      if (res.status) res.status(404).end?.("Not found");
+      else {
+        res.setHeader("Content-Type", "text/plain");
+        res.end?.("Not found");
+      }
+      return;
+    }
+    const relative = pathname.slice(pathPrefix.length).replace(/^\/+/, "") || "index";
+    const segments = relative.split("/");
+    if (segments[0] === "index" || segments[0] === "") {
+      sendJson(res, core.getSnapshot(snapshotLimit));
+      return;
+    }
+    if (segments[0] === "metrics") {
+      const snapshot = core.getSnapshot(1);
+      sendJson(res, snapshot.metrics ?? { timestamp: Date.now() / 1e3, spans: [] });
+      return;
+    }
+    if (segments[0] === "latest") {
+      const snapshot = core.getSnapshot(1);
+      const reqs = snapshot.requests;
+      if (reqs.length === 0) {
+        sendJson(res, { error: "No requests found" }, 404);
+        return;
+      }
+      const latest = core.getRequest(reqs[0].id);
+      sendJson(res, latest ?? {});
+      return;
+    }
+    const id = segments[0];
+    const request = core.getRequest(id);
+    if (!request) {
+      sendJson(res, { error: "Request not found" }, 404);
+      return;
+    }
+    sendJson(res, request);
+  };
+  const middleware = (req, res, next) => {
+    const pathname = getPathname(req);
+    if (isClockworkPath(pathname)) {
+      dataHandler(req, res);
+      return;
+    }
+    if (shouldIgnore(pathname)) {
+      next();
+      return;
+    }
+    const headers = sanitizeHeaders(
+      req.headers,
+      { redactKeys, maxValueLength: 500 }
+    );
+    const getData = req.query ?? {};
+    const postData = captureRequestBody && req.body !== void 0 ? sanitizeBody(req.body, sanitizeOpts) : void 0;
+    const cookies = req.cookies !== void 0 ? sanitizeHeaders(req.cookies, { redactKeys }) : void 0;
+    const requestId = core.captureRequest({
+      method: getMethod(req),
+      uri: getUri(req),
+      headers,
+      getData: sanitizeBody(getData, sanitizeOpts),
+      postData,
+      cookies,
+      controller: req.route?.path
+    });
+    const startTimeMs = Date.now();
+    let capturedResponseBody = void 0;
+    const setHeader = res.setHeader.bind(res);
+    res.setHeader = function(name, value) {
+      if (!res.headersSent) {
+        if (name.toLowerCase() === "x-clockwork-id") {
+          setHeader("X-Clockwork-Id", String(value));
+        } else if (name.toLowerCase() === "x-clockwork-version") {
+          setHeader("X-Clockwork-Version", "2.0");
+        } else if (name.toLowerCase() === "x-clockwork-path") {
+          setHeader("X-Clockwork-Path", `${pathPrefix}/${value}`);
+        }
+      }
+      return setHeader(name, value);
+    };
+    const originalSend = res.send;
+    const originalJson = res.json;
+    if (originalSend) {
+      res.send = function(body) {
+        if (!res.headersSent) {
+          res.setHeader("X-Clockwork-Id", requestId);
+          res.setHeader("X-Clockwork-Version", "2.0");
+          res.setHeader("X-Clockwork-Path", `${pathPrefix}/${requestId}`);
+        }
+        if (captureResponseBody && body !== void 0) {
+          try {
+            const str = typeof body === "string" ? body : JSON.stringify(body);
+            capturedResponseBody = str.length <= maxBodySize ? typeof body === "string" ? body : body : str.slice(0, maxBodySize) + "...[truncated]";
+          } catch {
+            capturedResponseBody = "[unserializable]";
+          }
+        }
+        return originalSend.call(this, body);
+      };
+    }
+    if (originalJson) {
+      res.json = function(body) {
+        if (!res.headersSent) {
+          res.setHeader("X-Clockwork-Id", requestId);
+          res.setHeader("X-Clockwork-Version", "2.0");
+          res.setHeader("X-Clockwork-Path", `${pathPrefix}/${requestId}`);
+        }
+        if (captureResponseBody && body !== void 0) {
+          try {
+            const str = JSON.stringify(body);
+            capturedResponseBody = str.length <= maxBodySize ? body : str.slice(0, maxBodySize) + "...[truncated]";
+          } catch {
+            capturedResponseBody = "[unserializable]";
+          }
+        }
+        return originalJson.call(this, body);
+      };
+    }
+    res.on("finish", () => {
+      const statusCode = typeof res.statusCode === "number" ? res.statusCode : 200;
+      const duration = Date.now() - startTimeMs;
+      core.finalizeRequest(requestId, {
+        responseStatus: statusCode,
+        responseDuration: duration,
+        responseData: capturedResponseBody !== void 0 ? sanitizeBody(capturedResponseBody, sanitizeOpts) : void 0
+      });
+    });
+    req.clockworkId = requestId;
+    if (contextRunner) {
+      contextRunner(requestId, next);
+    } else {
+      next();
+    }
+  };
+  return { middleware, dataHandler };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  createHttpAdapter
+});

package/node_modules/@adjedaini/clockwork-transport-http/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "@adjedaini/clockwork-transport-http",
+  "version": "0.0.1",
+  "private": true,
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs --dts"
+  },
+  "dependencies": {
+    "@adjedaini/clockwork-core": "*",
+    "@adjedaini/clockwork-shared": "*"
+  },
+  "devDependencies": {
+    "tsup": "^8.0.0",
+    "typescript": "^5.5.0"
+  }
+}