trickle-cli 0.1.0

package/dist/commands/annotate.js

@@ -0,0 +1,433 @@
+"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.annotateCommand = annotateCommand;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const chalk_1 = __importDefault(require("chalk"));
+const api_client_1 = require("../api-client");
+/**
+ * Detect file kind from extension.
+ * JavaScript files get JSDoc comments; TypeScript files get inline type annotations.
+ */
+function detectFileKind(filePath) {
+    const ext = path.extname(filePath).toLowerCase();
+    if ([".ts", ".tsx"].includes(ext))
+        return "typescript";
+    if ([".js", ".jsx", ".mjs", ".cjs"].includes(ext))
+        return "javascript";
+    if ([".py", ".pyi"].includes(ext))
+        return "python";
+    return null;
+}
+// ── Shared regex for JS/TS function detection ──
+const funcDeclRe = /^(\s*(?:export\s+)?(?:async\s+)?function\s+)(\w+)\s*\(([^)]*)\)/;
+const arrowRe = /^(\s*(?:export\s+)?(?:const|let|var)\s+)(\w+)\s*=\s*(?:async\s+)?\(([^)]*)\)/;
+const methodRe = /^(\s+)(\w+)\s*\(([^)]*)\)\s*\{/;
+/**
+ * Extract function name and raw params from a line, if it matches a function pattern.
+ */
+function matchFunction(line) {
+    let match = funcDeclRe.exec(line);
+    if (match)
+        return { fnName: match[2], rawParams: match[3].trim(), kind: "function", match };
+    match = arrowRe.exec(line);
+    if (match)
+        return { fnName: match[2], rawParams: match[3].trim(), kind: "arrow", match };
+    match = methodRe.exec(line);
+    if (match)
+        return { fnName: match[2], rawParams: match[3].trim(), kind: "method", match };
+    return null;
+}
+/**
+ * Get param names from raw param string, filtering out complex patterns.
+ */
+function getParamNames(rawParams) {
+    if (!rawParams)
+        return [];
+    return rawParams.split(",").map((p) => p.trim());
+}
+// ── JSDoc annotation for JavaScript files ──
+/**
+ * Annotate a JavaScript file with JSDoc comments above functions.
+ * Produces valid JavaScript that IDEs understand for type hints.
+ */
+function annotateJSDoc(source, annotations) {
+    const lines = source.split("\n");
+    const result = [];
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        const info = matchFunction(line);
+        if (!info) {
+            result.push(line);
+            continue;
+        }
+        const annotation = annotations[info.fnName];
+        if (!annotation) {
+            result.push(line);
+            continue;
+        }
+        // Skip if there's already a JSDoc comment right above
+        const prevLineIdx = result.length - 1;
+        if (prevLineIdx >= 0) {
+            const prevLine = result[prevLineIdx].trim();
+            if (prevLine === "*/" || prevLine.endsWith("*/")) {
+                // Check if this is a JSDoc block that already has @param or @returns
+                let j = prevLineIdx;
+                while (j >= 0 && !result[j].trim().startsWith("/**"))
+                    j--;
+                if (j >= 0) {
+                    const block = result.slice(j, prevLineIdx + 1).join("\n");
+                    if (block.includes("@param") || block.includes("@returns")) {
+                        result.push(line);
+                        continue;
+                    }
+                }
+            }
+        }
+        // Build JSDoc comment
+        const paramNames = getParamNames(info.rawParams);
+        const indent = line.match(/^(\s*)/)?.[1] || "";
+        const jsdocLines = [];
+        jsdocLines.push(`${indent}/**`);
+        // Add @param tags
+        for (const pName of paramNames) {
+            if (pName.startsWith("...") || pName.startsWith("{") || pName.includes("=")) {
+                // Handle rest, destructured, default params
+                const baseName = pName.startsWith("...")
+                    ? pName.slice(3)
+                    : pName.includes("=")
+                        ? pName.slice(0, pName.indexOf("=")).trim()
+                        : pName;
+                const paramType = annotation.params.find((a) => a.name === baseName);
+                if (paramType) {
+                    jsdocLines.push(`${indent} * @param {${paramType.type}} ${baseName}`);
+                }
+                continue;
+            }
+            // Try name match first, then positional
+            let paramType = annotation.params.find((a) => a.name === pName);
+            if (!paramType) {
+                const idx = paramNames.indexOf(pName);
+                if (idx >= 0 && idx < annotation.params.length) {
+                    paramType = annotation.params[idx];
+                }
+            }
+            if (paramType) {
+                jsdocLines.push(`${indent} * @param {${paramType.type}} ${pName}`);
+            }
+        }
+        // Add @returns tag
+        if (annotation.returnType && annotation.returnType !== "void" && annotation.returnType !== "undefined") {
+            jsdocLines.push(`${indent} * @returns {${annotation.returnType}}`);
+        }
+        jsdocLines.push(`${indent} */`);
+        // Only add JSDoc if we have useful content
+        if (jsdocLines.length > 2) {
+            // Insert JSDoc before the function line
+            result.push(...jsdocLines);
+        }
+        result.push(line);
+    }
+    return result.join("\n");
+}
+// ── TypeScript annotation (inline types) ──
+/**
+ * Annotate a TypeScript file with inline type annotations on function signatures.
+ */
+function annotateTS(source, annotations) {
+    const lines = source.split("\n");
+    const result = [];
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        const info = matchFunction(line);
+        if (!info) {
+            result.push(line);
+            continue;
+        }
+        const annotation = annotations[info.fnName];
+        if (!annotation) {
+            result.push(line);
+            continue;
+        }
+        // Skip if already typed (has a colon in param list or return annotation)
+        if (info.rawParams.includes(":") || line.includes("): ")) {
+            result.push(line);
+            continue;
+        }
+        // Build typed param list
+        const paramNames = getParamNames(info.rawParams);
+        const typedParams = paramNames.map((pName) => {
+            if (pName.startsWith("...") || pName.startsWith("{") || pName.includes("=")) {
+                return pName;
+            }
+            const paramType = annotation.params.find((a) => a.name === pName);
+            if (paramType) {
+                return `${pName}: ${paramType.type}`;
+            }
+            const idx = paramNames.indexOf(pName);
+            if (idx >= 0 && idx < annotation.params.length) {
+                return `${pName}: ${annotation.params[idx].type}`;
+            }
+            return pName;
+        });
+        const typedParamStr = typedParams.join(", ");
+        const retType = annotation.returnType;
+        if (info.kind === "function") {
+            const prefix = info.match[1];
+            const rest = line.slice(info.match[0].length);
+            const hasReturnType = rest.match(/^\s*:/);
+            if (hasReturnType) {
+                result.push(`${prefix}${info.fnName}(${typedParamStr})${rest}`);
+            }
+            else {
+                result.push(`${prefix}${info.fnName}(${typedParamStr}): ${retType}${rest}`);
+            }
+        }
+        else if (info.kind === "arrow") {
+            const prefix = info.match[1];
+            const afterMatch = line.slice(info.match[0].length);
+            const asyncMatch = line.match(new RegExp(`${info.fnName}\\s*=\\s*(async\\s+)?\\(`));
+            const asyncPrefix = asyncMatch?.[1] || "";
+            result.push(`${prefix}${info.fnName} = ${asyncPrefix}(${typedParamStr}): ${retType}${afterMatch}`);
+        }
+        else {
+            const indent = info.match[1];
+            const rest = line.slice(info.match[0].length);
+            result.push(`${indent}${info.fnName}(${typedParamStr}): ${retType} {${rest}`);
+        }
+    }
+    return result.join("\n");
+}
+// ── Python annotation ──
+/**
+ * Annotate a Python file with inline type annotations.
+ */
+function annotatePython(source, annotations) {
+    const lines = source.split("\n");
+    const result = [];
+    const defRe = /^(\s*(?:async\s+)?def\s+)(\w+)\s*\(([^)]*)\)\s*(->\s*\S+\s*)?:/;
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        const match = defRe.exec(line);
+        if (!match) {
+            result.push(line);
+            continue;
+        }
+        const prefix = match[1];
+        const fnName = match[2];
+        const rawParams = match[3].trim();
+        const existingReturn = match[4];
+        const annotation = annotations[fnName];
+        if (!annotation) {
+            result.push(line);
+            continue;
+        }
+        const paramsHaveTypes = rawParams.split(",").some((p) => {
+            const trimmed = p.trim();
+            if (trimmed === "self" || trimmed === "cls")
+                return false;
+            return trimmed.includes(":") && !trimmed.startsWith("*");
+        });
+        if (paramsHaveTypes && existingReturn) {
+            result.push(line);
+            continue;
+        }
+        const paramNames = rawParams ? rawParams.split(",").map((p) => p.trim()) : [];
+        const typedParams = paramNames.map((pName) => {
+            if (pName === "self" || pName === "cls" || pName.startsWith("*") || pName.includes(":")) {
+                return pName;
+            }
+            const eqIdx = pName.indexOf("=");
+            const baseName = eqIdx >= 0 ? pName.slice(0, eqIdx).trim() : pName;
+            const defaultPart = eqIdx >= 0 ? ` = ${pName.slice(eqIdx + 1).trim()}` : "";
+            const paramType = annotation.params.find((a) => a.name === baseName);
+            if (paramType) {
+                return `${baseName}: ${paramType.type}${defaultPart}`;
+            }
+            const nonSelfParams = paramNames.filter((p) => p !== "self" && p !== "cls" && !p.startsWith("*"));
+            const idx = nonSelfParams.indexOf(pName);
+            if (idx >= 0 && idx < annotation.params.length) {
+                return `${baseName}: ${annotation.params[idx].type}${defaultPart}`;
+            }
+            return pName;
+        });
+        const typedParamStr = typedParams.join(", ");
+        const retAnnotation = existingReturn || ` -> ${annotation.returnType}`;
+        result.push(`${prefix}${fnName}(${typedParamStr})${retAnnotation}:`);
+    }
+    return result.join("\n");
+}
+// ── Main command ──
+async function annotateCommand(file, opts) {
+    const filePath = path.resolve(file);
+    if (!fs.existsSync(filePath)) {
+        console.error(chalk_1.default.red(`\n  File not found: ${filePath}\n`));
+        process.exit(1);
+    }
+    const fileKind = detectFileKind(filePath);
+    if (!fileKind) {
+        console.error(chalk_1.default.red(`\n  Unsupported file type: ${path.extname(filePath)}\n`));
+        console.error(chalk_1.default.gray("  Supported: .ts, .tsx, .js, .jsx, .mjs, .cjs, .py, .pyi\n"));
+        process.exit(1);
+    }
+    // Determine annotation language for the API
+    const apiLanguage = fileKind === "python" ? "python" : undefined;
+    // Determine annotation mode
+    // --jsdoc flag forces JSDoc mode; otherwise JS files get JSDoc automatically
+    const useJSDoc = opts.jsdoc || fileKind === "javascript";
+    const { annotations } = await (0, api_client_1.fetchAnnotations)({
+        env: opts.env,
+        language: apiLanguage,
+    });
+    if (!annotations || Object.keys(annotations).length === 0) {
+        console.log(chalk_1.default.yellow("\n  No observed types found. Run your code with trickle first.\n"));
+        return;
+    }
+    const source = fs.readFileSync(filePath, "utf-8");
+    // Apply annotations based on file type
+    let annotated;
+    let mode;
+    if (fileKind === "python") {
+        annotated = annotatePython(source, annotations);
+        mode = "Python type annotations";
+    }
+    else if (useJSDoc) {
+        annotated = annotateJSDoc(source, annotations);
+        mode = "JSDoc comments";
+    }
+    else {
+        annotated = annotateTS(source, annotations);
+        mode = "TypeScript annotations";
+    }
+    // Count changes
+    const originalLines = source.split("\n");
+    const annotatedLines = annotated.split("\n");
+    // For JSDoc, count functions annotated (not lines changed, since JSDoc adds lines)
+    let changeCount = 0;
+    if (useJSDoc && fileKind !== "python") {
+        // Count new JSDoc blocks added
+        for (let i = 0; i < annotatedLines.length; i++) {
+            if (annotatedLines[i].trimEnd().endsWith("/**") && (i >= originalLines.length || originalLines[i] !== annotatedLines[i])) {
+                changeCount++;
+            }
+        }
+    }
+    else {
+        for (let i = 0; i < Math.max(originalLines.length, annotatedLines.length); i++) {
+            if ((originalLines[i] || "") !== (annotatedLines[i] || ""))
+                changeCount++;
+        }
+    }
+    if (changeCount === 0) {
+        console.log(chalk_1.default.gray("\n  No annotations to add — functions already typed or not observed.\n"));
+        return;
+    }
+    if (opts.dryRun) {
+        console.log(chalk_1.default.cyan(`\n  Dry run — ${mode} that would be added:\n`));
+        if (useJSDoc && fileKind !== "python") {
+            // Show JSDoc blocks that would be inserted
+            let inNew = false;
+            for (let i = 0; i < annotatedLines.length; i++) {
+                const isNewLine = i >= originalLines.length || originalLines[i] !== annotatedLines[i];
+                if (isNewLine && !inNew) {
+                    // Find the function line that follows this JSDoc
+                    inNew = true;
+                }
+                if (isNewLine) {
+                    console.log(chalk_1.default.green(`  + ${annotatedLines[i]}`));
+                    if (annotatedLines[i].trimEnd().endsWith("*/")) {
+                        inNew = false;
+                    }
+                }
+            }
+        }
+        else {
+            for (let i = 0; i < Math.max(originalLines.length, annotatedLines.length); i++) {
+                if ((originalLines[i] || "") !== (annotatedLines[i] || "")) {
+                    console.log(chalk_1.default.red(`  - ${(originalLines[i] || "").trim()}`));
+                    console.log(chalk_1.default.green(`  + ${(annotatedLines[i] || "").trim()}`));
+                    console.log();
+                }
+            }
+        }
+        console.log(chalk_1.default.gray(`\n  ${changeCount} function(s) would be annotated with ${mode}.\n`));
+        return;
+    }
+    // Write annotated file
+    fs.writeFileSync(filePath, annotated, "utf-8");
+    console.log(chalk_1.default.green(`\n  Annotated ${changeCount} function(s) in ${path.relative(process.cwd(), filePath)} (${mode})\n`));
+    // Show what changed
+    if (useJSDoc && fileKind !== "python") {
+        // Show JSDoc blocks that were added
+        let inBlock = false;
+        let blockLines = [];
+        for (let i = 0; i < annotatedLines.length; i++) {
+            const isNew = i >= originalLines.length || originalLines[i] !== annotatedLines[i];
+            if (isNew && annotatedLines[i].trimEnd().endsWith("/**")) {
+                inBlock = true;
+                blockLines = [annotatedLines[i]];
+            }
+            else if (inBlock) {
+                blockLines.push(annotatedLines[i]);
+                if (annotatedLines[i].trimEnd().endsWith("*/")) {
+                    inBlock = false;
+                    // Next line should be the function
+                    const fnLine = annotatedLines[i + 1] || "";
+                    const fnMatch = fnLine.match(/(?:function|const|let|var)\s+(\w+)/);
+                    const fnName = fnMatch?.[1] || "function";
+                    console.log(chalk_1.default.gray(`  ${fnName}:`));
+                    for (const bl of blockLines) {
+                        console.log(chalk_1.default.gray(`    ${bl.trim()}`));
+                    }
+                }
+            }
+        }
+    }
+    else {
+        for (let i = 0; i < annotatedLines.length; i++) {
+            if (i < originalLines.length && originalLines[i] !== annotatedLines[i]) {
+                const fnMatch = annotatedLines[i].match(/(?:function|def|const|let|var)\s+(\w+)/);
+                const fnName = fnMatch?.[1] || "unknown";
+                console.log(chalk_1.default.gray(`  ${fnName}:`));
+                console.log(chalk_1.default.gray(`    ${annotatedLines[i].trim()}`));
+            }
+        }
+    }
+    console.log();
+}

package/dist/commands/audit.d.ts

@@ -0,0 +1,7 @@
+export interface AuditOptions {
+    env?: string;
+    json?: boolean;
+    failOnError?: boolean;
+    failOnWarning?: boolean;
+}
+export declare function auditCommand(opts: AuditOptions): Promise<void>;

package/dist/commands/audit.js

@@ -0,0 +1,82 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.auditCommand = auditCommand;
+const chalk_1 = __importDefault(require("chalk"));
+const config_1 = require("../config");
+async function auditCommand(opts) {
+    const base = (0, config_1.getBackendUrl)();
+    const url = new URL("/api/audit", base);
+    if (opts.env)
+        url.searchParams.set("env", opts.env);
+    let data;
+    try {
+        const res = await fetch(url.toString());
+        if (!res.ok)
+            throw new Error(`HTTP ${res.status}`);
+        data = (await res.json());
+    }
+    catch {
+        console.error(chalk_1.default.red(`\n  Cannot connect to trickle backend at ${chalk_1.default.bold(base)}.`));
+        console.error(chalk_1.default.red("  Is the backend running?\n"));
+        process.exit(1);
+    }
+    if (opts.json) {
+        console.log(JSON.stringify(data, null, 2));
+        if (opts.failOnError && data.summary.errors > 0)
+            process.exit(1);
+        if (opts.failOnWarning && (data.summary.errors + data.summary.warnings) > 0)
+            process.exit(1);
+        return;
+    }
+    console.log("");
+    console.log(chalk_1.default.bold("  API Audit Report"));
+    console.log(chalk_1.default.gray(`  ${data.summary.routesAnalyzed} routes analyzed\n`));
+    if (data.issues.length === 0) {
+        console.log(chalk_1.default.green("  ✓ No issues found — your API looks clean!\n"));
+        return;
+    }
+    // Group by severity
+    const errors = data.issues.filter((i) => i.severity === "error");
+    const warnings = data.issues.filter((i) => i.severity === "warning");
+    const infos = data.issues.filter((i) => i.severity === "info");
+    if (errors.length > 0) {
+        console.log(chalk_1.default.red.bold(`  ✗ ${errors.length} error${errors.length > 1 ? "s" : ""}`));
+        for (const issue of errors) {
+            const route = issue.route ? chalk_1.default.gray(` [${issue.route}]`) : "";
+            console.log(chalk_1.default.red(`    • ${issue.message}${route}`));
+        }
+        console.log("");
+    }
+    if (warnings.length > 0) {
+        console.log(chalk_1.default.yellow.bold(`  ⚠ ${warnings.length} warning${warnings.length > 1 ? "s" : ""}`));
+        for (const issue of warnings) {
+            const route = issue.route ? chalk_1.default.gray(` [${issue.route}]`) : "";
+            console.log(chalk_1.default.yellow(`    • ${issue.message}${route}`));
+        }
+        console.log("");
+    }
+    if (infos.length > 0) {
+        console.log(chalk_1.default.blue.bold(`  ℹ ${infos.length} info`));
+        for (const issue of infos) {
+            const route = issue.route ? chalk_1.default.gray(` [${issue.route}]`) : "";
+            console.log(chalk_1.default.blue(`    • ${issue.message}${route}`));
+        }
+        console.log("");
+    }
+    // Summary line
+    const parts = [];
+    if (errors.length > 0)
+        parts.push(chalk_1.default.red(`${errors.length} errors`));
+    if (warnings.length > 0)
+        parts.push(chalk_1.default.yellow(`${warnings.length} warnings`));
+    if (infos.length > 0)
+        parts.push(chalk_1.default.blue(`${infos.length} info`));
+    console.log(chalk_1.default.gray(`  Total: ${parts.join(", ")}\n`));
+    if (opts.failOnError && data.summary.errors > 0)
+        process.exit(1);
+    if (opts.failOnWarning && (data.summary.errors + data.summary.warnings) > 0)
+        process.exit(1);
+}

package/dist/commands/auto.d.ts

@@ -0,0 +1,8 @@
+export interface AutoOptions {
+    dir?: string;
+    env?: string;
+}
+/**
+ * `trickle auto` — Auto-detect project deps and generate only relevant type files.
+ */
+export declare function autoCommand(opts: AutoOptions): Promise<void>;