trickle-cli 0.1.0

package/dist/commands/coverage.js

@@ -0,0 +1,126 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.coverageCommand = coverageCommand;
+const chalk_1 = __importDefault(require("chalk"));
+const config_1 = require("../config");
+/**
+ * `trickle coverage` — Type observation health report.
+ *
+ * Shows per-function type coverage, staleness, variant counts,
+ * error counts, and an overall health score. Useful for CI gates.
+ */
+async function coverageCommand(opts) {
+    const backendUrl = (0, config_1.getBackendUrl)();
+    // Fetch coverage data
+    const url = new URL("/api/coverage", backendUrl);
+    if (opts.env)
+        url.searchParams.set("env", opts.env);
+    if (opts.staleHours)
+        url.searchParams.set("stale_hours", opts.staleHours);
+    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);
+    }
+    // JSON output mode
+    if (opts.json) {
+        console.log(JSON.stringify(data, null, 2));
+        checkThreshold(data.summary.health, opts.failUnder);
+        return;
+    }
+    const { summary, entries } = data;
+    // Header
+    console.log("");
+    console.log(chalk_1.default.bold("  trickle coverage"));
+    console.log(chalk_1.default.gray("  " + "─".repeat(60)));
+    if (opts.env) {
+        console.log(chalk_1.default.gray(`  Environment: ${opts.env}`));
+    }
+    console.log(chalk_1.default.gray(`  Stale threshold: ${summary.staleThresholdHours}h`));
+    console.log(chalk_1.default.gray("  " + "─".repeat(60)));
+    console.log("");
+    if (entries.length === 0) {
+        console.log(chalk_1.default.yellow("  No functions observed yet."));
+        console.log(chalk_1.default.gray("  Instrument your app and make some requests first.\n"));
+        checkThreshold(0, opts.failUnder);
+        return;
+    }
+    // Health score bar
+    const healthColor = summary.health >= 80 ? chalk_1.default.green : summary.health >= 50 ? chalk_1.default.yellow : chalk_1.default.red;
+    const barFilled = Math.round(summary.health / 5);
+    const barEmpty = 20 - barFilled;
+    const healthBar = healthColor("█".repeat(barFilled)) + chalk_1.default.gray("░".repeat(barEmpty));
+    console.log(`  Health: ${healthBar} ${healthColor(chalk_1.default.bold(`${summary.health}%`))}`);
+    console.log("");
+    // Summary stats
+    console.log(chalk_1.default.bold("  Summary"));
+    console.log(`  ${chalk_1.default.cyan(String(summary.total))} functions observed`);
+    console.log(`  ${chalk_1.default.green(String(summary.withTypes))} with types  ${chalk_1.default.gray(`${summary.withoutTypes} without`)}`);
+    console.log(`  ${chalk_1.default.green(String(summary.fresh))} fresh  ${summary.stale > 0 ? chalk_1.default.yellow(`${summary.stale} stale`) : chalk_1.default.gray("0 stale")}`);
+    if (summary.withErrors > 0) {
+        console.log(`  ${chalk_1.default.red(String(summary.withErrors))} with errors`);
+    }
+    if (summary.withMultipleVariants > 0) {
+        console.log(`  ${chalk_1.default.yellow(String(summary.withMultipleVariants))} with multiple type variants`);
+    }
+    console.log("");
+    // Per-function table
+    console.log(chalk_1.default.bold("  Functions"));
+    console.log(chalk_1.default.gray("  " + "─".repeat(60)));
+    for (const entry of entries) {
+        const statusIcon = !entry.hasTypes
+            ? chalk_1.default.red("✗")
+            : entry.isStale
+                ? chalk_1.default.yellow("◦")
+                : chalk_1.default.green("✓");
+        const nameStr = chalk_1.default.bold(entry.functionName);
+        const moduleStr = entry.module !== "api" && entry.module !== "default" ? chalk_1.default.gray(` [${entry.module}]`) : "";
+        const badges = [];
+        if (entry.snapshots > 0)
+            badges.push(chalk_1.default.gray(`${entry.snapshots} snap`));
+        if (entry.variants > 1)
+            badges.push(chalk_1.default.yellow(`${entry.variants} variants`));
+        if (entry.errors > 0)
+            badges.push(chalk_1.default.red(`${entry.errors} err`));
+        if (entry.isStale)
+            badges.push(chalk_1.default.yellow("stale"));
+        const healthStr = entry.health >= 80
+            ? chalk_1.default.green(`${entry.health}%`)
+            : entry.health >= 50
+                ? chalk_1.default.yellow(`${entry.health}%`)
+                : chalk_1.default.red(`${entry.health}%`);
+        console.log(`  ${statusIcon} ${nameStr}${moduleStr}  ${badges.join(" ")}  ${healthStr}`);
+    }
+    console.log(chalk_1.default.gray("  " + "─".repeat(60)));
+    console.log("");
+    checkThreshold(summary.health, opts.failUnder);
+}
+function checkThreshold(health, failUnder) {
+    if (!failUnder)
+        return;
+    const threshold = parseInt(failUnder, 10);
+    if (isNaN(threshold))
+        return;
+    if (health < threshold) {
+        console.error(chalk_1.default.red(`  Coverage health ${health}% is below threshold ${threshold}%`));
+        console.error("");
+        process.exit(1);
+    }
+}

package/dist/commands/dashboard.d.ts

@@ -0,0 +1 @@
+export declare function dashboardCommand(): Promise<void>;

package/dist/commands/dashboard.js

@@ -0,0 +1,83 @@
+"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.dashboardCommand = dashboardCommand;
+const chalk_1 = __importDefault(require("chalk"));
+const config_1 = require("../config");
+async function dashboardCommand() {
+    const backendUrl = (0, config_1.getBackendUrl)();
+    const dashboardUrl = `${backendUrl}/dashboard`;
+    // Check backend is reachable
+    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: cd packages/backend && npm start\n"));
+        process.exit(1);
+    }
+    console.log("");
+    console.log(chalk_1.default.bold("  trickle dashboard"));
+    console.log(chalk_1.default.gray("  " + "─".repeat(50)));
+    console.log(chalk_1.default.gray(`  Opening ${chalk_1.default.bold(dashboardUrl)}`));
+    console.log(chalk_1.default.gray("  " + "─".repeat(50)));
+    console.log("");
+    // Open in browser
+    const { exec } = await Promise.resolve().then(() => __importStar(require("child_process")));
+    const platform = process.platform;
+    let cmd;
+    if (platform === "darwin") {
+        cmd = `open "${dashboardUrl}"`;
+    }
+    else if (platform === "win32") {
+        cmd = `start "" "${dashboardUrl}"`;
+    }
+    else {
+        cmd = `xdg-open "${dashboardUrl}"`;
+    }
+    exec(cmd, (err) => {
+        if (err) {
+            console.log(chalk_1.default.yellow(`  Could not open browser automatically.`));
+            console.log(chalk_1.default.yellow(`  Open this URL manually: ${dashboardUrl}\n`));
+        }
+    });
+    // Keep the process alive briefly so the user sees the message
+    await new Promise((resolve) => setTimeout(resolve, 1000));
+}

package/dist/commands/dev.d.ts

@@ -0,0 +1,14 @@
+export interface DevOptions {
+    port?: string;
+    out?: string;
+    client?: boolean;
+    python?: boolean;
+}
+/**
+ * `trickle dev` — All-in-one development command.
+ *
+ * Starts your app with auto-instrumentation and watches for type changes,
+ * regenerating type files as requests flow through. One command replaces
+ * the 2-terminal setup of `trickle:start` + `trickle:dev`.
+ */
+export declare function devCommand(command: string | undefined, opts: DevOptions): Promise<void>;

package/dist/commands/dev.js

@@ -0,0 +1,319 @@
+"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.devCommand = devCommand;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const child_process_1 = require("child_process");
+const chalk_1 = __importDefault(require("chalk"));
+const config_1 = require("../config");
+const api_client_1 = require("../api-client");
+/**
+ * `trickle dev` — All-in-one development command.
+ *
+ * Starts your app with auto-instrumentation and watches for type changes,
+ * regenerating type files as requests flow through. One command replaces
+ * the 2-terminal setup of `trickle:start` + `trickle:dev`.
+ */
+async function devCommand(command, opts) {
+    const backendUrl = (0, config_1.getBackendUrl)();
+    // Resolve the app command to run
+    const appCommand = resolveAppCommand(command);
+    if (!appCommand) {
+        console.error(chalk_1.default.red("\n  Could not determine app command to run."));
+        console.error(chalk_1.default.gray("  Provide a command: trickle dev \"node app.js\""));
+        console.error(chalk_1.default.gray("  Or ensure package.json has a start or dev script.\n"));
+        process.exit(1);
+    }
+    // Determine output paths
+    const isPython = opts.python === true;
+    const typesOut = opts.out || (isPython ? ".trickle/types.pyi" : ".trickle/types.d.ts");
+    const clientOut = opts.client ? ".trickle/api-client.ts" : undefined;
+    // Ensure .trickle directory exists
+    const trickleDir = path.resolve(".trickle");
+    if (!fs.existsSync(trickleDir)) {
+        fs.mkdirSync(trickleDir, { recursive: true });
+    }
+    // Check backend connectivity
+    const backendReachable = await checkBackend(backendUrl);
+    if (!backendReachable) {
+        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: cd packages/backend && npm start"));
+        console.error(chalk_1.default.gray("  Or set TRICKLE_BACKEND_URL to point to a running backend.\n"));
+        process.exit(1);
+    }
+    // Print header
+    console.log("");
+    console.log(chalk_1.default.bold("  trickle dev"));
+    console.log(chalk_1.default.gray("  " + "─".repeat(50)));
+    console.log(chalk_1.default.gray(`  App command:  ${appCommand}`));
+    console.log(chalk_1.default.gray(`  Backend:      ${backendUrl}`));
+    console.log(chalk_1.default.gray(`  Types output: ${typesOut}`));
+    if (clientOut) {
+        console.log(chalk_1.default.gray(`  Client output: ${clientOut}`));
+    }
+    console.log(chalk_1.default.gray("  " + "─".repeat(50)));
+    console.log("");
+    // Inject -r trickle-observe/register into the command
+    const instrumentedCommand = injectRegister(appCommand);
+    // Start the app process
+    const appProc = startApp(instrumentedCommand, backendUrl);
+    // Start the codegen watcher
+    const stopWatcher = startCodegenWatcher(typesOut, clientOut, isPython);
+    // Handle cleanup
+    let shuttingDown = false;
+    function cleanup() {
+        if (shuttingDown)
+            return;
+        shuttingDown = true;
+        console.log(chalk_1.default.gray("\n  Shutting down..."));
+        stopWatcher();
+        if (!appProc.killed) {
+            appProc.kill("SIGTERM");
+        }
+        // Give processes time to clean up
+        setTimeout(() => {
+            process.exit(0);
+        }, 500);
+    }
+    process.on("SIGINT", cleanup);
+    process.on("SIGTERM", cleanup);
+    appProc.on("exit", (code) => {
+        if (!shuttingDown) {
+            if (code !== null && code !== 0) {
+                console.log(chalk_1.default.red(`\n  App exited with code ${code}`));
+            }
+            else {
+                console.log(chalk_1.default.gray("\n  App exited."));
+            }
+            cleanup();
+        }
+    });
+}
+/**
+ * Resolve the command to run. Checks:
+ * 1. Explicit command argument
+ * 2. package.json scripts.start
+ * 3. package.json scripts.dev
+ */
+function resolveAppCommand(explicitCommand) {
+    if (explicitCommand) {
+        return explicitCommand;
+    }
+    // Try reading package.json
+    const pkgPath = path.resolve("package.json");
+    if (fs.existsSync(pkgPath)) {
+        try {
+            const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf-8"));
+            const scripts = pkg.scripts || {};
+            // Prefer trickle:start if it exists (already instrumented)
+            if (scripts["trickle:start"]) {
+                return scripts["trickle:start"];
+            }
+            if (scripts.start) {
+                return scripts.start;
+            }
+            if (scripts.dev) {
+                return scripts.dev;
+            }
+        }
+        catch {
+            // ignore
+        }
+    }
+    return null;
+}
+/**
+ * Inject `-r trickle-observe/register` into a node/ts-node/nodemon command.
+ * If the command already has it, return as-is.
+ */
+function injectRegister(command) {
+    // Already instrumented
+    if (command.includes("trickle-observe/register") || command.includes("trickle\\register")) {
+        return command;
+    }
+    // Inject -r flag
+    if (/\bnode\s/.test(command)) {
+        return command.replace(/\bnode\s/, "node -r trickle-observe/register ");
+    }
+    if (/\bts-node\s/.test(command)) {
+        return command.replace(/\bts-node\s/, "ts-node -r trickle-observe/register ");
+    }
+    if (/\bnodemon\s/.test(command)) {
+        return command.replace(/\bnodemon\s/, "nodemon -r trickle-observe/register ");
+    }
+    // Can't inject — run as-is with a warning
+    console.log(chalk_1.default.yellow("  Warning: Could not inject -r trickle-observe/register into command."));
+    console.log(chalk_1.default.yellow("  Auto-instrumentation may not work. Consider using:"));
+    console.log(chalk_1.default.yellow(`    node -r trickle-observe/register ${command}\n`));
+    return command;
+}
+/**
+ * Start the app as a child process with environment variables set.
+ */
+function startApp(command, backendUrl) {
+    const parts = command.split(/\s+/);
+    const cmd = parts[0];
+    const args = parts.slice(1);
+    const prefix = chalk_1.default.cyan("[app]");
+    const proc = (0, child_process_1.spawn)(cmd, args, {
+        stdio: ["inherit", "pipe", "pipe"],
+        env: {
+            ...process.env,
+            TRICKLE_BACKEND_URL: backendUrl,
+        },
+        shell: true,
+    });
+    proc.stdout?.on("data", (data) => {
+        const lines = data.toString().split("\n");
+        for (const line of lines) {
+            if (line.trim()) {
+                console.log(`${prefix} ${line}`);
+            }
+        }
+    });
+    proc.stderr?.on("data", (data) => {
+        const lines = data.toString().split("\n");
+        for (const line of lines) {
+            if (line.trim()) {
+                console.error(`${prefix} ${chalk_1.default.red(line)}`);
+            }
+        }
+    });
+    return proc;
+}
+/**
+ * Start a codegen watcher that polls for type changes.
+ * Returns a stop function.
+ */
+function startCodegenWatcher(typesOut, clientOut, isPython) {
+    const prefix = chalk_1.default.magenta("[types]");
+    const language = isPython ? "python" : undefined;
+    let lastTypesContent = "";
+    let lastClientContent = "";
+    let stopped = false;
+    let firstRun = true;
+    // Wait a bit before first poll to let the app start
+    let initialDelay = true;
+    const poll = async () => {
+        if (stopped)
+            return;
+        try {
+            // Generate types
+            const result = await (0, api_client_1.fetchCodegen)({ language });
+            const types = result.types;
+            if (types !== lastTypesContent) {
+                lastTypesContent = types;
+                const resolvedPath = path.resolve(typesOut);
+                const dir = path.dirname(resolvedPath);
+                if (!fs.existsSync(dir)) {
+                    fs.mkdirSync(dir, { recursive: true });
+                }
+                fs.writeFileSync(resolvedPath, types, "utf-8");
+                if (!firstRun) {
+                    const count = countTypes(types);
+                    console.log(`${prefix} ${chalk_1.default.green("Updated")} ${chalk_1.default.bold(typesOut)} ${chalk_1.default.gray(`(${count} types)`)}`);
+                }
+                else {
+                    firstRun = false;
+                }
+            }
+            // Generate client if requested
+            if (clientOut) {
+                const clientResult = await (0, api_client_1.fetchCodegen)({ format: "client" });
+                if (clientResult.types !== lastClientContent) {
+                    lastClientContent = clientResult.types;
+                    const resolvedPath = path.resolve(clientOut);
+                    const dir = path.dirname(resolvedPath);
+                    if (!fs.existsSync(dir)) {
+                        fs.mkdirSync(dir, { recursive: true });
+                    }
+                    fs.writeFileSync(resolvedPath, clientResult.types, "utf-8");
+                    if (!firstRun) {
+                        console.log(`${prefix} ${chalk_1.default.green("Updated")} ${chalk_1.default.bold(clientOut)}`);
+                    }
+                }
+            }
+        }
+        catch {
+            // Backend might not be ready yet or app hasn't served requests — silently retry
+            if (!initialDelay) {
+                // Only log after initial startup period
+            }
+        }
+        initialDelay = false;
+    };
+    // First poll after 3s (give app time to start), then every 3s
+    const startTimeout = setTimeout(() => {
+        poll();
+        const interval = setInterval(poll, 3000);
+        // Store interval for cleanup
+        startTimeout.__interval = interval;
+    }, 3000);
+    let intervalRef = null;
+    // Use a different approach: start polling immediately with setInterval
+    const interval = setInterval(async () => {
+        if (stopped)
+            return;
+        await poll();
+    }, 3000);
+    intervalRef = interval;
+    // Initial poll after 2s delay
+    const initTimer = setTimeout(poll, 2000);
+    return () => {
+        stopped = true;
+        clearTimeout(startTimeout);
+        clearTimeout(initTimer);
+        if (intervalRef)
+            clearInterval(intervalRef);
+    };
+}
+function countTypes(code) {
+    const tsMatches = code.match(/export (interface|type) /g);
+    const pyMatches = code.match(/class \w+\(TypedDict\)/g);
+    return (tsMatches?.length ?? 0) + (pyMatches?.length ?? 0);
+}
+async function checkBackend(url) {
+    try {
+        const res = await fetch(`${url}/api/health`, { signal: AbortSignal.timeout(3000) });
+        return res.ok;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/commands/diff.d.ts

@@ -0,0 +1,7 @@
+export interface DiffOptions {
+    since?: string;
+    env?: string;
+    env1?: string;
+    env2?: string;
+}
+export declare function diffCommand(opts: DiffOptions): Promise<void>;

package/dist/commands/diff.js

@@ -0,0 +1,79 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.diffCommand = diffCommand;
+const chalk_1 = __importDefault(require("chalk"));
+const api_client_1 = require("../api-client");
+const diff_formatter_1 = require("../formatters/diff-formatter");
+const badges_1 = require("../ui/badges");
+const helpers_1 = require("../ui/helpers");
+async function diffCommand(opts) {
+    try {
+        // Parse --since into a datetime string for the backend
+        let sinceStr;
+        if (opts.since) {
+            sinceStr = (0, helpers_1.parseSince)(opts.since);
+        }
+        const result = await (0, api_client_1.fetchDiffReport)({
+            since: sinceStr,
+            env: opts.env,
+            env1: opts.env1,
+            env2: opts.env2,
+        });
+        console.log("");
+        if (result.mode === "cross-env") {
+            console.log(chalk_1.default.white.bold("  Type drift: ") +
+                (0, badges_1.envBadge)(result.env1) +
+                chalk_1.default.gray(" → ") +
+                (0, badges_1.envBadge)(result.env2));
+        }
+        else {
+            const label = opts.since
+                ? `changes in the last ${opts.since}`
+                : "all type changes";
+            console.log(chalk_1.default.white.bold(`  Type drift: ${label}`));
+            if (opts.env) {
+                console.log(chalk_1.default.gray(`  Environment: ${opts.env}`));
+            }
+        }
+        console.log(chalk_1.default.gray("  " + "─".repeat(50)));
+        if (result.total === 0) {
+            console.log("");
+            console.log(chalk_1.default.green("  No type drift detected."));
+            if (opts.since) {
+                console.log(chalk_1.default.gray(`  No functions had type changes in the last ${opts.since}.`));
+            }
+            console.log("");
+            return;
+        }
+        console.log(chalk_1.default.gray(`  ${result.total} function${result.total === 1 ? "" : "s"} with type changes`));
+        for (const entry of result.entries) {
+            console.log("");
+            console.log(chalk_1.default.white.bold(`  ${entry.functionName}`) +
+                chalk_1.default.gray(` (${entry.module})`));
+            // Show from/to metadata
+            console.log(chalk_1.default.gray("    from: ") +
+                (0, badges_1.envBadge)(entry.from.env) +
+                chalk_1.default.gray("  " + (0, badges_1.timeBadge)(entry.from.observed_at)));
+            console.log(chalk_1.default.gray("    to:   ") +
+                (0, badges_1.envBadge)(entry.to.env) +
+                chalk_1.default.gray("  " + (0, badges_1.timeBadge)(entry.to.observed_at)));
+            console.log("");
+            // Indent diffs by 2 extra spaces
+            const formattedDiffs = (0, diff_formatter_1.formatDiffs)(entry.diffs);
+            const indented = formattedDiffs
+                .split("\n")
+                .map((line) => "  " + line)
+                .join("\n");
+            console.log(indented);
+        }
+        console.log("");
+    }
+    catch (err) {
+        if (err instanceof Error) {
+            console.error(chalk_1.default.red(`\n  Error: ${err.message}\n`));
+        }
+    }
+}

package/dist/commands/docs.d.ts

@@ -0,0 +1,13 @@
+export interface DocsOptions {
+    out?: string;
+    html?: boolean;
+    env?: string;
+    title?: string;
+}
+/**
+ * `trickle docs` — Generate API documentation from observed runtime types.
+ *
+ * Produces clean Markdown (or self-contained HTML) documenting every
+ * observed API route with request/response types and example payloads.
+ */
+export declare function docsCommand(opts: DocsOptions): Promise<void>;