trickle-cli 0.1.0

package/dist/commands/proxy.js

@@ -0,0 +1,312 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.proxyCommand = proxyCommand;
+const http = __importStar(require("http"));
+const https = __importStar(require("https"));
+const crypto = __importStar(require("crypto"));
+const chalk_1 = __importDefault(require("chalk"));
+const config_1 = require("../config");
+/**
+ * `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.
+ */
+async function proxyCommand(opts) {
+    const targetUrl = opts.target;
+    if (!targetUrl) {
+        console.error(chalk_1.default.red("\n  Missing --target flag."));
+        console.error(chalk_1.default.gray("  Usage: trickle proxy --target http://localhost:3000\n"));
+        process.exit(1);
+    }
+    let parsedTarget;
+    try {
+        parsedTarget = new URL(targetUrl);
+    }
+    catch {
+        console.error(chalk_1.default.red(`\n  Invalid target URL: ${targetUrl}\n`));
+        process.exit(1);
+    }
+    const port = parseInt(opts.port || "4000", 10);
+    const backendUrl = (0, config_1.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_1.default.red(`\n  Cannot reach trickle backend at ${chalk_1.default.bold(backendUrl)}`));
+        console.error(chalk_1.default.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 = 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 = [];
+            proxyRes.on("data", (chunk) => 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 = 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_1.default.green : chalk_1.default.red;
+                    console.log(chalk_1.default.gray(`  ${chalk_1.default.bold(method)} ${urlPath} → `) +
+                        statusColor(`${status}`) +
+                        chalk_1.default.gray(` (${typesSent} types captured)`));
+                }
+            });
+        });
+        proxyReq.on("error", (err) => {
+            console.error(chalk_1.default.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_1.default.bold("  trickle proxy"));
+        console.log(chalk_1.default.gray("  " + "─".repeat(50)));
+        console.log(chalk_1.default.gray(`  Proxy:    http://localhost:${port}`));
+        console.log(chalk_1.default.gray(`  Target:   ${targetUrl}`));
+        console.log(chalk_1.default.gray(`  Backend:  ${backendUrl}`));
+        console.log(chalk_1.default.gray("  " + "─".repeat(50)));
+        console.log(chalk_1.default.gray("  Point your frontend at the proxy URL."));
+        console.log(chalk_1.default.gray("  Press Ctrl+C to stop.\n"));
+    });
+    process.on("SIGINT", () => {
+        console.log(chalk_1.default.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) {
+    return new Promise((resolve) => {
+        const chunks = [];
+        stream.on("data", (chunk) => 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) {
+    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) {
+    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;
+    const properties = {};
+    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) {
+    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, returnType) {
+    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, urlPath, reqJson, resJson, backendUrl) {
+    const normalizedPath = normalizePath(urlPath);
+    const functionName = `${method} ${normalizedPath}`;
+    // Build argsType: { body, params, query }
+    const argsProperties = {};
+    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 = {};
+        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 = 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/dist/commands/replay.d.ts

@@ -0,0 +1,14 @@
+export interface ReplayOptions {
+    target?: string;
+    strict?: boolean;
+    json?: boolean;
+    failFast?: boolean;
+}
+/**
+ * `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 declare function replayCommand(opts: ReplayOptions): Promise<void>;

package/dist/commands/replay.js

@@ -0,0 +1,289 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.replayCommand = replayCommand;
+const chalk_1 = __importDefault(require("chalk"));
+const api_client_1 = require("../api-client");
+/**
+ * `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.
+ */
+async function replayCommand(opts) {
+    const target = opts.target || "http://localhost:3000";
+    // Fetch observed routes
+    let routes;
+    try {
+        const config = await (0, api_client_1.fetchMockConfig)();
+        routes = config.routes;
+    }
+    catch {
+        console.error(chalk_1.default.red("\n  Cannot connect to trickle backend."));
+        console.error(chalk_1.default.gray("  Is the backend running?\n"));
+        process.exit(1);
+    }
+    if (routes.length === 0) {
+        console.error(chalk_1.default.yellow("\n  No observed routes to replay."));
+        console.error(chalk_1.default.gray("  Instrument your app and make some requests first.\n"));
+        process.exit(0);
+    }
+    if (!opts.json) {
+        console.log("");
+        console.log(chalk_1.default.bold("  trickle replay"));
+        console.log(chalk_1.default.gray("  " + "─".repeat(50)));
+        console.log(chalk_1.default.gray(`  Target:  ${target}`));
+        console.log(chalk_1.default.gray(`  Routes:  ${routes.length}`));
+        console.log(chalk_1.default.gray(`  Mode:    ${opts.strict ? "strict (exact values)" : "shape (structural match)"}`));
+        console.log(chalk_1.default.gray("  " + "─".repeat(50)));
+        console.log("");
+    }
+    const results = [];
+    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_1.default.green("✓")
+                : result.status === "fail"
+                    ? chalk_1.default.red("✗")
+                    : chalk_1.default.yellow("!");
+            const statusStr = result.httpStatus ? chalk_1.default.gray(` [${result.httpStatus}]`) : "";
+            const timeStr = chalk_1.default.gray(` ${result.durationMs}ms`);
+            const msg = result.message ? chalk_1.default.gray(` — ${result.message}`) : "";
+            console.log(`  ${icon} ${chalk_1.default.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_1.default.gray("  " + "─".repeat(50)));
+        if (failed === 0 && errors === 0) {
+            console.log(chalk_1.default.green(`  ${passed}/${results.length} passed`) + chalk_1.default.gray(` — all routes match`));
+        }
+        else {
+            const parts = [];
+            if (passed > 0)
+                parts.push(chalk_1.default.green(`${passed} passed`));
+            if (failed > 0)
+                parts.push(chalk_1.default.red(`${failed} failed`));
+            if (errors > 0)
+                parts.push(chalk_1.default.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, target, strict) {
+    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;
+        const params = input.params;
+        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 = { method };
+        const hasBody = ["POST", "PUT", "PATCH"].includes(method);
+        if (hasBody && route.sampleInput) {
+            const input = route.sampleInput;
+            const body = input.body || input;
+            if (body && typeof body === "object" && Object.keys(body).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) {
+        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, path, expected, actual, httpStatus, durationMs) {
+    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, actual, prefix) {
+    const mismatches = [];
+    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;
+        const actualObj = actual;
+        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;
+        const actualArr = actual;
+        if (expectedArr.length > 0 && actualArr.length > 0) {
+            mismatches.push(...findShapeMismatches(expectedArr[0], actualArr[0], `${prefix}[0]`));
+        }
+    }
+    return mismatches;
+}
+function typeOf(value) {
+    if (value === null)
+        return "null";
+    if (Array.isArray(value))
+        return "array";
+    return typeof value;
+}
+/**
+ * Strict comparison: verify exact value match.
+ */
+function compareStrict(method, path, expected, actual, httpStatus, durationMs) {
+    // 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, actual, prefix) {
+    const mismatches = [];
+    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;
+        const actualObj = actual;
+        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;
+        const actualArr = actual;
+        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;
+}

package/dist/commands/run.d.ts

@@ -0,0 +1,17 @@
+export interface RunOptions {
+    module?: string;
+    include?: string;
+    exclude?: string;
+    stubs?: string;
+    annotate?: string;
+    watch?: boolean;
+}
+/**
+ * `trickle run <command>` — Run any command with universal type observation.
+ *
+ * Auto-detects JS or Python, injects the right instrumentation, starts the
+ * backend if needed, and shows a summary of captured types after exit.
+ * With --stubs or --annotate, also generates type files automatically.
+ * Reads .tricklerc.json for project defaults.
+ */
+export declare function runCommand(command: string | undefined, opts: RunOptions): Promise<void>;