@typokit/plugin-debug 0.1.4

package/dist/index.d.ts

@@ -0,0 +1,35 @@
+import type { TypoKitPlugin } from "@typokit/core";
+/** Security configuration for production mode */
+export interface DebugSecurityConfig {
+    /** API key required via X-Debug-Key header */
+    apiKey?: string;
+    /** IP/CIDR allowlist (e.g., ["127.0.0.1", "10.0.0.0/8"]) */
+    allowlist?: string[];
+    /** Hostname to bind to (default: "127.0.0.1" in production) */
+    hostname?: string;
+    /** Field paths to redact from responses (e.g., ["*.password", "authorization"]) */
+    redact?: string[];
+    /** Rate limit: max requests per window */
+    rateLimit?: number;
+    /** Rate limit window in milliseconds (default: 60000) */
+    rateLimitWindow?: number;
+}
+/** Options for the debugPlugin factory */
+export interface DebugPluginOptions {
+    /** Port for the debug sidecar (default: 9800) */
+    port?: number;
+    /** Enable in production mode (default: false — only auto-enabled in dev) */
+    production?: boolean;
+    /** Security config (required in production mode) */
+    security?: DebugSecurityConfig;
+}
+/**
+ * Create a debug sidecar plugin that exposes introspection endpoints
+ * on a separate port.
+ *
+ * Development mode (default): no auth required, binds to 0.0.0.0.
+ * Production mode (opt-in): requires apiKey, supports IP allowlist,
+ * binds to 127.0.0.1 by default.
+ */
+export declare function debugPlugin(options?: DebugPluginOptions): TypoKitPlugin;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,aAAa,EAAe,MAAM,eAAe,CAAC;AAkBhE,iDAAiD;AACjD,MAAM,WAAW,mBAAmB;IAClC,8CAA8C;IAC9C,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,4DAA4D;IAC5D,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,+DAA+D;IAC/D,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,mFAAmF;IACnF,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,0CAA0C;IAC1C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,yDAAyD;IACzD,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,0CAA0C;AAC1C,MAAM,WAAW,kBAAkB;IACjC,iDAAiD;IACjD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,4EAA4E;IAC5E,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,oDAAoD;IACpD,QAAQ,CAAC,EAAE,mBAAmB,CAAC;CAChC;AAgHD;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,OAAO,GAAE,kBAAuB,GAAG,aAAa,CAoW3E"}

package/dist/index.js

@@ -0,0 +1,382 @@
+// @typokit/plugin-debug — Debug Sidecar Server
+//
+// A plugin that runs a read-only debug HTTP server on a separate port,
+// exposing structured introspection endpoints for AI agents and dev tools.
+import { redactFields } from "@typokit/otel";
+import { createServer } from "@typokit/platform-node";
+// ─── Route Table Traversal ───────────────────────────────────
+function collectRoutes(node, pathPrefix) {
+    const routes = [];
+    const currentPath = pathPrefix + (node.segment ? `/${node.segment}` : "");
+    if (node.handlers) {
+        for (const [method, handler] of Object.entries(node.handlers)) {
+            if (handler) {
+                routes.push({
+                    method: method,
+                    path: currentPath || "/",
+                    ref: handler.ref,
+                    middleware: handler.middleware,
+                    ...(handler.validators ? { validators: handler.validators } : {}),
+                    ...(handler.serializer ? { serializer: handler.serializer } : {}),
+                });
+            }
+        }
+    }
+    if (node.children) {
+        for (const child of Object.values(node.children)) {
+            routes.push(...collectRoutes(child, currentPath));
+        }
+    }
+    if (node.paramChild) {
+        const paramPath = `${currentPath}/:${node.paramChild.paramName}`;
+        routes.push(...collectRoutes(node.paramChild, paramPath.replace(`/${node.paramChild.segment}`, "")));
+    }
+    if (node.wildcardChild) {
+        const wcPath = `${currentPath}/*${node.wildcardChild.paramName}`;
+        routes.push(...collectRoutes(node.wildcardChild, wcPath.replace(`/${node.wildcardChild.segment}`, "")));
+    }
+    return routes;
+}
+// ─── CIDR Check ──────────────────────────────────────────────
+function ipToLong(ip) {
+    const parts = ip.split(".").map(Number);
+    return (((parts[0] << 24) | (parts[1] << 16) | (parts[2] << 8) | parts[3]) >>> 0);
+}
+function isIpAllowed(clientIp, allowlist) {
+    if (allowlist.length === 0)
+        return true;
+    const clientLong = ipToLong(clientIp);
+    for (const entry of allowlist) {
+        if (entry.includes("/")) {
+            const [network, bits] = entry.split("/");
+            const mask = (~0 << (32 - Number(bits))) >>> 0;
+            if ((clientLong & mask) === (ipToLong(network) & mask))
+                return true;
+        }
+        else {
+            if (clientIp === entry)
+                return true;
+        }
+    }
+    return false;
+}
+// ─── Percentile Calculation ──────────────────────────────────
+function percentile(sorted, p) {
+    if (sorted.length === 0)
+        return 0;
+    const idx = Math.ceil((p / 100) * sorted.length) - 1;
+    return sorted[Math.max(0, idx)];
+}
+// ─── Debug Plugin Factory ────────────────────────────────────
+/**
+ * Create a debug sidecar plugin that exposes introspection endpoints
+ * on a separate port.
+ *
+ * Development mode (default): no auth required, binds to 0.0.0.0.
+ * Production mode (opt-in): requires apiKey, supports IP allowlist,
+ * binds to 127.0.0.1 by default.
+ */
+export function debugPlugin(options = {}) {
+    const port = options.port ?? 9800;
+    const isProduction = options.production ?? false;
+    const security = options.security ?? {};
+    const redactPatterns = security.redact ?? [];
+    const rateLimit = security.rateLimit ?? 0;
+    const rateLimitWindow = security.rateLimitWindow ?? 60_000;
+    // Internal state
+    let cachedRoutes = [];
+    let middlewareNames = [];
+    const recentErrors = [];
+    const recentTraces = [];
+    const recentLogs = [];
+    const performanceData = [];
+    let serverHandle = null;
+    let dependencies = {};
+    // Rate limiting state
+    const rateLimitMap = new Map();
+    function checkRateLimit(clientIp) {
+        if (rateLimit <= 0)
+            return true;
+        const now = Date.now();
+        const entry = rateLimitMap.get(clientIp);
+        if (!entry || now >= entry.resetAt) {
+            rateLimitMap.set(clientIp, { count: 1, resetAt: now + rateLimitWindow });
+            return true;
+        }
+        entry.count++;
+        return entry.count <= rateLimit;
+    }
+    function getClientIp(req) {
+        const forwarded = req.headers["x-forwarded-for"];
+        if (typeof forwarded === "string")
+            return forwarded.split(",")[0].trim();
+        return "127.0.0.1";
+    }
+    // Security middleware
+    function checkSecurity(req) {
+        if (!isProduction)
+            return null;
+        // API key check
+        if (security.apiKey) {
+            const key = req.headers["x-debug-key"];
+            if (key !== security.apiKey) {
+                return {
+                    status: 401,
+                    headers: { "content-type": "application/json" },
+                    body: {
+                        error: {
+                            code: "UNAUTHORIZED",
+                            message: "Invalid or missing X-Debug-Key header",
+                        },
+                    },
+                };
+            }
+        }
+        // IP allowlist check
+        if (security.allowlist && security.allowlist.length > 0) {
+            const clientIp = getClientIp(req);
+            if (!isIpAllowed(clientIp, security.allowlist)) {
+                return {
+                    status: 403,
+                    headers: { "content-type": "application/json" },
+                    body: { error: { code: "FORBIDDEN", message: "IP not allowed" } },
+                };
+            }
+        }
+        // Rate limiting
+        if (rateLimit > 0) {
+            const clientIp = getClientIp(req);
+            if (!checkRateLimit(clientIp)) {
+                return {
+                    status: 429,
+                    headers: { "content-type": "application/json" },
+                    body: {
+                        error: { code: "RATE_LIMITED", message: "Too many requests" },
+                    },
+                };
+            }
+        }
+        return null;
+    }
+    function maybeRedact(data) {
+        if (redactPatterns.length === 0)
+            return data;
+        return redactFields(data, redactPatterns);
+    }
+    function parseDuration(value) {
+        if (!value || Array.isArray(value))
+            return 300_000; // default 5 min
+        const match = value.match(/^(\d+)(ms|s|m|h)?$/);
+        if (!match)
+            return 300_000;
+        const num = Number(match[1]);
+        switch (match[2]) {
+            case "ms":
+                return num;
+            case "s":
+                return num * 1000;
+            case "m":
+                return num * 60_000;
+            case "h":
+                return num * 3_600_000;
+            default:
+                return num * 1000; // default to seconds
+        }
+    }
+    // Endpoint handlers
+    const endpoints = {
+        "/_debug/routes": () => {
+            return { routes: cachedRoutes };
+        },
+        "/_debug/middleware": () => {
+            return { middleware: middlewareNames };
+        },
+        "/_debug/performance": (req) => {
+            const windowMs = parseDuration(req.query["window"]);
+            const cutoff = new Date(Date.now() - windowMs).toISOString();
+            const relevant = performanceData.filter((d) => d.timestamp >= cutoff);
+            const durations = relevant.map((d) => d.value).sort((a, b) => a - b);
+            return {
+                window: `${windowMs}ms`,
+                count: durations.length,
+                p50: percentile(durations, 50),
+                p95: percentile(durations, 95),
+                p99: percentile(durations, 99),
+                min: durations.length > 0 ? durations[0] : 0,
+                max: durations.length > 0 ? durations[durations.length - 1] : 0,
+            };
+        },
+        "/_debug/errors": (req) => {
+            const sinceMs = parseDuration(req.query["since"]);
+            const cutoff = new Date(Date.now() - sinceMs).toISOString();
+            const filtered = recentErrors.filter((e) => e.timestamp >= cutoff);
+            return {
+                errors: filtered.map((e) => redactPatterns.length > 0
+                    ? {
+                        ...e,
+                        ...(e.details ? { details: maybeRedact(e.details) } : {}),
+                    }
+                    : e),
+            };
+        },
+        "/_debug/health": () => {
+            const proc = globalThis.process;
+            const mem = proc?.memoryUsage?.();
+            return {
+                status: "ok",
+                uptime: Date.now(),
+                memory: mem
+                    ? { heapUsed: mem.heapUsed, heapTotal: mem.heapTotal, rss: mem.rss }
+                    : null,
+            };
+        },
+        "/_debug/dependencies": () => {
+            return { dependencies };
+        },
+        "/_debug/traces": () => {
+            return {
+                traces: recentTraces.slice(-100).map((spans) => spans.map((s) => redactPatterns.length > 0
+                    ? {
+                        ...s,
+                        attributes: maybeRedact(s.attributes),
+                    }
+                    : s)),
+            };
+        },
+        "/_debug/logs": (req) => {
+            const sinceMs = parseDuration(req.query["since"]);
+            const cutoff = new Date(Date.now() - sinceMs).toISOString();
+            const filtered = recentLogs.filter((l) => l.timestamp >= cutoff);
+            return {
+                logs: filtered.map((l) => redactPatterns.length > 0 && l.data
+                    ? { ...l, data: maybeRedact(l.data) }
+                    : l),
+            };
+        },
+    };
+    async function handleRequest(req) {
+        // Only GET requests allowed (read-only)
+        if (req.method !== "GET") {
+            return {
+                status: 405,
+                headers: { "content-type": "application/json", allow: "GET" },
+                body: {
+                    error: {
+                        code: "METHOD_NOT_ALLOWED",
+                        message: "Debug endpoints are read-only",
+                    },
+                },
+            };
+        }
+        // Security check
+        const secError = checkSecurity(req);
+        if (secError)
+            return secError;
+        const handler = endpoints[req.path];
+        if (!handler) {
+            return {
+                status: 404,
+                headers: { "content-type": "application/json" },
+                body: {
+                    error: {
+                        code: "NOT_FOUND",
+                        message: `Unknown debug endpoint: ${req.path}`,
+                    },
+                },
+            };
+        }
+        const body = handler(req);
+        return {
+            status: 200,
+            headers: { "content-type": "application/json" },
+            body,
+        };
+    }
+    const plugin = {
+        name: "plugin-debug",
+        async onStart(app) {
+            // Collect middleware names from plugins
+            middlewareNames = app.plugins
+                .filter((p) => p.name !== "plugin-debug")
+                .map((p) => p.name);
+            // Build dependency graph from services
+            dependencies = {};
+            for (const [key, value] of Object.entries(app.services)) {
+                if (typeof value === "object" &&
+                    value !== null &&
+                    "dependencies" in value) {
+                    dependencies[key] = value.dependencies;
+                }
+            }
+            // Expose data collection APIs via services
+            app.services["_debug"] = {
+                recordError: (error, route) => {
+                    recentErrors.push({
+                        timestamp: new Date().toISOString(),
+                        code: error.code,
+                        status: error.status,
+                        message: error.message,
+                        details: error.details,
+                        route,
+                    });
+                    // Keep at most 1000 errors
+                    if (recentErrors.length > 1000)
+                        recentErrors.splice(0, recentErrors.length - 1000);
+                },
+                recordTrace: (spans) => {
+                    recentTraces.push(spans);
+                    if (recentTraces.length > 500)
+                        recentTraces.splice(0, recentTraces.length - 500);
+                },
+                recordLog: (entry) => {
+                    recentLogs.push(entry);
+                    if (recentLogs.length > 2000)
+                        recentLogs.splice(0, recentLogs.length - 2000);
+                },
+                recordPerformance: (dataPoint) => {
+                    performanceData.push(dataPoint);
+                    if (performanceData.length > 5000)
+                        performanceData.splice(0, performanceData.length - 5000);
+                },
+                setRouteTable: (routeTable) => {
+                    cachedRoutes = collectRoutes(routeTable, "");
+                },
+                setMiddleware: (names) => {
+                    middlewareNames = names;
+                },
+            };
+        },
+        async onReady(_app) {
+            const hostname = isProduction
+                ? (security.hostname ?? "127.0.0.1")
+                : "0.0.0.0";
+            const srv = createServer(handleRequest, { hostname });
+            serverHandle = await srv.listen(port);
+        },
+        onError(error, ctx) {
+            recentErrors.push({
+                timestamp: new Date().toISOString(),
+                code: error.code,
+                status: error.status,
+                message: error.message,
+                details: error.details,
+                route: ctx.requestId,
+            });
+            if (recentErrors.length > 1000)
+                recentErrors.splice(0, recentErrors.length - 1000);
+        },
+        async onStop(_app) {
+            if (serverHandle) {
+                await serverHandle.close();
+                serverHandle = null;
+            }
+        },
+        onSchemaChange(_changes) {
+            // Route map will be refreshed by the next build cycle calling setRouteTable
+            // Clear cached routes so they'll be re-populated
+            cachedRoutes = [];
+        },
+    };
+    return plugin;
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

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

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@typokit/plugin-debug",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "version": "0.1.4",
+  "type": "module",
+  "files": [
+    "dist",
+    "src"
+  ],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "dependencies": {
+    "@typokit/core": "0.1.4",
+    "@typokit/types": "0.1.4",
+    "@typokit/errors": "0.1.4",
+    "@typokit/platform-node": "0.1.4",
+    "@typokit/otel": "0.1.4"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/KyleBastien/typokit",
+    "directory": "packages/plugin-debug"
+  },
+  "scripts": {
+    "test": "rstest run --passWithNoTests"
+  }
+}

package/src/index.test.ts

@@ -0,0 +1,342 @@
+// @typokit/plugin-debug — Integration Tests
+
+import { describe, it, expect } from "@rstest/core";
+import { debugPlugin } from "./index.js";
+import type { TypoKitPlugin, AppInstance } from "@typokit/core";
+import type { CompiledRouteTable, SchemaChange } from "@typokit/types";
+import type { HistogramDataPoint, LogEntry, SpanData } from "@typokit/otel";
+
+// ─── Helpers ─────────────────────────────────────────────────
+
+function createTestApp(plugins: TypoKitPlugin[]): AppInstance {
+  return {
+    name: "test-app",
+    plugins,
+    services: {},
+  };
+}
+
+const sampleRouteTable: CompiledRouteTable = {
+  segment: "",
+  children: {
+    users: {
+      segment: "users",
+      handlers: {
+        GET: { ref: "users#list", middleware: ["auth"] },
+        POST: { ref: "users#create", middleware: ["auth", "validate"] },
+      },
+      paramChild: {
+        segment: ":id",
+        paramName: "id",
+        handlers: {
+          GET: {
+            ref: "users#get",
+            middleware: ["auth"],
+            validators: { params: "userId" },
+          },
+        },
+      },
+    },
+  },
+};
+
+interface FetchOptions {
+  method?: string;
+  headers?: Record<string, string>;
+}
+
+async function fetchDebug(
+  port: number,
+  path: string,
+  options: FetchOptions = {},
+): Promise<{ status: number; body: Record<string, unknown> }> {
+  const fetchFn = globalThis.fetch;
+  const resp = await fetchFn(`http://127.0.0.1:${port}${path}`, {
+    method: options.method ?? "GET",
+    headers: options.headers ?? {},
+  });
+  const body = (await resp.json()) as Record<string, unknown>;
+  return { status: resp.status, body };
+}
+
+// ─── Tests ───────────────────────────────────────────────────
+
+describe("debugPlugin", () => {
+  it("should create a plugin with the correct name", () => {
+    const plugin = debugPlugin();
+    expect(plugin.name).toBe("plugin-debug");
+  });
+
+  it("should implement TypoKitPlugin lifecycle hooks", () => {
+    const plugin = debugPlugin();
+    expect(typeof plugin.onStart).toBe("function");
+    expect(typeof plugin.onReady).toBe("function");
+    expect(typeof plugin.onStop).toBe("function");
+    expect(typeof plugin.onError).toBe("function");
+    expect(typeof plugin.onSchemaChange).toBe("function");
+  });
+
+  it("should start and stop the sidecar server", async () => {
+    const plugin = debugPlugin({ port: 0 });
+    const app = createTestApp([plugin]);
+
+    await plugin.onStart!(app);
+    // Use a random port for tests
+    // onReady starts the server
+    await plugin.onReady!(app);
+
+    // Server should be running — stop it
+    await plugin.onStop!(app);
+  });
+
+  it("should clear cached routes on schema change", () => {
+    const plugin = debugPlugin();
+    const changes: SchemaChange[] = [
+      { type: "add", entity: "User", field: "email" },
+    ];
+    // Should not throw
+    plugin.onSchemaChange!(changes);
+  });
+});
+
+describe("debug endpoints", () => {
+  let plugin: TypoKitPlugin;
+  let app: AppInstance;
+  const port = 19800; // Use non-default port for tests
+
+  // Start the debug server before tests
+  it("should start the debug sidecar", async () => {
+    plugin = debugPlugin({ port });
+    app = createTestApp([plugin]);
+    await plugin.onStart!(app);
+
+    // Set up test data via the services API
+    const debug = app.services["_debug"] as {
+      setRouteTable: (rt: CompiledRouteTable) => void;
+      setMiddleware: (names: string[]) => void;
+      recordError: (
+        error: {
+          code: string;
+          status: number;
+          message: string;
+          details?: Record<string, unknown>;
+        },
+        route?: string,
+      ) => void;
+      recordTrace: (spans: SpanData[]) => void;
+      recordLog: (entry: LogEntry) => void;
+      recordPerformance: (dp: HistogramDataPoint) => void;
+    };
+
+    debug.setRouteTable(sampleRouteTable);
+    debug.setMiddleware(["auth", "cors", "logging"]);
+    debug.recordError(
+      { code: "NOT_FOUND", status: 404, message: "User not found" },
+      "GET /users/999",
+    );
+    debug.recordTrace([
+      {
+        traceId: "abc123",
+        spanId: "span1",
+        name: "GET /users",
+        kind: "server",
+        startTime: new Date().toISOString(),
+        endTime: new Date().toISOString(),
+        durationMs: 42,
+        status: "ok",
+        attributes: { "http.method": "GET" },
+      },
+    ]);
+    debug.recordLog({
+      level: "info",
+      message: "Request processed",
+      timestamp: new Date().toISOString(),
+      data: { userId: "123" },
+    });
+    debug.recordPerformance({
+      labels: { route: "GET /users", method: "GET", status: 200 },
+      value: 42,
+      timestamp: new Date().toISOString(),
+    });
+
+    await plugin.onReady!(app);
+  });
+
+  it("GET /_debug/routes should return registered routes", async () => {
+    const { status, body } = await fetchDebug(port, "/_debug/routes");
+    expect(status).toBe(200);
+    const routes = body["routes"] as Array<{ method: string; ref: string }>;
+    expect(Array.isArray(routes)).toBe(true);
+    expect(routes.length).toBeGreaterThan(0);
+    // Should have the users routes
+    const listRoute = routes.find((r) => r.ref === "users#list");
+    expect(listRoute).toBeDefined();
+    expect(listRoute!.method).toBe("GET");
+  });
+
+  it("GET /_debug/middleware should return middleware chain", async () => {
+    const { status, body } = await fetchDebug(port, "/_debug/middleware");
+    expect(status).toBe(200);
+    const mw = body["middleware"] as string[];
+    expect(Array.isArray(mw)).toBe(true);
+    expect(mw).toContain("auth");
+    expect(mw).toContain("cors");
+  });
+
+  it("GET /_debug/performance should return latency percentiles", async () => {
+    const { status, body } = await fetchDebug(
+      port,
+      "/_debug/performance?window=5m",
+    );
+    expect(status).toBe(200);
+    expect(typeof body["p50"]).toBe("number");
+    expect(typeof body["p95"]).toBe("number");
+    expect(typeof body["p99"]).toBe("number");
+    expect(typeof body["count"]).toBe("number");
+  });
+
+  it("GET /_debug/errors should return recent errors", async () => {
+    const { status, body } = await fetchDebug(port, "/_debug/errors?since=5m");
+    expect(status).toBe(200);
+    const errors = body["errors"] as Array<{ code: string }>;
+    expect(Array.isArray(errors)).toBe(true);
+    expect(errors.length).toBeGreaterThan(0);
+    expect(errors[0].code).toBe("NOT_FOUND");
+  });
+
+  it("GET /_debug/health should return health status", async () => {
+    const { status, body } = await fetchDebug(port, "/_debug/health");
+    expect(status).toBe(200);
+    expect(body["status"]).toBe("ok");
+    expect(body["memory"]).toBeDefined();
+  });
+
+  it("GET /_debug/dependencies should return dependency graph", async () => {
+    const { status, body } = await fetchDebug(port, "/_debug/dependencies");
+    expect(status).toBe(200);
+    expect(body["dependencies"]).toBeDefined();
+  });
+
+  it("GET /_debug/traces should return recent traces", async () => {
+    const { status, body } = await fetchDebug(port, "/_debug/traces");
+    expect(status).toBe(200);
+    const traces = body["traces"] as SpanData[][];
+    expect(Array.isArray(traces)).toBe(true);
+    expect(traces.length).toBeGreaterThan(0);
+  });
+
+  it("GET /_debug/logs should return recent logs", async () => {
+    const { status, body } = await fetchDebug(port, "/_debug/logs?since=5m");
+    expect(status).toBe(200);
+    const logs = body["logs"] as LogEntry[];
+    expect(Array.isArray(logs)).toBe(true);
+    expect(logs.length).toBeGreaterThan(0);
+    expect(logs[0].message).toBe("Request processed");
+  });
+
+  it("POST should be rejected (read-only)", async () => {
+    const { status } = await fetchDebug(port, "/_debug/routes", {
+      method: "POST",
+    });
+    expect(status).toBe(405);
+  });
+
+  it("unknown endpoint should return 404", async () => {
+    const { status } = await fetchDebug(port, "/_debug/unknown");
+    expect(status).toBe(404);
+  });
+
+  it("should stop the sidecar", async () => {
+    await plugin.onStop!(app);
+  });
+});
+
+describe("production mode security", () => {
+  it("should require API key in production mode", async () => {
+    const testPort = 19801;
+    const plugin = debugPlugin({
+      port: testPort,
+      production: true,
+      security: { apiKey: "test-secret-key" },
+    });
+    const app = createTestApp([plugin]);
+    await plugin.onStart!(app);
+    await plugin.onReady!(app);
+
+    // Request without key should fail
+    const { status: noKeyStatus } = await fetchDebug(
+      testPort,
+      "/_debug/health",
+    );
+    expect(noKeyStatus).toBe(401);
+
+    // Request with correct key should succeed
+    const { status: withKeyStatus } = await fetchDebug(
+      testPort,
+      "/_debug/health",
+      {
+        headers: { "x-debug-key": "test-secret-key" },
+      },
+    );
+    expect(withKeyStatus).toBe(200);
+
+    // Request with wrong key should fail
+    const { status: wrongKeyStatus } = await fetchDebug(
+      testPort,
+      "/_debug/health",
+      {
+        headers: { "x-debug-key": "wrong-key" },
+      },
+    );
+    expect(wrongKeyStatus).toBe(401);
+
+    await plugin.onStop!(app);
+  });
+});
+
+describe("redaction", () => {
+  it("should redact sensitive fields from error details", async () => {
+    const testPort = 19802;
+    const plugin = debugPlugin({
+      port: testPort,
+      security: { redact: ["password", "*.secret"] },
+    });
+    const app = createTestApp([plugin]);
+    await plugin.onStart!(app);
+
+    const debug = app.services["_debug"] as {
+      recordError: (
+        error: {
+          code: string;
+          status: number;
+          message: string;
+          details?: Record<string, unknown>;
+        },
+        route?: string,
+      ) => void;
+    };
+
+    debug.recordError({
+      code: "AUTH_FAILED",
+      status: 401,
+      message: "Auth failed",
+      details: { password: "hunter2", username: "admin" },
+    });
+
+    await plugin.onReady!(app);
+
+    const { status, body } = await fetchDebug(
+      testPort,
+      "/_debug/errors?since=5m",
+    );
+    expect(status).toBe(200);
+    const errors = body["errors"] as Array<{
+      details?: Record<string, unknown>;
+    }>;
+    expect(errors.length).toBeGreaterThan(0);
+    expect(errors[0].details?.["password"]).toBe("[REDACTED]");
+    expect(errors[0].details?.["username"]).toBe("admin");
+
+    await plugin.onStop!(app);
+  });
+});

package/src/index.ts

@@ -0,0 +1,524 @@
+// @typokit/plugin-debug — Debug Sidecar Server
+//
+// A plugin that runs a read-only debug HTTP server on a separate port,
+// exposing structured introspection endpoints for AI agents and dev tools.
+
+import type { TypoKitPlugin, AppInstance } from "@typokit/core";
+import type {
+  CompiledRoute,
+  CompiledRouteTable,
+  HttpMethod,
+  SchemaChange,
+  ServerHandle,
+  TypoKitRequest,
+  TypoKitResponse,
+} from "@typokit/types";
+import type { AppError } from "@typokit/errors";
+import type { RequestContext } from "@typokit/types";
+import type { HistogramDataPoint, LogEntry, SpanData } from "@typokit/otel";
+import { redactFields } from "@typokit/otel";
+import { createServer } from "@typokit/platform-node";
+
+// ─── Types ───────────────────────────────────────────────────
+
+/** Security configuration for production mode */
+export interface DebugSecurityConfig {
+  /** API key required via X-Debug-Key header */
+  apiKey?: string;
+  /** IP/CIDR allowlist (e.g., ["127.0.0.1", "10.0.0.0/8"]) */
+  allowlist?: string[];
+  /** Hostname to bind to (default: "127.0.0.1" in production) */
+  hostname?: string;
+  /** Field paths to redact from responses (e.g., ["*.password", "authorization"]) */
+  redact?: string[];
+  /** Rate limit: max requests per window */
+  rateLimit?: number;
+  /** Rate limit window in milliseconds (default: 60000) */
+  rateLimitWindow?: number;
+}
+
+/** Options for the debugPlugin factory */
+export interface DebugPluginOptions {
+  /** Port for the debug sidecar (default: 9800) */
+  port?: number;
+  /** Enable in production mode (default: false — only auto-enabled in dev) */
+  production?: boolean;
+  /** Security config (required in production mode) */
+  security?: DebugSecurityConfig;
+}
+
+// ─── Internal State ──────────────────────────────────────────
+
+interface RouteInfo {
+  method: HttpMethod;
+  path: string;
+  ref: string;
+  middleware: string[];
+  validators?: { params?: string; query?: string; body?: string };
+  serializer?: string;
+}
+
+interface ErrorRecord {
+  timestamp: string;
+  code: string;
+  status: number;
+  message: string;
+  details?: Record<string, unknown>;
+  route?: string;
+}
+
+interface RateLimitEntry {
+  count: number;
+  resetAt: number;
+}
+
+// ─── Route Table Traversal ───────────────────────────────────
+
+function collectRoutes(node: CompiledRoute, pathPrefix: string): RouteInfo[] {
+  const routes: RouteInfo[] = [];
+  const currentPath = pathPrefix + (node.segment ? `/${node.segment}` : "");
+
+  if (node.handlers) {
+    for (const [method, handler] of Object.entries(node.handlers)) {
+      if (handler) {
+        routes.push({
+          method: method as HttpMethod,
+          path: currentPath || "/",
+          ref: handler.ref,
+          middleware: handler.middleware,
+          ...(handler.validators ? { validators: handler.validators } : {}),
+          ...(handler.serializer ? { serializer: handler.serializer } : {}),
+        });
+      }
+    }
+  }
+
+  if (node.children) {
+    for (const child of Object.values(node.children)) {
+      routes.push(...collectRoutes(child, currentPath));
+    }
+  }
+
+  if (node.paramChild) {
+    const paramPath = `${currentPath}/:${node.paramChild.paramName}`;
+    routes.push(
+      ...collectRoutes(
+        node.paramChild,
+        paramPath.replace(`/${node.paramChild.segment}`, ""),
+      ),
+    );
+  }
+
+  if (node.wildcardChild) {
+    const wcPath = `${currentPath}/*${node.wildcardChild.paramName}`;
+    routes.push(
+      ...collectRoutes(
+        node.wildcardChild,
+        wcPath.replace(`/${node.wildcardChild.segment}`, ""),
+      ),
+    );
+  }
+
+  return routes;
+}
+
+// ─── CIDR Check ──────────────────────────────────────────────
+
+function ipToLong(ip: string): number {
+  const parts = ip.split(".").map(Number);
+  return (
+    ((parts[0] << 24) | (parts[1] << 16) | (parts[2] << 8) | parts[3]) >>> 0
+  );
+}
+
+function isIpAllowed(clientIp: string, allowlist: string[]): boolean {
+  if (allowlist.length === 0) return true;
+  const clientLong = ipToLong(clientIp);
+
+  for (const entry of allowlist) {
+    if (entry.includes("/")) {
+      const [network, bits] = entry.split("/");
+      const mask = (~0 << (32 - Number(bits))) >>> 0;
+      if ((clientLong & mask) === (ipToLong(network) & mask)) return true;
+    } else {
+      if (clientIp === entry) return true;
+    }
+  }
+  return false;
+}
+
+// ─── Percentile Calculation ──────────────────────────────────
+
+function percentile(sorted: number[], p: number): number {
+  if (sorted.length === 0) return 0;
+  const idx = Math.ceil((p / 100) * sorted.length) - 1;
+  return sorted[Math.max(0, idx)];
+}
+
+// ─── Debug Plugin Factory ────────────────────────────────────
+
+/**
+ * Create a debug sidecar plugin that exposes introspection endpoints
+ * on a separate port.
+ *
+ * Development mode (default): no auth required, binds to 0.0.0.0.
+ * Production mode (opt-in): requires apiKey, supports IP allowlist,
+ * binds to 127.0.0.1 by default.
+ */
+export function debugPlugin(options: DebugPluginOptions = {}): TypoKitPlugin {
+  const port = options.port ?? 9800;
+  const isProduction = options.production ?? false;
+  const security = options.security ?? {};
+  const redactPatterns = security.redact ?? [];
+  const rateLimit = security.rateLimit ?? 0;
+  const rateLimitWindow = security.rateLimitWindow ?? 60_000;
+
+  // Internal state
+  let cachedRoutes: RouteInfo[] = [];
+  let middlewareNames: string[] = [];
+  const recentErrors: ErrorRecord[] = [];
+  const recentTraces: SpanData[][] = [];
+  const recentLogs: LogEntry[] = [];
+  const performanceData: HistogramDataPoint[] = [];
+  let serverHandle: ServerHandle | null = null;
+  let dependencies: Record<string, string[]> = {};
+
+  // Rate limiting state
+  const rateLimitMap = new Map<string, RateLimitEntry>();
+
+  function checkRateLimit(clientIp: string): boolean {
+    if (rateLimit <= 0) return true;
+    const now = Date.now();
+    const entry = rateLimitMap.get(clientIp);
+    if (!entry || now >= entry.resetAt) {
+      rateLimitMap.set(clientIp, { count: 1, resetAt: now + rateLimitWindow });
+      return true;
+    }
+    entry.count++;
+    return entry.count <= rateLimit;
+  }
+
+  function getClientIp(req: TypoKitRequest): string {
+    const forwarded = req.headers["x-forwarded-for"];
+    if (typeof forwarded === "string") return forwarded.split(",")[0].trim();
+    return "127.0.0.1";
+  }
+
+  // Security middleware
+  function checkSecurity(req: TypoKitRequest): TypoKitResponse | null {
+    if (!isProduction) return null;
+
+    // API key check
+    if (security.apiKey) {
+      const key = req.headers["x-debug-key"];
+      if (key !== security.apiKey) {
+        return {
+          status: 401,
+          headers: { "content-type": "application/json" },
+          body: {
+            error: {
+              code: "UNAUTHORIZED",
+              message: "Invalid or missing X-Debug-Key header",
+            },
+          },
+        };
+      }
+    }
+
+    // IP allowlist check
+    if (security.allowlist && security.allowlist.length > 0) {
+      const clientIp = getClientIp(req);
+      if (!isIpAllowed(clientIp, security.allowlist)) {
+        return {
+          status: 403,
+          headers: { "content-type": "application/json" },
+          body: { error: { code: "FORBIDDEN", message: "IP not allowed" } },
+        };
+      }
+    }
+
+    // Rate limiting
+    if (rateLimit > 0) {
+      const clientIp = getClientIp(req);
+      if (!checkRateLimit(clientIp)) {
+        return {
+          status: 429,
+          headers: { "content-type": "application/json" },
+          body: {
+            error: { code: "RATE_LIMITED", message: "Too many requests" },
+          },
+        };
+      }
+    }
+
+    return null;
+  }
+
+  function maybeRedact(data: Record<string, unknown>): Record<string, unknown> {
+    if (redactPatterns.length === 0) return data;
+    return redactFields(data, redactPatterns);
+  }
+
+  function parseDuration(value: string | string[] | undefined): number {
+    if (!value || Array.isArray(value)) return 300_000; // default 5 min
+    const match = value.match(/^(\d+)(ms|s|m|h)?$/);
+    if (!match) return 300_000;
+    const num = Number(match[1]);
+    switch (match[2]) {
+      case "ms":
+        return num;
+      case "s":
+        return num * 1000;
+      case "m":
+        return num * 60_000;
+      case "h":
+        return num * 3_600_000;
+      default:
+        return num * 1000; // default to seconds
+    }
+  }
+
+  // Endpoint handlers
+  const endpoints: Record<string, (req: TypoKitRequest) => unknown> = {
+    "/_debug/routes": () => {
+      return { routes: cachedRoutes };
+    },
+
+    "/_debug/middleware": () => {
+      return { middleware: middlewareNames };
+    },
+
+    "/_debug/performance": (req) => {
+      const windowMs = parseDuration(req.query["window"] as string | undefined);
+      const cutoff = new Date(Date.now() - windowMs).toISOString();
+      const relevant = performanceData.filter((d) => d.timestamp >= cutoff);
+      const durations = relevant.map((d) => d.value).sort((a, b) => a - b);
+
+      return {
+        window: `${windowMs}ms`,
+        count: durations.length,
+        p50: percentile(durations, 50),
+        p95: percentile(durations, 95),
+        p99: percentile(durations, 99),
+        min: durations.length > 0 ? durations[0] : 0,
+        max: durations.length > 0 ? durations[durations.length - 1] : 0,
+      };
+    },
+
+    "/_debug/errors": (req) => {
+      const sinceMs = parseDuration(req.query["since"] as string | undefined);
+      const cutoff = new Date(Date.now() - sinceMs).toISOString();
+      const filtered = recentErrors.filter((e) => e.timestamp >= cutoff);
+
+      return {
+        errors: filtered.map((e) =>
+          redactPatterns.length > 0
+            ? {
+                ...e,
+                ...(e.details ? { details: maybeRedact(e.details) } : {}),
+              }
+            : e,
+        ),
+      };
+    },
+
+    "/_debug/health": () => {
+      const proc = (
+        globalThis as unknown as {
+          process?: {
+            memoryUsage?: () => {
+              heapUsed: number;
+              heapTotal: number;
+              rss: number;
+            };
+          };
+        }
+      ).process;
+      const mem = proc?.memoryUsage?.();
+
+      return {
+        status: "ok",
+        uptime: Date.now(),
+        memory: mem
+          ? { heapUsed: mem.heapUsed, heapTotal: mem.heapTotal, rss: mem.rss }
+          : null,
+      };
+    },
+
+    "/_debug/dependencies": () => {
+      return { dependencies };
+    },
+
+    "/_debug/traces": () => {
+      return {
+        traces: recentTraces.slice(-100).map((spans) =>
+          spans.map((s) =>
+            redactPatterns.length > 0
+              ? {
+                  ...s,
+                  attributes: maybeRedact(
+                    s.attributes as unknown as Record<string, unknown>,
+                  ) as unknown as Record<string, string | number | boolean>,
+                }
+              : s,
+          ),
+        ),
+      };
+    },
+
+    "/_debug/logs": (req) => {
+      const sinceMs = parseDuration(req.query["since"] as string | undefined);
+      const cutoff = new Date(Date.now() - sinceMs).toISOString();
+      const filtered = recentLogs.filter((l) => l.timestamp >= cutoff);
+
+      return {
+        logs: filtered.map((l) =>
+          redactPatterns.length > 0 && l.data
+            ? { ...l, data: maybeRedact(l.data) }
+            : l,
+        ),
+      };
+    },
+  };
+
+  async function handleRequest(req: TypoKitRequest): Promise<TypoKitResponse> {
+    // Only GET requests allowed (read-only)
+    if (req.method !== "GET") {
+      return {
+        status: 405,
+        headers: { "content-type": "application/json", allow: "GET" },
+        body: {
+          error: {
+            code: "METHOD_NOT_ALLOWED",
+            message: "Debug endpoints are read-only",
+          },
+        },
+      };
+    }
+
+    // Security check
+    const secError = checkSecurity(req);
+    if (secError) return secError;
+
+    const handler = endpoints[req.path];
+    if (!handler) {
+      return {
+        status: 404,
+        headers: { "content-type": "application/json" },
+        body: {
+          error: {
+            code: "NOT_FOUND",
+            message: `Unknown debug endpoint: ${req.path}`,
+          },
+        },
+      };
+    }
+
+    const body = handler(req);
+    return {
+      status: 200,
+      headers: { "content-type": "application/json" },
+      body,
+    };
+  }
+
+  const plugin: TypoKitPlugin = {
+    name: "plugin-debug",
+
+    async onStart(app: AppInstance): Promise<void> {
+      // Collect middleware names from plugins
+      middlewareNames = app.plugins
+        .filter((p) => p.name !== "plugin-debug")
+        .map((p) => p.name);
+
+      // Build dependency graph from services
+      dependencies = {};
+      for (const [key, value] of Object.entries(app.services)) {
+        if (
+          typeof value === "object" &&
+          value !== null &&
+          "dependencies" in value
+        ) {
+          dependencies[key] = (
+            value as { dependencies: string[] }
+          ).dependencies;
+        }
+      }
+
+      // Expose data collection APIs via services
+      app.services["_debug"] = {
+        recordError: (error: AppError, route?: string) => {
+          recentErrors.push({
+            timestamp: new Date().toISOString(),
+            code: error.code,
+            status: error.status,
+            message: error.message,
+            details: error.details,
+            route,
+          });
+          // Keep at most 1000 errors
+          if (recentErrors.length > 1000)
+            recentErrors.splice(0, recentErrors.length - 1000);
+        },
+        recordTrace: (spans: SpanData[]) => {
+          recentTraces.push(spans);
+          if (recentTraces.length > 500)
+            recentTraces.splice(0, recentTraces.length - 500);
+        },
+        recordLog: (entry: LogEntry) => {
+          recentLogs.push(entry);
+          if (recentLogs.length > 2000)
+            recentLogs.splice(0, recentLogs.length - 2000);
+        },
+        recordPerformance: (dataPoint: HistogramDataPoint) => {
+          performanceData.push(dataPoint);
+          if (performanceData.length > 5000)
+            performanceData.splice(0, performanceData.length - 5000);
+        },
+        setRouteTable: (routeTable: CompiledRouteTable) => {
+          cachedRoutes = collectRoutes(routeTable, "");
+        },
+        setMiddleware: (names: string[]) => {
+          middlewareNames = names;
+        },
+      };
+    },
+
+    async onReady(_app: AppInstance): Promise<void> {
+      const hostname = isProduction
+        ? (security.hostname ?? "127.0.0.1")
+        : "0.0.0.0";
+
+      const srv = createServer(handleRequest, { hostname });
+      serverHandle = await srv.listen(port);
+    },
+
+    onError(error: AppError, ctx: RequestContext): void {
+      recentErrors.push({
+        timestamp: new Date().toISOString(),
+        code: error.code,
+        status: error.status,
+        message: error.message,
+        details: error.details,
+        route: ctx.requestId,
+      });
+      if (recentErrors.length > 1000)
+        recentErrors.splice(0, recentErrors.length - 1000);
+    },
+
+    async onStop(_app: AppInstance): Promise<void> {
+      if (serverHandle) {
+        await serverHandle.close();
+        serverHandle = null;
+      }
+    },
+
+    onSchemaChange(_changes: SchemaChange[]): void {
+      // Route map will be refreshed by the next build cycle calling setRouteTable
+      // Clear cached routes so they'll be re-populated
+      cachedRoutes = [];
+    },
+  };
+
+  return plugin;
+}