trickle-cli 0.1.0

package/src/commands/types.ts

@@ -0,0 +1,161 @@
+import chalk from "chalk";
+import { listFunctions, listTypes, getTypeDiff } from "../api-client";
+import { formatType } from "../formatters/type-formatter";
+import { formatDiffs } from "../formatters/diff-formatter";
+import { envBadge, timeBadge } from "../ui/badges";
+
+export interface TypesOptions {
+  env?: string;
+  diff?: boolean;
+  env1?: string;
+  env2?: string;
+}
+
+export async function typesCommand(functionName: string, opts: TypesOptions): Promise<void> {
+  // Look up function by name (partial match)
+  const result = await listFunctions({ search: functionName });
+  const { functions } = result;
+
+  if (functions.length === 0) {
+    console.log(chalk.yellow(`\n  No function found matching "${functionName}".\n`));
+    return;
+  }
+
+  // Prefer exact match, then first partial match
+  const exactMatch = functions.find(
+    (f) => f.function_name === functionName || f.function_name.toLowerCase() === functionName.toLowerCase()
+  );
+  const fn = exactMatch || functions[0];
+
+  if (!exactMatch && functions.length > 1) {
+    console.log(
+      chalk.gray(`\n  Multiple matches found, showing results for "${chalk.white(fn.function_name)}"`)
+    );
+    console.log(
+      chalk.gray(
+        `  Other matches: ${functions
+          .slice(1, 5)
+          .map((f) => f.function_name)
+          .join(", ")}${functions.length > 5 ? "..." : ""}\n`
+      )
+    );
+  }
+
+  // Diff mode
+  if (opts.diff) {
+    await showDiff(fn.id, fn.function_name, opts);
+    return;
+  }
+
+  // Normal mode: show type snapshots
+  const typesResult = await listTypes(fn.id, { env: opts.env });
+  const { snapshots } = typesResult;
+
+  if (snapshots.length === 0) {
+    console.log(chalk.yellow(`\n  No type snapshots found for "${fn.function_name}".\n`));
+    return;
+  }
+
+  console.log("");
+  console.log(chalk.white.bold(`  ${fn.function_name}`) + chalk.gray(` (${fn.module})`));
+  console.log(chalk.gray("  " + "─".repeat(50)));
+
+  for (const snapshot of snapshots) {
+    console.log("");
+    console.log(
+      `  ${envBadge(snapshot.env)}  ${timeBadge(snapshot.observed_at)}`
+    );
+    console.log("");
+
+    // Display function signature
+    console.log(chalk.gray("  args: ") + formatType(snapshot.args_type, 4));
+    console.log(chalk.gray("  returns: ") + formatType(snapshot.return_type, 4));
+
+    if (snapshot.sample_input !== undefined && snapshot.sample_input !== null) {
+      console.log("");
+      console.log(chalk.gray("  sample input:"));
+      console.log(chalk.gray("  ") + colorizeJson(snapshot.sample_input, 4));
+    }
+
+    if (snapshot.sample_output !== undefined && snapshot.sample_output !== null) {
+      console.log(chalk.gray("  sample output:"));
+      console.log(chalk.gray("  ") + colorizeJson(snapshot.sample_output, 4));
+    }
+  }
+
+  console.log("");
+}
+
+async function showDiff(functionId: number, functionName: string, opts: TypesOptions): Promise<void> {
+  try {
+    let diffResult;
+
+    if (opts.env1 && opts.env2) {
+      diffResult = await getTypeDiff(functionId, {
+        fromEnv: opts.env1,
+        toEnv: opts.env2,
+      });
+    } else {
+      // Get latest two snapshots and diff by their IDs
+      const typesResult = await listTypes(functionId, { limit: 2 });
+      const { snapshots } = typesResult;
+
+      if (snapshots.length < 2) {
+        console.log(chalk.yellow(`\n  Not enough snapshots to diff for "${functionName}".`));
+        console.log(chalk.gray("  Need at least 2 snapshots. Try specifying --env1 and --env2.\n"));
+        return;
+      }
+
+      diffResult = await getTypeDiff(functionId, {
+        from: snapshots[1].id,
+        to: snapshots[0].id,
+      });
+    }
+
+    console.log("");
+    console.log(chalk.white.bold(`  Type diff for ${functionName}`));
+    console.log(chalk.gray("  " + "─".repeat(50)));
+    console.log("");
+
+    console.log(
+      chalk.gray("  from: ") +
+        envBadge(diffResult.from.env) +
+        chalk.gray("  " + diffResult.from.observed_at)
+    );
+    console.log(
+      chalk.gray("  to:   ") +
+        envBadge(diffResult.to.env) +
+        chalk.gray("  " + diffResult.to.observed_at)
+    );
+    console.log("");
+
+    if (diffResult.diffs.length === 0) {
+      console.log(chalk.green("  No type differences found.\n"));
+    } else {
+      console.log(formatDiffs(diffResult.diffs));
+      console.log("");
+    }
+  } catch (err: unknown) {
+    if (err instanceof Error) {
+      console.error(chalk.red(`\n  Error: ${err.message}\n`));
+    }
+  }
+}
+
+function colorizeJson(value: unknown, indent: number = 0): string {
+  const json = JSON.stringify(value, null, 2);
+  if (!json) return chalk.gray("null");
+
+  return json
+    .split("\n")
+    .map((line, i) => {
+      const padded = i === 0 ? line : " ".repeat(indent) + line;
+      return padded
+        .replace(/"([^"]+)":/g, (_, key) => `${chalk.white(`"${key}"`)}:`)
+        .replace(/: "([^"]*)"/g, (_, val) => `: ${chalk.green(`"${val}"`)}`)
+        .replace(/: (\d+\.?\d*)/g, (_, val) => `: ${chalk.yellow(val)}`)
+        .replace(/: (true|false)/g, (_, val) => `: ${chalk.blue(val)}`)
+        .replace(/: (null)/g, (_, val) => `: ${chalk.gray(val)}`);
+    })
+    .join("\n");
+}

package/src/commands/unpack.ts

@@ -0,0 +1,179 @@
+import * as fs from "fs";
+import * as crypto from "crypto";
+import chalk from "chalk";
+import { getBackendUrl } from "../config";
+
+export interface UnpackOptions {
+  env?: string;
+  dryRun?: boolean;
+}
+
+interface PackedSnapshot {
+  typeHash: string;
+  env: string;
+  argsType: unknown;
+  returnType: unknown;
+  sampleInput?: unknown;
+  sampleOutput?: unknown;
+  observedAt: string;
+}
+
+interface PackedFunction {
+  functionName: string;
+  module: string;
+  language: string;
+  environment: string;
+  snapshots: PackedSnapshot[];
+}
+
+interface PackBundle {
+  version: number;
+  createdAt: string;
+  source: string;
+  functions: PackedFunction[];
+  stats: {
+    totalFunctions: number;
+    totalSnapshots: number;
+  };
+}
+
+/**
+ * `trickle unpack <file>` — Import types from a packed bundle into the backend.
+ *
+ * Reads a .trickle.json bundle (created by `trickle pack`) and ingests
+ * all functions and their type snapshots into the backend.
+ */
+export async function unpackCommand(
+  file: string,
+  opts: UnpackOptions,
+): Promise<void> {
+  const backendUrl = getBackendUrl();
+
+  // Read and parse the bundle
+  if (!fs.existsSync(file)) {
+    console.error(chalk.red(`\n  File not found: ${file}\n`));
+    process.exit(1);
+  }
+
+  let bundle: PackBundle;
+  try {
+    const content = fs.readFileSync(file, "utf-8");
+    bundle = JSON.parse(content) as PackBundle;
+  } catch {
+    console.error(chalk.red("\n  Invalid bundle file — expected JSON.\n"));
+    process.exit(1);
+  }
+
+  // Validate bundle structure
+  if (!bundle.version || !bundle.functions || !Array.isArray(bundle.functions)) {
+    console.error(chalk.red("\n  Invalid bundle format — missing required fields.\n"));
+    process.exit(1);
+  }
+
+  if (bundle.version !== 1) {
+    console.error(chalk.red(`\n  Unsupported bundle version: ${bundle.version}\n`));
+    process.exit(1);
+  }
+
+  console.log("");
+  console.log(chalk.bold("  trickle unpack"));
+  console.log(chalk.gray("  " + "─".repeat(50)));
+  console.log(chalk.gray(`  File:     ${file}`));
+  console.log(chalk.gray(`  Created:  ${bundle.createdAt}`));
+  console.log(chalk.gray(`  Source:   ${bundle.source}`));
+  console.log(chalk.gray(`  Contains: ${bundle.functions.length} functions, ${bundle.stats.totalSnapshots} snapshots`));
+  console.log(chalk.gray("  " + "─".repeat(50)));
+
+  if (opts.dryRun) {
+    console.log("");
+    console.log(chalk.yellow("  Dry run — listing contents without importing:"));
+    console.log("");
+    for (const fn of bundle.functions) {
+      console.log(
+        chalk.white(`  ${fn.functionName}`) +
+        chalk.gray(` (${fn.module}, ${fn.language}, ${fn.snapshots.length} snapshot${fn.snapshots.length === 1 ? "" : "s"})`),
+      );
+    }
+    console.log("");
+    console.log(chalk.gray(`  ${bundle.functions.length} functions would be imported.`));
+    console.log(chalk.gray("  Remove --dry-run to import.\n"));
+    return;
+  }
+
+  // Check backend connectivity
+  try {
+    const res = await fetch(`${backendUrl}/api/health`, { signal: AbortSignal.timeout(3000) });
+    if (!res.ok) throw new Error("not ok");
+  } catch {
+    console.error(chalk.red(`\n  Cannot reach trickle backend at ${chalk.bold(backendUrl)}\n`));
+    process.exit(1);
+  }
+
+  console.log("");
+
+  // Ingest each function's snapshots
+  let imported = 0;
+  let skipped = 0;
+  let errors = 0;
+
+  for (const fn of bundle.functions) {
+    // Use the latest snapshot for ingest
+    const snapshot = fn.snapshots[0];
+    if (!snapshot) {
+      skipped++;
+      continue;
+    }
+
+    const env = opts.env || snapshot.env || fn.environment;
+    const typeHash = snapshot.typeHash || computeTypeHash(snapshot.argsType, snapshot.returnType);
+
+    const payload = {
+      functionName: fn.functionName,
+      module: fn.module,
+      language: fn.language,
+      environment: env,
+      typeHash,
+      argsType: snapshot.argsType,
+      returnType: snapshot.returnType,
+      sampleInput: snapshot.sampleInput,
+      sampleOutput: snapshot.sampleOutput,
+    };
+
+    try {
+      const res = await fetch(`${backendUrl}/api/ingest`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(payload),
+        signal: AbortSignal.timeout(5000),
+      });
+      if (!res.ok) throw new Error(`HTTP ${res.status}`);
+      imported++;
+      console.log(chalk.green("  ✓ ") + chalk.white(fn.functionName));
+    } catch {
+      errors++;
+      console.log(chalk.red("  ✗ ") + chalk.white(fn.functionName) + chalk.gray(" (failed)"));
+    }
+  }
+
+  console.log("");
+  console.log(chalk.gray("  " + "─".repeat(50)));
+
+  if (imported > 0) {
+    console.log(chalk.green(`  ${imported} functions imported successfully`));
+  }
+  if (skipped > 0) {
+    console.log(chalk.yellow(`  ${skipped} skipped (no snapshots)`));
+  }
+  if (errors > 0) {
+    console.log(chalk.red(`  ${errors} failed`));
+  }
+
+  console.log("");
+  console.log(chalk.gray("  Run ") + chalk.white("trickle overview") + chalk.gray(" to see imported types."));
+  console.log("");
+}
+
+function computeTypeHash(argsType: unknown, returnType: unknown): string {
+  const data = JSON.stringify({ a: argsType, r: returnType });
+  return crypto.createHash("sha256").update(data).digest("hex").slice(0, 16);
+}

package/src/commands/validate.ts

@@ -0,0 +1,368 @@
+import chalk from "chalk";
+import { getBackendUrl } from "../config";
+
+export interface ValidateOptions {
+  header?: string[];
+  body?: string;
+  env?: string;
+  strict?: boolean;
+}
+
+interface TypeNode {
+  kind: string;
+  [key: string]: unknown;
+}
+
+interface Mismatch {
+  path: string;
+  issue: "missing" | "extra" | "type_mismatch" | "kind_mismatch";
+  expected?: string;
+  actual?: string;
+}
+
+/**
+ * `trickle validate <method> <url>` — Validate a live API response against observed types.
+ *
+ * Makes an HTTP request, infers types from the response, fetches the stored
+ * type for that route from the backend, and reports any mismatches.
+ */
+export async function validateCommand(
+  method: string,
+  url: string,
+  opts: ValidateOptions,
+): Promise<void> {
+  const backendUrl = getBackendUrl();
+
+  const httpMethod = method.toUpperCase();
+  const validMethods = ["GET", "POST", "PUT", "PATCH", "DELETE"];
+  if (!validMethods.includes(httpMethod)) {
+    console.error(chalk.red(`\n  Invalid HTTP method: ${method}\n`));
+    process.exit(1);
+  }
+
+  let parsedUrl: URL;
+  try {
+    parsedUrl = new URL(url);
+  } catch {
+    console.error(chalk.red(`\n  Invalid URL: ${url}\n`));
+    process.exit(1);
+  }
+
+  // Check backend
+  try {
+    const res = await fetch(`${backendUrl}/api/health`, { signal: AbortSignal.timeout(3000) });
+    if (!res.ok) throw new Error("not ok");
+  } catch {
+    console.error(chalk.red(`\n  Cannot reach trickle backend at ${chalk.bold(backendUrl)}\n`));
+    process.exit(1);
+  }
+
+  // Build request headers
+  const headers: Record<string, string> = { Accept: "application/json" };
+  if (opts.header) {
+    for (const h of opts.header) {
+      const colonIdx = h.indexOf(":");
+      if (colonIdx === -1) {
+        console.error(chalk.red(`\n  Invalid header: ${h}\n`));
+        process.exit(1);
+      }
+      headers[h.slice(0, colonIdx).trim()] = h.slice(colonIdx + 1).trim();
+    }
+  }
+
+  let reqBody: string | undefined;
+  if (opts.body) {
+    reqBody = opts.body;
+    headers["Content-Type"] = headers["Content-Type"] || "application/json";
+  }
+
+  console.log("");
+  console.log(chalk.bold("  trickle validate"));
+  console.log(chalk.gray("  " + "─".repeat(50)));
+  console.log(chalk.gray(`  ${chalk.bold(httpMethod)} ${url}`));
+
+  // Make the request
+  let response: Response;
+  try {
+    response = await fetch(url, {
+      method: httpMethod,
+      headers,
+      body: reqBody,
+      signal: AbortSignal.timeout(30000),
+    });
+  } catch (err: unknown) {
+    const msg = err instanceof Error ? err.message : "Unknown error";
+    console.error(chalk.red(`\n  Request failed: ${msg}\n`));
+    process.exit(1);
+  }
+
+  const status = response.status;
+  const statusColor = status < 400 ? chalk.green : chalk.red;
+  console.log(chalk.gray(`  Status:   `) + statusColor(`${status} ${response.statusText}`));
+
+  // Parse response
+  const resText = await response.text();
+  let resJson: unknown;
+  const contentType = response.headers.get("content-type") || "";
+  if (contentType.includes("json") && resText.length > 0) {
+    try {
+      resJson = JSON.parse(resText);
+    } catch {
+      console.error(chalk.red("\n  Response is not valid JSON.\n"));
+      process.exit(1);
+    }
+  } else {
+    console.error(chalk.red("\n  Response is not JSON.\n"));
+    process.exit(1);
+  }
+
+  // Normalize path and find stored types
+  const routePath = normalizePath(parsedUrl.pathname);
+  const functionName = `${httpMethod} ${routePath}`;
+  console.log(chalk.gray(`  Route:    `) + chalk.white(functionName));
+
+  // Fetch stored function from backend
+  const funcsRes = await fetch(
+    `${backendUrl}/api/functions?q=${encodeURIComponent(functionName)}&limit=100`,
+    { signal: AbortSignal.timeout(5000) },
+  );
+  const funcsData = await funcsRes.json() as { functions: Array<{ id: number; function_name: string }> };
+
+  const matchedFunc = funcsData.functions.find(
+    (f) => f.function_name === functionName,
+  );
+
+  if (!matchedFunc) {
+    console.log(chalk.gray("  " + "─".repeat(50)));
+    console.log(chalk.yellow("  No previously observed types for this route."));
+    console.log(chalk.gray("  Run ") + chalk.white("trickle capture") + chalk.gray(" first to establish a baseline.\n"));
+    process.exit(1);
+  }
+
+  // Fetch latest type snapshot
+  const envQuery = opts.env ? `&env=${encodeURIComponent(opts.env)}` : "";
+  const typesRes = await fetch(
+    `${backendUrl}/api/types/${matchedFunc.id}?limit=1${envQuery}`,
+    { signal: AbortSignal.timeout(5000) },
+  );
+  const typesData = await typesRes.json() as {
+    snapshots: Array<{ return_type: string; observed_at: string }>;
+  };
+
+  if (!typesData.snapshots || typesData.snapshots.length === 0) {
+    console.log(chalk.yellow("  No type snapshots found for this route.\n"));
+    process.exit(1);
+  }
+
+  const snapshot = typesData.snapshots[0];
+  let expectedType: TypeNode;
+  try {
+    expectedType = (typeof snapshot.return_type === 'string'
+      ? JSON.parse(snapshot.return_type)
+      : snapshot.return_type) as TypeNode;
+  } catch {
+    console.error(chalk.red("  Cannot parse stored type snapshot.\n"));
+    process.exit(1);
+  }
+
+  console.log(chalk.gray(`  Baseline: `) + chalk.gray(`observed ${snapshot.observed_at}`));
+  console.log(chalk.gray("  " + "─".repeat(50)));
+
+  // Infer type from actual response
+  const actualType = jsonToTypeNode(resJson);
+
+  // Compare
+  const mismatches: Mismatch[] = [];
+  compareTypes(expectedType, actualType, "response", mismatches, opts.strict || false);
+
+  if (mismatches.length === 0) {
+    console.log(chalk.green("\n  ✓ Response matches observed type shape\n"));
+    console.log(chalk.gray("  All fields present with expected types.\n"));
+  } else {
+    console.log(chalk.red(`\n  ✗ ${mismatches.length} mismatch${mismatches.length === 1 ? "" : "es"} found\n`));
+
+    for (const m of mismatches) {
+      switch (m.issue) {
+        case "missing":
+          console.log(
+            chalk.red("  MISSING ") +
+            chalk.white(m.path) +
+            chalk.gray(` (expected ${m.expected})`),
+          );
+          break;
+        case "extra":
+          console.log(
+            chalk.yellow("  EXTRA   ") +
+            chalk.white(m.path) +
+            chalk.gray(` (${m.actual}, not in observed types)`),
+          );
+          break;
+        case "type_mismatch":
+          console.log(
+            chalk.red("  TYPE    ") +
+            chalk.white(m.path) +
+            chalk.gray(` (expected ${m.expected}, got ${m.actual})`),
+          );
+          break;
+        case "kind_mismatch":
+          console.log(
+            chalk.red("  SHAPE   ") +
+            chalk.white(m.path) +
+            chalk.gray(` (expected ${m.expected}, got ${m.actual})`),
+          );
+          break;
+      }
+    }
+
+    const errors = mismatches.filter((m) => m.issue !== "extra");
+    const warnings = mismatches.filter((m) => m.issue === "extra");
+
+    console.log("");
+    if (errors.length > 0) {
+      console.log(chalk.red(`  ${errors.length} error${errors.length === 1 ? "" : "s"}`) +
+        (warnings.length > 0 ? chalk.yellow(`, ${warnings.length} warning${warnings.length === 1 ? "" : "s"}`) : ""));
+    } else {
+      console.log(chalk.yellow(`  ${warnings.length} warning${warnings.length === 1 ? "" : "s"} (extra fields only)`));
+    }
+    console.log("");
+
+    if (errors.length > 0) {
+      process.exitCode = 1;
+    }
+  }
+}
+
+/**
+ * Recursively compare expected vs actual TypeNode.
+ */
+function compareTypes(
+  expected: TypeNode,
+  actual: TypeNode,
+  path: string,
+  mismatches: Mismatch[],
+  strict: boolean,
+): void {
+  // Kind mismatch
+  if (expected.kind !== actual.kind) {
+    // Special case: unknown expected matches anything
+    if (expected.kind === "unknown") return;
+    // Special case: expected primitive null matches any actual (nullable)
+    if (expected.kind === "primitive" && (expected as unknown as { name: string }).name === "null") return;
+
+    mismatches.push({
+      path,
+      issue: "kind_mismatch",
+      expected: describeType(expected),
+      actual: describeType(actual),
+    });
+    return;
+  }
+
+  switch (expected.kind) {
+    case "primitive": {
+      const expectedName = (expected as unknown as { name: string }).name;
+      const actualName = (actual as unknown as { name: string }).name;
+      if (expectedName !== actualName) {
+        mismatches.push({
+          path,
+          issue: "type_mismatch",
+          expected: expectedName,
+          actual: actualName,
+        });
+      }
+      break;
+    }
+
+    case "object": {
+      const expectedProps = expected.properties as Record<string, TypeNode>;
+      const actualProps = actual.properties as Record<string, TypeNode>;
+
+      // Check for missing fields
+      for (const key of Object.keys(expectedProps)) {
+        if (!(key in actualProps)) {
+          mismatches.push({
+            path: `${path}.${key}`,
+            issue: "missing",
+            expected: describeType(expectedProps[key]),
+          });
+        } else {
+          compareTypes(expectedProps[key], actualProps[key], `${path}.${key}`, mismatches, strict);
+        }
+      }
+
+      // Check for extra fields (warnings in non-strict, errors in strict)
+      if (strict) {
+        for (const key of Object.keys(actualProps)) {
+          if (!(key in expectedProps)) {
+            mismatches.push({
+              path: `${path}.${key}`,
+              issue: "extra",
+              actual: describeType(actualProps[key]),
+            });
+          }
+        }
+      }
+      break;
+    }
+
+    case "array": {
+      const expectedElement = expected.element as TypeNode;
+      const actualElement = actual.element as TypeNode;
+      if (expectedElement.kind !== "unknown" && actualElement.kind !== "unknown") {
+        compareTypes(expectedElement, actualElement, `${path}[]`, mismatches, strict);
+      }
+      break;
+    }
+
+    case "union": {
+      // For unions, check that actual matches at least one member
+      // Simplified: just skip deep comparison for unions
+      break;
+    }
+  }
+}
+
+function describeType(node: TypeNode): string {
+  switch (node.kind) {
+    case "primitive":
+      return (node as unknown as { name: string }).name;
+    case "object":
+      return "object";
+    case "array":
+      return `${describeType(node.element as TypeNode)}[]`;
+    case "union":
+      return (node.members as TypeNode[]).map(describeType).join(" | ");
+    default:
+      return node.kind;
+  }
+}
+
+function jsonToTypeNode(value: unknown): TypeNode {
+  if (value === null) return { kind: "primitive", name: "null" };
+  if (value === undefined) return { kind: "primitive", name: "undefined" };
+  switch (typeof value) {
+    case "string": return { kind: "primitive", name: "string" };
+    case "number": return { kind: "primitive", name: "number" };
+    case "boolean": return { kind: "primitive", name: "boolean" };
+  }
+  if (Array.isArray(value)) {
+    if (value.length === 0) return { kind: "array", element: { kind: "unknown" } };
+    return { kind: "array", element: jsonToTypeNode(value[0]) };
+  }
+  const obj = value as Record<string, unknown>;
+  const properties: Record<string, TypeNode> = {};
+  for (const [key, val] of Object.entries(obj)) {
+    properties[key] = jsonToTypeNode(val);
+  }
+  return { kind: "object", properties };
+}
+
+function normalizePath(urlPath: string): string {
+  return urlPath.split("/").map((part, i) => {
+    if (!part) return part;
+    if (/^\d+$/.test(part)) return ":id";
+    if (/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(part)) return ":id";
+    if (/^[0-9a-f]{16,}$/i.test(part) && i > 1) return ":id";
+    return part;
+  }).join("/");
+}