trickle-cli 0.1.0

package/dist/commands/run.js

@@ -0,0 +1,997 @@
+"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.runCommand = runCommand;
+const path = __importStar(require("path"));
+const fs = __importStar(require("fs"));
+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");
+function loadProjectConfig() {
+    const configNames = [".tricklerc.json", ".tricklerc", "trickle.config.json"];
+    for (const name of configNames) {
+        const p = path.resolve(name);
+        if (fs.existsSync(p)) {
+            try {
+                return JSON.parse(fs.readFileSync(p, "utf-8"));
+            }
+            catch {
+                return null;
+            }
+        }
+    }
+    // Also check package.json "trickle" field
+    const pkgPath = path.resolve("package.json");
+    if (fs.existsSync(pkgPath)) {
+        try {
+            const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf-8"));
+            if (pkg.trickle && typeof pkg.trickle === "object") {
+                return pkg.trickle;
+            }
+        }
+        catch {
+            // ignore
+        }
+    }
+    return null;
+}
+function mergeConfigWithOpts(opts, config) {
+    if (!config)
+        return opts;
+    const merged = { ...opts };
+    // CLI flags override config
+    if (!merged.stubs && config.stubs) {
+        merged.stubs = config.stubs;
+    }
+    if (!merged.annotate && config.annotate) {
+        // If array, join first item (run --annotate takes a single path)
+        merged.annotate = Array.isArray(config.annotate)
+            ? config.annotate[0]
+            : config.annotate;
+    }
+    if (!merged.include && config.include) {
+        merged.include = Array.isArray(config.include)
+            ? config.include.join(",")
+            : config.include;
+    }
+    if (!merged.exclude && config.exclude) {
+        merged.exclude = Array.isArray(config.exclude)
+            ? config.exclude.join(",")
+            : config.exclude;
+    }
+    return merged;
+}
+// ── Detect if command is a single source file ──
+function detectSingleFile(command) {
+    const trimmed = command.trim();
+    // Must be a single token (no spaces unless quoted)
+    if (/\s/.test(trimmed))
+        return null;
+    const ext = path.extname(trimmed).toLowerCase();
+    if (![".js", ".ts", ".tsx", ".jsx", ".mjs", ".cjs", ".mts", ".py"].includes(ext)) {
+        return null;
+    }
+    const resolved = path.resolve(trimmed);
+    if (!fs.existsSync(resolved))
+        return null;
+    return resolved;
+}
+// ── Auto-detect runtime from file extension ──
+function autoDetectCommand(input) {
+    // If it already starts with a known runtime, return as-is
+    if (/^(node|ts-node|tsx|nodemon|bun|deno|python3?|python3?\.\d+|vitest|jest|mocha|npx|bunx|pytest|uvicorn|gunicorn|flask|django-admin)\b/.test(input)) {
+        return input;
+    }
+    // Check if the first token is a file path
+    const parts = input.split(/\s+/);
+    const file = parts[0];
+    const rest = parts.slice(1).join(" ");
+    const ext = path.extname(file).toLowerCase();
+    // Resolve relative to cwd
+    const resolved = path.resolve(file);
+    const fileExists = fs.existsSync(resolved);
+    if (!fileExists) {
+        // Not a file — might be a custom command, return as-is
+        return input;
+    }
+    switch (ext) {
+        case ".js":
+        case ".cjs":
+            return rest ? `node ${file} ${rest}` : `node ${file}`;
+        case ".mjs":
+            return rest ? `node ${file} ${rest}` : `node ${file}`;
+        case ".ts":
+        case ".tsx":
+        case ".mts": {
+            // Find best available TS runtime
+            const tsRunner = findTsRunner();
+            return rest ? `${tsRunner} ${file} ${rest}` : `${tsRunner} ${file}`;
+        }
+        case ".py":
+            return rest ? `python ${file} ${rest}` : `python ${file}`;
+        default:
+            return input;
+    }
+}
+function findTsRunner() {
+    // Check for tsx (fastest, most compatible)
+    try {
+        const { execSync } = require("child_process");
+        execSync("tsx --version", { stdio: "ignore" });
+        return "tsx";
+    }
+    catch {
+        // not available
+    }
+    // Check for ts-node
+    try {
+        const { execSync } = require("child_process");
+        execSync("ts-node --version", { stdio: "ignore" });
+        return "ts-node";
+    }
+    catch {
+        // not available
+    }
+    // Check for bun (supports TS natively)
+    try {
+        const { execSync } = require("child_process");
+        execSync("bun --version", { stdio: "ignore" });
+        return "bun";
+    }
+    catch {
+        // not available
+    }
+    // Fallback to npx tsx
+    return "npx tsx";
+}
+/**
+ * `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.
+ */
+async function runCommand(command, opts) {
+    if (!command) {
+        console.error(chalk_1.default.red("\n  Usage: trickle run <command>\n"));
+        console.error(chalk_1.default.gray("  Examples:"));
+        console.error(chalk_1.default.gray('    trickle run "node app.js"'));
+        console.error(chalk_1.default.gray("    trickle run app.ts              # auto-detects TypeScript runtime"));
+        console.error(chalk_1.default.gray("    trickle run script.py            # auto-detects Python"));
+        console.error(chalk_1.default.gray('    trickle run "node app.js" --stubs src/'));
+        console.error(chalk_1.default.gray("    trickle run app.js --watch       # watch for changes and re-run"));
+        console.error("");
+        process.exit(1);
+    }
+    // Load project config
+    const config = loadProjectConfig();
+    opts = mergeConfigWithOpts(opts, config);
+    // Detect if command is a single file — if so, auto-generate sidecar types
+    const singleFile = detectSingleFile(command);
+    // Auto-detect runtime from file extension
+    const resolvedCommand = autoDetectCommand(command);
+    const backendUrl = (0, config_1.getBackendUrl)();
+    // Auto-start backend if not running — fall back to local mode
+    let backendProc = null;
+    let localMode = false;
+    const backendRunning = await checkBackend(backendUrl);
+    if (!backendRunning) {
+        // Only try auto-start if using default URL (custom URL means user manages their own backend)
+        const isCustomUrl = !!process.env.TRICKLE_BACKEND_URL &&
+            process.env.TRICKLE_BACKEND_URL !== "http://localhost:4888";
+        if (!isCustomUrl) {
+            backendProc = await autoStartBackend();
+        }
+        if (!backendProc) {
+            // Fall back to local/offline mode instead of exiting
+            localMode = true;
+            console.log(chalk_1.default.yellow(`\n  Backend not available — using local mode (offline)`));
+            console.log(chalk_1.default.gray("  Observations will be saved to .trickle/observations.jsonl"));
+        }
+    }
+    // Detect language and inject instrumentation
+    const { instrumentedCommand, env: extraEnv } = injectObservation(resolvedCommand, backendUrl, opts);
+    // Print header
+    console.log("");
+    console.log(chalk_1.default.bold(opts.watch ? "  trickle run --watch" : "  trickle run"));
+    console.log(chalk_1.default.gray("  " + "─".repeat(50)));
+    if (resolvedCommand !== command) {
+        console.log(chalk_1.default.gray(`  File:      ${command}`));
+        console.log(chalk_1.default.gray(`  Resolved:  ${resolvedCommand}`));
+    }
+    else {
+        console.log(chalk_1.default.gray(`  Command:   ${command}`));
+    }
+    if (instrumentedCommand !== resolvedCommand) {
+        console.log(chalk_1.default.gray(`  Injected:  ${instrumentedCommand}`));
+    }
+    if (localMode) {
+        console.log(chalk_1.default.gray(`  Mode:      local (offline)`));
+    }
+    else {
+        console.log(chalk_1.default.gray(`  Backend:   ${backendUrl}`));
+    }
+    if (config) {
+        console.log(chalk_1.default.gray(`  Config:    .tricklerc.json`));
+    }
+    if (opts.stubs) {
+        console.log(chalk_1.default.gray(`  Stubs:     ${opts.stubs}`));
+    }
+    if (opts.annotate) {
+        console.log(chalk_1.default.gray(`  Annotate:  ${opts.annotate}`));
+    }
+    if (opts.watch) {
+        console.log(chalk_1.default.gray(`  Watch:     enabled`));
+    }
+    console.log(chalk_1.default.gray("  " + "─".repeat(50)));
+    console.log("");
+    // Shared env for all runs
+    const runEnv = {
+        ...extraEnv,
+        TRICKLE_BACKEND_URL: backendUrl,
+        TRICKLE_DEBUG: process.env.TRICKLE_DEBUG || "",
+    };
+    // In local mode, set TRICKLE_LOCAL=1 so the client writes to JSONL
+    if (localMode) {
+        runEnv.TRICKLE_LOCAL = "1";
+        // Forward TRICKLE_LOCAL_DIR if set
+        if (process.env.TRICKLE_LOCAL_DIR) {
+            runEnv.TRICKLE_LOCAL_DIR = process.env.TRICKLE_LOCAL_DIR;
+        }
+    }
+    // Execute the single-run flow
+    const exitCode = await executeSingleRun(instrumentedCommand, runEnv, opts, singleFile, localMode);
+    // If --watch, enter watch loop instead of exiting
+    if (opts.watch) {
+        await enterWatchLoop(command, instrumentedCommand, runEnv, opts, singleFile, backendProc, localMode);
+        // enterWatchLoop never returns (handles its own exit)
+    }
+    // Clean up
+    if (backendProc) {
+        backendProc.kill("SIGTERM");
+        await sleep(500);
+    }
+    process.exit(exitCode);
+}
+/**
+ * Execute a single observation run: run the command, wait for flush, show summary.
+ */
+async function executeSingleRun(instrumentedCommand, env, opts, singleFile, localMode) {
+    if (!localMode) {
+        // Snapshot functions before run (to compute delta)
+        let functionsBefore = [];
+        let errorsBefore = [];
+        try {
+            const fb = await (0, api_client_1.listFunctions)();
+            functionsBefore = fb.functions;
+            const eb = await (0, api_client_1.listErrors)();
+            errorsBefore = eb.errors;
+        }
+        catch {
+            // Backend might not have data yet
+        }
+        // Start live type generation for backend mode
+        let liveStop = null;
+        if (singleFile && !opts.stubs) {
+            liveStop = startLiveBackendTypes(singleFile);
+        }
+        // Run the instrumented command
+        const exitCode = await runProcess(instrumentedCommand, env);
+        // Stop live watcher
+        if (liveStop)
+            liveStop();
+        // Wait for transport to flush
+        console.log(chalk_1.default.gray("\n  Waiting for type data to flush..."));
+        await sleep(3000);
+        // Show summary with inline type signatures
+        await showSummary(functionsBefore, errorsBefore);
+        // Auto-generate stubs if --stubs was specified
+        if (opts.stubs) {
+            await autoGenerateStubs(opts.stubs);
+        }
+        // Auto-annotate if --annotate was specified
+        if (opts.annotate) {
+            await autoAnnotateFiles(opts.annotate);
+        }
+        // Auto-generate sidecar type file when invoked with a single file
+        // (unless --stubs was explicitly specified, which overrides this)
+        if (singleFile && !opts.stubs) {
+            await autoGenerateSidecar(singleFile);
+        }
+        return exitCode;
+    }
+    // ── Local/offline mode ──
+    const localDir = env.TRICKLE_LOCAL_DIR || process.env.TRICKLE_LOCAL_DIR || path.join(process.cwd(), ".trickle");
+    const jsonlPath = path.join(localDir, "observations.jsonl");
+    const { generateLocalStubs, generateFromJsonl } = await Promise.resolve().then(() => __importStar(require("../local-codegen")));
+    // Start live type generation — types update while the process runs
+    let liveTypesStop = null;
+    if (singleFile) {
+        liveTypesStop = startLiveLocalTypes(singleFile, jsonlPath, generateLocalStubs);
+    }
+    // Run the instrumented command
+    const exitCode = await runProcess(instrumentedCommand, env);
+    // Stop live watcher
+    if (liveTypesStop)
+        liveTypesStop();
+    // Brief pause for any async file writes to complete
+    await sleep(500);
+    if (!fs.existsSync(jsonlPath)) {
+        console.log(chalk_1.default.gray("\n  No observations captured."));
+        return exitCode;
+    }
+    // Final type generation (catches any remaining observations)
+    if (singleFile) {
+        generateLocalStubs(singleFile, jsonlPath);
+    }
+    // Show local summary
+    const stubs = generateFromJsonl(jsonlPath);
+    const allModules = Object.keys(stubs);
+    let totalFunctions = 0;
+    for (const mod of allModules) {
+        const lines = stubs[mod].ts.split("\n");
+        totalFunctions += lines.filter((l) => l.startsWith("export declare function")).length;
+    }
+    console.log("");
+    console.log(chalk_1.default.bold("  Summary (local mode)"));
+    console.log(chalk_1.default.gray("  " + "─".repeat(50)));
+    console.log(`  Functions observed: ${chalk_1.default.bold(String(totalFunctions))}`);
+    console.log(`  Data saved to: ${chalk_1.default.gray(jsonlPath)}`);
+    if (singleFile) {
+        const ext = path.extname(singleFile).toLowerCase();
+        const isPython = ext === ".py";
+        const baseName = path.basename(singleFile, ext);
+        const stubExt = isPython ? ".pyi" : ".d.ts";
+        const stubFile = path.join(path.dirname(singleFile), `${baseName}${stubExt}`);
+        if (fs.existsSync(stubFile)) {
+            const relPath = path.relative(process.cwd(), stubFile);
+            console.log(chalk_1.default.green(`  Types written to ${chalk_1.default.bold(relPath)}`));
+        }
+    }
+    console.log(chalk_1.default.gray("  " + "─".repeat(50)));
+    console.log("");
+    return exitCode;
+}
+// ── Live type generation ──
+/**
+ * Start a background watcher that regenerates type stubs whenever the
+ * JSONL file changes. Returns a stop function.
+ *
+ * Uses polling (fs.watchFile) because the file is being appended to by
+ * the child process and fs.watch can be unreliable with rapid appends.
+ */
+function startLiveLocalTypes(sourceFile, jsonlPath, generateLocalStubs) {
+    let lastSize = 0;
+    let lastFunctionCount = 0;
+    let debounceTimer = null;
+    let stopped = false;
+    const regenerate = () => {
+        if (stopped)
+            return;
+        try {
+            if (!fs.existsSync(jsonlPath))
+                return;
+            const stat = fs.statSync(jsonlPath);
+            if (stat.size === lastSize)
+                return; // no new data
+            lastSize = stat.size;
+            const { written, functionCount } = generateLocalStubs(sourceFile, jsonlPath);
+            if (written.length > 0 && functionCount > lastFunctionCount) {
+                const newCount = functionCount - lastFunctionCount;
+                const ts = new Date().toLocaleTimeString("en-US", { hour12: false });
+                const relPath = path.relative(process.cwd(), written[0]);
+                console.log(chalk_1.default.gray(`  [${ts}]`) +
+                    chalk_1.default.green(` +${newCount} type(s)`) +
+                    chalk_1.default.gray(` → ${relPath}`) +
+                    chalk_1.default.gray(` (${functionCount} total)`));
+                lastFunctionCount = functionCount;
+            }
+        }
+        catch {
+            // Never crash — this is a background helper
+        }
+    };
+    // Do an initial check after a short delay (catch fast-running scripts)
+    const initialTimer = setTimeout(regenerate, 800);
+    // Poll every 2 seconds
+    const interval = setInterval(regenerate, 2000);
+    // Also try fs.watchFile for faster response on changes
+    try {
+        fs.watchFile(jsonlPath, { interval: 1000 }, () => {
+            if (debounceTimer)
+                clearTimeout(debounceTimer);
+            debounceTimer = setTimeout(regenerate, 200);
+        });
+    }
+    catch {
+        // watchFile may fail if file doesn't exist yet — polling handles it
+    }
+    return () => {
+        stopped = true;
+        clearTimeout(initialTimer);
+        clearInterval(interval);
+        if (debounceTimer)
+            clearTimeout(debounceTimer);
+        try {
+            fs.unwatchFile(jsonlPath);
+        }
+        catch { }
+    };
+}
+/**
+ * Start a background poller that fetches stubs from the backend and
+ * writes sidecar type files while the process runs. Returns a stop function.
+ */
+function startLiveBackendTypes(sourceFile) {
+    let lastFunctionCount = 0;
+    let stopped = false;
+    const ext = path.extname(sourceFile).toLowerCase();
+    const isPython = ext === ".py";
+    const dir = path.dirname(sourceFile);
+    const baseName = path.basename(sourceFile, ext);
+    const sidecarName = isPython ? `${baseName}.pyi` : `${baseName}.d.ts`;
+    const sidecarPath = path.join(dir, sidecarName);
+    const poll = async () => {
+        if (stopped)
+            return;
+        try {
+            const { stubsCommand } = await Promise.resolve().then(() => __importStar(require("./stubs")));
+            await stubsCommand(dir, { silent: true });
+            if (fs.existsSync(sidecarPath)) {
+                const content = fs.readFileSync(sidecarPath, "utf-8");
+                const funcCount = (content.match(/export declare function/g) || []).length;
+                if (funcCount > lastFunctionCount) {
+                    const newCount = funcCount - lastFunctionCount;
+                    const ts = new Date().toLocaleTimeString("en-US", { hour12: false });
+                    console.log(chalk_1.default.gray(`  [${ts}]`) +
+                        chalk_1.default.green(` +${newCount} type(s)`) +
+                        chalk_1.default.gray(` → ${sidecarName}`) +
+                        chalk_1.default.gray(` (${funcCount} total)`));
+                    lastFunctionCount = funcCount;
+                }
+            }
+        }
+        catch {
+            // Never crash — background helper
+        }
+    };
+    // Poll every 3 seconds (backend mode has higher overhead)
+    const interval = setInterval(poll, 3000);
+    return () => {
+        stopped = true;
+        clearInterval(interval);
+    };
+}
+// ── Auto-generate sidecar type file ──
+async function autoGenerateSidecar(filePath) {
+    try {
+        const ext = path.extname(filePath).toLowerCase();
+        const isPython = ext === ".py";
+        const dir = path.dirname(filePath);
+        const baseName = path.basename(filePath, ext);
+        // Determine sidecar filename
+        const sidecarName = isPython ? `${baseName}.pyi` : `${baseName}.d.ts`;
+        const sidecarPath = path.join(dir, sidecarName);
+        // Use the stubs command to generate stubs for the file's directory
+        const { stubsCommand } = await Promise.resolve().then(() => __importStar(require("./stubs")));
+        await stubsCommand(dir, { silent: true });
+        // Check if the sidecar was generated
+        if (fs.existsSync(sidecarPath)) {
+            const stats = fs.statSync(sidecarPath);
+            if (stats.size > 0) {
+                console.log(chalk_1.default.green(`\n  Types written to ${chalk_1.default.bold(sidecarName)}`));
+            }
+        }
+    }
+    catch {
+        // Don't fail the run if sidecar generation fails
+    }
+}
+// ── Watch mode ──
+/**
+ * Find source files to watch based on the command.
+ * Returns the directory to watch and specific file paths.
+ */
+function findWatchTargets(command) {
+    const parts = command.split(/\s+/);
+    // Find the first token that looks like a file path
+    for (const part of parts) {
+        const ext = path.extname(part).toLowerCase();
+        if ([".js", ".ts", ".tsx", ".mjs", ".cjs", ".mts", ".py", ".jsx"].includes(ext)) {
+            const resolved = path.resolve(part);
+            if (fs.existsSync(resolved)) {
+                return {
+                    dir: path.dirname(resolved),
+                    file: resolved,
+                };
+            }
+        }
+    }
+    return { dir: process.cwd(), file: null };
+}
+/**
+ * Enter watch mode — watch source files and re-run on changes.
+ */
+async function enterWatchLoop(originalCommand, instrumentedCommand, env, opts, singleFile, backendProc, localMode) {
+    const { dir: watchDir, file: watchFile } = findWatchTargets(originalCommand);
+    const watchExts = new Set([".js", ".ts", ".tsx", ".mjs", ".cjs", ".mts", ".py", ".jsx"]);
+    const ignoreDirs = new Set(["node_modules", ".git", "dist", "build", "__pycache__", ".trickle"]);
+    console.log("");
+    console.log(chalk_1.default.gray("  " + "─".repeat(50)));
+    console.log(chalk_1.default.cyan("  Watching for changes...") + chalk_1.default.gray(` (${watchDir})`));
+    console.log(chalk_1.default.gray("  Press Ctrl+C to stop."));
+    console.log(chalk_1.default.gray("  " + "─".repeat(50)));
+    console.log("");
+    let debounceTimer = null;
+    let runCount = 1;
+    const triggerRerun = () => {
+        if (debounceTimer)
+            clearTimeout(debounceTimer);
+        debounceTimer = setTimeout(async () => {
+            runCount++;
+            const ts = new Date().toLocaleTimeString("en-US", { hour12: false });
+            console.log("");
+            console.log(chalk_1.default.cyan(`  [${ts}]`) + chalk_1.default.bold(` Re-running (#${runCount})...`));
+            console.log(chalk_1.default.gray("  " + "─".repeat(50)));
+            try {
+                await executeSingleRun(instrumentedCommand, env, opts, singleFile, localMode);
+            }
+            catch {
+                console.log(chalk_1.default.red("  Run failed. Waiting for next change..."));
+            }
+            console.log("");
+            console.log(chalk_1.default.gray("  Watching for changes..."));
+        }, 300); // 300ms debounce
+    };
+    // Use fs.watch with recursive option (supported on macOS and Windows)
+    try {
+        const watcher = fs.watch(watchDir, { recursive: true }, (_eventType, filename) => {
+            if (!filename)
+                return;
+            // Check file extension
+            const ext = path.extname(filename).toLowerCase();
+            if (!watchExts.has(ext))
+                return;
+            // Skip ignored directories
+            const parts = filename.split(path.sep);
+            if (parts.some(p => ignoreDirs.has(p)))
+                return;
+            const ts = new Date().toLocaleTimeString("en-US", { hour12: false });
+            console.log(chalk_1.default.gray(`  [${ts}] Changed: ${filename}`));
+            triggerRerun();
+        });
+        // Handle graceful shutdown
+        const cleanup = () => {
+            watcher.close();
+            if (debounceTimer)
+                clearTimeout(debounceTimer);
+            if (backendProc) {
+                backendProc.kill("SIGTERM");
+            }
+            console.log(chalk_1.default.gray("\n  Watch stopped.\n"));
+            process.exit(0);
+        };
+        process.on("SIGINT", cleanup);
+        process.on("SIGTERM", cleanup);
+        // Keep the process alive
+        await new Promise(() => { });
+    }
+    catch (err) {
+        // Fallback: if recursive watch isn't supported, watch just the target file
+        if (watchFile) {
+            console.log(chalk_1.default.gray("  (Watching single file: " + path.basename(watchFile) + ")"));
+            const watcher = fs.watch(watchFile, () => {
+                const ts = new Date().toLocaleTimeString("en-US", { hour12: false });
+                console.log(chalk_1.default.gray(`  [${ts}] Changed: ${path.basename(watchFile)}`));
+                triggerRerun();
+            });
+            const cleanup = () => {
+                watcher.close();
+                if (debounceTimer)
+                    clearTimeout(debounceTimer);
+                if (backendProc) {
+                    backendProc.kill("SIGTERM");
+                }
+                console.log(chalk_1.default.gray("\n  Watch stopped.\n"));
+                process.exit(0);
+            };
+            process.on("SIGINT", cleanup);
+            process.on("SIGTERM", cleanup);
+            await new Promise(() => { });
+        }
+        // Can't watch anything
+        console.error(chalk_1.default.red("  Could not set up file watcher."));
+        if (backendProc)
+            backendProc.kill("SIGTERM");
+        process.exit(1);
+    }
+}
+// ── Auto-generate stubs ──
+async function autoGenerateStubs(dir) {
+    try {
+        const { stubsCommand } = await Promise.resolve().then(() => __importStar(require("./stubs")));
+        await stubsCommand(dir, {});
+    }
+    catch (err) {
+        if (err instanceof Error) {
+            console.error(chalk_1.default.yellow(`\n  Stubs generation warning: ${err.message}`));
+        }
+    }
+}
+// ── Auto-annotate files ──
+async function autoAnnotateFiles(fileOrDir) {
+    try {
+        const { annotateCommand } = await Promise.resolve().then(() => __importStar(require("./annotate")));
+        const resolved = path.resolve(fileOrDir);
+        if (fs.existsSync(resolved) && fs.statSync(resolved).isDirectory()) {
+            // Annotate all JS/TS/Python files in the directory
+            const files = findAnnotatableFiles(resolved);
+            if (files.length === 0) {
+                console.log(chalk_1.default.gray(`\n  No annotatable files found in ${fileOrDir}`));
+                return;
+            }
+            for (const file of files) {
+                await annotateCommand(file, {});
+            }
+        }
+        else {
+            // Annotate a single file
+            await annotateCommand(fileOrDir, {});
+        }
+    }
+    catch (err) {
+        if (err instanceof Error) {
+            console.error(chalk_1.default.yellow(`\n  Annotation warning: ${err.message}`));
+        }
+    }
+}
+function findAnnotatableFiles(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()) {
+            if (["node_modules", "__pycache__", ".git", "dist", "build", ".trickle"].includes(entry.name))
+                continue;
+            results.push(...findAnnotatableFiles(fullPath));
+        }
+        else if (entry.isFile()) {
+            const ext = path.extname(entry.name).toLowerCase();
+            if ([".js", ".jsx", ".mjs", ".cjs", ".ts", ".tsx", ".py"].includes(ext)) {
+                results.push(fullPath);
+            }
+        }
+    }
+    return results;
+}
+// ── Inline type signatures in summary ──
+async function fetchTypeSignatures(newFunctions) {
+    try {
+        const { annotations } = await (0, api_client_1.fetchAnnotations)({});
+        return annotations || {};
+    }
+    catch {
+        return {};
+    }
+}
+function formatSignature(fnName, annotation, maxLen = 90) {
+    const params = annotation.params
+        .map((p) => `${p.name}: ${p.type}`)
+        .join(", ");
+    const sig = `${fnName}(${params}) → ${annotation.returnType}`;
+    if (sig.length > maxLen) {
+        return sig.substring(0, maxLen - 1) + "…";
+    }
+    return sig;
+}
+/**
+ * Detect if a script file uses ES modules.
+ */
+function isEsmFile(command) {
+    const parts = command.split(/\s+/);
+    for (const part of parts) {
+        if (part.endsWith(".mjs") || part.endsWith(".mts"))
+            return true;
+        if (part.endsWith(".js") ||
+            part.endsWith(".ts") ||
+            part.endsWith(".tsx") ||
+            part.endsWith(".jsx")) {
+            const filePath = path.resolve(part);
+            try {
+                const content = fs.readFileSync(filePath, "utf-8");
+                if (/^\s*(import|export)\s/m.test(content))
+                    return true;
+            }
+            catch {
+                // File might not exist at this path
+            }
+            try {
+                let dir = path.dirname(filePath);
+                for (let i = 0; i < 10; i++) {
+                    const pkgPath = path.join(dir, "package.json");
+                    if (fs.existsSync(pkgPath)) {
+                        const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf-8"));
+                        if (pkg.type === "module")
+                            return true;
+                        break;
+                    }
+                    const parent = path.dirname(dir);
+                    if (parent === dir)
+                        break;
+                    dir = parent;
+                }
+            }
+            catch {
+                // Ignore
+            }
+        }
+    }
+    return false;
+}
+/**
+ * Detect the language and inject the appropriate auto-observation mechanism.
+ */
+function injectObservation(command, backendUrl, opts) {
+    const env = {};
+    if (command.includes("trickle-observe/observe") ||
+        command.includes("trickle-observe/register") ||
+        command.includes("trickle/observe") ||
+        command.includes("trickle/register") ||
+        command.includes("-m trickle")) {
+        return { instrumentedCommand: command, env };
+    }
+    const observePath = resolveObservePath();
+    const observeEsmPath = resolveObserveEsmPath();
+    if (opts.include)
+        env.TRICKLE_OBSERVE_INCLUDE = opts.include;
+    if (opts.exclude)
+        env.TRICKLE_OBSERVE_EXCLUDE = opts.exclude;
+    const nodeMatch = command.match(/^(node|ts-node|tsx|nodemon)\s/);
+    if (nodeMatch) {
+        const runner = nodeMatch[1];
+        const useEsm = isEsmFile(command) && observeEsmPath;
+        if (useEsm) {
+            const modified = command.replace(new RegExp(`^${runner}\\s`), `${runner} --import ${observeEsmPath} `);
+            return { instrumentedCommand: modified, env };
+        }
+        else {
+            const modified = command.replace(new RegExp(`^${runner}\\s`), `${runner} -r ${observePath} `);
+            return { instrumentedCommand: modified, env };
+        }
+    }
+    if (/^(vitest|jest|mocha|npx|bunx|bun)\b/.test(command)) {
+        const existing = process.env.NODE_OPTIONS || "";
+        if (observeEsmPath) {
+            env.NODE_OPTIONS =
+                `${existing} -r ${observePath} --import ${observeEsmPath}`.trim();
+        }
+        else {
+            env.NODE_OPTIONS = `${existing} -r ${observePath}`.trim();
+        }
+        return { instrumentedCommand: command, env };
+    }
+    const pyMatch = command.match(/^(python3?|python3?\.\d+)\s/);
+    if (pyMatch) {
+        const python = pyMatch[1];
+        const rest = command.slice(pyMatch[0].length);
+        if (opts.include)
+            env.TRICKLE_OBSERVE_INCLUDE = opts.include;
+        if (opts.exclude)
+            env.TRICKLE_OBSERVE_EXCLUDE = opts.exclude;
+        return {
+            instrumentedCommand: `${python} -c "from trickle.observe_runner import main; main()" ${rest}`,
+            env,
+        };
+    }
+    if (/^(pytest|uvicorn|gunicorn|flask|django-admin)\b/.test(command)) {
+        if (opts.include)
+            env.TRICKLE_OBSERVE_INCLUDE = opts.include;
+        if (opts.exclude)
+            env.TRICKLE_OBSERVE_EXCLUDE = opts.exclude;
+        return {
+            instrumentedCommand: `python -c "from trickle.observe_runner import main; main()" -m ${command}`,
+            env,
+        };
+    }
+    console.log(chalk_1.default.yellow("  Could not detect language. Trying Node.js instrumentation..."));
+    const existing = process.env.NODE_OPTIONS || "";
+    env.NODE_OPTIONS = `${existing} -r ${observePath}`.trim();
+    return { instrumentedCommand: command, env };
+}
+function resolveObservePath() {
+    try {
+        return require.resolve("trickle-observe/observe");
+    }
+    catch {
+        // Not in node_modules
+    }
+    try {
+        return require.resolve("trickle/observe");
+    }
+    catch {
+        // Not in node_modules
+    }
+    const monorepoPath = path.resolve(__dirname, "..", "..", "..", "client-js", "observe.js");
+    if (fs.existsSync(monorepoPath))
+        return monorepoPath;
+    return "trickle-observe/observe";
+}
+function resolveObserveEsmPath() {
+    try {
+        return require.resolve("trickle-observe/observe-esm");
+    }
+    catch {
+        // Not in node_modules
+    }
+    const monorepoPath = path.resolve(__dirname, "..", "..", "..", "client-js", "observe-esm.mjs");
+    if (fs.existsSync(monorepoPath))
+        return monorepoPath;
+    return null;
+}
+function runProcess(command, env) {
+    return new Promise((resolve) => {
+        const proc = (0, child_process_1.spawn)(command, [], {
+            stdio: "inherit",
+            shell: true,
+            env: { ...process.env, ...env },
+        });
+        proc.on("error", (err) => {
+            console.error(chalk_1.default.red(`\n  Failed to start: ${err.message}\n`));
+            resolve(1);
+        });
+        proc.on("exit", (code) => {
+            resolve(code ?? 1);
+        });
+    });
+}
+/**
+ * Show a summary of what was captured during the run, with inline type signatures.
+ */
+async function showSummary(functionsBefore, errorsBefore) {
+    try {
+        const { functions } = await (0, api_client_1.listFunctions)();
+        const { errors } = await (0, api_client_1.listErrors)();
+        const beforeIds = new Set(functionsBefore.map((f) => f.id));
+        const newFunctions = functions.filter((f) => !beforeIds.has(f.id));
+        const beforeErrorIds = new Set(errorsBefore.map((e) => e.id));
+        const newErrors = errors.filter((e) => !beforeErrorIds.has(e.id));
+        // Fetch inline type signatures for the new functions
+        const annotations = await fetchTypeSignatures(newFunctions);
+        console.log("");
+        console.log(chalk_1.default.bold("  Summary"));
+        console.log(chalk_1.default.gray("  " + "─".repeat(50)));
+        if (functions.length === 0) {
+            console.log(chalk_1.default.yellow("  No functions captured. The command may not have"));
+            console.log(chalk_1.default.yellow("  loaded any modules that could be instrumented."));
+        }
+        else {
+            console.log(`  Functions observed: ${chalk_1.default.bold(String(functions.length))} total, ${chalk_1.default.green(String(newFunctions.length) + " new")}`);
+            if (newFunctions.length > 0) {
+                console.log("");
+                const shown = newFunctions.slice(0, 15);
+                for (const fn of shown) {
+                    const annotation = annotations[fn.function_name];
+                    if (annotation) {
+                        // Show full type signature
+                        const sig = formatSignature(fn.function_name, annotation);
+                        console.log(`    ${chalk_1.default.green("+")} ${sig}`);
+                        console.log(chalk_1.default.gray(`      ${fn.module} module`));
+                    }
+                    else {
+                        const moduleBadge = chalk_1.default.gray(`[${fn.module}]`);
+                        console.log(`    ${chalk_1.default.green("+")} ${fn.function_name} ${moduleBadge}`);
+                    }
+                }
+                if (newFunctions.length > 15) {
+                    console.log(chalk_1.default.gray(`    ... and ${newFunctions.length - 15} more`));
+                }
+            }
+            if (newErrors.length > 0) {
+                console.log("");
+                console.log(`  Errors captured: ${chalk_1.default.red(String(newErrors.length))}`);
+                const shownErrors = newErrors.slice(0, 5);
+                for (const err of shownErrors) {
+                    const fn = functions.find((f) => f.id === err.function_id);
+                    const fnName = fn ? fn.function_name : "unknown";
+                    console.log(`    ${chalk_1.default.red("!")} ${fnName}: ${chalk_1.default.gray(err.error_message.substring(0, 80))}`);
+                }
+            }
+            console.log("");
+            console.log(chalk_1.default.gray("  Explore results:"));
+            console.log(chalk_1.default.gray("    trickle functions          # list all captured functions"));
+            if (newFunctions.length > 0) {
+                const example = newFunctions[0].function_name;
+                console.log(chalk_1.default.gray(`    trickle types ${example}  # see types + sample data`));
+            }
+            if (newErrors.length > 0) {
+                console.log(chalk_1.default.gray("    trickle errors             # see captured errors"));
+            }
+        }
+        console.log(chalk_1.default.gray("  " + "─".repeat(50)));
+        console.log("");
+    }
+    catch {
+        console.log(chalk_1.default.gray("\n  Could not fetch summary from backend.\n"));
+    }
+}
+async function checkBackend(url) {
+    try {
+        const res = await fetch(`${url}/api/health`, {
+            signal: AbortSignal.timeout(2000),
+        });
+        return res.ok;
+    }
+    catch {
+        return false;
+    }
+}
+async function autoStartBackend() {
+    const backendPaths = [
+        path.resolve("packages/backend/dist/index.js"),
+        path.resolve("node_modules/trickle-backend/dist/index.js"),
+    ];
+    for (const p of backendPaths) {
+        if (fs.existsSync(p)) {
+            console.log(chalk_1.default.gray("  Auto-starting trickle backend..."));
+            const proc = (0, child_process_1.spawn)("node", [p], {
+                stdio: ["ignore", "pipe", "pipe"],
+                env: { ...process.env },
+                detached: false,
+            });
+            proc.stdout?.on("data", () => { });
+            proc.stderr?.on("data", () => { });
+            proc.unref();
+            for (let i = 0; i < 20; i++) {
+                await sleep(500);
+                const ready = await checkBackend((0, config_1.getBackendUrl)());
+                if (ready) {
+                    console.log(chalk_1.default.gray("  Backend started ✓\n"));
+                    return proc;
+                }
+            }
+            proc.kill("SIGTERM");
+            return null;
+        }
+    }
+    return null;
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}