trickle-cli 0.1.0

package/src/commands/export.ts

@@ -0,0 +1,287 @@
+import * as fs from "fs";
+import * as path from "path";
+import chalk from "chalk";
+import { fetchCodegen, fetchOpenApiSpec, fetchMockConfig } from "../api-client";
+import { testGenCommand } from "./test-gen";
+
+export interface ExportOptions {
+  dir?: string;
+  env?: string;
+}
+
+interface ExportResult {
+  file: string;
+  label: string;
+  ok: boolean;
+  count?: string;
+}
+
+/**
+ * `trickle export` — Generate all output formats into a directory at once.
+ *
+ * Creates a complete `.trickle/` directory with:
+ * - types.d.ts — TypeScript type declarations
+ * - api-client.ts — Typed fetch-based API client
+ * - handlers.d.ts — Express handler type aliases
+ * - schemas.ts — Zod validation schemas
+ * - hooks.ts — TanStack React Query hooks
+ * - guards.ts — Runtime type guard functions
+ * - openapi.json — OpenAPI 3.0 specification
+ * - api.test.ts — Generated API test scaffolds
+ */
+export async function exportCommand(opts: ExportOptions): Promise<void> {
+  const outDir = path.resolve(opts.dir || ".trickle");
+
+  // Ensure directory exists
+  if (!fs.existsSync(outDir)) {
+    fs.mkdirSync(outDir, { recursive: true });
+  }
+
+  console.log("");
+  console.log(chalk.bold("  trickle export"));
+  console.log(chalk.gray("  " + "─".repeat(50)));
+  console.log(chalk.gray(`  Output directory: ${outDir}`));
+  if (opts.env) {
+    console.log(chalk.gray(`  Environment: ${opts.env}`));
+  }
+  console.log(chalk.gray("  " + "─".repeat(50)));
+  console.log("");
+
+  const results: ExportResult[] = [];
+  const queryOpts = { env: opts.env };
+
+  // 1. TypeScript types
+  results.push(await generateFile(
+    path.join(outDir, "types.d.ts"),
+    "TypeScript types",
+    () => fetchCodegen({ ...queryOpts }).then((r) => r.types),
+    countInterfaces,
+  ));
+
+  // 2. API client
+  results.push(await generateFile(
+    path.join(outDir, "api-client.ts"),
+    "Typed API client",
+    () => fetchCodegen({ ...queryOpts, format: "client" }).then((r) => r.types),
+    countFunctions,
+  ));
+
+  // 3. Express handler types
+  results.push(await generateFile(
+    path.join(outDir, "handlers.d.ts"),
+    "Express handler types",
+    () => fetchCodegen({ ...queryOpts, format: "handlers" }).then((r) => r.types),
+    countHandlers,
+  ));
+
+  // 4. Zod schemas
+  results.push(await generateFile(
+    path.join(outDir, "schemas.ts"),
+    "Zod schemas",
+    () => fetchCodegen({ ...queryOpts, format: "zod" }).then((r) => r.types),
+    countSchemas,
+  ));
+
+  // 5. React Query hooks
+  results.push(await generateFile(
+    path.join(outDir, "hooks.ts"),
+    "React Query hooks",
+    () => fetchCodegen({ ...queryOpts, format: "react-query" }).then((r) => r.types),
+    countHooks,
+  ));
+
+  // 6. Type guards
+  results.push(await generateFile(
+    path.join(outDir, "guards.ts"),
+    "Type guards",
+    () => fetchCodegen({ ...queryOpts, format: "guards" }).then((r) => r.types),
+    countGuards,
+  ));
+
+  // OpenAPI spec
+  results.push(await generateFile(
+    path.join(outDir, "openapi.json"),
+    "OpenAPI 3.0 spec",
+    async () => {
+      const spec = await fetchOpenApiSpec({ env: opts.env });
+      return JSON.stringify(spec, null, 2);
+    },
+    countPaths,
+  ));
+
+  // API tests
+  results.push(await generateFile(
+    path.join(outDir, "api.test.ts"),
+    "API test scaffolds",
+    async () => {
+      const { routes } = await fetchMockConfig();
+      if (routes.length === 0) return null;
+      // Use the testGenCommand's internal logic by fetching via codegen format?
+      // Actually, let's generate a simple version directly
+      return generateTestContent(routes);
+    },
+    countTests,
+  ));
+
+  // Summary
+  console.log("");
+  const successCount = results.filter((r) => r.ok).length;
+  const skipCount = results.filter((r) => !r.ok).length;
+
+  for (const r of results) {
+    if (r.ok) {
+      const countStr = r.count ? chalk.gray(` (${r.count})`) : "";
+      console.log(chalk.green("  ✓ ") + chalk.bold(r.file) + countStr);
+    } else {
+      console.log(chalk.yellow("  ─ ") + chalk.gray(r.file) + chalk.gray(" (skipped — no data)"));
+    }
+  }
+
+  console.log("");
+  if (successCount > 0) {
+    console.log(chalk.green(`  ${successCount} files generated`) + (skipCount > 0 ? chalk.gray(`, ${skipCount} skipped`) : ""));
+  } else {
+    console.log(chalk.yellow("  No files generated — instrument your app and make some requests first."));
+  }
+  console.log("");
+}
+
+async function generateFile(
+  filePath: string,
+  label: string,
+  generator: () => Promise<string | null>,
+  counter: (content: string) => string | undefined,
+): Promise<ExportResult> {
+  const fileName = path.basename(filePath);
+  try {
+    const content = await generator();
+    if (!content || content.includes("No functions found") || content.includes("No API routes found") || content.includes("No observations")) {
+      return { file: fileName, label, ok: false };
+    }
+
+    fs.writeFileSync(filePath, content, "utf-8");
+    const count = counter(content);
+    return { file: fileName, label, ok: true, count };
+  } catch {
+    return { file: fileName, label, ok: false };
+  }
+}
+
+function countInterfaces(content: string): string | undefined {
+  const count = (content.match(/export (interface|type) /g) || []).length;
+  return count > 0 ? `${count} types` : undefined;
+}
+
+function countFunctions(content: string): string | undefined {
+  if (content.includes("createTrickleClient")) return "client factory";
+  return undefined;
+}
+
+function countHandlers(content: string): string | undefined {
+  const count = (content.match(/export type \w+Handler/g) || []).length;
+  return count > 0 ? `${count} handlers` : undefined;
+}
+
+function countSchemas(content: string): string | undefined {
+  const count = (content.match(/Schema = /g) || []).length;
+  return count > 0 ? `${count} schemas` : undefined;
+}
+
+function countHooks(content: string): string | undefined {
+  const count = (content.match(/export function use\w+/g) || []).length;
+  return count > 0 ? `${count} hooks` : undefined;
+}
+
+function countPaths(content: string): string | undefined {
+  try {
+    const spec = JSON.parse(content);
+    const paths = Object.keys(spec.paths || {}).length;
+    return paths > 0 ? `${paths} paths` : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function countTests(content: string): string | undefined {
+  const count = (content.match(/it\("/g) || []).length;
+  return count > 0 ? `${count} tests` : undefined;
+}
+
+function countGuards(content: string): string | undefined {
+  const count = (content.match(/export function is\w+/g) || []).length;
+  return count > 0 ? `${count} guards` : undefined;
+}
+
+// Simplified test generation (reuses the same logic as test-gen but inline)
+interface MockRoute {
+  method: string;
+  path: string;
+  functionName: string;
+  sampleInput: unknown;
+  sampleOutput: unknown;
+}
+
+function generateTestContent(routes: MockRoute[]): string {
+  const lines: string[] = [];
+  lines.push("// Auto-generated API tests by trickle");
+  lines.push(`// Generated at ${new Date().toISOString()}`);
+  lines.push("// Do not edit manually — re-run `trickle export` to update");
+  lines.push("");
+  lines.push('import { describe, it, expect } from "vitest";');
+  lines.push("");
+  lines.push('const BASE_URL = process.env.TEST_API_URL || "http://localhost:3000";');
+  lines.push("");
+
+  // Group by resource
+  const groups: Record<string, MockRoute[]> = {};
+  for (const r of routes) {
+    const parts = r.path.split("/").filter(Boolean);
+    const resource = parts[0] === "api" && parts.length >= 2 ? `/api/${parts[1]}` : `/${parts[0] || "root"}`;
+    if (!groups[resource]) groups[resource] = [];
+    groups[resource].push(r);
+  }
+
+  for (const [resource, resourceRoutes] of Object.entries(groups)) {
+    lines.push(`describe("${resource}", () => {`);
+    for (const route of resourceRoutes) {
+      const hasBody = ["POST", "PUT", "PATCH"].includes(route.method);
+      const fetchPath = route.path.replace(/:(\w+)/g, "test-$1");
+
+      lines.push(`  it("${route.method} ${route.path} — returns expected shape", async () => {`);
+      lines.push(`    const res = await fetch(\`\${BASE_URL}${fetchPath}\`, {`);
+      lines.push(`      method: "${route.method}",`);
+      if (hasBody && route.sampleInput) {
+        const body = typeof route.sampleInput === "object" && route.sampleInput !== null
+          ? (route.sampleInput as Record<string, unknown>).body || route.sampleInput
+          : route.sampleInput;
+        if (body && typeof body === "object" && Object.keys(body as object).length > 0) {
+          lines.push(`      headers: { "Content-Type": "application/json" },`);
+          lines.push(`      body: JSON.stringify(${JSON.stringify(body)}),`);
+        }
+      }
+      lines.push("    });");
+      lines.push("    expect(res.ok).toBe(true);");
+
+      if (route.sampleOutput && typeof route.sampleOutput === "object") {
+        lines.push("    const body = await res.json();");
+        for (const [key, value] of Object.entries(route.sampleOutput as Record<string, unknown>)) {
+          if (Array.isArray(value)) {
+            lines.push(`    expect(Array.isArray(body.${key})).toBe(true);`);
+          } else if (typeof value === "string") {
+            lines.push(`    expect(typeof body.${key}).toBe("string");`);
+          } else if (typeof value === "number") {
+            lines.push(`    expect(typeof body.${key}).toBe("number");`);
+          } else if (typeof value === "boolean") {
+            lines.push(`    expect(typeof body.${key}).toBe("boolean");`);
+          }
+        }
+      }
+      lines.push("  });");
+      lines.push("");
+    }
+    lines.push("});");
+    lines.push("");
+  }
+
+  return lines.join("\n").trimEnd() + "\n";
+}

package/src/commands/functions.ts

@@ -0,0 +1,81 @@
+import chalk from "chalk";
+import Table from "cli-table3";
+import { listFunctions } from "../api-client";
+import { envBadge, langBadge, timeBadge } from "../ui/badges";
+import { relativeTime } from "../ui/helpers";
+
+export interface FunctionsOptions {
+  env?: string;
+  lang?: string;
+  search?: string;
+}
+
+export async function functionsCommand(opts: FunctionsOptions): Promise<void> {
+  const result = await listFunctions({
+    env: opts.env,
+    language: opts.lang,
+    search: opts.search,
+  });
+
+  const { functions } = result;
+
+  if (functions.length === 0) {
+    console.log(chalk.yellow("\n  No functions found.\n"));
+    if (opts.env || opts.lang || opts.search) {
+      console.log(chalk.gray("  Try adjusting your filters.\n"));
+    }
+    return;
+  }
+
+  console.log("");
+
+  const table = new Table({
+    head: [
+      chalk.cyan.bold("Name"),
+      chalk.cyan.bold("Module"),
+      chalk.cyan.bold("Language"),
+      chalk.cyan.bold("Environment"),
+      chalk.cyan.bold("Last Seen"),
+    ],
+    style: {
+      head: [],
+      border: ["gray"],
+    },
+    chars: {
+      top: "─",
+      "top-mid": "┬",
+      "top-left": "┌",
+      "top-right": "┐",
+      bottom: "─",
+      "bottom-mid": "┴",
+      "bottom-left": "└",
+      "bottom-right": "┘",
+      left: "│",
+      "left-mid": "├",
+      mid: "─",
+      "mid-mid": "┼",
+      right: "│",
+      "right-mid": "┤",
+      middle: "│",
+    },
+  });
+
+  for (const fn of functions) {
+    table.push([
+      chalk.white.bold(fn.function_name),
+      chalk.gray(fn.module),
+      langBadge(fn.language),
+      envBadge(fn.environment),
+      timeBadge(fn.last_seen_at),
+    ]);
+  }
+
+  console.log(table.toString());
+  console.log(
+    chalk.gray(`\n  Showing ${chalk.white.bold(String(functions.length))} functions`) +
+      (result.total > functions.length
+        ? chalk.gray(` of ${result.total} total`)
+        : "") +
+      "\n"
+  );
+}

package/src/commands/infer.ts

@@ -0,0 +1,260 @@
+import * as fs from "fs";
+import * as crypto from "crypto";
+import chalk from "chalk";
+import { getBackendUrl } from "../config";
+
+export interface InferOptions {
+  name: string;
+  env?: string;
+  module?: string;
+  requestBody?: string;
+}
+
+interface TypeNode {
+  kind: string;
+  [key: string]: unknown;
+}
+
+/**
+ * `trickle infer <file>` — Infer types from a JSON file or stdin and store them.
+ *
+ * Reads JSON from a file (or stdin if file is "-" or omitted with piped input),
+ * infers TypeNode from the data, and sends the observation to the trickle backend.
+ * Works offline with saved API responses, test fixtures, or piped command output.
+ */
+export async function inferCommand(
+  file: string | undefined,
+  opts: InferOptions,
+): Promise<void> {
+  const backendUrl = getBackendUrl();
+
+  // 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);
+  }
+
+  // Read JSON input
+  let jsonText: string;
+  let sourceName: string;
+
+  if (!file || file === "-") {
+    // Read from stdin
+    if (process.stdin.isTTY) {
+      console.error(chalk.red("\n  No input provided."));
+      console.error(chalk.gray("  Pipe JSON via stdin or provide a file path:\n"));
+      console.error(chalk.gray('  echo \'{"key":"value"}\' | trickle infer --name "GET /api/data"'));
+      console.error(chalk.gray('  trickle infer response.json --name "GET /api/data"\n'));
+      process.exit(1);
+    }
+    jsonText = await readStdin();
+    sourceName = "stdin";
+  } else {
+    // Read from file
+    if (!fs.existsSync(file)) {
+      console.error(chalk.red(`\n  File not found: ${file}\n`));
+      process.exit(1);
+    }
+    jsonText = fs.readFileSync(file, "utf-8");
+    sourceName = file;
+  }
+
+  // Parse JSON
+  let jsonData: unknown;
+  try {
+    jsonData = JSON.parse(jsonText.trim());
+  } catch {
+    console.error(chalk.red("\n  Input is not valid JSON.\n"));
+    process.exit(1);
+  }
+
+  // Build type observations
+  const functionName = opts.name;
+  const returnType = jsonToTypeNode(jsonData);
+
+  const argsProperties: Record<string, TypeNode> = {};
+
+  // Parse request body example if provided
+  if (opts.requestBody) {
+    try {
+      const reqJson = JSON.parse(opts.requestBody);
+      argsProperties.body = jsonToTypeNode(reqJson);
+    } catch {
+      console.error(chalk.red("\n  --request-body is not valid JSON.\n"));
+      process.exit(1);
+    }
+  }
+
+  const argsType: TypeNode = Object.keys(argsProperties).length > 0
+    ? { kind: "object", properties: argsProperties }
+    : { kind: "object", properties: {} };
+
+  const typeHash = computeTypeHash(argsType, returnType);
+
+  const payload = {
+    functionName,
+    module: opts.module || "infer",
+    language: "js",
+    environment: opts.env || "development",
+    typeHash,
+    argsType,
+    returnType,
+    sampleInput: Object.keys(argsProperties).length > 0 ? argsProperties : undefined,
+    sampleOutput: jsonData,
+  };
+
+  // Send to backend
+  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}`);
+  } catch (err: unknown) {
+    const msg = err instanceof Error ? err.message : "Unknown error";
+    console.error(chalk.red(`\n  Failed to send types to backend: ${msg}\n`));
+    process.exit(1);
+  }
+
+  console.log("");
+  console.log(chalk.bold("  trickle infer"));
+  console.log(chalk.gray("  " + "─".repeat(50)));
+  console.log(chalk.gray(`  Source:   `) + chalk.white(sourceName));
+  console.log(chalk.gray(`  Name:     `) + chalk.white(functionName));
+  console.log(chalk.gray(`  Backend:  `) + chalk.white(backendUrl));
+  console.log(chalk.gray("  " + "─".repeat(50)));
+  console.log(chalk.green("  Types inferred and stored successfully!"));
+
+  // Show a preview of the inferred shape
+  const shape = describeShape(returnType, 1);
+  console.log("");
+  console.log(chalk.gray("  Inferred shape:"));
+  for (const line of shape) {
+    console.log(chalk.gray("    ") + line);
+  }
+
+  if (opts.requestBody) {
+    const reqShape = describeShape(argsProperties.body, 1);
+    console.log("");
+    console.log(chalk.gray("  Request body shape:"));
+    for (const line of reqShape) {
+      console.log(chalk.gray("    ") + line);
+    }
+  }
+
+  console.log("");
+  console.log(chalk.gray("  Run ") + chalk.white("trickle codegen") + chalk.gray(" to generate type definitions."));
+  console.log("");
+}
+
+function readStdin(): Promise<string> {
+  return new Promise((resolve, reject) => {
+    let data = "";
+    process.stdin.setEncoding("utf-8");
+    process.stdin.on("data", (chunk) => { data += chunk; });
+    process.stdin.on("end", () => resolve(data));
+    process.stdin.on("error", reject);
+    // Timeout after 10 seconds
+    setTimeout(() => {
+      if (data.length === 0) {
+        reject(new Error("No input received from stdin"));
+      } else {
+        resolve(data);
+      }
+    }, 10000);
+  });
+}
+
+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 computeTypeHash(argsType: TypeNode, returnType: TypeNode): string {
+  const data = JSON.stringify({ a: argsType, r: returnType });
+  return crypto.createHash("sha256").update(data).digest("hex").slice(0, 16);
+}
+
+/**
+ * Describe a TypeNode shape as human-readable lines.
+ */
+function describeShape(node: TypeNode, maxDepth: number, depth: number = 0): string[] {
+  const indent = "  ".repeat(depth);
+  const lines: string[] = [];
+
+  if (node.kind === "primitive") {
+    lines.push(indent + chalk.cyan(node.name as string));
+  } else if (node.kind === "array") {
+    const element = node.element as TypeNode;
+    if (element.kind === "object" && depth < maxDepth) {
+      lines.push(indent + chalk.yellow("Array<{"));
+      const subLines = describeShape(element, maxDepth, depth + 1);
+      lines.push(...subLines);
+      lines.push(indent + chalk.yellow("}>"));
+    } else {
+      lines.push(indent + chalk.yellow(`${describeTypeCompact(element)}[]`));
+    }
+  } else if (node.kind === "object") {
+    const props = node.properties as Record<string, TypeNode>;
+    const keys = Object.keys(props);
+    if (keys.length === 0) {
+      lines.push(indent + chalk.gray("{}"));
+    } else {
+      for (const key of keys) {
+        const propType = props[key];
+        const typeStr = describeTypeCompact(propType);
+        lines.push(indent + chalk.white(key) + chalk.gray(": ") + chalk.cyan(typeStr));
+      }
+    }
+  } else {
+    lines.push(indent + chalk.gray(node.kind));
+  }
+
+  return lines;
+}
+
+function describeTypeCompact(node: TypeNode): string {
+  switch (node.kind) {
+    case "primitive":
+      return node.name as string;
+    case "array": {
+      const element = node.element as TypeNode;
+      return `${describeTypeCompact(element)}[]`;
+    }
+    case "object": {
+      const props = node.properties as Record<string, TypeNode>;
+      const keys = Object.keys(props);
+      if (keys.length === 0) return "{}";
+      if (keys.length <= 3) {
+        const inner = keys.map((k) => `${k}: ${describeTypeCompact(props[k])}`).join(", ");
+        return `{ ${inner} }`;
+      }
+      return `{ ${keys.slice(0, 2).map((k) => `${k}: ${describeTypeCompact(props[k])}`).join(", ")}, ... }`;
+    }
+    default:
+      return node.kind;
+  }
+}