trickle-cli 0.1.0

package/dist/commands/sample.d.ts

@@ -0,0 +1,13 @@
+export interface SampleOptions {
+    format?: string;
+    out?: string;
+    route?: string;
+}
+/**
+ * `trickle sample` — Generate test fixtures from observed runtime data.
+ *
+ * Produces JSON, TypeScript constants, or factory functions from the
+ * actual sample inputs and outputs captured by trickle. Great for tests,
+ * seed scripts, and Storybook data.
+ */
+export declare function sampleCommand(routeFilter: string | undefined, opts: SampleOptions): Promise<void>;

package/dist/commands/sample.js

@@ -0,0 +1,260 @@
+"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.sampleCommand = sampleCommand;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const chalk_1 = __importDefault(require("chalk"));
+const api_client_1 = require("../api-client");
+/**
+ * `trickle sample` — Generate test fixtures from observed runtime data.
+ *
+ * Produces JSON, TypeScript constants, or factory functions from the
+ * actual sample inputs and outputs captured by trickle. Great for tests,
+ * seed scripts, and Storybook data.
+ */
+async function sampleCommand(routeFilter, opts) {
+    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);
+    }
+    // Filter routes
+    if (routeFilter) {
+        const filter = routeFilter.toLowerCase();
+        routes = routes.filter((r) => r.functionName.toLowerCase().includes(filter) ||
+            r.path.toLowerCase().includes(filter));
+    }
+    // Only include routes with sample data
+    routes = routes.filter((r) => r.sampleOutput !== null && r.sampleOutput !== undefined);
+    if (routes.length === 0) {
+        console.error(chalk_1.default.yellow("\n  No sample data found."));
+        if (routeFilter) {
+            console.error(chalk_1.default.gray(`  No routes matching "${routeFilter}" with sample data.\n`));
+        }
+        else {
+            console.error(chalk_1.default.gray("  Instrument your app and make some requests first.\n"));
+        }
+        process.exit(0);
+    }
+    const format = (opts.format || "json").toLowerCase();
+    let output;
+    switch (format) {
+        case "json":
+            output = generateJson(routes);
+            break;
+        case "ts":
+        case "typescript":
+            output = generateTypeScript(routes);
+            break;
+        case "factory":
+            output = generateFactories(routes);
+            break;
+        default:
+            console.error(chalk_1.default.red(`\n  Unknown format: ${format}`));
+            console.error(chalk_1.default.gray("  Supported: json, ts, factory\n"));
+            process.exit(1);
+    }
+    if (opts.out) {
+        const resolvedPath = path.resolve(opts.out);
+        const dir = path.dirname(resolvedPath);
+        if (!fs.existsSync(dir)) {
+            fs.mkdirSync(dir, { recursive: true });
+        }
+        fs.writeFileSync(resolvedPath, output, "utf-8");
+        console.log(chalk_1.default.green(`\n  Fixtures written to ${chalk_1.default.bold(opts.out)}`));
+        console.log(chalk_1.default.gray(`  ${routes.length} routes, format: ${format}\n`));
+    }
+    else {
+        console.log(output);
+    }
+}
+function toPascalCase(name) {
+    return name
+        .replace(/[^a-zA-Z0-9]+/g, " ")
+        .split(/\s+/)
+        .map((w) => w.charAt(0).toUpperCase() + w.slice(1).toLowerCase())
+        .join("");
+}
+function toCamelCase(name) {
+    const pascal = toPascalCase(name);
+    return pascal.charAt(0).toLowerCase() + pascal.slice(1);
+}
+// ── JSON format ──
+function generateJson(routes) {
+    const samples = {};
+    for (const route of routes) {
+        const key = `${route.method} ${route.path}`;
+        const entry = {
+            response: route.sampleOutput,
+        };
+        if (route.sampleInput) {
+            const input = route.sampleInput;
+            const body = input.body || input;
+            if (body && typeof body === "object" && Object.keys(body).length > 0) {
+                entry.request = body;
+            }
+        }
+        samples[key] = entry;
+    }
+    return JSON.stringify(samples, null, 2) + "\n";
+}
+// ── TypeScript constants ──
+function generateTypeScript(routes) {
+    const lines = [];
+    lines.push("// Auto-generated test fixtures by trickle");
+    lines.push(`// Generated at ${new Date().toISOString()}`);
+    lines.push("// Do not edit manually — re-run `trickle sample --format ts` to update");
+    lines.push("");
+    for (const route of routes) {
+        const varName = toCamelCase(route.functionName);
+        // Response sample
+        lines.push(`/** Sample response for ${route.method} ${route.path} */`);
+        lines.push(`export const ${varName}Response = ${formatValue(route.sampleOutput, 0)} as const;`);
+        lines.push("");
+        // Request body sample (for POST/PUT/PATCH)
+        if (["POST", "PUT", "PATCH"].includes(route.method) && route.sampleInput) {
+            const input = route.sampleInput;
+            const body = input.body || input;
+            if (body && typeof body === "object" && Object.keys(body).length > 0) {
+                lines.push(`/** Sample request body for ${route.method} ${route.path} */`);
+                lines.push(`export const ${varName}Request = ${formatValue(body, 0)} as const;`);
+                lines.push("");
+            }
+        }
+    }
+    return lines.join("\n").trimEnd() + "\n";
+}
+// ── Factory functions ──
+function generateFactories(routes) {
+    const lines = [];
+    lines.push("// Auto-generated test fixture factories by trickle");
+    lines.push(`// Generated at ${new Date().toISOString()}`);
+    lines.push("// Do not edit manually — re-run `trickle sample --format factory` to update");
+    lines.push("");
+    // First emit the base samples as constants
+    for (const route of routes) {
+        const varName = toCamelCase(route.functionName);
+        lines.push(`const _${varName}Response = ${formatValue(route.sampleOutput, 0)};`);
+        lines.push("");
+        if (["POST", "PUT", "PATCH"].includes(route.method) && route.sampleInput) {
+            const input = route.sampleInput;
+            const body = input.body || input;
+            if (body && typeof body === "object" && Object.keys(body).length > 0) {
+                lines.push(`const _${varName}Request = ${formatValue(body, 0)};`);
+                lines.push("");
+            }
+        }
+    }
+    // Then emit factory functions
+    for (const route of routes) {
+        const varName = toCamelCase(route.functionName);
+        const typeName = toPascalCase(route.functionName);
+        // Response factory
+        if (route.sampleOutput && typeof route.sampleOutput === "object" && !Array.isArray(route.sampleOutput)) {
+            lines.push(`/** Create a test fixture for ${route.method} ${route.path} response */`);
+            lines.push(`export function create${typeName}Response(overrides?: Partial<typeof _${varName}Response>): typeof _${varName}Response {`);
+            lines.push(`  return { ..._${varName}Response, ...overrides };`);
+            lines.push(`}`);
+            lines.push("");
+        }
+        else {
+            // For non-object responses (arrays, primitives), just export the constant
+            lines.push(`/** Sample response for ${route.method} ${route.path} */`);
+            lines.push(`export const ${varName}Response = _${varName}Response;`);
+            lines.push("");
+        }
+        // Request body factory
+        if (["POST", "PUT", "PATCH"].includes(route.method) && route.sampleInput) {
+            const input = route.sampleInput;
+            const body = input.body || input;
+            if (body && typeof body === "object" && !Array.isArray(body) && Object.keys(body).length > 0) {
+                lines.push(`/** Create a test fixture for ${route.method} ${route.path} request body */`);
+                lines.push(`export function create${typeName}Request(overrides?: Partial<typeof _${varName}Request>): typeof _${varName}Request {`);
+                lines.push(`  return { ..._${varName}Request, ...overrides };`);
+                lines.push(`}`);
+                lines.push("");
+            }
+        }
+    }
+    return lines.join("\n").trimEnd() + "\n";
+}
+// ── Value formatting ──
+function formatValue(value, indent) {
+    const pad = "  ".repeat(indent);
+    const innerPad = "  ".repeat(indent + 1);
+    if (value === null)
+        return "null";
+    if (value === undefined)
+        return "undefined";
+    switch (typeof value) {
+        case "string":
+            return JSON.stringify(value);
+        case "number":
+        case "boolean":
+            return String(value);
+    }
+    if (Array.isArray(value)) {
+        if (value.length === 0)
+            return "[]";
+        if (value.length === 1 && typeof value[0] !== "object") {
+            return `[${formatValue(value[0], 0)}]`;
+        }
+        const items = value.map((v) => `${innerPad}${formatValue(v, indent + 1)}`);
+        return `[\n${items.join(",\n")}\n${pad}]`;
+    }
+    if (typeof value === "object") {
+        const obj = value;
+        const keys = Object.keys(obj);
+        if (keys.length === 0)
+            return "{}";
+        const entries = keys.map((key) => {
+            const formattedVal = formatValue(obj[key], indent + 1);
+            // Use identifier-safe keys without quotes, quoted otherwise
+            const safeKey = /^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(key) ? key : JSON.stringify(key);
+            return `${innerPad}${safeKey}: ${formattedVal}`;
+        });
+        return `{\n${entries.join(",\n")}\n${pad}}`;
+    }
+    return JSON.stringify(value);
+}

package/dist/commands/search.d.ts

@@ -0,0 +1,5 @@
+export interface SearchOptions {
+    env?: string;
+    json?: boolean;
+}
+export declare function searchCommand(query: string, opts: SearchOptions): Promise<void>;

package/dist/commands/search.js

@@ -0,0 +1,80 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.searchCommand = searchCommand;
+const chalk_1 = __importDefault(require("chalk"));
+const config_1 = require("../config");
+async function searchCommand(query, opts) {
+    const backendUrl = (0, config_1.getBackendUrl)();
+    const url = new URL("/api/search", backendUrl);
+    url.searchParams.set("q", query);
+    if (opts.env) {
+        url.searchParams.set("env", opts.env);
+    }
+    let data;
+    try {
+        const res = await fetch(url.toString());
+        if (!res.ok) {
+            const body = await res.text();
+            throw new Error(`HTTP ${res.status}: ${body}`);
+        }
+        data = await res.json();
+    }
+    catch (err) {
+        if (err instanceof Error && err.message.startsWith("HTTP ")) {
+            console.error(chalk_1.default.red(`\n  Error: ${err.message}\n`));
+        }
+        else {
+            console.error(chalk_1.default.red(`\n  Cannot connect to trickle backend at ${chalk_1.default.bold(backendUrl)}.`));
+            console.error(chalk_1.default.red("  Is the backend running?\n"));
+        }
+        process.exit(1);
+    }
+    if (opts.json) {
+        console.log(JSON.stringify(data, null, 2));
+        return;
+    }
+    console.log("");
+    console.log(chalk_1.default.bold(`  Search: "${query}"`));
+    console.log(chalk_1.default.gray("  " + "─".repeat(50)));
+    if (data.total === 0) {
+        console.log(chalk_1.default.gray("  No matches found.\n"));
+        return;
+    }
+    console.log(chalk_1.default.gray(`  ${data.total} function${data.total === 1 ? "" : "s"} matched\n`));
+    for (const result of data.results) {
+        // Function name with method coloring
+        const fnName = result.functionName;
+        const methodMatch = fnName.match(/^(GET|POST|PUT|PATCH|DELETE)\s/);
+        if (methodMatch) {
+            const method = methodMatch[1];
+            const rest = fnName.slice(method.length);
+            const methodColors = {
+                GET: chalk_1.default.green,
+                POST: chalk_1.default.yellow,
+                PUT: chalk_1.default.blue,
+                PATCH: chalk_1.default.cyan,
+                DELETE: chalk_1.default.red,
+            };
+            const colorFn = methodColors[method] || chalk_1.default.white;
+            console.log(`  ${colorFn(chalk_1.default.bold(method))}${chalk_1.default.white(rest)}`);
+        }
+        else {
+            console.log(`  ${chalk_1.default.white(chalk_1.default.bold(fnName))}`);
+        }
+        console.log(chalk_1.default.gray(`  module: ${result.module}  env: ${result.environment}`));
+        // Show matching fields
+        for (const match of result.matches) {
+            const typeStr = match.typeName ? chalk_1.default.cyan(match.typeName) : chalk_1.default.gray(match.kind);
+            if (match.kind === "name") {
+                console.log(chalk_1.default.gray("    → ") + chalk_1.default.yellow("function name match"));
+            }
+            else {
+                console.log(chalk_1.default.gray("    → ") + chalk_1.default.white(match.path) + chalk_1.default.gray(": ") + typeStr);
+            }
+        }
+        console.log("");
+    }
+}

package/dist/commands/stubs.d.ts

@@ -0,0 +1,6 @@
+export interface StubsOptions {
+    env?: string;
+    dryRun?: boolean;
+    silent?: boolean;
+}
+export declare function stubsCommand(dir: string, opts: StubsOptions): Promise<void>;

package/dist/commands/stubs.js

@@ -0,0 +1,187 @@
+"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.stubsCommand = stubsCommand;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const chalk_1 = __importDefault(require("chalk"));
+const api_client_1 = require("../api-client");
+/**
+ * Map of file extensions to their stub extension.
+ */
+const JS_EXTS = new Set([".js", ".jsx", ".mjs", ".cjs", ".ts", ".tsx"]);
+const PY_EXTS = new Set([".py"]);
+/**
+ * Normalize a module name for matching against file stems.
+ * Module names from trickle may use dashes or underscores.
+ * File stems use whatever the OS has.
+ */
+function normalizeForMatch(name) {
+    return name.replace(/[-_]/g, "").toLowerCase();
+}
+/**
+ * Recursively find all source files in a directory.
+ */
+function findSourceFiles(dir) {
+    const results = [];
+    const entries = fs.readdirSync(dir, { withFileTypes: true });
+    for (const entry of entries) {
+        const fullPath = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+            // Skip node_modules, __pycache__, .git, etc.
+            if (entry.name === "node_modules" ||
+                entry.name === "__pycache__" ||
+                entry.name === ".git" ||
+                entry.name === "dist" ||
+                entry.name === "build" ||
+                entry.name === ".trickle") {
+                continue;
+            }
+            results.push(...findSourceFiles(fullPath));
+        }
+        else if (entry.isFile()) {
+            const ext = path.extname(entry.name).toLowerCase();
+            if (JS_EXTS.has(ext) || PY_EXTS.has(ext)) {
+                results.push(fullPath);
+            }
+        }
+    }
+    return results;
+}
+async function stubsCommand(dir, opts) {
+    const targetDir = path.resolve(dir);
+    if (!fs.existsSync(targetDir)) {
+        console.error(chalk_1.default.red(`\n  Directory not found: ${targetDir}\n`));
+        process.exit(1);
+    }
+    if (!fs.statSync(targetDir).isDirectory()) {
+        console.error(chalk_1.default.red(`\n  Not a directory: ${targetDir}\n`));
+        process.exit(1);
+    }
+    // Fetch per-module stubs from backend
+    const { stubs } = await (0, api_client_1.fetchStubs)({ env: opts.env });
+    if (!stubs || Object.keys(stubs).length === 0) {
+        if (!opts.silent) {
+            console.log(chalk_1.default.yellow("\n  No observed types found. Run your code with trickle first.\n"));
+        }
+        return;
+    }
+    // Find all source files in the target directory
+    const sourceFiles = findSourceFiles(targetDir);
+    if (sourceFiles.length === 0) {
+        if (!opts.silent) {
+            console.log(chalk_1.default.yellow(`\n  No source files found in ${targetDir}\n`));
+        }
+        return;
+    }
+    // Build a map: normalized stem → source file path
+    const fileMap = new Map();
+    for (const filePath of sourceFiles) {
+        const ext = path.extname(filePath);
+        const stem = path.basename(filePath, ext);
+        const key = normalizeForMatch(stem);
+        if (!fileMap.has(key))
+            fileMap.set(key, []);
+        fileMap.get(key).push(filePath);
+    }
+    const written = [];
+    const writtenPaths = new Set();
+    const skipped = [];
+    for (const [moduleName, moduleStubs] of Object.entries(stubs)) {
+        const normalizedModule = normalizeForMatch(moduleName);
+        // Find matching source files
+        const matchingFiles = fileMap.get(normalizedModule);
+        if (!matchingFiles || matchingFiles.length === 0) {
+            skipped.push(moduleName);
+            continue;
+        }
+        for (const sourceFile of matchingFiles) {
+            const ext = path.extname(sourceFile).toLowerCase();
+            const isPython = PY_EXTS.has(ext);
+            const stubContent = isPython ? moduleStubs.python : moduleStubs.ts;
+            const stubExt = isPython ? ".pyi" : ".d.ts";
+            // Generate stub file path next to source file
+            const sourceDir = path.dirname(sourceFile);
+            const sourceStem = path.basename(sourceFile, ext);
+            const stubPath = path.join(sourceDir, `${sourceStem}${stubExt}`);
+            // Skip if already written (multiple modules may normalize to same name)
+            if (writtenPaths.has(stubPath))
+                continue;
+            writtenPaths.add(stubPath);
+            if (opts.dryRun) {
+                const relPath = path.relative(process.cwd(), stubPath);
+                console.log(chalk_1.default.cyan(`  Would create: ${relPath}`));
+                console.log(chalk_1.default.gray(`    (from module "${moduleName}" → ${path.basename(sourceFile)})`));
+                written.push(relPath);
+                continue;
+            }
+            // Write stub file
+            fs.writeFileSync(stubPath, stubContent, "utf-8");
+            const relPath = path.relative(process.cwd(), stubPath);
+            written.push(relPath);
+        }
+    }
+    // Output summary
+    if (opts.silent)
+        return;
+    console.log();
+    if (opts.dryRun) {
+        console.log(chalk_1.default.cyan("  Dry run — no files written.\n"));
+        if (written.length > 0) {
+            console.log(chalk_1.default.gray(`  ${written.length} stub file(s) would be created.\n`));
+        }
+    }
+    else if (written.length > 0) {
+        console.log(chalk_1.default.green(`  Generated ${written.length} type stub file(s):\n`));
+        for (const f of written) {
+            console.log(chalk_1.default.gray(`    ${f}`));
+        }
+        console.log();
+        console.log(chalk_1.default.gray("  Your IDE should now pick up these types automatically."));
+        console.log(chalk_1.default.gray("  Add *.d.ts / *.pyi to .gitignore if you don't want to commit them."));
+        console.log();
+    }
+    else {
+        console.log(chalk_1.default.yellow("  No matching source files found for observed modules.\n"));
+        if (skipped.length > 0) {
+            console.log(chalk_1.default.gray(`  Observed modules: ${skipped.join(", ")}`));
+            console.log(chalk_1.default.gray(`  Source files in: ${path.relative(process.cwd(), targetDir) || "."}`));
+            console.log(chalk_1.default.gray("  Make sure module names match file names (e.g., module 'helpers' → helpers.js)\n"));
+        }
+    }
+}

package/dist/commands/tail.d.ts

@@ -0,0 +1,4 @@
+export interface TailOptions {
+    filter?: string;
+}
+export declare function tailCommand(opts: TailOptions): Promise<void>;

package/dist/commands/tail.js

@@ -0,0 +1,76 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.tailCommand = tailCommand;
+const chalk_1 = __importDefault(require("chalk"));
+const api_client_1 = require("../api-client");
+const badges_1 = require("../ui/badges");
+const config_1 = require("../config");
+function eventBadge(event) {
+    const lower = event.toLowerCase();
+    if (lower === "error" || lower.includes("error")) {
+        return chalk_1.default.bgRed.white.bold(" ERROR ");
+    }
+    if (lower === "new_type" || lower.includes("new")) {
+        return chalk_1.default.bgGreen.black.bold(" NEW_TYPE ");
+    }
+    if (lower === "type_changed" || lower.includes("changed")) {
+        return chalk_1.default.bgYellow.black.bold(" TYPE_CHANGED ");
+    }
+    if (lower === "ingest" || lower.includes("ingest")) {
+        return chalk_1.default.bgBlue.white.bold(" INGEST ");
+    }
+    return chalk_1.default.bgGray.white.bold(` ${event.toUpperCase()} `);
+}
+function formatEventDetail(event) {
+    const data = event.data;
+    const parts = [];
+    if (data.functionName) {
+        parts.push(chalk_1.default.white.bold(String(data.functionName)));
+    }
+    if (data.module) {
+        parts.push(chalk_1.default.gray(`(${data.module})`));
+    }
+    if (data.env) {
+        parts.push((0, badges_1.envBadge)(String(data.env)));
+    }
+    if (data.error && typeof data.error === "object") {
+        const err = data.error;
+        if (err.message) {
+            parts.push(chalk_1.default.red(String(err.message)));
+        }
+    }
+    if (data.error_message) {
+        parts.push(chalk_1.default.red(String(data.error_message)));
+    }
+    return parts.join("  ");
+}
+async function tailCommand(opts) {
+    const url = (0, config_1.getBackendUrl)();
+    console.log(chalk_1.default.gray(`\n  Connecting to trickle at ${url}...`));
+    const cleanup = (0, api_client_1.tailEvents)((event) => {
+        const now = new Date().toISOString();
+        const timeStr = chalk_1.default.gray(now.replace(/T/, " ").replace(/\..+/, ""));
+        const badge = eventBadge(event.event);
+        const detail = formatEventDetail(event);
+        console.log(`  ${timeStr}  ${badge}  ${detail}`);
+    }, opts.filter);
+    // Give it a moment to connect, then show the listening message
+    setTimeout(() => {
+        console.log(chalk_1.default.green("  Listening for events...") + chalk_1.default.gray(" (Ctrl+C to stop)\n"));
+    }, 500);
+    // Keep the process alive and handle graceful shutdown
+    const onSignal = () => {
+        console.log(chalk_1.default.gray("\n  Disconnected.\n"));
+        cleanup();
+        process.exit(0);
+    };
+    process.on("SIGINT", onSignal);
+    process.on("SIGTERM", onSignal);
+    // Keep the event loop alive
+    await new Promise(() => {
+        // Never resolves — the process stays alive until killed
+    });
+}

package/dist/commands/test-gen.d.ts

@@ -0,0 +1,13 @@
+export interface TestGenOptions {
+    out?: string;
+    framework?: string;
+    baseUrl?: string;
+}
+/**
+ * `trickle test --generate` — Generate API test files from runtime observations.
+ *
+ * Uses real sample request/response data captured at runtime to generate
+ * ready-to-run test files with correct endpoints, request bodies, and
+ * response shape assertions.
+ */
+export declare function testGenCommand(opts: TestGenOptions): Promise<void>;