trickle-cli 0.1.0

package/dist/ui/badges.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Colored badge for environment names.
+ */
+export declare function envBadge(env: string): string;
+/**
+ * Colored badge for language.
+ */
+export declare function langBadge(lang: string): string;
+/**
+ * Colored badge for error type.
+ */
+export declare function errorTypeBadge(type: string): string;
+/**
+ * Format a timestamp as a relative time badge.
+ */
+export declare function timeBadge(timestamp: string): string;

package/dist/ui/badges.js

@@ -0,0 +1,71 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.envBadge = envBadge;
+exports.langBadge = langBadge;
+exports.errorTypeBadge = errorTypeBadge;
+exports.timeBadge = timeBadge;
+const chalk_1 = __importDefault(require("chalk"));
+const helpers_1 = require("./helpers");
+/**
+ * Colored badge for environment names.
+ */
+function envBadge(env) {
+    const lower = env.toLowerCase();
+    if (lower === "prod" || lower === "production") {
+        return chalk_1.default.bgRed.white.bold(` ${env} `);
+    }
+    if (lower === "staging" || lower === "stage") {
+        return chalk_1.default.bgYellow.black.bold(` ${env} `);
+    }
+    if (lower === "local" || lower === "dev" || lower === "development") {
+        return chalk_1.default.bgGreen.black.bold(` ${env} `);
+    }
+    if (lower === "test" || lower === "ci") {
+        return chalk_1.default.bgCyan.black.bold(` ${env} `);
+    }
+    return chalk_1.default.bgGray.white.bold(` ${env} `);
+}
+/**
+ * Colored badge for language.
+ */
+function langBadge(lang) {
+    const lower = lang.toLowerCase();
+    if (lower === "js" || lower === "javascript" || lower === "typescript" || lower === "ts") {
+        return chalk_1.default.bgYellow.black(` ${lang} `);
+    }
+    if (lower === "python" || lower === "py") {
+        return chalk_1.default.bgBlue.white(` ${lang} `);
+    }
+    if (lower === "go" || lower === "golang") {
+        return chalk_1.default.bgCyan.black(` ${lang} `);
+    }
+    return chalk_1.default.bgGray.white(` ${lang} `);
+}
+/**
+ * Colored badge for error type.
+ */
+function errorTypeBadge(type) {
+    const lower = type.toLowerCase();
+    if (lower.includes("type")) {
+        return chalk_1.default.bgMagenta.white.bold(` ${type} `);
+    }
+    if (lower.includes("reference") || lower.includes("undefined")) {
+        return chalk_1.default.bgRed.white.bold(` ${type} `);
+    }
+    if (lower.includes("syntax")) {
+        return chalk_1.default.bgYellow.black.bold(` ${type} `);
+    }
+    if (lower.includes("range") || lower.includes("overflow")) {
+        return chalk_1.default.bgCyan.black.bold(` ${type} `);
+    }
+    return chalk_1.default.bgRed.white.bold(` ${type} `);
+}
+/**
+ * Format a timestamp as a relative time badge.
+ */
+function timeBadge(timestamp) {
+    return chalk_1.default.gray((0, helpers_1.relativeTime)(timestamp));
+}

package/dist/ui/helpers.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Parse human-readable time strings into ISO date strings.
+ * Supports: "30s", "5m", "5 min", "2h", "3d", "1w"
+ */
+export declare function parseSince(since: string): string;
+/**
+ * Truncate a string with ellipsis.
+ */
+export declare function truncate(str: string, maxLen: number): string;
+/**
+ * Convert an ISO date string to a relative time string like "2m ago".
+ */
+export declare function relativeTime(isoDate: string): string;

package/dist/ui/helpers.js

@@ -0,0 +1,85 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseSince = parseSince;
+exports.truncate = truncate;
+exports.relativeTime = relativeTime;
+/**
+ * Parse human-readable time strings into ISO date strings.
+ * Supports: "30s", "5m", "5 min", "2h", "3d", "1w"
+ */
+function parseSince(since) {
+    const now = Date.now();
+    const cleaned = since.trim().toLowerCase();
+    const match = cleaned.match(/^(\d+)\s*(s|sec|seconds?|m|min|minutes?|h|hrs?|hours?|d|days?|w|weeks?)$/);
+    if (!match) {
+        // Try to parse as ISO date directly
+        const d = new Date(since);
+        if (!isNaN(d.getTime())) {
+            return d.toISOString();
+        }
+        throw new Error(`Cannot parse time string: "${since}". Use formats like "30s", "5m", "2h", "3d", "1w".`);
+    }
+    const amount = parseInt(match[1], 10);
+    const unit = match[2];
+    let ms;
+    if (unit.startsWith("s")) {
+        ms = amount * 1000;
+    }
+    else if (unit.startsWith("m") && !unit.startsWith("mo")) {
+        ms = amount * 60 * 1000;
+    }
+    else if (unit.startsWith("h")) {
+        ms = amount * 60 * 60 * 1000;
+    }
+    else if (unit.startsWith("d")) {
+        ms = amount * 24 * 60 * 60 * 1000;
+    }
+    else if (unit.startsWith("w")) {
+        ms = amount * 7 * 24 * 60 * 60 * 1000;
+    }
+    else {
+        ms = amount * 60 * 1000; // default to minutes
+    }
+    // Output in SQLite datetime format to match backend storage
+    return new Date(now - ms).toISOString().replace('T', ' ').replace(/\.\d+Z$/, '');
+}
+/**
+ * Truncate a string with ellipsis.
+ */
+function truncate(str, maxLen) {
+    if (str.length <= maxLen)
+        return str;
+    return str.slice(0, maxLen - 1) + "\u2026";
+}
+/**
+ * Convert an ISO date string to a relative time string like "2m ago".
+ */
+function relativeTime(isoDate) {
+    const now = Date.now();
+    const then = new Date(isoDate).getTime();
+    const diff = now - then;
+    if (isNaN(then))
+        return isoDate;
+    const seconds = Math.floor(diff / 1000);
+    if (seconds < 5)
+        return "just now";
+    if (seconds < 60)
+        return `${seconds}s ago`;
+    const minutes = Math.floor(seconds / 60);
+    if (minutes < 60)
+        return `${minutes}m ago`;
+    const hours = Math.floor(minutes / 60);
+    if (hours < 24)
+        return `${hours}h ago`;
+    const days = Math.floor(hours / 24);
+    if (days < 7)
+        return `${days}d ago`;
+    const weeks = Math.floor(days / 7);
+    if (weeks < 4)
+        return `${weeks}w ago`;
+    const months = Math.floor(days / 30);
+    if (months < 12)
+        return `${months}mo ago`;
+    const years = Math.floor(days / 365);
+    return `${years}y ago`;
+}

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "trickle-cli",
+  "version": "0.1.0",
+  "description": "CLI for trickle runtime type observability",
+  "bin": {
+    "trickle": "dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "ts-node src/index.ts"
+  },
+  "dependencies": {
+    "chalk": "^4.1.2",
+    "cli-table3": "^0.6.5",
+    "commander": "^12.0.0",
+    "trickle-observe": "^0.1.0",
+    "trickle-backend": "^0.1.0"
+  },
+  "devDependencies": {
+    "ts-node": "^10.9.0",
+    "typescript": "^5.4.0"
+  }
+}

package/src/api-client.ts

@@ -0,0 +1,407 @@
+import * as http from "http";
+import * as https from "https";
+import { URL } from "url";
+import chalk from "chalk";
+import { getBackendUrl } from "./config";
+
+// ── Types matching backend responses ──
+
+export interface FunctionRow {
+  id: number;
+  function_name: string;
+  module: string;
+  language: string;
+  environment: string;
+  first_seen_at: string;
+  last_seen_at: string;
+}
+
+export interface FunctionDetail {
+  function: FunctionRow;
+  latestSnapshots: Record<string, TypeSnapshot>;
+}
+
+export interface TypeSnapshot {
+  id: number;
+  function_id: number;
+  type_hash: string;
+  env: string;
+  args_type: unknown;
+  return_type: unknown;
+  observed_at: string;
+  sample_input?: unknown;
+  sample_output?: unknown;
+}
+
+export interface ErrorRow {
+  id: number;
+  function_id: number;
+  function_name: string;
+  module: string;
+  language: string;
+  env: string;
+  error_type: string;
+  error_message: string;
+  stack_trace?: string;
+  type_hash?: string;
+  args_type?: unknown;
+  return_type?: unknown;
+  variables_type?: unknown;
+  args_snapshot?: unknown;
+  occurred_at: string;
+}
+
+export interface ErrorDetail {
+  error: ErrorRow;
+  snapshot: TypeSnapshot | null;
+}
+
+export interface TypeDiff {
+  kind: "added" | "removed" | "changed";
+  path: string;
+  from?: unknown;
+  to?: unknown;
+  type?: unknown;
+}
+
+export interface DiffResponse {
+  from: { id: number; env: string; observed_at: string };
+  to: { id: number; env: string; observed_at: string };
+  diffs: TypeDiff[];
+}
+
+export interface TailEvent {
+  event: string;
+  data: Record<string, unknown>;
+}
+
+// ── Helpers ──
+
+function backendUrl(): string {
+  return getBackendUrl();
+}
+
+function connectionError(): never {
+  const url = backendUrl();
+  console.error(
+    chalk.red(`\nCannot connect to trickle backend at ${chalk.bold(url)}.`)
+  );
+  console.error(chalk.red("Is the backend running?\n"));
+  process.exit(1);
+}
+
+async function fetchJson<T>(path: string, query?: Record<string, string | undefined>): Promise<T> {
+  const base = backendUrl();
+  const url = new URL(path, base);
+
+  if (query) {
+    for (const [key, value] of Object.entries(query)) {
+      if (value !== undefined && value !== "") {
+        url.searchParams.set(key, value);
+      }
+    }
+  }
+
+  try {
+    const res = await fetch(url.toString());
+    if (!res.ok) {
+      const body = await res.text();
+      throw new Error(`HTTP ${res.status}: ${body}`);
+    }
+    return (await res.json()) as T;
+  } catch (err: unknown) {
+    if (err instanceof Error && err.message.startsWith("HTTP ")) {
+      throw err;
+    }
+    connectionError();
+  }
+}
+
+// ── API Functions ──
+
+export interface ListFunctionsOpts {
+  env?: string;
+  language?: string;
+  search?: string;
+  limit?: number;
+  offset?: number;
+}
+
+export async function listFunctions(opts?: ListFunctionsOpts): Promise<{ functions: FunctionRow[]; total: number }> {
+  return fetchJson("/api/functions", {
+    env: opts?.env,
+    language: opts?.language,
+    q: opts?.search,
+    limit: opts?.limit?.toString(),
+    offset: opts?.offset?.toString(),
+  });
+}
+
+export async function getFunction(id: number): Promise<FunctionDetail> {
+  return fetchJson(`/api/functions/${id}`);
+}
+
+export interface ListErrorsOpts {
+  env?: string;
+  functionName?: string;
+  since?: string;
+  limit?: number;
+  offset?: number;
+}
+
+export async function listErrors(opts?: ListErrorsOpts): Promise<{ errors: ErrorRow[]; total: number }> {
+  return fetchJson("/api/errors", {
+    env: opts?.env,
+    functionName: opts?.functionName,
+    since: opts?.since,
+    limit: opts?.limit?.toString(),
+    offset: opts?.offset?.toString(),
+  });
+}
+
+export async function getError(id: number): Promise<ErrorDetail> {
+  return fetchJson(`/api/errors/${id}`);
+}
+
+export interface ListTypesOpts {
+  env?: string;
+  limit?: number;
+}
+
+export async function listTypes(functionId: number, opts?: ListTypesOpts): Promise<{ snapshots: TypeSnapshot[] }> {
+  return fetchJson(`/api/types/${functionId}`, {
+    env: opts?.env,
+    limit: opts?.limit?.toString(),
+  });
+}
+
+export interface GetTypeDiffOpts {
+  from?: number;
+  to?: number;
+  fromEnv?: string;
+  toEnv?: string;
+}
+
+export async function getTypeDiff(functionId: number, opts?: GetTypeDiffOpts): Promise<DiffResponse> {
+  return fetchJson(`/api/types/${functionId}/diff`, {
+    from: opts?.from?.toString(),
+    to: opts?.to?.toString(),
+    fromEnv: opts?.fromEnv,
+    toEnv: opts?.toEnv,
+  });
+}
+
+export interface CodegenOpts {
+  functionName?: string;
+  env?: string;
+  language?: string;
+  format?: string;
+}
+
+export async function fetchCodegen(opts?: CodegenOpts): Promise<{ types: string }> {
+  const pathStr = opts?.functionName
+    ? `/api/codegen/${encodeURIComponent(opts.functionName)}`
+    : "/api/codegen";
+
+  return fetchJson(pathStr, {
+    env: opts?.env,
+    language: opts?.language,
+    format: opts?.format,
+  });
+}
+
+export interface AnnotationParam {
+  name: string;
+  type: string;
+}
+
+export interface AnnotationEntry {
+  params: AnnotationParam[];
+  returnType: string;
+}
+
+export async function fetchAnnotations(opts?: {
+  env?: string;
+  language?: string;
+}): Promise<{ annotations: Record<string, AnnotationEntry> }> {
+  return fetchJson("/api/codegen", {
+    env: opts?.env,
+    language: opts?.language,
+    format: "annotate",
+  });
+}
+
+export interface StubsResponse {
+  stubs: Record<string, { ts: string; python: string }>;
+}
+
+export async function fetchStubs(opts?: {
+  env?: string;
+}): Promise<StubsResponse> {
+  return fetchJson("/api/codegen", {
+    env: opts?.env,
+    format: "stubs",
+  });
+}
+
+export interface MockRoute {
+  method: string;
+  path: string;
+  functionName: string;
+  module: string;
+  sampleInput: unknown;
+  sampleOutput: unknown;
+  observedAt: string;
+}
+
+export async function fetchMockConfig(): Promise<{ routes: MockRoute[] }> {
+  return fetchJson("/api/mock-config");
+}
+
+// ── Snapshot (for trickle check) ──
+
+export interface SnapshotFunction {
+  name: string;
+  module: string;
+  env?: string;
+  argsType: unknown;
+  returnType: unknown;
+}
+
+export interface CheckSnapshot {
+  version: number;
+  createdAt: string;
+  functions: SnapshotFunction[];
+}
+
+export async function fetchSnapshot(opts?: { env?: string }): Promise<CheckSnapshot> {
+  return fetchJson("/api/codegen", {
+    format: "snapshot",
+    env: opts?.env,
+  });
+}
+
+// ── OpenAPI ──
+
+export interface OpenApiOpts {
+  env?: string;
+  title?: string;
+  version?: string;
+  serverUrl?: string;
+}
+
+export async function fetchOpenApiSpec(opts?: OpenApiOpts): Promise<object> {
+  return fetchJson("/api/codegen", {
+    format: "openapi",
+    env: opts?.env,
+    title: opts?.title,
+    version: opts?.version,
+    serverUrl: opts?.serverUrl,
+  });
+}
+
+// ── Diff Report ──
+
+export interface DiffReportEntry {
+  functionName: string;
+  module: string;
+  language: string;
+  from: { id: number; env: string; observed_at: string; type_hash: string };
+  to: { id: number; env: string; observed_at: string; type_hash: string };
+  diffs: TypeDiff[];
+}
+
+export interface DiffReportResponse {
+  mode: "temporal" | "cross-env";
+  entries: DiffReportEntry[];
+  total: number;
+  since?: string | null;
+  env?: string | null;
+  env1?: string;
+  env2?: string;
+}
+
+export interface DiffReportOpts {
+  since?: string;
+  env?: string;
+  env1?: string;
+  env2?: string;
+}
+
+export async function fetchDiffReport(opts?: DiffReportOpts): Promise<DiffReportResponse> {
+  return fetchJson("/api/diff", {
+    since: opts?.since,
+    env: opts?.env,
+    env1: opts?.env1,
+    env2: opts?.env2,
+  });
+}
+
+export function tailEvents(
+  onEvent: (event: TailEvent) => void,
+  filter?: string
+): () => void {
+  const base = backendUrl();
+  const url = new URL("/api/tail", base);
+  if (filter) {
+    url.searchParams.set("filter", filter);
+  }
+
+  const mod = url.protocol === "https:" ? https : http;
+  let destroyed = false;
+  let currentReq: http.ClientRequest | null = null;
+
+  function connect() {
+    if (destroyed) return;
+
+    const req = mod.get(url.toString(), (res) => {
+      let buffer = "";
+
+      res.on("data", (chunk: Buffer) => {
+        buffer += chunk.toString();
+        const lines = buffer.split("\n");
+        buffer = lines.pop() || "";
+
+        let currentEvent = "";
+        for (const line of lines) {
+          if (line.startsWith("event: ")) {
+            currentEvent = line.slice(7).trim();
+          } else if (line.startsWith("data: ")) {
+            const dataStr = line.slice(6).trim();
+            try {
+              const data = JSON.parse(dataStr);
+              onEvent({ event: currentEvent, data });
+            } catch {
+              // Ignore invalid JSON
+            }
+            currentEvent = "";
+          }
+        }
+      });
+
+      res.on("end", () => {
+        if (!destroyed) {
+          // Reconnect after a delay
+          setTimeout(connect, 2000);
+        }
+      });
+    });
+
+    req.on("error", () => {
+      if (!destroyed) {
+        setTimeout(connect, 3000);
+      }
+    });
+
+    currentReq = req;
+  }
+
+  connect();
+
+  return () => {
+    destroyed = true;
+    if (currentReq) {
+      currentReq.destroy();
+    }
+  };
+}