trickle-cli 0.1.0

package/src/commands/sample.ts

@@ -0,0 +1,259 @@
+import * as fs from "fs";
+import * as path from "path";
+import chalk from "chalk";
+import { fetchMockConfig, MockRoute } from "../api-client";
+
+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 async function sampleCommand(routeFilter: string | undefined, opts: SampleOptions): Promise<void> {
+  let routes: MockRoute[];
+  try {
+    const config = await fetchMockConfig();
+    routes = config.routes;
+  } catch {
+    console.error(chalk.red("\n  Cannot connect to trickle backend."));
+    console.error(chalk.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.yellow("\n  No sample data found."));
+    if (routeFilter) {
+      console.error(chalk.gray(`  No routes matching "${routeFilter}" with sample data.\n`));
+    } else {
+      console.error(chalk.gray("  Instrument your app and make some requests first.\n"));
+    }
+    process.exit(0);
+  }
+
+  const format = (opts.format || "json").toLowerCase();
+  let output: string;
+
+  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.red(`\n  Unknown format: ${format}`));
+      console.error(chalk.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.green(`\n  Fixtures written to ${chalk.bold(opts.out)}`));
+    console.log(chalk.gray(`  ${routes.length} routes, format: ${format}\n`));
+  } else {
+    console.log(output);
+  }
+}
+
+function toPascalCase(name: string): string {
+  return name
+    .replace(/[^a-zA-Z0-9]+/g, " ")
+    .split(/\s+/)
+    .map((w) => w.charAt(0).toUpperCase() + w.slice(1).toLowerCase())
+    .join("");
+}
+
+function toCamelCase(name: string): string {
+  const pascal = toPascalCase(name);
+  return pascal.charAt(0).toLowerCase() + pascal.slice(1);
+}
+
+// ── JSON format ──
+
+function generateJson(routes: MockRoute[]): string {
+  const samples: Record<string, { request?: unknown; response: unknown }> = {};
+
+  for (const route of routes) {
+    const key = `${route.method} ${route.path}`;
+    const entry: { request?: unknown; response: unknown } = {
+      response: route.sampleOutput,
+    };
+
+    if (route.sampleInput) {
+      const input = route.sampleInput as Record<string, unknown>;
+      const body = input.body || input;
+      if (body && typeof body === "object" && Object.keys(body as object).length > 0) {
+        entry.request = body;
+      }
+    }
+
+    samples[key] = entry;
+  }
+
+  return JSON.stringify(samples, null, 2) + "\n";
+}
+
+// ── TypeScript constants ──
+
+function generateTypeScript(routes: MockRoute[]): string {
+  const lines: string[] = [];
+  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 as Record<string, unknown>;
+      const body = input.body || input;
+      if (body && typeof body === "object" && Object.keys(body as object).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: MockRoute[]): string {
+  const lines: string[] = [];
+  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 as Record<string, unknown>;
+      const body = input.body || input;
+      if (body && typeof body === "object" && Object.keys(body as object).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 as Record<string, unknown>;
+      const body = input.body || input;
+      if (body && typeof body === "object" && !Array.isArray(body) && Object.keys(body as object).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: unknown, indent: number): string {
+  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 as Record<string, unknown>;
+    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/src/commands/search.ts

@@ -0,0 +1,107 @@
+import chalk from "chalk";
+import { getBackendUrl } from "../config";
+
+export interface SearchOptions {
+  env?: string;
+  json?: boolean;
+}
+
+interface FieldMatch {
+  path: string;
+  kind: string;
+  typeName?: string;
+}
+
+interface SearchResult {
+  functionName: string;
+  module: string;
+  environment: string;
+  lastSeen: string;
+  matches: FieldMatch[];
+}
+
+interface SearchResponse {
+  query: string;
+  total: number;
+  results: SearchResult[];
+}
+
+export async function searchCommand(
+  query: string,
+  opts: SearchOptions,
+): Promise<void> {
+  const backendUrl = getBackendUrl();
+  const url = new URL("/api/search", backendUrl);
+  url.searchParams.set("q", query);
+  if (opts.env) {
+    url.searchParams.set("env", opts.env);
+  }
+
+  let data: SearchResponse;
+  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() as SearchResponse;
+  } catch (err: unknown) {
+    if (err instanceof Error && err.message.startsWith("HTTP ")) {
+      console.error(chalk.red(`\n  Error: ${err.message}\n`));
+    } else {
+      console.error(chalk.red(`\n  Cannot connect to trickle backend at ${chalk.bold(backendUrl)}.`));
+      console.error(chalk.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.bold(`  Search: "${query}"`));
+  console.log(chalk.gray("  " + "─".repeat(50)));
+
+  if (data.total === 0) {
+    console.log(chalk.gray("  No matches found.\n"));
+    return;
+  }
+
+  console.log(chalk.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: Record<string, (s: string) => string> = {
+        GET: chalk.green,
+        POST: chalk.yellow,
+        PUT: chalk.blue,
+        PATCH: chalk.cyan,
+        DELETE: chalk.red,
+      };
+      const colorFn = methodColors[method] || chalk.white;
+      console.log(`  ${colorFn(chalk.bold(method))}${chalk.white(rest)}`);
+    } else {
+      console.log(`  ${chalk.white(chalk.bold(fnName))}`);
+    }
+
+    console.log(chalk.gray(`  module: ${result.module}  env: ${result.environment}`));
+
+    // Show matching fields
+    for (const match of result.matches) {
+      const typeStr = match.typeName ? chalk.cyan(match.typeName) : chalk.gray(match.kind);
+      if (match.kind === "name") {
+        console.log(chalk.gray("    → ") + chalk.yellow("function name match"));
+      } else {
+        console.log(chalk.gray("    → ") + chalk.white(match.path) + chalk.gray(": ") + typeStr);
+      }
+    }
+    console.log("");
+  }
+}

package/src/commands/stubs.ts

@@ -0,0 +1,211 @@
+import * as fs from "fs";
+import * as path from "path";
+import chalk from "chalk";
+import { fetchStubs } from "../api-client";
+
+export interface StubsOptions {
+  env?: string;
+  dryRun?: boolean;
+  silent?: boolean;
+}
+
+/**
+ * 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: string): string {
+  return name.replace(/[-_]/g, "").toLowerCase();
+}
+
+/**
+ * Recursively find all source files in a directory.
+ */
+function findSourceFiles(dir: string): string[] {
+  const results: string[] = [];
+  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;
+}
+
+export async function stubsCommand(
+  dir: string,
+  opts: StubsOptions,
+): Promise<void> {
+  const targetDir = path.resolve(dir);
+
+  if (!fs.existsSync(targetDir)) {
+    console.error(chalk.red(`\n  Directory not found: ${targetDir}\n`));
+    process.exit(1);
+  }
+
+  if (!fs.statSync(targetDir).isDirectory()) {
+    console.error(chalk.red(`\n  Not a directory: ${targetDir}\n`));
+    process.exit(1);
+  }
+
+  // Fetch per-module stubs from backend
+  const { stubs } = await fetchStubs({ env: opts.env });
+
+  if (!stubs || Object.keys(stubs).length === 0) {
+    if (!opts.silent) {
+      console.log(
+        chalk.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.yellow(`\n  No source files found in ${targetDir}\n`),
+      );
+    }
+    return;
+  }
+
+  // Build a map: normalized stem → source file path
+  const fileMap: Map<string, string[]> = 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: string[] = [];
+  const writtenPaths = new Set<string>();
+  const skipped: string[] = [];
+
+  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.cyan(`  Would create: ${relPath}`));
+        console.log(
+          chalk.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.cyan("  Dry run — no files written.\n"));
+    if (written.length > 0) {
+      console.log(chalk.gray(`  ${written.length} stub file(s) would be created.\n`));
+    }
+  } else if (written.length > 0) {
+    console.log(chalk.green(`  Generated ${written.length} type stub file(s):\n`));
+    for (const f of written) {
+      console.log(chalk.gray(`    ${f}`));
+    }
+    console.log();
+    console.log(
+      chalk.gray(
+        "  Your IDE should now pick up these types automatically.",
+      ),
+    );
+    console.log(
+      chalk.gray(
+        "  Add *.d.ts / *.pyi to .gitignore if you don't want to commit them.",
+      ),
+    );
+    console.log();
+  } else {
+    console.log(
+      chalk.yellow(
+        "  No matching source files found for observed modules.\n",
+      ),
+    );
+    if (skipped.length > 0) {
+      console.log(
+        chalk.gray(
+          `  Observed modules: ${skipped.join(", ")}`,
+        ),
+      );
+      console.log(
+        chalk.gray(
+          `  Source files in: ${path.relative(process.cwd(), targetDir) || "."}`,
+        ),
+      );
+      console.log(
+        chalk.gray(
+          "  Make sure module names match file names (e.g., module 'helpers' → helpers.js)\n",
+        ),
+      );
+    }
+  }
+}

package/src/commands/tail.ts

@@ -0,0 +1,94 @@
+import chalk from "chalk";
+import { tailEvents, TailEvent } from "../api-client";
+import { envBadge, timeBadge } from "../ui/badges";
+import { getBackendUrl } from "../config";
+
+export interface TailOptions {
+  filter?: string;
+}
+
+function eventBadge(event: string): string {
+  const lower = event.toLowerCase();
+  if (lower === "error" || lower.includes("error")) {
+    return chalk.bgRed.white.bold(" ERROR ");
+  }
+  if (lower === "new_type" || lower.includes("new")) {
+    return chalk.bgGreen.black.bold(" NEW_TYPE ");
+  }
+  if (lower === "type_changed" || lower.includes("changed")) {
+    return chalk.bgYellow.black.bold(" TYPE_CHANGED ");
+  }
+  if (lower === "ingest" || lower.includes("ingest")) {
+    return chalk.bgBlue.white.bold(" INGEST ");
+  }
+  return chalk.bgGray.white.bold(` ${event.toUpperCase()} `);
+}
+
+function formatEventDetail(event: TailEvent): string {
+  const data = event.data;
+  const parts: string[] = [];
+
+  if (data.functionName) {
+    parts.push(chalk.white.bold(String(data.functionName)));
+  }
+
+  if (data.module) {
+    parts.push(chalk.gray(`(${data.module})`));
+  }
+
+  if (data.env) {
+    parts.push(envBadge(String(data.env)));
+  }
+
+  if (data.error && typeof data.error === "object") {
+    const err = data.error as Record<string, unknown>;
+    if (err.message) {
+      parts.push(chalk.red(String(err.message)));
+    }
+  }
+
+  if (data.error_message) {
+    parts.push(chalk.red(String(data.error_message)));
+  }
+
+  return parts.join("  ");
+}
+
+export async function tailCommand(opts: TailOptions): Promise<void> {
+  const url = getBackendUrl();
+  console.log(chalk.gray(`\n  Connecting to trickle at ${url}...`));
+
+  const cleanup = tailEvents(
+    (event: TailEvent) => {
+      const now = new Date().toISOString();
+      const timeStr = chalk.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.green("  Listening for events...") + chalk.gray(" (Ctrl+C to stop)\n"));
+  }, 500);
+
+  // Keep the process alive and handle graceful shutdown
+  const onSignal = () => {
+    console.log(chalk.gray("\n  Disconnected.\n"));
+    cleanup();
+    process.exit(0);
+  };
+
+  process.on("SIGINT", onSignal);
+  process.on("SIGTERM", onSignal);
+
+  // Keep the event loop alive
+  await new Promise<void>(() => {
+    // Never resolves — the process stays alive until killed
+  });
+}