trickle-cli 0.1.0

package/src/commands/proxy.ts

@@ -0,0 +1,314 @@
+import * as http from "http";
+import * as https from "https";
+import * as crypto from "crypto";
+import chalk from "chalk";
+import { getBackendUrl } from "../config";
+
+export interface ProxyOptions {
+  target: string;
+  port?: string;
+}
+
+interface TypeNode {
+  kind: string;
+  [key: string]: unknown;
+}
+
+/**
+ * `trickle proxy` — Transparent reverse proxy that captures API types.
+ *
+ * Sits between the frontend and backend, forwarding all requests while
+ * observing request/response shapes and sending type observations to
+ * the trickle backend. Works with any backend language or framework —
+ * no instrumentation needed.
+ */
+export async function proxyCommand(opts: ProxyOptions): Promise<void> {
+  const targetUrl = opts.target;
+  if (!targetUrl) {
+    console.error(chalk.red("\n  Missing --target flag."));
+    console.error(chalk.gray("  Usage: trickle proxy --target http://localhost:3000\n"));
+    process.exit(1);
+  }
+
+  let parsedTarget: URL;
+  try {
+    parsedTarget = new URL(targetUrl);
+  } catch {
+    console.error(chalk.red(`\n  Invalid target URL: ${targetUrl}\n`));
+    process.exit(1);
+  }
+
+  const port = parseInt(opts.port || "4000", 10);
+  const backendUrl = getBackendUrl();
+
+  // Check backend connectivity
+  try {
+    const res = await fetch(`${backendUrl}/api/health`, { signal: AbortSignal.timeout(3000) });
+    if (!res.ok) throw new Error("not ok");
+  } catch {
+    console.error(chalk.red(`\n  Cannot reach trickle backend at ${chalk.bold(backendUrl)}`));
+    console.error(chalk.gray("  Start the backend first.\n"));
+    process.exit(1);
+  }
+
+  let requestCount = 0;
+  let typesSent = 0;
+
+  const server = http.createServer(async (req, res) => {
+    const method = (req.method || "GET").toUpperCase();
+    const urlPath = req.url || "/";
+
+    // Read request body
+    const reqBody = await readBody(req);
+    let reqJson: unknown = undefined;
+    if (reqBody.length > 0) {
+      try {
+        reqJson = JSON.parse(reqBody.toString("utf-8"));
+      } catch {
+        // Not JSON — skip type capture for request body
+      }
+    }
+
+    // Forward to target
+    const targetReqUrl = new URL(urlPath, targetUrl);
+    const isHttps = parsedTarget.protocol === "https:";
+    const mod = isHttps ? https : http;
+
+    const proxyReq = mod.request(
+      targetReqUrl.toString(),
+      {
+        method,
+        headers: {
+          ...req.headers,
+          host: parsedTarget.host,
+        },
+      },
+      (proxyRes) => {
+        // Read response body
+        const chunks: Buffer[] = [];
+        proxyRes.on("data", (chunk: Buffer) => chunks.push(chunk));
+        proxyRes.on("end", () => {
+          const resBody = Buffer.concat(chunks);
+
+          // Forward response to client
+          res.writeHead(proxyRes.statusCode || 200, proxyRes.headers);
+          res.end(resBody);
+
+          requestCount++;
+
+          // Parse response JSON for type capture
+          let resJson: unknown = undefined;
+          const contentType = proxyRes.headers["content-type"] || "";
+          if (contentType.includes("json") && resBody.length > 0) {
+            try {
+              resJson = JSON.parse(resBody.toString("utf-8"));
+            } catch {
+              // Not valid JSON
+            }
+          }
+
+          // Only capture types for JSON API-like routes
+          if (resJson !== undefined && isApiRoute(urlPath)) {
+            captureTypes(method, urlPath, reqJson, resJson, backendUrl).then((sent) => {
+              if (sent) typesSent++;
+            }).catch(() => {});
+
+            // Log
+            const status = proxyRes.statusCode || 200;
+            const statusColor = status < 400 ? chalk.green : chalk.red;
+            console.log(
+              chalk.gray(`  ${chalk.bold(method)} ${urlPath} → `) +
+              statusColor(`${status}`) +
+              chalk.gray(` (${typesSent} types captured)`),
+            );
+          }
+        });
+      },
+    );
+
+    proxyReq.on("error", (err) => {
+      console.error(chalk.red(`  Proxy error: ${err.message}`));
+      res.writeHead(502);
+      res.end(JSON.stringify({ error: "Bad Gateway", message: err.message }));
+    });
+
+    if (reqBody.length > 0) {
+      proxyReq.write(reqBody);
+    }
+    proxyReq.end();
+  });
+
+  server.listen(port, () => {
+    console.log("");
+    console.log(chalk.bold("  trickle proxy"));
+    console.log(chalk.gray("  " + "─".repeat(50)));
+    console.log(chalk.gray(`  Proxy:    http://localhost:${port}`));
+    console.log(chalk.gray(`  Target:   ${targetUrl}`));
+    console.log(chalk.gray(`  Backend:  ${backendUrl}`));
+    console.log(chalk.gray("  " + "─".repeat(50)));
+    console.log(chalk.gray("  Point your frontend at the proxy URL."));
+    console.log(chalk.gray("  Press Ctrl+C to stop.\n"));
+  });
+
+  process.on("SIGINT", () => {
+    console.log(chalk.gray(`\n  Shutting down... (${requestCount} requests, ${typesSent} types captured)`));
+    server.close();
+    process.exit(0);
+  });
+
+  process.on("SIGTERM", () => {
+    server.close();
+    process.exit(0);
+  });
+}
+
+function readBody(stream: http.IncomingMessage): Promise<Buffer> {
+  return new Promise((resolve) => {
+    const chunks: Buffer[] = [];
+    stream.on("data", (chunk: Buffer) => chunks.push(chunk));
+    stream.on("end", () => resolve(Buffer.concat(chunks)));
+    stream.on("error", () => resolve(Buffer.alloc(0)));
+  });
+}
+
+/**
+ * Heuristic: only capture types for API-like routes (not static assets).
+ */
+function isApiRoute(urlPath: string): boolean {
+  const path = urlPath.split("?")[0];
+  // Skip obvious static assets
+  if (/\.(js|css|html|png|jpg|gif|svg|ico|woff|woff2|ttf|eot|map)$/i.test(path)) {
+    return false;
+  }
+  // Include /api/ routes always
+  if (path.includes("/api/")) return true;
+  // Include anything that doesn't look like a file
+  if (!path.includes(".")) return true;
+  return false;
+}
+
+/**
+ * Infer a TypeNode from a JSON value.
+ */
+function jsonToTypeNode(value: unknown): TypeNode {
+  if (value === null) return { kind: "primitive", name: "null" };
+  if (value === undefined) return { kind: "primitive", name: "undefined" };
+
+  switch (typeof value) {
+    case "string":  return { kind: "primitive", name: "string" };
+    case "number":  return { kind: "primitive", name: "number" };
+    case "boolean": return { kind: "primitive", name: "boolean" };
+    case "bigint":  return { kind: "primitive", name: "bigint" };
+    case "symbol":  return { kind: "primitive", name: "symbol" };
+    case "function": return { kind: "function", params: [], returnType: { kind: "unknown" } };
+  }
+
+  if (Array.isArray(value)) {
+    if (value.length === 0) return { kind: "array", element: { kind: "unknown" } };
+    // Infer element type from first element
+    const elementType = jsonToTypeNode(value[0]);
+    return { kind: "array", element: elementType };
+  }
+
+  // Object
+  const obj = value as Record<string, unknown>;
+  const properties: Record<string, TypeNode> = {};
+  for (const [key, val] of Object.entries(obj)) {
+    properties[key] = jsonToTypeNode(val);
+  }
+  return { kind: "object", properties };
+}
+
+/**
+ * Normalize URL path: replace dynamic segments like /users/123 with :param patterns.
+ * Uses heuristics: numeric segments and UUID-like segments become params.
+ */
+function normalizePath(urlPath: string): string {
+  const path = urlPath.split("?")[0];
+  const parts = path.split("/");
+  return parts
+    .map((part, i) => {
+      if (!part) return part;
+      // Numeric IDs
+      if (/^\d+$/.test(part)) return ":id";
+      // UUIDs
+      if (/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(part)) return ":id";
+      // Short hex hashes
+      if (/^[0-9a-f]{16,}$/i.test(part) && i > 1) return ":id";
+      return part;
+    })
+    .join("/");
+}
+
+/**
+ * Compute a SHA-256 hash (16 hex chars) for type dedup.
+ */
+function computeTypeHash(argsType: TypeNode, returnType: TypeNode): string {
+  const data = JSON.stringify({ a: argsType, r: returnType });
+  return crypto.createHash("sha256").update(data).digest("hex").slice(0, 16);
+}
+
+/**
+ * Send captured types to the trickle backend.
+ */
+async function captureTypes(
+  method: string,
+  urlPath: string,
+  reqJson: unknown,
+  resJson: unknown,
+  backendUrl: string,
+): Promise<boolean> {
+  const normalizedPath = normalizePath(urlPath);
+  const functionName = `${method} ${normalizedPath}`;
+
+  // Build argsType: { body, params, query }
+  const argsProperties: Record<string, TypeNode> = {};
+
+  if (reqJson !== undefined && reqJson !== null) {
+    argsProperties.body = jsonToTypeNode(reqJson);
+  }
+
+  // Extract query params
+  const queryStart = urlPath.indexOf("?");
+  if (queryStart !== -1) {
+    const searchParams = new URLSearchParams(urlPath.slice(queryStart + 1));
+    const queryProps: Record<string, TypeNode> = {};
+    for (const [key] of searchParams) {
+      queryProps[key] = { kind: "primitive", name: "string" };
+    }
+    if (Object.keys(queryProps).length > 0) {
+      argsProperties.query = { kind: "object", properties: queryProps };
+    }
+  }
+
+  const argsType: TypeNode = Object.keys(argsProperties).length > 0
+    ? { kind: "object", properties: argsProperties }
+    : { kind: "object", properties: {} };
+
+  const returnType = jsonToTypeNode(resJson);
+  const typeHash = computeTypeHash(argsType, returnType);
+
+  const payload = {
+    functionName,
+    module: "proxy",
+    language: "js",
+    environment: "development",
+    typeHash,
+    argsType,
+    returnType,
+    sampleInput: reqJson !== undefined ? (Object.keys(argsProperties).length > 0 ? argsProperties : undefined) : undefined,
+    sampleOutput: resJson,
+  };
+
+  try {
+    const res = await fetch(`${backendUrl}/api/ingest`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(payload),
+      signal: AbortSignal.timeout(5000),
+    });
+    return res.ok;
+  } catch {
+    return false;
+  }
+}

package/src/commands/replay.ts

@@ -0,0 +1,356 @@
+import chalk from "chalk";
+import { fetchMockConfig, MockRoute } from "../api-client";
+
+export interface ReplayOptions {
+  target?: string;
+  strict?: boolean;
+  json?: boolean;
+  failFast?: boolean;
+}
+
+interface ReplayResult {
+  method: string;
+  path: string;
+  status: "pass" | "fail" | "error";
+  httpStatus?: number;
+  message?: string;
+  expectedKeys?: string[];
+  actualKeys?: string[];
+  durationMs: number;
+}
+
+/**
+ * `trickle replay` — Replay captured API requests as regression tests.
+ *
+ * Uses the sample inputs/outputs already captured by trickle to replay
+ * requests against a running server and verify response shapes match.
+ * Developers get free regression tests without writing any test code.
+ */
+export async function replayCommand(opts: ReplayOptions): Promise<void> {
+  const target = opts.target || "http://localhost:3000";
+
+  // Fetch observed routes
+  let routes: MockRoute[];
+  try {
+    const config = await fetchMockConfig();
+    routes = config.routes;
+  } catch {
+    console.error(chalk.red("\n  Cannot connect to trickle backend."));
+    console.error(chalk.gray("  Is the backend running?\n"));
+    process.exit(1);
+  }
+
+  if (routes.length === 0) {
+    console.error(chalk.yellow("\n  No observed routes to replay."));
+    console.error(chalk.gray("  Instrument your app and make some requests first.\n"));
+    process.exit(0);
+  }
+
+  if (!opts.json) {
+    console.log("");
+    console.log(chalk.bold("  trickle replay"));
+    console.log(chalk.gray("  " + "─".repeat(50)));
+    console.log(chalk.gray(`  Target:  ${target}`));
+    console.log(chalk.gray(`  Routes:  ${routes.length}`));
+    console.log(chalk.gray(`  Mode:    ${opts.strict ? "strict (exact values)" : "shape (structural match)"}`));
+    console.log(chalk.gray("  " + "─".repeat(50)));
+    console.log("");
+  }
+
+  const results: ReplayResult[] = [];
+
+  for (const route of routes) {
+    const result = await replayRoute(route, target, opts.strict || false);
+    results.push(result);
+
+    if (!opts.json) {
+      const icon = result.status === "pass"
+        ? chalk.green("✓")
+        : result.status === "fail"
+          ? chalk.red("✗")
+          : chalk.yellow("!");
+      const statusStr = result.httpStatus ? chalk.gray(` [${result.httpStatus}]`) : "";
+      const timeStr = chalk.gray(` ${result.durationMs}ms`);
+      const msg = result.message ? chalk.gray(` — ${result.message}`) : "";
+      console.log(`  ${icon} ${chalk.bold(route.method)} ${route.path}${statusStr}${timeStr}${msg}`);
+    }
+
+    if (opts.failFast && result.status !== "pass") {
+      break;
+    }
+  }
+
+  // Summary
+  const passed = results.filter((r) => r.status === "pass").length;
+  const failed = results.filter((r) => r.status === "fail").length;
+  const errors = results.filter((r) => r.status === "error").length;
+
+  if (opts.json) {
+    console.log(JSON.stringify({
+      target,
+      mode: opts.strict ? "strict" : "shape",
+      total: results.length,
+      passed,
+      failed,
+      errors,
+      results,
+    }, null, 2));
+  } else {
+    console.log("");
+    console.log(chalk.gray("  " + "─".repeat(50)));
+    if (failed === 0 && errors === 0) {
+      console.log(chalk.green(`  ${passed}/${results.length} passed`) + chalk.gray(` — all routes match`));
+    } else {
+      const parts: string[] = [];
+      if (passed > 0) parts.push(chalk.green(`${passed} passed`));
+      if (failed > 0) parts.push(chalk.red(`${failed} failed`));
+      if (errors > 0) parts.push(chalk.yellow(`${errors} errors`));
+      console.log(`  ${parts.join(", ")} out of ${results.length} routes`);
+    }
+    console.log("");
+  }
+
+  if (failed > 0 || errors > 0) {
+    process.exit(1);
+  }
+}
+
+async function replayRoute(
+  route: MockRoute,
+  target: string,
+  strict: boolean,
+): Promise<ReplayResult> {
+  const { method, path: routePath } = route;
+
+  // Build URL — replace :param patterns with sample values if available
+  let url = routePath;
+  if (route.sampleInput && typeof route.sampleInput === "object") {
+    const input = route.sampleInput as Record<string, unknown>;
+    const params = input.params as Record<string, string> | undefined;
+    if (params) {
+      for (const [key, value] of Object.entries(params)) {
+        url = url.replace(`:${key}`, String(value));
+      }
+    }
+  }
+  // Replace any remaining :params with "1" as fallback
+  url = url.replace(/:(\w+)/g, "1");
+
+  const fullUrl = `${target}${url}`;
+  const start = Date.now();
+
+  try {
+    // Build request
+    const fetchOpts: RequestInit = { method };
+    const hasBody = ["POST", "PUT", "PATCH"].includes(method);
+
+    if (hasBody && route.sampleInput) {
+      const input = route.sampleInput as Record<string, unknown>;
+      const body = input.body || input;
+      if (body && typeof body === "object" && Object.keys(body as object).length > 0) {
+        fetchOpts.headers = { "Content-Type": "application/json" };
+        fetchOpts.body = JSON.stringify(body);
+      }
+    }
+
+    const res = await fetch(fullUrl, {
+      ...fetchOpts,
+      signal: AbortSignal.timeout(10000),
+    });
+    const durationMs = Date.now() - start;
+
+    if (!res.ok) {
+      return {
+        method, path: routePath, status: "fail",
+        httpStatus: res.status,
+        message: `HTTP ${res.status}`,
+        durationMs,
+      };
+    }
+
+    // Parse response
+    const contentType = res.headers.get("content-type") || "";
+    if (!contentType.includes("json")) {
+      return {
+        method, path: routePath, status: "pass",
+        httpStatus: res.status,
+        message: "non-JSON response",
+        durationMs,
+      };
+    }
+
+    const actual = await res.json();
+
+    if (!route.sampleOutput) {
+      return {
+        method, path: routePath, status: "pass",
+        httpStatus: res.status,
+        durationMs,
+      };
+    }
+
+    // Compare
+    if (strict) {
+      return compareStrict(method, routePath, route.sampleOutput, actual, res.status, durationMs);
+    } else {
+      return compareShape(method, routePath, route.sampleOutput, actual, res.status, durationMs);
+    }
+  } catch (err: unknown) {
+    const durationMs = Date.now() - start;
+    const message = err instanceof Error ? err.message : "Unknown error";
+    return {
+      method, path: routePath, status: "error",
+      message: message.includes("ECONNREFUSED") ? "connection refused" : message,
+      durationMs,
+    };
+  }
+}
+
+/**
+ * Shape comparison: verify that the actual response has the same structure
+ * (same keys, same types) as the expected sample output.
+ */
+function compareShape(
+  method: string,
+  path: string,
+  expected: unknown,
+  actual: unknown,
+  httpStatus: number,
+  durationMs: number,
+): ReplayResult {
+  const mismatches = findShapeMismatches(expected, actual, "");
+
+  if (mismatches.length === 0) {
+    return { method, path, status: "pass", httpStatus, durationMs };
+  }
+
+  return {
+    method, path, status: "fail", httpStatus,
+    message: mismatches[0],
+    durationMs,
+  };
+}
+
+function findShapeMismatches(expected: unknown, actual: unknown, prefix: string): string[] {
+  const mismatches: string[] = [];
+
+  if (expected === null || expected === undefined) {
+    return mismatches;
+  }
+
+  const expectedType = typeOf(expected);
+  const actualType = typeOf(actual);
+
+  if (expectedType !== actualType) {
+    mismatches.push(`${prefix || "root"}: expected ${expectedType}, got ${actualType}`);
+    return mismatches;
+  }
+
+  if (expectedType === "object") {
+    const expectedObj = expected as Record<string, unknown>;
+    const actualObj = actual as Record<string, unknown>;
+    const expectedKeys = Object.keys(expectedObj).sort();
+    const actualKeys = Object.keys(actualObj).sort();
+
+    // Check for missing keys
+    for (const key of expectedKeys) {
+      if (!(key in actualObj)) {
+        mismatches.push(`${prefix ? prefix + "." : ""}${key}: missing`);
+      } else {
+        // Recurse (limit depth to avoid noise)
+        if (prefix.split(".").length < 3) {
+          mismatches.push(
+            ...findShapeMismatches(expectedObj[key], actualObj[key], `${prefix ? prefix + "." : ""}${key}`),
+          );
+        }
+      }
+    }
+  }
+
+  if (expectedType === "array") {
+    const expectedArr = expected as unknown[];
+    const actualArr = actual as unknown[];
+    if (expectedArr.length > 0 && actualArr.length > 0) {
+      mismatches.push(
+        ...findShapeMismatches(expectedArr[0], actualArr[0], `${prefix}[0]`),
+      );
+    }
+  }
+
+  return mismatches;
+}
+
+function typeOf(value: unknown): string {
+  if (value === null) return "null";
+  if (Array.isArray(value)) return "array";
+  return typeof value;
+}
+
+/**
+ * Strict comparison: verify exact value match.
+ */
+function compareStrict(
+  method: string,
+  path: string,
+  expected: unknown,
+  actual: unknown,
+  httpStatus: number,
+  durationMs: number,
+): ReplayResult {
+  // Deep compare, but be lenient with dynamic fields (ids, timestamps)
+  const mismatches = findValueMismatches(expected, actual, "");
+
+  if (mismatches.length === 0) {
+    return { method, path, status: "pass", httpStatus, durationMs };
+  }
+
+  return {
+    method, path, status: "fail", httpStatus,
+    message: mismatches[0],
+    durationMs,
+  };
+}
+
+function findValueMismatches(expected: unknown, actual: unknown, prefix: string): string[] {
+  const mismatches: string[] = [];
+
+  if (expected === null || expected === undefined) return mismatches;
+
+  const expectedType = typeOf(expected);
+  const actualType = typeOf(actual);
+
+  if (expectedType !== actualType) {
+    mismatches.push(`${prefix || "root"}: expected ${expectedType} got ${actualType}`);
+    return mismatches;
+  }
+
+  if (expectedType === "object") {
+    const expectedObj = expected as Record<string, unknown>;
+    const actualObj = actual as Record<string, unknown>;
+
+    for (const key of Object.keys(expectedObj)) {
+      if (!(key in actualObj)) {
+        mismatches.push(`${prefix ? prefix + "." : ""}${key}: missing`);
+      } else if (prefix.split(".").length < 3) {
+        mismatches.push(
+          ...findValueMismatches(expectedObj[key], actualObj[key], `${prefix ? prefix + "." : ""}${key}`),
+        );
+      }
+    }
+  } else if (expectedType === "array") {
+    const expectedArr = expected as unknown[];
+    const actualArr = actual as unknown[];
+    if (expectedArr.length > 0 && actualArr.length > 0) {
+      mismatches.push(
+        ...findValueMismatches(expectedArr[0], actualArr[0], `${prefix}[0]`),
+      );
+    }
+  } else {
+    // Primitive comparison
+    if (expected !== actual) {
+      mismatches.push(`${prefix || "root"}: expected ${JSON.stringify(expected)} got ${JSON.stringify(actual)}`);
+    }
+  }
+
+  return mismatches;
+}