@adjedaini/clockwork-node 0.0.1

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

@@ -0,0 +1,277 @@
+/**
+ * @adjedaini/clockwork-transport-http
+ * HTTP adapter: wraps core, exposes middleware + data handler.
+ * No hard dependency on Express types.
+ */
+
+import type { MonitorCore } from '@adjedaini/clockwork-core';
+import type {
+  ClockworkRequestLike,
+  ClockworkResponseLike,
+  NextLike,
+} from './types';
+import { sanitizeHeaders, sanitizeBody } from './sanitize';
+
+export type { ClockworkRequestLike, ClockworkResponseLike, NextLike } from './types.js';
+
+export type ContextRunner = (requestId: string, next: NextLike) => void;
+
+export 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[];
+}
+
+const DEFAULT_PATH = '/__clockwork';
+const DEFAULT_REDACT_KEYS = [
+  'authorization', 'cookie', 'set-cookie', 'x-api-key', 'x-auth-token',
+  'password', 'passwd', 'secret', 'token', 'access_token', 'refresh_token',
+];
+
+export 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;
+}
+
+function getPathPrefix(path: string): string {
+  return path.replace(/\/$/, '') || DEFAULT_PATH;
+}
+
+function getMethod(req: ClockworkRequestLike): string {
+  return (req.method || 'GET').toUpperCase();
+}
+
+function getUri(req: ClockworkRequestLike): string {
+  return req.originalUrl ?? req.url ?? req.path ?? '/';
+}
+
+function getPathname(req: ClockworkRequestLike): string {
+  const u = req.originalUrl ?? req.url ?? req.path ?? '/';
+  const q = u.indexOf('?');
+  return q === -1 ? u : u.slice(0, q);
+}
+
+export function createHttpAdapter(
+  core: MonitorCore,
+  options: HttpAdapterOptions = {}
+): HttpAdapter {
+  const pathPrefix = getPathPrefix(options.path ?? DEFAULT_PATH);
+  const contextRunner = options.contextRunner;
+  const snapshotLimit = options.snapshotLimit ?? 50;
+  const redactKeys = options.redactKeys ?? DEFAULT_REDACT_KEYS;
+  const maxBodySize = options.maxBodySize ?? 10000;
+  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: string): boolean {
+    return ignoreStartsWith.some((p) => pathname.startsWith(p));
+  }
+
+  function isClockworkPath(pathname: string): boolean {
+    return pathname === pathPrefix || pathname.startsWith(pathPrefix + '/');
+  }
+
+  function sendJson(res: ClockworkResponseLike, body: unknown, statusCode?: number): void {
+    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: HttpAdapter['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('/');
+
+    // GET /__clockwork -> snapshot (requests list)
+    if (segments[0] === 'index' || segments[0] === '') {
+      sendJson(res, core.getSnapshot(snapshotLimit));
+      return;
+    }
+
+    // GET /__clockwork/metrics -> metrics only
+    if (segments[0] === 'metrics') {
+      const snapshot = core.getSnapshot(1);
+      sendJson(res, snapshot.metrics ?? { timestamp: Date.now() / 1000, spans: [] });
+      return;
+    }
+
+    // GET /__clockwork/latest -> latest request
+    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;
+    }
+
+    // GET /__clockwork/:id -> single request
+    const id = segments[0];
+    const request = core.getRequest(id);
+    if (!request) {
+      sendJson(res, { error: 'Request not found' }, 404);
+      return;
+    }
+    sendJson(res, request);
+  };
+
+  const middleware: HttpAdapter['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 as Record<string, unknown>,
+      { redactKeys, maxValueLength: 500 }
+    );
+    const getData = (req.query ?? {}) as Record<string, unknown>;
+    const postData =
+      captureRequestBody && req.body !== undefined
+        ? sanitizeBody(req.body, sanitizeOpts)
+        : undefined;
+    const cookies =
+      req.cookies !== undefined
+        ? sanitizeHeaders(req.cookies as Record<string, unknown>, { redactKeys })
+        : undefined;
+
+    const requestId = core.captureRequest({
+      method: getMethod(req),
+      uri: getUri(req),
+      headers,
+      getData: sanitizeBody(getData, sanitizeOpts) as Record<string, unknown>,
+      postData,
+      cookies,
+      controller: req.route?.path,
+    });
+    const startTimeMs = Date.now();
+    let capturedResponseBody: unknown = undefined;
+
+    const setHeader = res.setHeader.bind(res);
+    res.setHeader = function (name: string, value: string | number) {
+      if (!(res as { headersSent?: boolean }).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?: unknown) {
+        if (!(res as { headersSent?: boolean }).headersSent) {
+          res.setHeader('X-Clockwork-Id', requestId);
+          res.setHeader('X-Clockwork-Version', '2.0');
+          res.setHeader('X-Clockwork-Path', `${pathPrefix}/${requestId}`);
+        }
+        if (captureResponseBody && body !== undefined) {
+          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?: unknown) {
+        if (!(res as { headersSent?: boolean }).headersSent) {
+          res.setHeader('X-Clockwork-Id', requestId);
+          res.setHeader('X-Clockwork-Version', '2.0');
+          res.setHeader('X-Clockwork-Path', `${pathPrefix}/${requestId}`);
+        }
+        if (captureResponseBody && body !== undefined) {
+          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 as { statusCode?: number }).statusCode === 'number'
+          ? (res as { statusCode: number }).statusCode
+          : 200;
+      const duration = Date.now() - startTimeMs;
+      core.finalizeRequest(requestId, {
+        responseStatus: statusCode,
+        responseDuration: duration,
+        responseData:
+          capturedResponseBody !== undefined
+            ? sanitizeBody(capturedResponseBody, sanitizeOpts)
+            : undefined,
+      });
+    });
+
+    (req as { clockworkId?: string }).clockworkId = requestId;
+    if (contextRunner) {
+      contextRunner(requestId, next);
+    } else {
+      next();
+    }
+  };
+
+  return { middleware, dataHandler };
+}

package/node_modules/@adjedaini/clockwork-transport-http/src/sanitize.ts

@@ -0,0 +1,92 @@
+/** Minimal sanitization for headers/body. No framework deps. */
+
+const 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(): string {
+  return '[REDACTED]';
+}
+
+function truncate(str: string, maxLength: number): string {
+  if (typeof str !== 'string') return str;
+  if (str.length <= maxLength) return str;
+  return str.slice(0, maxLength) + '...[truncated]';
+}
+
+function shouldRedact(key: string, redactKeys: string[]): boolean {
+  const lower = key.toLowerCase();
+  return redactKeys.some((k) => lower.includes(k.toLowerCase()) || k.toLowerCase().includes(lower));
+}
+
+export function sanitizeHeaders(
+  obj: Record<string, unknown> | undefined,
+  options: { redactKeys?: string[]; maxValueLength?: number } = {}
+): Record<string, unknown> {
+  if (!obj || typeof obj !== 'object') return {};
+  const keys = options.redactKeys ?? DEFAULT_REDACT_KEYS;
+  const maxLen = options.maxValueLength ?? 500;
+  const out: Record<string, unknown> = {};
+  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;
+}
+
+const DEFAULT_MAX_DEPTH = 10;
+const OMITTED_DEPTH = '[depth exceeded]';
+
+export interface SanitizeBodyOptions {
+  redactKeys?: string[];
+  maxLength?: number;
+  maxDepth?: number;
+}
+
+function sanitizeBodyAtDepth(
+  value: unknown,
+  options: SanitizeBodyOptions & { _depth?: number }
+): unknown {
+  const keys = options.redactKeys ?? DEFAULT_REDACT_KEYS;
+  const maxLength = options.maxLength ?? 10000;
+  const maxDepth = options.maxDepth ?? DEFAULT_MAX_DEPTH;
+  const depth = options._depth ?? 0;
+
+  if (value === null || value === undefined) return value;
+  if (typeof value === 'string') return truncate(value, maxLength);
+  if (depth >= maxDepth) return OMITTED_DEPTH;
+
+  const nextOpts: SanitizeBodyOptions & { _depth?: number } = {
+    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: Record<string, unknown> = {};
+    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;
+}
+
+export function sanitizeBody(value: unknown, options: SanitizeBodyOptions = {}): unknown {
+  const { _depth, ...opts } = options as SanitizeBodyOptions & { _depth?: number };
+  return sanitizeBodyAtDepth(value, opts);
+}
+
+export { DEFAULT_REDACT_KEYS };

package/node_modules/@adjedaini/clockwork-transport-http/src/types.ts

@@ -0,0 +1,37 @@
+/**
+ * Minimal HTTP request/response-like types.
+ * No hard dependency on Express; compatible with Express, Fastify (with adapters), etc.
+ */
+
+export 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 };
+}
+
+export 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;
+}
+
+export type NextLike = (err?: unknown) => void;

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

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

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

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

package/node_modules/@adjedaini/clockwork-transport-http/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/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "@adjedaini/clockwork-node",
+  "version": "0.0.1",
+  "description": "Clockwork Node — framework-agnostic debugging, profiling & metrics for Node.js backends",
+  "private": false,
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./globals": "./dist/globals.d.ts"
+  },
+  "workspaces": [
+    ".",
+    "packages/*",
+    "apps/*"
+  ],
+  "scripts": {
+    "build": "npm run build:packages && npm run build:ui && npm run build:root && npm run build:copy-ui",
+    "build:packages": "node scripts/build-packages.cjs",
+    "build:ui": "npm run build -w @adjedaini/clockwork-ui",
+    "build:root": "tsup",
+    "build:copy-ui": "node scripts/copy-ui.cjs",
+    "dev:ui": "npm run dev -w @adjedaini/clockwork-ui",
+    "dev:example": "npm run start -w example",
+    "clean": "rm -rf dist packages/*/dist; true",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "version": "changeset version",
+    "release": "changeset publish",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@adjedaini/clockwork-core": "*",
+    "@adjedaini/clockwork-transport-http": "*",
+    "@adjedaini/clockwork-shared": "*",
+    "@adjedaini/clockwork-plugins": "*",
+    "@adjedaini/clockwork-db-interceptor": "*",
+    "@adjedaini/clockwork-log-interceptor": "*"
+  },
+  "devDependencies": {
+    "@changesets/cli": "^2.27.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.5.0",
+    "vitest": "^2.0.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "bundledDependencies": [
+    "@adjedaini/clockwork-core",
+    "@adjedaini/clockwork-transport-http",
+    "@adjedaini/clockwork-shared",
+    "@adjedaini/clockwork-plugins",
+    "@adjedaini/clockwork-db-interceptor",
+    "@adjedaini/clockwork-log-interceptor"
+  ]
+}