trickle-cli 0.1.1 → 0.1.3

package/dist/api-client.d.ts

@@ -137,6 +137,12 @@ export interface StubsResponse {
 export declare function fetchStubs(opts?: {
     env?: string;
 }): Promise<StubsResponse>;
+export interface FunctionSample {
+    functionName: string;
+    sampleInput: unknown;
+    sampleOutput: unknown;
+}
+export declare function fetchFunctionSamples(): Promise<FunctionSample[]>;
 export interface MockRoute {
     method: string;
     path: string;

package/dist/api-client.js

@@ -45,6 +45,7 @@ exports.getTypeDiff = getTypeDiff;
 exports.fetchCodegen = fetchCodegen;
 exports.fetchAnnotations = fetchAnnotations;
 exports.fetchStubs = fetchStubs;
+exports.fetchFunctionSamples = fetchFunctionSamples;
 exports.fetchMockConfig = fetchMockConfig;
 exports.fetchSnapshot = fetchSnapshot;
 exports.fetchOpenApiSpec = fetchOpenApiSpec;
@@ -151,6 +152,29 @@ async function fetchStubs(opts) {
         format: "stubs",
     });
 }
+async function fetchFunctionSamples() {
+    const { functions } = await listFunctions({ limit: 500 });
+    const samples = [];
+    for (const fn of functions) {
+        try {
+            const data = await fetchJson(`/api/types/${encodeURIComponent(fn.function_name)}`);
+            if (data.snapshots && data.snapshots.length > 0) {
+                const snap = data.snapshots[0];
+                if (snap.sample_input || snap.sample_output) {
+                    samples.push({
+                        functionName: fn.function_name,
+                        sampleInput: snap.sample_input,
+                        sampleOutput: snap.sample_output,
+                    });
+                }
+            }
+        }
+        catch {
+            // Skip functions with no data
+        }
+    }
+    return samples;
+}
 async function fetchMockConfig() {
     return fetchJson("/api/mock-config");
 }

package/dist/commands/annotate.js

@@ -169,8 +169,9 @@ function annotateJSDoc(source, annotations) {
 // ── TypeScript annotation (inline types) ──
 /**
  * Annotate a TypeScript file with inline type annotations on function signatures.
+ * When samples are provided, adds JSDoc @example comments even for already-typed functions.
  */
-function annotateTS(source, annotations) {
+function annotateTS(source, annotations, samples) {
     const lines = source.split("\n");
     const result = [];
     for (let i = 0; i < lines.length; i++) {
@@ -181,15 +182,63 @@ function annotateTS(source, annotations) {
             continue;
         }
         const annotation = annotations[info.fnName];
-        if (!annotation) {
+        const sample = samples?.[info.fnName];
+        if (!annotation && !sample) {
             result.push(line);
             continue;
         }
-        // Skip if already typed (has a colon in param list or return annotation)
+        // Add JSDoc with @example from sample data (even for already-typed functions)
+        if (sample) {
+            // Check if there's already a trickle JSDoc comment above
+            const prevIdx = result.length - 1;
+            let alreadyHasTrickleDoc = false;
+            if (prevIdx >= 0) {
+                // Look back for a JSDoc block containing @example and "trickle"
+                let j = prevIdx;
+                while (j >= 0 && !result[j].trim().startsWith("/**"))
+                    j--;
+                if (j >= 0 && result[prevIdx].trim().endsWith("*/")) {
+                    const block = result.slice(j, prevIdx + 1).join("\n");
+                    if (block.includes("@example") && block.includes("trickle")) {
+                        alreadyHasTrickleDoc = true;
+                    }
+                }
+            }
+            if (!alreadyHasTrickleDoc) {
+                const indent = line.match(/^(\s*)/)?.[1] || "";
+                const jsdocLines = [];
+                jsdocLines.push(`${indent}/** @trickle`);
+                if (sample.sampleInput !== undefined && sample.sampleInput !== null) {
+                    jsdocLines.push(`${indent} * @example`);
+                    jsdocLines.push(`${indent} * // Sample input:`);
+                    const inputStr = JSON.stringify(sample.sampleInput, null, 2);
+                    for (const l of inputStr.split('\n')) {
+                        jsdocLines.push(`${indent} * ${l}`);
+                    }
+                }
+                if (sample.sampleOutput !== undefined && sample.sampleOutput !== null) {
+                    if (sample.sampleInput === undefined || sample.sampleInput === null) {
+                        jsdocLines.push(`${indent} * @example`);
+                    }
+                    jsdocLines.push(`${indent} * // Sample output:`);
+                    const outputStr = JSON.stringify(sample.sampleOutput, null, 2);
+                    for (const l of outputStr.split('\n')) {
+                        jsdocLines.push(`${indent} * ${l}`);
+                    }
+                }
+                jsdocLines.push(`${indent} */`);
+                result.push(...jsdocLines);
+            }
+        }
+        // Skip inline type modification if already typed
         if (info.rawParams.includes(":") || line.includes("): ")) {
             result.push(line);
             continue;
         }
+        if (!annotation) {
+            result.push(line);
+            continue;
+        }
         // Build typed param list
         const paramNames = getParamNames(info.rawParams);
         const typedParams = paramNames.map((pName) => {
@@ -315,7 +364,18 @@ async function annotateCommand(file, opts) {
         env: opts.env,
         language: apiLanguage,
     });
-    if (!annotations || Object.keys(annotations).length === 0) {
+    // Fetch sample data for @example JSDoc
+    let samplesMap = {};
+    try {
+        const samples = await (0, api_client_1.fetchFunctionSamples)();
+        for (const s of samples) {
+            samplesMap[s.functionName] = s;
+        }
+    }
+    catch {
+        // Sample data is optional
+    }
+    if ((!annotations || Object.keys(annotations).length === 0) && Object.keys(samplesMap).length === 0) {
         console.log(chalk_1.default.yellow("\n  No observed types found. Run your code with trickle first.\n"));
         return;
     }
@@ -332,8 +392,8 @@ async function annotateCommand(file, opts) {
         mode = "JSDoc comments";
     }
     else {
-        annotated = annotateTS(source, annotations);
-        mode = "TypeScript annotations";
+        annotated = annotateTS(source, annotations, samplesMap);
+        mode = "TypeScript annotations + sample data";
     }
     // Count changes
     const originalLines = source.split("\n");

package/dist/commands/run.js

@@ -309,7 +309,10 @@ async function executeSingleRun(instrumentedCommand, env, opts, singleFile, loca
         }
         // Start live type generation for backend mode
         let liveStop = null;
-        if (singleFile && !opts.stubs) {
+        if (opts.stubs) {
+            liveStop = startLiveStubsGeneration(opts.stubs);
+        }
+        else if (singleFile) {
             liveStop = startLiveBackendTypes(singleFile);
         }
         // Run the instrumented command
@@ -499,6 +502,43 @@ function startLiveBackendTypes(sourceFile) {
         clearInterval(interval);
     };
 }
+// ── Live stubs generation during run ──
+function startLiveStubsGeneration(stubsDir) {
+    let lastTotal = 0;
+    let stopped = false;
+    const poll = async () => {
+        if (stopped)
+            return;
+        try {
+            const { stubsCommand } = await Promise.resolve().then(() => __importStar(require("./stubs")));
+            const result = await stubsCommand(stubsDir, { silent: true });
+            // Count .d.ts files in the stubs dir to track progress
+            const files = fs.readdirSync(stubsDir).filter(f => f.endsWith('.d.ts'));
+            let funcCount = 0;
+            for (const f of files) {
+                const content = fs.readFileSync(path.join(stubsDir, f), 'utf-8');
+                funcCount += (content.match(/export declare function/g) || []).length;
+            }
+            if (funcCount > lastTotal) {
+                const newCount = funcCount - lastTotal;
+                const ts = new Date().toLocaleTimeString("en-US", { hour12: false });
+                console.log(chalk_1.default.gray(`  [${ts}]`) +
+                    chalk_1.default.green(` +${newCount} type(s)`) +
+                    chalk_1.default.gray(` → ${stubsDir}`) +
+                    chalk_1.default.gray(` (${funcCount} total)`));
+                lastTotal = funcCount;
+            }
+        }
+        catch {
+            // Never crash — background helper
+        }
+    };
+    const interval = setInterval(poll, 3000);
+    return () => {
+        stopped = true;
+        clearInterval(interval);
+    };
+}
 // ── Auto-generate sidecar type file ──
 async function autoGenerateSidecar(filePath) {
     try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "trickle-cli",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "CLI for trickle runtime type observability",
   "bin": {
     "trickle": "dist/index.js"

package/src/api-client.ts

@@ -244,6 +244,37 @@ export async function fetchStubs(opts?: {
   });
 }
 
+export interface FunctionSample {
+  functionName: string;
+  sampleInput: unknown;
+  sampleOutput: unknown;
+}
+
+export async function fetchFunctionSamples(): Promise<FunctionSample[]> {
+  const { functions } = await listFunctions({ limit: 500 });
+  const samples: FunctionSample[] = [];
+  for (const fn of functions) {
+    try {
+      const data = await fetchJson<{ snapshots: Array<{ sample_input: unknown; sample_output: unknown }> }>(
+        `/api/types/${encodeURIComponent(fn.function_name)}`
+      );
+      if (data.snapshots && data.snapshots.length > 0) {
+        const snap = data.snapshots[0];
+        if (snap.sample_input || snap.sample_output) {
+          samples.push({
+            functionName: fn.function_name,
+            sampleInput: snap.sample_input,
+            sampleOutput: snap.sample_output,
+          });
+        }
+      }
+    } catch {
+      // Skip functions with no data
+    }
+  }
+  return samples;
+}
+
 export interface MockRoute {
   method: string;
   path: string;

package/src/commands/annotate.ts

@@ -1,7 +1,7 @@
 import * as fs from "fs";
 import * as path from "path";
 import chalk from "chalk";
-import { fetchAnnotations, AnnotationEntry } from "../api-client";
+import { fetchAnnotations, fetchFunctionSamples, AnnotationEntry, FunctionSample } from "../api-client";
 
 export interface AnnotateOptions {
   env?: string;
@@ -151,8 +151,9 @@ function annotateJSDoc(source: string, annotations: Record<string, AnnotationEnt
 
 /**
  * Annotate a TypeScript file with inline type annotations on function signatures.
+ * When samples are provided, adds JSDoc @example comments even for already-typed functions.
  */
-function annotateTS(source: string, annotations: Record<string, AnnotationEntry>): string {
+function annotateTS(source: string, annotations: Record<string, AnnotationEntry>, samples?: Record<string, FunctionSample>): string {
   const lines = source.split("\n");
   const result: string[] = [];
 
@@ -166,17 +167,71 @@ function annotateTS(source: string, annotations: Record<string, AnnotationEntry>
     }
 
     const annotation = annotations[info.fnName];
-    if (!annotation) {
+    const sample = samples?.[info.fnName];
+
+    if (!annotation && !sample) {
       result.push(line);
       continue;
     }
 
-    // Skip if already typed (has a colon in param list or return annotation)
+    // Add JSDoc with @example from sample data (even for already-typed functions)
+    if (sample) {
+      // Check if there's already a trickle JSDoc comment above
+      const prevIdx = result.length - 1;
+      let alreadyHasTrickleDoc = false;
+      if (prevIdx >= 0) {
+        // Look back for a JSDoc block containing @example and "trickle"
+        let j = prevIdx;
+        while (j >= 0 && !result[j].trim().startsWith("/**")) j--;
+        if (j >= 0 && result[prevIdx].trim().endsWith("*/")) {
+          const block = result.slice(j, prevIdx + 1).join("\n");
+          if (block.includes("@example") && block.includes("trickle")) {
+            alreadyHasTrickleDoc = true;
+          }
+        }
+      }
+
+      if (!alreadyHasTrickleDoc) {
+        const indent = line.match(/^(\s*)/)?.[1] || "";
+        const jsdocLines: string[] = [];
+        jsdocLines.push(`${indent}/** @trickle`);
+
+        if (sample.sampleInput !== undefined && sample.sampleInput !== null) {
+          jsdocLines.push(`${indent} * @example`);
+          jsdocLines.push(`${indent} * // Sample input:`);
+          const inputStr = JSON.stringify(sample.sampleInput, null, 2);
+          for (const l of inputStr.split('\n')) {
+            jsdocLines.push(`${indent} * ${l}`);
+          }
+        }
+
+        if (sample.sampleOutput !== undefined && sample.sampleOutput !== null) {
+          if (sample.sampleInput === undefined || sample.sampleInput === null) {
+            jsdocLines.push(`${indent} * @example`);
+          }
+          jsdocLines.push(`${indent} * // Sample output:`);
+          const outputStr = JSON.stringify(sample.sampleOutput, null, 2);
+          for (const l of outputStr.split('\n')) {
+            jsdocLines.push(`${indent} * ${l}`);
+          }
+        }
+
+        jsdocLines.push(`${indent} */`);
+        result.push(...jsdocLines);
+      }
+    }
+
+    // Skip inline type modification if already typed
     if (info.rawParams.includes(":") || line.includes("): ")) {
       result.push(line);
       continue;
     }
 
+    if (!annotation) {
+      result.push(line);
+      continue;
+    }
+
     // Build typed param list
     const paramNames = getParamNames(info.rawParams);
 
@@ -331,7 +386,18 @@ export async function annotateCommand(
     language: apiLanguage,
   });
 
-  if (!annotations || Object.keys(annotations).length === 0) {
+  // Fetch sample data for @example JSDoc
+  let samplesMap: Record<string, FunctionSample> = {};
+  try {
+    const samples = await fetchFunctionSamples();
+    for (const s of samples) {
+      samplesMap[s.functionName] = s;
+    }
+  } catch {
+    // Sample data is optional
+  }
+
+  if ((!annotations || Object.keys(annotations).length === 0) && Object.keys(samplesMap).length === 0) {
     console.log(chalk.yellow("\n  No observed types found. Run your code with trickle first.\n"));
     return;
   }
@@ -348,8 +414,8 @@ export async function annotateCommand(
     annotated = annotateJSDoc(source, annotations);
     mode = "JSDoc comments";
   } else {
-    annotated = annotateTS(source, annotations);
-    mode = "TypeScript annotations";
+    annotated = annotateTS(source, annotations, samplesMap);
+    mode = "TypeScript annotations + sample data";
   }
 
   // Count changes

package/src/commands/run.ts

@@ -350,7 +350,9 @@ async function executeSingleRun(
 
     // Start live type generation for backend mode
     let liveStop: (() => void) | null = null;
-    if (singleFile && !opts.stubs) {
+    if (opts.stubs) {
+      liveStop = startLiveStubsGeneration(opts.stubs);
+    } else if (singleFile) {
       liveStop = startLiveBackendTypes(singleFile);
     }
 
@@ -573,6 +575,49 @@ function startLiveBackendTypes(sourceFile: string): () => void {
   };
 }
 
+// ── Live stubs generation during run ──
+
+function startLiveStubsGeneration(stubsDir: string): () => void {
+  let lastTotal = 0;
+  let stopped = false;
+
+  const poll = async () => {
+    if (stopped) return;
+    try {
+      const { stubsCommand } = await import("./stubs");
+      const result = await stubsCommand(stubsDir, { silent: true });
+
+      // Count .d.ts files in the stubs dir to track progress
+      const files = fs.readdirSync(stubsDir).filter(f => f.endsWith('.d.ts'));
+      let funcCount = 0;
+      for (const f of files) {
+        const content = fs.readFileSync(path.join(stubsDir, f), 'utf-8');
+        funcCount += (content.match(/export declare function/g) || []).length;
+      }
+
+      if (funcCount > lastTotal) {
+        const newCount = funcCount - lastTotal;
+        const ts = new Date().toLocaleTimeString("en-US", { hour12: false });
+        console.log(
+          chalk.gray(`  [${ts}]`) +
+          chalk.green(` +${newCount} type(s)`) +
+          chalk.gray(` → ${stubsDir}`) +
+          chalk.gray(` (${funcCount} total)`),
+        );
+        lastTotal = funcCount;
+      }
+    } catch {
+      // Never crash — background helper
+    }
+  };
+
+  const interval = setInterval(poll, 3000);
+  return () => {
+    stopped = true;
+    clearInterval(interval);
+  };
+}
+
 // ── Auto-generate sidecar type file ──
 
 async function autoGenerateSidecar(filePath: string): Promise<void> {