trickle-cli 0.1.0

package/dist/index.js

@@ -0,0 +1,419 @@
+#!/usr/bin/env node
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const commander_1 = require("commander");
+const chalk_1 = __importDefault(require("chalk"));
+const functions_1 = require("./commands/functions");
+const types_1 = require("./commands/types");
+const errors_1 = require("./commands/errors");
+const tail_1 = require("./commands/tail");
+const codegen_1 = require("./commands/codegen");
+const mock_1 = require("./commands/mock");
+const init_1 = require("./commands/init");
+const diff_1 = require("./commands/diff");
+const openapi_1 = require("./commands/openapi");
+const check_1 = require("./commands/check");
+const dev_1 = require("./commands/dev");
+const test_gen_1 = require("./commands/test-gen");
+const dashboard_1 = require("./commands/dashboard");
+const proxy_1 = require("./commands/proxy");
+const export_1 = require("./commands/export");
+const coverage_1 = require("./commands/coverage");
+const replay_1 = require("./commands/replay");
+const docs_1 = require("./commands/docs");
+const sample_1 = require("./commands/sample");
+const audit_1 = require("./commands/audit");
+const capture_1 = require("./commands/capture");
+const search_1 = require("./commands/search");
+const auto_1 = require("./commands/auto");
+const validate_1 = require("./commands/validate");
+const watch_1 = require("./commands/watch");
+const infer_1 = require("./commands/infer");
+const overview_1 = require("./commands/overview");
+const trace_1 = require("./commands/trace");
+const pack_1 = require("./commands/pack");
+const unpack_1 = require("./commands/unpack");
+const run_1 = require("./commands/run");
+const annotate_1 = require("./commands/annotate");
+const stubs_1 = require("./commands/stubs");
+const program = new commander_1.Command();
+program
+    .name("trickle")
+    .description("CLI for trickle runtime type observability")
+    .version("0.1.0");
+// trickle init
+program
+    .command("init")
+    .description("Set up trickle in your project — configures types, tsconfig, and npm scripts")
+    .option("--dir <path>", "Project directory (defaults to current directory)")
+    .option("--python", "Set up for a Python project")
+    .action(async (opts) => {
+    await (0, init_1.initCommand)(opts);
+});
+// trickle dev [command]
+program
+    .command("dev [command]")
+    .description("Start your app with auto-instrumentation and live type generation")
+    .option("-o, --out <path>", "Types output path (default: .trickle/types.d.ts)")
+    .option("--client", "Also generate typed API client (.trickle/api-client.ts)")
+    .option("--python", "Generate Python type stubs instead of TypeScript")
+    .action(async (command, opts) => {
+    await (0, dev_1.devCommand)(command, opts);
+});
+// trickle run <command>
+program
+    .command("run [command]")
+    .description("Run any command or file with universal type observation — zero code changes needed")
+    .option("--module <name>", "Module name for captured functions")
+    .option("--include <patterns>", "Comma-separated substrings — only observe matching modules")
+    .option("--exclude <patterns>", "Comma-separated substrings — skip matching modules")
+    .option("--stubs <dir>", "Auto-generate .d.ts/.pyi type stubs in this directory after the run")
+    .option("--annotate <path>", "Auto-annotate this file or directory with types after the run")
+    .option("-w, --watch", "Watch source files and re-run on changes")
+    .action(async (command, opts) => {
+    await (0, run_1.runCommand)(command, opts);
+});
+// trickle functions
+program
+    .command("functions")
+    .description("List observed functions")
+    .option("--env <env>", "Filter by environment")
+    .option("--lang <lang>", "Filter by language")
+    .option("--search <query>", "Search by function name")
+    .action(async (opts) => {
+    await (0, functions_1.functionsCommand)(opts);
+});
+// trickle types <function-name>
+program
+    .command("types <function-name>")
+    .description("Show type snapshots for a function")
+    .option("--env <env>", "Filter by environment")
+    .option("--diff", "Show diff between latest two snapshots")
+    .option("--env1 <env>", "First environment for cross-env diff")
+    .option("--env2 <env>", "Second environment for cross-env diff")
+    .action(async (functionName, opts) => {
+    await (0, types_1.typesCommand)(functionName, opts);
+});
+// trickle errors [id]
+program
+    .command("errors [id]")
+    .description("List errors or show error detail")
+    .option("--env <env>", "Filter by environment")
+    .option("--since <timeframe>", "Show errors since (e.g., 2d, 5m, 1h)")
+    .option("--function <name>", "Filter by function name")
+    .option("--limit <n>", "Limit number of results")
+    .action(async (id, opts) => {
+    await (0, errors_1.errorsCommand)(id, opts);
+});
+// trickle tail
+program
+    .command("tail")
+    .description("Stream live events from the backend")
+    .option("--filter <pattern>", "Filter by function name pattern")
+    .action(async (opts) => {
+    await (0, tail_1.tailCommand)(opts);
+});
+// trickle codegen [function-name]
+program
+    .command("codegen [function-name]")
+    .description("Generate TypeScript (or Python) type definitions from observed runtime types")
+    .option("-o, --out <path>", "Write output to a file instead of stdout")
+    .option("--env <env>", "Filter by environment")
+    .option("--python", "Generate Python type stubs (.pyi) instead of TypeScript")
+    .option("--client", "Generate a typed fetch-based API client from observed routes")
+    .option("--handlers", "Generate typed Express handler types for route handlers")
+    .option("--zod", "Generate Zod validation schemas with inferred types")
+    .option("--react-query", "Generate typed TanStack React Query hooks")
+    .option("--guards", "Generate runtime type guard functions")
+    .option("--middleware", "Generate Express request validation middleware")
+    .option("--msw", "Generate Mock Service Worker (MSW) request handlers")
+    .option("--json-schema", "Generate JSON Schema definitions from observed types")
+    .option("--swr", "Generate typed SWR data-fetching hooks")
+    .option("--pydantic", "Generate Pydantic BaseModel classes (Python)")
+    .option("--class-validator", "Generate class-validator DTOs for NestJS")
+    .option("--graphql", "Generate GraphQL SDL schema from observed routes")
+    .option("--trpc", "Generate typed tRPC router from observed routes")
+    .option("--axios", "Generate typed Axios client from observed routes")
+    .option("--watch", "Watch mode: re-generate when new types are observed")
+    .action(async (functionName, opts) => {
+    await (0, codegen_1.codegenCommand)(functionName, opts);
+});
+// trickle diff
+program
+    .command("diff")
+    .description("Show type drift across all functions — what changed and where")
+    .option("--since <timeframe>", "Show changes since (e.g., 1h, 2d, 1w)")
+    .option("--env <env>", "Filter by environment")
+    .option("--env1 <env>", "First environment for cross-env comparison")
+    .option("--env2 <env>", "Second environment for cross-env comparison")
+    .action(async (opts) => {
+    await (0, diff_1.diffCommand)(opts);
+});
+// trickle openapi
+program
+    .command("openapi")
+    .description("Generate an OpenAPI 3.0 spec from runtime-observed API routes")
+    .option("-o, --out <path>", "Write spec to a file (JSON)")
+    .option("--env <env>", "Filter by environment")
+    .option("--title <title>", "API title in the spec", "API")
+    .option("--api-version <version>", "API version in the spec", "1.0.0")
+    .option("--server <url>", "Server URL to include in the spec")
+    .action(async (opts) => {
+    await (0, openapi_1.openapiCommand)(opts);
+});
+// trickle check
+program
+    .command("check")
+    .description("Detect breaking API changes by comparing against a saved baseline")
+    .option("--save <file>", "Save current types as a baseline snapshot")
+    .option("--against <file>", "Check current types against a baseline (exit 1 on breaking changes)")
+    .option("--env <env>", "Filter by environment")
+    .action(async (opts) => {
+    await (0, check_1.checkCommand)(opts);
+});
+// trickle mock
+program
+    .command("mock")
+    .description("Start a mock API server from runtime-observed routes and sample data")
+    .option("-p, --port <port>", "Port to listen on", "3000")
+    .option("--no-cors", "Disable CORS headers")
+    .action(async (opts) => {
+    await (0, mock_1.mockCommand)(opts);
+});
+// trickle test --generate
+program
+    .command("test")
+    .description("Generate API test files from runtime-observed routes and sample data")
+    .option("--generate", "Generate test file from observed routes")
+    .option("-o, --out <path>", "Write tests to a file")
+    .option("--framework <name>", "Test framework: vitest or jest (default: vitest)")
+    .option("--base-url <url>", "Base URL for API requests (default: http://localhost:3000)")
+    .action(async (opts) => {
+    if (!opts.generate) {
+        console.log(chalk_1.default.gray("\n  Usage: trickle test --generate [--out tests.ts] [--framework vitest|jest]\n"));
+        return;
+    }
+    await (0, test_gen_1.testGenCommand)(opts);
+});
+// trickle dashboard
+program
+    .command("dashboard")
+    .description("Open the trickle web dashboard to explore observed types visually")
+    .action(async () => {
+    await (0, dashboard_1.dashboardCommand)();
+});
+// trickle proxy
+program
+    .command("proxy")
+    .description("Transparent reverse proxy that captures API types without any backend code changes")
+    .requiredOption("-t, --target <url>", "Target server URL to proxy to (e.g. http://localhost:3000)")
+    .option("-p, --port <port>", "Port for the proxy server", "4000")
+    .action(async (opts) => {
+    await (0, proxy_1.proxyCommand)(opts);
+});
+// trickle export
+program
+    .command("export")
+    .description("Generate all output formats into a .trickle/ directory at once")
+    .option("-d, --dir <path>", "Output directory (default: .trickle)")
+    .option("--env <env>", "Filter by environment")
+    .action(async (opts) => {
+    await (0, export_1.exportCommand)(opts);
+});
+// trickle coverage
+program
+    .command("coverage")
+    .description("Type observation health report — coverage, staleness, variants, and overall score")
+    .option("--env <env>", "Filter by environment")
+    .option("--json", "Output raw JSON (for CI integration)")
+    .option("--fail-under <score>", "Exit 1 if health score is below this threshold (0-100)")
+    .option("--stale-hours <hours>", "Hours before a function is considered stale (default: 24)")
+    .action(async (opts) => {
+    await (0, coverage_1.coverageCommand)(opts);
+});
+// trickle replay
+program
+    .command("replay")
+    .description("Replay captured API requests as regression tests — verify response shapes match")
+    .option("-t, --target <url>", "Target server URL (default: http://localhost:3000)")
+    .option("--strict", "Compare exact values instead of just shapes")
+    .option("--json", "Output JSON results (for CI)")
+    .option("--fail-fast", "Stop on first failure")
+    .action(async (opts) => {
+    await (0, replay_1.replayCommand)(opts);
+});
+// trickle docs
+program
+    .command("docs")
+    .description("Generate API documentation from observed runtime types and sample data")
+    .option("-o, --out <path>", "Write docs to a file instead of stdout")
+    .option("--html", "Generate self-contained HTML instead of Markdown")
+    .option("--env <env>", "Filter by environment")
+    .option("--title <title>", "Documentation title", "API Documentation")
+    .action(async (opts) => {
+    await (0, docs_1.docsCommand)(opts);
+});
+// trickle sample [route]
+program
+    .command("sample [route]")
+    .description("Generate test fixtures and factory functions from observed runtime data")
+    .option("-f, --format <format>", "Output format: json, ts, or factory (default: json)")
+    .option("-o, --out <path>", "Write fixtures to a file")
+    .action(async (route, opts) => {
+    await (0, sample_1.sampleCommand)(route, opts);
+});
+// trickle audit
+program
+    .command("audit")
+    .description("Analyze observed API types for quality issues — sensitive data, naming, complexity")
+    .option("--env <env>", "Filter by environment")
+    .option("--json", "Output raw JSON (for CI integration)")
+    .option("--fail-on-error", "Exit 1 if any errors are found")
+    .option("--fail-on-warning", "Exit 1 if any errors or warnings are found")
+    .action(async (opts) => {
+    await (0, audit_1.auditCommand)(opts);
+});
+// trickle capture <method> <url>
+program
+    .command("capture <method> <url>")
+    .description("Capture types from a live API endpoint — no instrumentation needed")
+    .option("-H, --header <header...>", "HTTP headers (e.g. -H 'Authorization: Bearer token')")
+    .option("-d, --body <body>", "Request body (JSON string)")
+    .option("--env <env>", "Environment label (default: development)")
+    .option("--module <module>", "Module label (default: capture)")
+    .action(async (method, url, opts) => {
+    await (0, capture_1.captureCommand)(method, url, opts);
+});
+// trickle search <query>
+program
+    .command("search <query>")
+    .description("Search across all observed types — find functions by field names, types, or patterns")
+    .option("--env <env>", "Filter by environment")
+    .option("--json", "Output raw JSON")
+    .action(async (query, opts) => {
+    await (0, search_1.searchCommand)(query, opts);
+});
+// trickle auto
+program
+    .command("auto")
+    .description("Auto-detect project dependencies and generate only the relevant type files")
+    .option("-d, --dir <path>", "Output directory (default: .trickle)")
+    .option("--env <env>", "Filter by environment")
+    .action(async (opts) => {
+    await (0, auto_1.autoCommand)(opts);
+});
+// trickle validate <method> <url>
+program
+    .command("validate <method> <url>")
+    .description("Validate a live API response against previously observed types")
+    .option("-H, --header <header...>", "HTTP headers")
+    .option("-d, --body <body>", "Request body (JSON string)")
+    .option("--env <env>", "Filter by environment")
+    .option("--strict", "Treat extra fields as errors (not just warnings)")
+    .action(async (method, url, opts) => {
+    await (0, validate_1.validateCommand)(method, url, opts);
+});
+// trickle watch
+program
+    .command("watch")
+    .description("Watch for new type observations and auto-regenerate type files")
+    .option("-d, --dir <path>", "Output directory (default: .trickle)")
+    .option("--env <env>", "Filter by environment")
+    .option("--interval <interval>", "Poll interval (e.g., 3s, 500ms, 1m)", "3s")
+    .action(async (opts) => {
+    await (0, watch_1.watchCommand)(opts);
+});
+// trickle infer [file]
+program
+    .command("infer [file]")
+    .description("Infer types from a JSON file or stdin — no live API needed")
+    .requiredOption("-n, --name <name>", "Function/route name (e.g., 'GET /api/users')")
+    .option("--env <env>", "Environment label (default: development)")
+    .option("--module <module>", "Module label (default: infer)")
+    .option("--request-body <json>", "Example request body JSON (for documenting input types)")
+    .action(async (file, opts) => {
+    await (0, infer_1.inferCommand)(file, opts);
+});
+// trickle overview
+program
+    .command("overview")
+    .description("Compact API overview — all routes with inline type signatures")
+    .option("--env <env>", "Filter by environment")
+    .option("--json", "Output raw JSON")
+    .action(async (opts) => {
+    await (0, overview_1.overviewCommand)(opts);
+});
+// trickle trace <method> <url>
+program
+    .command("trace <method> <url>")
+    .description("Make an HTTP request and show the response with inline type annotations")
+    .option("-H, --header <header...>", "HTTP headers")
+    .option("-d, --body <body>", "Request body (JSON string)")
+    .option("--save", "Save inferred types to the backend")
+    .option("--env <env>", "Environment label (default: development)")
+    .option("--module <module>", "Module label (default: trace)")
+    .action(async (method, url, opts) => {
+    await (0, trace_1.traceCommand)(method, url, opts);
+});
+// trickle pack
+program
+    .command("pack")
+    .description("Export all observed types as a portable bundle")
+    .option("-o, --out <file>", "Write bundle to a file (otherwise stdout)")
+    .option("--env <env>", "Filter by environment")
+    .action(async (opts) => {
+    await (0, pack_1.packCommand)(opts);
+});
+// trickle unpack <file>
+program
+    .command("unpack <file>")
+    .description("Import types from a packed bundle into the backend")
+    .option("--env <env>", "Override environment for all imported types")
+    .option("--dry-run", "List contents without importing")
+    .action(async (file, opts) => {
+    await (0, unpack_1.unpackCommand)(file, opts);
+});
+// trickle stubs <dir>
+program
+    .command("stubs <dir>")
+    .description("Generate .d.ts and .pyi sidecar type stubs next to source files — IDEs pick them up automatically")
+    .option("--env <env>", "Filter by environment")
+    .option("--dry-run", "Preview which files would be created without writing them")
+    .action(async (dir, opts) => {
+    await (0, stubs_1.stubsCommand)(dir, opts);
+});
+// trickle annotate <file>
+program
+    .command("annotate <file>")
+    .description("Add runtime-observed type annotations directly into source files")
+    .option("--env <env>", "Filter by environment")
+    .option("--dry-run", "Preview changes without modifying the file")
+    .option("--jsdoc", "Force JSDoc comments (default for .js files)")
+    .action(async (file, opts) => {
+    await (0, annotate_1.annotateCommand)(file, opts);
+});
+// Handle unhandled rejections
+process.on("unhandledRejection", (err) => {
+    if (err instanceof Error) {
+        console.error(chalk_1.default.red(`\n  Error: ${err.message}\n`));
+    }
+    else {
+        console.error(chalk_1.default.red("\n  An unexpected error occurred.\n"));
+    }
+    process.exit(1);
+});
+// ── Direct file execution shorthand ──
+// `trickle app.js` → `trickle run app.js`
+// `trickle script.py --watch` → `trickle run script.py --watch`
+const CODE_EXTENSIONS = /\.(js|ts|tsx|jsx|mjs|cjs|mts|py)$/i;
+const firstArg = process.argv[2];
+if (firstArg &&
+    !firstArg.startsWith("-") &&
+    CODE_EXTENSIONS.test(firstArg)) {
+    // Inject "run" before the file argument
+    process.argv.splice(2, 0, "run");
+}
+program.parse();

package/dist/local-codegen.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Local codegen: reads .trickle/observations.jsonl and generates
+ * type stubs without needing the backend running.
+ *
+ * Used by `trickle run` in offline/local mode.
+ */
+/**
+ * Generate type stubs from a .trickle/observations.jsonl file.
+ * Returns { ts, python } content strings, grouped by module.
+ */
+export declare function generateFromJsonl(jsonlPath: string): Record<string, {
+    ts: string;
+    python: string;
+}>;
+/**
+ * Generate sidecar type files from local observations.
+ * Writes .d.ts or .pyi files next to the source file.
+ */
+export declare function generateLocalStubs(sourceFile: string, jsonlPath?: string): {
+    written: string[];
+    functionCount: number;
+};