trickle-cli 0.1.0

package/dist/commands/openapi.js

@@ -0,0 +1,82 @@
+"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.openapiCommand = openapiCommand;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const chalk_1 = __importDefault(require("chalk"));
+const api_client_1 = require("../api-client");
+async function openapiCommand(opts) {
+    try {
+        const spec = await (0, api_client_1.fetchOpenApiSpec)({
+            env: opts.env,
+            title: opts.title,
+            version: opts.apiVersion,
+            serverUrl: opts.server,
+        });
+        const json = JSON.stringify(spec, null, 2) + "\n";
+        if (opts.out) {
+            const outPath = path.resolve(opts.out);
+            const dir = path.dirname(outPath);
+            if (!fs.existsSync(dir)) {
+                fs.mkdirSync(dir, { recursive: true });
+            }
+            fs.writeFileSync(outPath, json, "utf-8");
+            console.log("");
+            console.log(chalk_1.default.green(`  OpenAPI spec written to ${chalk_1.default.bold(opts.out)}`));
+            // Show summary
+            const specObj = spec;
+            const paths = specObj.paths || {};
+            const pathCount = Object.keys(paths).length;
+            let operationCount = 0;
+            for (const methods of Object.values(paths)) {
+                operationCount += Object.keys(methods).length;
+            }
+            console.log(chalk_1.default.gray(`  ${pathCount} path${pathCount !== 1 ? "s" : ""}, ${operationCount} operation${operationCount !== 1 ? "s" : ""}`));
+            console.log("");
+        }
+        else {
+            process.stdout.write(json);
+        }
+    }
+    catch (err) {
+        if (err instanceof Error) {
+            console.error(chalk_1.default.red(`\n  Error: ${err.message}\n`));
+        }
+    }
+}

package/dist/commands/overview.d.ts

@@ -0,0 +1,11 @@
+export interface OverviewOptions {
+    env?: string;
+    json?: boolean;
+}
+/**
+ * `trickle overview` — Compact API overview with inline type signatures.
+ *
+ * Shows all observed routes with their return type shapes, making it easy to
+ * understand your entire API surface at a glance. Like `git log --oneline` for APIs.
+ */
+export declare function overviewCommand(opts: OverviewOptions): Promise<void>;

package/dist/commands/overview.js

@@ -0,0 +1,266 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.overviewCommand = overviewCommand;
+const chalk_1 = __importDefault(require("chalk"));
+const api_client_1 = require("../api-client");
+const config_1 = require("../config");
+const helpers_1 = require("../ui/helpers");
+/**
+ * `trickle overview` — Compact API overview with inline type signatures.
+ *
+ * Shows all observed routes with their return type shapes, making it easy to
+ * understand your entire API surface at a glance. Like `git log --oneline` for APIs.
+ */
+async function overviewCommand(opts) {
+    const backendUrl = (0, config_1.getBackendUrl)();
+    // Check backend
+    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)}\n`));
+        process.exit(1);
+    }
+    // Fetch all functions
+    const result = await (0, api_client_1.listFunctions)({ env: opts.env, limit: 500 });
+    const { functions } = result;
+    if (functions.length === 0) {
+        console.log(chalk_1.default.yellow("\n  No observed routes yet."));
+        console.log(chalk_1.default.gray("  Run ") + chalk_1.default.white("trickle capture") + chalk_1.default.gray(" or ") + chalk_1.default.white("trickle dev") + chalk_1.default.gray(" to start observing.\n"));
+        return;
+    }
+    // Fetch latest type snapshot for each function
+    const routes = [];
+    for (const fn of functions) {
+        try {
+            const typesResult = await (0, api_client_1.listTypes)(fn.id, { env: opts.env, limit: 1 });
+            const snapshot = typesResult.snapshots[0];
+            const returnType = snapshot
+                ? (typeof snapshot.return_type === "string"
+                    ? JSON.parse(snapshot.return_type)
+                    : snapshot.return_type)
+                : null;
+            const argsType = snapshot
+                ? (typeof snapshot.args_type === "string"
+                    ? JSON.parse(snapshot.args_type)
+                    : snapshot.args_type)
+                : null;
+            const { method, path: routePath } = parseRoute(fn.function_name);
+            routes.push({
+                name: fn.function_name,
+                method,
+                path: routePath,
+                module: fn.module,
+                environment: fn.environment,
+                lastSeen: fn.last_seen_at,
+                argsSignature: argsType ? compactSignature(argsType, 60) : "",
+                returnSignature: returnType ? compactSignature(returnType, 60) : "unknown",
+                fieldCount: returnType ? countFields(returnType) : 0,
+            });
+        }
+        catch {
+            // Skip functions with errors
+            const { method, path: routePath } = parseRoute(fn.function_name);
+            routes.push({
+                name: fn.function_name,
+                method,
+                path: routePath,
+                module: fn.module,
+                environment: fn.environment,
+                lastSeen: fn.last_seen_at,
+                argsSignature: "",
+                returnSignature: "?",
+                fieldCount: 0,
+            });
+        }
+    }
+    // JSON output
+    if (opts.json) {
+        console.log(JSON.stringify({ routes, total: routes.length }, null, 2));
+        return;
+    }
+    // Group by module
+    const byModule = new Map();
+    for (const r of routes) {
+        const mod = r.module || "default";
+        if (!byModule.has(mod))
+            byModule.set(mod, []);
+        byModule.get(mod).push(r);
+    }
+    console.log("");
+    console.log(chalk_1.default.bold("  trickle overview"));
+    console.log(chalk_1.default.gray("  " + "─".repeat(60)));
+    console.log(chalk_1.default.gray(`  ${routes.length} route${routes.length === 1 ? "" : "s"} observed`));
+    if (opts.env) {
+        console.log(chalk_1.default.gray(`  Environment: ${opts.env}`));
+    }
+    console.log(chalk_1.default.gray("  " + "─".repeat(60)));
+    // Find the longest method for alignment
+    const maxMethodLen = Math.max(...routes.map((r) => r.method.length));
+    const maxPathLen = Math.min(30, Math.max(...routes.map((r) => r.path.length)));
+    for (const [mod, modRoutes] of byModule) {
+        console.log("");
+        if (byModule.size > 1) {
+            console.log(chalk_1.default.gray(`  ┌─ ${mod}`));
+        }
+        // Sort routes: GET before POST before PUT before DELETE, then by path
+        const methodOrder = { GET: 0, POST: 1, PUT: 2, PATCH: 3, DELETE: 4 };
+        modRoutes.sort((a, b) => {
+            const orderA = methodOrder[a.method] ?? 5;
+            const orderB = methodOrder[b.method] ?? 5;
+            if (orderA !== orderB)
+                return orderA - orderB;
+            return a.path.localeCompare(b.path);
+        });
+        for (const route of modRoutes) {
+            const methodColor = getMethodColor(route.method);
+            const methodStr = route.method.padEnd(maxMethodLen);
+            const pathStr = route.path.padEnd(maxPathLen);
+            const age = (0, helpers_1.relativeTime)(route.lastSeen);
+            // Build the line
+            const prefix = byModule.size > 1 ? "  │ " : "  ";
+            const line = prefix +
+                methodColor(methodStr) +
+                " " +
+                chalk_1.default.white(pathStr) +
+                chalk_1.default.gray(" → ") +
+                chalk_1.default.cyan(route.returnSignature) +
+                chalk_1.default.gray(`  ${age}`);
+            console.log(line);
+            // Show request body if present and non-empty
+            if (route.argsSignature && route.argsSignature !== "{ }") {
+                const argsLine = prefix +
+                    " ".repeat(maxMethodLen) +
+                    " " +
+                    " ".repeat(maxPathLen) +
+                    chalk_1.default.gray(" ← ") +
+                    chalk_1.default.yellow(route.argsSignature);
+                console.log(argsLine);
+            }
+        }
+        if (byModule.size > 1) {
+            console.log(chalk_1.default.gray("  └─"));
+        }
+    }
+    console.log("");
+    const totalFields = routes.reduce((sum, r) => sum + r.fieldCount, 0);
+    console.log(chalk_1.default.gray(`  ${routes.length} routes, ${totalFields} fields observed`) +
+        chalk_1.default.gray(` · ${backendUrl}`));
+    console.log("");
+}
+function parseRoute(functionName) {
+    const spaceIdx = functionName.indexOf(" ");
+    if (spaceIdx > 0) {
+        return {
+            method: functionName.slice(0, spaceIdx),
+            path: functionName.slice(spaceIdx + 1),
+        };
+    }
+    return { method: "", path: functionName };
+}
+function getMethodColor(method) {
+    switch (method) {
+        case "GET": return chalk_1.default.green;
+        case "POST": return chalk_1.default.yellow;
+        case "PUT": return chalk_1.default.blue;
+        case "PATCH": return chalk_1.default.magenta;
+        case "DELETE": return chalk_1.default.red;
+        default: return chalk_1.default.white;
+    }
+}
+/**
+ * Render a compact type signature from a TypeNode.
+ * Truncates to maxLen characters.
+ */
+function compactSignature(node, maxLen) {
+    const sig = renderCompact(node);
+    if (sig.length <= maxLen)
+        return sig;
+    return sig.slice(0, maxLen - 1) + "…";
+}
+function renderCompact(node) {
+    switch (node.kind) {
+        case "primitive":
+            return node.name;
+        case "object": {
+            const props = node.properties;
+            const keys = Object.keys(props);
+            if (keys.length === 0)
+                return "{ }";
+            const parts = [];
+            for (const key of keys) {
+                const val = props[key];
+                const valStr = renderCompactShort(val);
+                parts.push(`${key}: ${valStr}`);
+            }
+            const full = `{ ${parts.join(", ")} }`;
+            if (full.length <= 60)
+                return full;
+            // Truncate: show first few fields
+            let result = "{ ";
+            for (let i = 0; i < parts.length; i++) {
+                if (i > 0)
+                    result += ", ";
+                if (result.length + parts[i].length > 55 && i > 0) {
+                    result += `…+${parts.length - i}`;
+                    break;
+                }
+                result += parts[i];
+            }
+            return result + " }";
+        }
+        case "array": {
+            const element = node.element;
+            return `${renderCompact(element)}[]`;
+        }
+        case "union": {
+            const members = node.members;
+            return members.map(renderCompactShort).join(" | ");
+        }
+        default:
+            return node.kind;
+    }
+}
+function renderCompactShort(node) {
+    switch (node.kind) {
+        case "primitive":
+            return node.name;
+        case "object": {
+            const props = node.properties;
+            const keys = Object.keys(props);
+            if (keys.length === 0)
+                return "{}";
+            if (keys.length <= 3) {
+                return `{${keys.join(", ")}}`;
+            }
+            return `{${keys.slice(0, 2).join(", ")}, …+${keys.length - 2}}`;
+        }
+        case "array":
+            return `${renderCompactShort(node.element)}[]`;
+        case "union": {
+            const members = node.members;
+            return members.map(renderCompactShort).join(" | ");
+        }
+        default:
+            return node.kind;
+    }
+}
+function countFields(node) {
+    if (node.kind === "object") {
+        const props = node.properties;
+        let count = Object.keys(props).length;
+        for (const val of Object.values(props)) {
+            count += countFields(val);
+        }
+        return count;
+    }
+    if (node.kind === "array") {
+        return countFields(node.element);
+    }
+    return 0;
+}

package/dist/commands/pack.d.ts

@@ -0,0 +1,11 @@
+export interface PackOptions {
+    out?: string;
+    env?: string;
+}
+/**
+ * `trickle pack` — Export all observed types as a portable bundle.
+ *
+ * Creates a JSON file containing all functions and their type snapshots
+ * that can be shared, committed to version control, or imported elsewhere.
+ */
+export declare function packCommand(opts: PackOptions): Promise<void>;

package/dist/commands/pack.js

@@ -0,0 +1,133 @@
+"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.packCommand = packCommand;
+const fs = __importStar(require("fs"));
+const chalk_1 = __importDefault(require("chalk"));
+const api_client_1 = require("../api-client");
+const config_1 = require("../config");
+/**
+ * `trickle pack` — Export all observed types as a portable bundle.
+ *
+ * Creates a JSON file containing all functions and their type snapshots
+ * that can be shared, committed to version control, or imported elsewhere.
+ */
+async function packCommand(opts) {
+    const backendUrl = (0, config_1.getBackendUrl)();
+    // Check backend
+    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)}\n`));
+        process.exit(1);
+    }
+    // Use stderr for status when writing JSON to stdout
+    const log = opts.out ? console.log : (...args) => process.stderr.write(args.join(" ") + "\n");
+    log("");
+    log(chalk_1.default.bold("  trickle pack"));
+    log(chalk_1.default.gray("  " + "─".repeat(50)));
+    // Fetch all functions
+    const result = await (0, api_client_1.listFunctions)({ env: opts.env, limit: 10000 });
+    const { functions } = result;
+    if (functions.length === 0) {
+        log(chalk_1.default.yellow("  No observed types to pack."));
+        log(chalk_1.default.gray("  Run ") + chalk_1.default.white("trickle capture") + chalk_1.default.gray(" or ") + chalk_1.default.white("trickle dev") + chalk_1.default.gray(" first.\n"));
+        process.exit(1);
+    }
+    log(chalk_1.default.gray(`  Packing ${functions.length} functions...`));
+    // Fetch snapshots for each function
+    const packedFunctions = [];
+    let totalSnapshots = 0;
+    for (const fn of functions) {
+        const typesResult = await (0, api_client_1.listTypes)(fn.id, { env: opts.env, limit: 100 });
+        const snapshots = [];
+        for (const snap of typesResult.snapshots) {
+            snapshots.push({
+                typeHash: snap.type_hash,
+                env: snap.env,
+                argsType: snap.args_type,
+                returnType: snap.return_type,
+                sampleInput: snap.sample_input || undefined,
+                sampleOutput: snap.sample_output || undefined,
+                observedAt: snap.observed_at,
+            });
+        }
+        if (snapshots.length > 0) {
+            packedFunctions.push({
+                functionName: fn.function_name,
+                module: fn.module,
+                language: fn.language,
+                environment: fn.environment,
+                snapshots,
+            });
+            totalSnapshots += snapshots.length;
+        }
+    }
+    const bundle = {
+        version: 1,
+        createdAt: new Date().toISOString(),
+        source: backendUrl,
+        functions: packedFunctions,
+        stats: {
+            totalFunctions: packedFunctions.length,
+            totalSnapshots,
+        },
+    };
+    const json = JSON.stringify(bundle, null, 2);
+    if (opts.out) {
+        fs.writeFileSync(opts.out, json, "utf-8");
+        log(chalk_1.default.green(`  Packed ${packedFunctions.length} functions (${totalSnapshots} snapshots)`));
+        log(chalk_1.default.gray(`  Written to ${opts.out}`));
+        const sizeKb = (Buffer.byteLength(json, "utf-8") / 1024).toFixed(1);
+        log(chalk_1.default.gray(`  Size: ${sizeKb}KB`));
+        log("");
+        log(chalk_1.default.gray("  Share this file or import it with:"));
+        log(chalk_1.default.white(`  trickle unpack ${opts.out}`));
+        log("");
+    }
+    else {
+        // Write JSON to stdout for piping
+        process.stdout.write(json + "\n");
+        // Summary to stderr
+        log(chalk_1.default.green(`  Packed ${packedFunctions.length} functions (${totalSnapshots} snapshots)`));
+        log("");
+    }
+}

package/dist/commands/proxy.d.ts

@@ -0,0 +1,13 @@
+export interface ProxyOptions {
+    target: string;
+    port?: string;
+}
+/**
+ * `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 declare function proxyCommand(opts: ProxyOptions): Promise<void>;