trickle-cli 0.1.0

package/dist/commands/docs.js

@@ -0,0 +1,383 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.docsCommand = docsCommand;
+const fs = __importStar(require("fs"));
+const chalk_1 = __importDefault(require("chalk"));
+const api_client_1 = require("../api-client");
+/**
+ * `trickle docs` — Generate API documentation from observed runtime types.
+ *
+ * Produces clean Markdown (or self-contained HTML) documenting every
+ * observed API route with request/response types and example payloads.
+ */
+async function docsCommand(opts) {
+    const title = opts.title || "API Documentation";
+    // Fetch data
+    let routes;
+    let typesContent;
+    let totalFunctions;
+    try {
+        const [mockConfig, codegen, funcList] = await Promise.all([
+            (0, api_client_1.fetchMockConfig)(),
+            (0, api_client_1.fetchCodegen)({ env: opts.env }),
+            (0, api_client_1.listFunctions)({ env: opts.env, limit: 500 }),
+        ]);
+        routes = mockConfig.routes;
+        typesContent = codegen.types;
+        totalFunctions = funcList.total;
+    }
+    catch {
+        console.error(chalk_1.default.red("\n  Cannot connect to trickle backend."));
+        console.error(chalk_1.default.gray("  Is the backend running?\n"));
+        process.exit(1);
+    }
+    if (routes.length === 0) {
+        console.error(chalk_1.default.yellow("\n  No observed API routes to document."));
+        console.error(chalk_1.default.gray("  Instrument your app and make some requests first.\n"));
+        process.exit(0);
+    }
+    // Parse type definitions to map route names to their types
+    const typeMap = buildTypeMap(typesContent);
+    // Group routes by resource
+    const groups = groupRoutesByResource(routes);
+    // Generate markdown
+    const markdown = generateMarkdown(title, groups, typeMap, totalFunctions);
+    if (opts.html) {
+        const html = wrapInHtml(title, markdown);
+        if (opts.out) {
+            fs.writeFileSync(opts.out, html, "utf-8");
+            console.log(chalk_1.default.green(`\n  API docs written to ${chalk_1.default.bold(opts.out)}`));
+            console.log(chalk_1.default.gray(`  ${routes.length} routes documented\n`));
+        }
+        else {
+            console.log(html);
+        }
+    }
+    else {
+        if (opts.out) {
+            fs.writeFileSync(opts.out, markdown, "utf-8");
+            console.log(chalk_1.default.green(`\n  API docs written to ${chalk_1.default.bold(opts.out)}`));
+            console.log(chalk_1.default.gray(`  ${routes.length} routes documented\n`));
+        }
+        else {
+            console.log(markdown);
+        }
+    }
+}
+function groupRoutesByResource(routes) {
+    const groups = {};
+    for (const route of routes) {
+        const parts = route.path.split("/").filter(Boolean);
+        let resource;
+        if (parts[0] === "api" && parts.length >= 2) {
+            resource = `/${parts[0]}/${parts[1]}`;
+        }
+        else {
+            resource = `/${parts[0] || "root"}`;
+        }
+        if (!groups[resource])
+            groups[resource] = [];
+        groups[resource].push(route);
+    }
+    // Sort groups alphabetically, routes by method order
+    const methodOrder = { GET: 0, POST: 1, PUT: 2, PATCH: 3, DELETE: 4 };
+    const result = [];
+    for (const [resource, resourceRoutes] of Object.entries(groups).sort((a, b) => a[0].localeCompare(b[0]))) {
+        resourceRoutes.sort((a, b) => {
+            const ma = methodOrder[a.method] ?? 5;
+            const mb = methodOrder[b.method] ?? 5;
+            if (ma !== mb)
+                return ma - mb;
+            return a.path.localeCompare(b.path);
+        });
+        result.push({ resource, routes: resourceRoutes });
+    }
+    return result;
+}
+/**
+ * Extract type definitions from generated TypeScript code and map them
+ * to route function names.
+ */
+function buildTypeMap(typesContent) {
+    const map = new Map();
+    if (!typesContent)
+        return map;
+    // Find interface/type blocks and their associated route comments
+    const blocks = typesContent.split(/(?=\/\*\*|export interface|export type)/);
+    let currentComment = "";
+    for (const block of blocks) {
+        if (block.startsWith("/**")) {
+            currentComment = block;
+            continue;
+        }
+        const match = block.match(/export (?:interface|type) (\w+)/);
+        if (match) {
+            const typeName = match[1];
+            // Clean up the block
+            const cleanBlock = block.trim();
+            if (cleanBlock) {
+                map.set(typeName, cleanBlock);
+            }
+        }
+        currentComment = "";
+    }
+    return map;
+}
+function toPascalCase(name) {
+    return name
+        .replace(/[^a-zA-Z0-9]+/g, " ")
+        .split(/\s+/)
+        .map((w) => w.charAt(0).toUpperCase() + w.slice(1))
+        .join("");
+}
+function generateMarkdown(title, groups, typeMap, totalFunctions) {
+    const lines = [];
+    const now = new Date().toISOString().split("T")[0];
+    lines.push(`# ${title}`);
+    lines.push("");
+    lines.push(`> Auto-generated by [trickle](https://github.com/yiheinchai/trickle) from runtime-observed types.`);
+    lines.push(`> Generated on ${now} — ${totalFunctions} functions observed.`);
+    lines.push("");
+    // Table of contents
+    lines.push("## Table of Contents");
+    lines.push("");
+    for (const group of groups) {
+        const anchor = group.resource.replace(/[^a-zA-Z0-9]/g, "").toLowerCase();
+        lines.push(`- [${group.resource}](#${anchor})`);
+    }
+    lines.push("");
+    lines.push("---");
+    lines.push("");
+    // Route groups
+    for (const group of groups) {
+        lines.push(`## ${group.resource}`);
+        lines.push("");
+        for (const route of group.routes) {
+            const methodBadge = `\`${route.method}\``;
+            lines.push(`### ${methodBadge} ${route.path}`);
+            lines.push("");
+            // Metadata
+            const observed = route.observedAt ? new Date(route.observedAt).toISOString().split("T")[0] : "unknown";
+            lines.push(`*Last observed: ${observed}*`);
+            lines.push("");
+            // Request body
+            const hasBody = ["POST", "PUT", "PATCH"].includes(route.method);
+            if (hasBody && route.sampleInput) {
+                const input = route.sampleInput;
+                const body = input.body || input;
+                if (body && typeof body === "object" && Object.keys(body).length > 0) {
+                    lines.push("**Request Body**");
+                    lines.push("");
+                    lines.push("```typescript");
+                    lines.push(formatTypeFromSample(body));
+                    lines.push("```");
+                    lines.push("");
+                    lines.push("<details>");
+                    lines.push("<summary>Example</summary>");
+                    lines.push("");
+                    lines.push("```json");
+                    lines.push(JSON.stringify(body, null, 2));
+                    lines.push("```");
+                    lines.push("</details>");
+                    lines.push("");
+                }
+            }
+            // Response
+            if (route.sampleOutput) {
+                // Try to find the TypeScript type
+                const typeName = toPascalCase(route.functionName);
+                const responseTypeName = typeName + "Response";
+                const typeBlock = typeMap.get(responseTypeName);
+                lines.push("**Response**");
+                lines.push("");
+                if (typeBlock) {
+                    lines.push("```typescript");
+                    lines.push(typeBlock);
+                    lines.push("```");
+                }
+                else {
+                    lines.push("```typescript");
+                    lines.push(formatTypeFromSample(route.sampleOutput));
+                    lines.push("```");
+                }
+                lines.push("");
+                lines.push("<details>");
+                lines.push("<summary>Example Response</summary>");
+                lines.push("");
+                lines.push("```json");
+                lines.push(JSON.stringify(route.sampleOutput, null, 2));
+                lines.push("```");
+                lines.push("</details>");
+                lines.push("");
+            }
+            lines.push("---");
+            lines.push("");
+        }
+    }
+    // Footer
+    lines.push("*Generated by trickle — runtime type observability for JavaScript and Python.*");
+    lines.push("");
+    return lines.join("\n");
+}
+/**
+ * Infer a TypeScript type string from a sample JSON value.
+ */
+function formatTypeFromSample(value, indent = 0) {
+    const pad = "  ".repeat(indent);
+    if (value === null)
+        return `${pad}null`;
+    if (value === undefined)
+        return `${pad}undefined`;
+    switch (typeof value) {
+        case "string": return `${pad}string`;
+        case "number": return `${pad}number`;
+        case "boolean": return `${pad}boolean`;
+    }
+    if (Array.isArray(value)) {
+        if (value.length === 0)
+            return `${pad}unknown[]`;
+        const elementType = formatTypeFromSample(value[0], 0);
+        if (elementType.includes("\n")) {
+            // Multi-line element
+            return `${pad}Array<${formatTypeFromSample(value[0], indent).trimStart()}>`;
+        }
+        return `${pad}${elementType.trim()}[]`;
+    }
+    if (typeof value === "object") {
+        const obj = value;
+        const keys = Object.keys(obj);
+        if (keys.length === 0)
+            return `${pad}{}`;
+        const lines = [];
+        lines.push(`${pad}{`);
+        for (const key of keys) {
+            const val = obj[key];
+            const valType = formatTypeFromSample(val, indent + 1).trimStart();
+            lines.push(`${pad}  ${key}: ${valType};`);
+        }
+        lines.push(`${pad}}`);
+        return lines.join("\n");
+    }
+    return `${pad}unknown`;
+}
+/**
+ * Wrap markdown in a self-contained HTML document with a simple renderer.
+ */
+function wrapInHtml(title, markdown) {
+    // Escape for embedding in JS
+    const escapedMd = markdown
+        .replace(/\\/g, "\\\\")
+        .replace(/`/g, "\\`")
+        .replace(/\$/g, "\\$");
+    return `<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<title>${escapeHtml(title)}</title>
+<style>
+  * { margin: 0; padding: 0; box-sizing: border-box; }
+  body {
+    font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
+    line-height: 1.6; color: #1a1a2e; background: #fafafa;
+    max-width: 900px; margin: 0 auto; padding: 2rem 1.5rem;
+  }
+  h1 { font-size: 2rem; margin-bottom: 0.5rem; border-bottom: 2px solid #e0e0e0; padding-bottom: 0.5rem; }
+  h2 { font-size: 1.5rem; margin-top: 2rem; margin-bottom: 0.75rem; color: #2d3748; border-bottom: 1px solid #e2e8f0; padding-bottom: 0.3rem; }
+  h3 { font-size: 1.1rem; margin-top: 1.5rem; margin-bottom: 0.5rem; }
+  p { margin-bottom: 0.75rem; }
+  blockquote { border-left: 3px solid #cbd5e0; padding-left: 1rem; color: #718096; margin-bottom: 1rem; }
+  code { background: #f0f0f0; padding: 0.15em 0.4em; border-radius: 3px; font-size: 0.9em; }
+  pre { background: #1a1a2e; color: #e2e8f0; padding: 1rem; border-radius: 6px; overflow-x: auto; margin-bottom: 1rem; }
+  pre code { background: none; padding: 0; color: inherit; }
+  hr { border: none; border-top: 1px solid #e2e8f0; margin: 1.5rem 0; }
+  em { color: #718096; }
+  strong { color: #2d3748; }
+  ul { padding-left: 1.5rem; margin-bottom: 0.75rem; }
+  li { margin-bottom: 0.25rem; }
+  a { color: #3182ce; text-decoration: none; }
+  a:hover { text-decoration: underline; }
+  details { margin-bottom: 1rem; }
+  summary { cursor: pointer; color: #3182ce; font-weight: 500; margin-bottom: 0.5rem; }
+  summary:hover { text-decoration: underline; }
+  /* Method badges */
+  code:first-child { font-weight: bold; }
+</style>
+</head>
+<body>
+<div id="content"></div>
+<script>
+// Simple markdown renderer
+function renderMd(md) {
+  let html = md;
+  // Code blocks (fenced)
+  html = html.replace(/\`\`\`(\\w*)\\n([\\s\\S]*?)\`\`\`/g, '<pre><code class="lang-$1">$2</code></pre>');
+  // Inline code
+  html = html.replace(/\`([^\`]+)\`/g, '<code>$1</code>');
+  // Headers
+  html = html.replace(/^### (.+)$/gm, '<h3>$1</h3>');
+  html = html.replace(/^## (.+)$/gm, '<h2>$1</h2>');
+  html = html.replace(/^# (.+)$/gm, '<h1>$1</h1>');
+  // Blockquotes
+  html = html.replace(/^> (.+)$/gm, '<blockquote>$1</blockquote>');
+  // Bold
+  html = html.replace(/\\*\\*(.+?)\\*\\*/g, '<strong>$1</strong>');
+  // Italic
+  html = html.replace(/\\*(.+?)\\*/g, '<em>$1</em>');
+  // Links
+  html = html.replace(/\\[([^\\]]+)\\]\\(([^)]+)\\)/g, '<a href="$2">$1</a>');
+  // Unordered lists
+  html = html.replace(/^- (.+)$/gm, '<li>$1</li>');
+  html = html.replace(/(<li>.*<\\/li>\\n?)+/g, '<ul>$&</ul>');
+  // HR
+  html = html.replace(/^---$/gm, '<hr>');
+  // Details/summary (passthrough)
+  // Paragraphs
+  html = html.replace(/^(?!<[hupbold]|<li|<ul|<hr|<details|<summary|<\\/|<pre|<blockquote)(.+)$/gm, '<p>$1</p>');
+  return html;
+}
+const md = \`${escapedMd}\`;
+document.getElementById('content').innerHTML = renderMd(md);
+</script>
+</body>
+</html>`;
+}
+function escapeHtml(str) {
+    return str.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}

package/dist/commands/errors.d.ts

@@ -0,0 +1,7 @@
+export interface ErrorsListOptions {
+    env?: string;
+    since?: string;
+    function?: string;
+    limit?: string;
+}
+export declare function errorsCommand(idOrUndefined: string | undefined, opts: ErrorsListOptions): Promise<void>;

package/dist/commands/errors.js

@@ -0,0 +1,180 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.errorsCommand = errorsCommand;
+const chalk_1 = __importDefault(require("chalk"));
+const cli_table3_1 = __importDefault(require("cli-table3"));
+const api_client_1 = require("../api-client");
+const badges_1 = require("../ui/badges");
+const helpers_1 = require("../ui/helpers");
+const type_formatter_1 = require("../formatters/type-formatter");
+async function errorsCommand(idOrUndefined, opts) {
+    // If an ID was provided, show detail mode
+    if (idOrUndefined !== undefined) {
+        const id = parseInt(idOrUndefined, 10);
+        if (isNaN(id)) {
+            console.error(chalk_1.default.red(`\n  Invalid error ID: "${idOrUndefined}"\n`));
+            process.exit(1);
+        }
+        await showErrorDetail(id);
+        return;
+    }
+    // List mode
+    let sinceIso;
+    if (opts.since) {
+        try {
+            sinceIso = (0, helpers_1.parseSince)(opts.since);
+        }
+        catch (err) {
+            if (err instanceof Error) {
+                console.error(chalk_1.default.red(`\n  ${err.message}\n`));
+            }
+            process.exit(1);
+        }
+    }
+    const limit = opts.limit ? parseInt(opts.limit, 10) : undefined;
+    const result = await (0, api_client_1.listErrors)({
+        env: opts.env,
+        functionName: opts.function,
+        since: sinceIso,
+        limit,
+    });
+    const { errors } = result;
+    if (errors.length === 0) {
+        console.log(chalk_1.default.yellow("\n  No errors found.\n"));
+        if (opts.env || opts.since || opts.function) {
+            console.log(chalk_1.default.gray("  Try adjusting your filters.\n"));
+        }
+        return;
+    }
+    console.log("");
+    const table = new cli_table3_1.default({
+        head: [
+            chalk_1.default.cyan.bold("ID"),
+            chalk_1.default.cyan.bold("Function"),
+            chalk_1.default.cyan.bold("Error Type"),
+            chalk_1.default.cyan.bold("Message"),
+            chalk_1.default.cyan.bold("Env"),
+            chalk_1.default.cyan.bold("Time"),
+        ],
+        style: {
+            head: [],
+            border: ["gray"],
+        },
+        colWidths: [8, 22, 18, 36, 12, 12],
+        wordWrap: true,
+        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 err of errors) {
+        table.push([
+            chalk_1.default.gray(String(err.id)),
+            chalk_1.default.white((0, helpers_1.truncate)(err.function_name || "", 20)),
+            (0, badges_1.errorTypeBadge)(err.error_type),
+            (0, helpers_1.truncate)(err.error_message, 34),
+            (0, badges_1.envBadge)(err.env),
+            (0, badges_1.timeBadge)(err.occurred_at),
+        ]);
+    }
+    console.log(table.toString());
+    console.log(chalk_1.default.gray(`\n  Showing ${chalk_1.default.white.bold(String(errors.length))} errors`) +
+        (result.total > errors.length
+            ? chalk_1.default.gray(` of ${result.total} total`)
+            : "") +
+        "\n");
+}
+async function showErrorDetail(id) {
+    const result = await (0, api_client_1.getError)(id);
+    const { error: err, snapshot } = result;
+    console.log("");
+    console.log(chalk_1.default.red.bold("  ━━━ Error Detail ━━━"));
+    console.log("");
+    // Error header
+    console.log(`  ${(0, badges_1.errorTypeBadge)(err.error_type)}  ${(0, badges_1.envBadge)(err.env)}`);
+    console.log("");
+    console.log(chalk_1.default.white.bold(`  ${err.error_message}`));
+    console.log(chalk_1.default.gray(`  ${(0, helpers_1.relativeTime)(err.occurred_at)} (${err.occurred_at})`));
+    // Stack trace
+    if (err.stack_trace) {
+        console.log("");
+        console.log(chalk_1.default.gray("  ── Stack Trace ──"));
+        console.log("");
+        const lines = err.stack_trace.split("\n");
+        for (const line of lines) {
+            if (line.trim().startsWith("at ")) {
+                console.log(chalk_1.default.gray(`    ${line.trim()}`));
+            }
+            else {
+                console.log(chalk_1.default.red(`    ${line.trim()}`));
+            }
+        }
+    }
+    // Type context
+    console.log("");
+    console.log(chalk_1.default.cyan.bold("  ── Type Context at Point of Failure ──"));
+    console.log("");
+    console.log(chalk_1.default.gray("  Function: ") + chalk_1.default.white.bold(err.function_name || `id:${err.function_id}`));
+    console.log(chalk_1.default.gray("  Module:   ") + chalk_1.default.white(err.module || "unknown"));
+    if (err.args_type) {
+        console.log("");
+        console.log(chalk_1.default.gray("  Input types:"));
+        console.log(`    ${(0, type_formatter_1.formatType)(err.args_type, 4)}`);
+    }
+    if (err.return_type) {
+        console.log("");
+        console.log(chalk_1.default.gray("  Return type:"));
+        console.log(`    ${(0, type_formatter_1.formatType)(err.return_type, 4)}`);
+    }
+    if (err.args_snapshot !== undefined && err.args_snapshot !== null) {
+        console.log("");
+        console.log(chalk_1.default.gray("  Sample data:"));
+        const json = JSON.stringify(err.args_snapshot, null, 2);
+        if (json) {
+            const lines = json.split("\n");
+            for (const line of lines) {
+                const colored = line
+                    .replace(/"([^"]+)":/g, (_, key) => `${chalk_1.default.white(`"${key}"`)}:`)
+                    .replace(/: "([^"]*)"/g, (_, val) => `: ${chalk_1.default.green(`"${val}"`)}`)
+                    .replace(/: (\d+\.?\d*)/g, (_, val) => `: ${chalk_1.default.yellow(val)}`)
+                    .replace(/: (true|false)/g, (_, val) => `: ${chalk_1.default.blue(val)}`)
+                    .replace(/: (null)/g, (_, val) => `: ${chalk_1.default.gray(val)}`);
+                console.log(`    ${colored}`);
+            }
+        }
+    }
+    // Expected types (from the latest non-error snapshot)
+    if (snapshot) {
+        console.log("");
+        console.log(chalk_1.default.green.bold("  ── Expected Types (Happy Path) ──"));
+        console.log("");
+        console.log(chalk_1.default.gray("  Last successful snapshot:") + `  ${(0, badges_1.envBadge)(snapshot.env)}  ${(0, badges_1.timeBadge)(snapshot.observed_at)}`);
+        if (snapshot.args_type) {
+            console.log("");
+            console.log(chalk_1.default.gray("  Expected input types:"));
+            console.log(`    ${(0, type_formatter_1.formatType)(snapshot.args_type, 4)}`);
+        }
+        if (snapshot.return_type) {
+            console.log("");
+            console.log(chalk_1.default.gray("  Expected return type:"));
+            console.log(`    ${(0, type_formatter_1.formatType)(snapshot.return_type, 4)}`);
+        }
+    }
+    console.log("");
+}

package/dist/commands/export.d.ts

@@ -0,0 +1,18 @@
+export interface ExportOptions {
+    dir?: string;
+    env?: 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 declare function exportCommand(opts: ExportOptions): Promise<void>;