trickle-observe 0.2.60 → 0.2.62

package/dist/lambda.d.ts

@@ -0,0 +1,61 @@
+/**
+ * trickle/lambda — Zero-config observability for AWS Lambda functions.
+ *
+ * Wraps a Lambda handler to:
+ * 1. Auto-instrument all functions with type observation
+ * 2. Write observations to /tmp/.trickle/ (Lambda's writable filesystem)
+ *    OR send to TRICKLE_BACKEND_URL if set
+ * 3. Flush all pending observations synchronously before Lambda freezes
+ *
+ * Usage:
+ *
+ *   import { wrapLambda } from 'trickle-observe/lambda';
+ *
+ *   export const handler = wrapLambda(async (event, context) => {
+ *     const result = await processOrder(event.orderId);
+ *     return { statusCode: 200, body: JSON.stringify(result) };
+ *   });
+ *
+ * OR zero-code via NODE_OPTIONS:
+ *
+ *   NODE_OPTIONS="--require trickle-observe/auto-env" TRICKLE_AUTO=1
+ *
+ * Environment variables:
+ *   TRICKLE_BACKEND_URL    — Send observations to HTTP backend (optional)
+ *   TRICKLE_LOCAL_DIR      — Override local dir (default: /tmp/.trickle)
+ *   TRICKLE_DEBUG          — Set to "1" for debug logging
+ *   TRICKLE_OBSERVE_INCLUDE — Comma-separated substrings to observe
+ *   TRICKLE_OBSERVE_EXCLUDE — Comma-separated substrings to skip
+ */
+import './observe-register';
+export type LambdaEvent = Record<string, unknown>;
+export type LambdaContext = {
+    functionName: string;
+    functionVersion: string;
+    invokedFunctionArn: string;
+    awsRequestId: string;
+    remainingTimeInMillis?: () => number;
+    [key: string]: unknown;
+};
+export type LambdaHandler<E = LambdaEvent, R = unknown> = (event: E, context: LambdaContext) => Promise<R>;
+/**
+ * Wrap a Lambda handler with trickle observability.
+ *
+ * Instruments all called functions automatically, writes type observations
+ * to /tmp/.trickle/, and flushes before Lambda freezes the process.
+ */
+export declare function wrapLambda<E = LambdaEvent, R = unknown>(handler: LambdaHandler<E, R>): LambdaHandler<E, R>;
+/**
+ * Print the contents of the local trickle observations directory to stdout
+ * as newline-delimited JSON. Useful for inspecting Lambda observations in
+ * CloudWatch Logs when TRICKLE_BACKEND_URL is not set.
+ *
+ * Call at the end of your handler to stream observations to CloudWatch:
+ *
+ *   export const handler = wrapLambda(async (event) => {
+ *     const result = await processOrder(event.orderId);
+ *     printObservations();  // → streamed to CloudWatch Logs
+ *     return result;
+ *   });
+ */
+export declare function printObservations(): void;

package/dist/lambda.js

@@ -0,0 +1,177 @@
+"use strict";
+/**
+ * trickle/lambda — Zero-config observability for AWS Lambda functions.
+ *
+ * Wraps a Lambda handler to:
+ * 1. Auto-instrument all functions with type observation
+ * 2. Write observations to /tmp/.trickle/ (Lambda's writable filesystem)
+ *    OR send to TRICKLE_BACKEND_URL if set
+ * 3. Flush all pending observations synchronously before Lambda freezes
+ *
+ * Usage:
+ *
+ *   import { wrapLambda } from 'trickle-observe/lambda';
+ *
+ *   export const handler = wrapLambda(async (event, context) => {
+ *     const result = await processOrder(event.orderId);
+ *     return { statusCode: 200, body: JSON.stringify(result) };
+ *   });
+ *
+ * OR zero-code via NODE_OPTIONS:
+ *
+ *   NODE_OPTIONS="--require trickle-observe/auto-env" TRICKLE_AUTO=1
+ *
+ * Environment variables:
+ *   TRICKLE_BACKEND_URL    — Send observations to HTTP backend (optional)
+ *   TRICKLE_LOCAL_DIR      — Override local dir (default: /tmp/.trickle)
+ *   TRICKLE_DEBUG          — Set to "1" for debug logging
+ *   TRICKLE_OBSERVE_INCLUDE — Comma-separated substrings to observe
+ *   TRICKLE_OBSERVE_EXCLUDE — Comma-separated substrings to skip
+ */
+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;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.wrapLambda = wrapLambda;
+exports.printObservations = printObservations;
+const path = __importStar(require("path"));
+const fs = __importStar(require("fs"));
+const transport_1 = require("./transport");
+const trace_var_1 = require("./trace-var");
+// Install Module._compile and Module._load hooks for auto-instrumentation
+require("./observe-register");
+let initialized = false;
+function initOnce() {
+    if (initialized)
+        return;
+    initialized = true;
+    const debug = process.env.TRICKLE_DEBUG === '1';
+    const dir = process.env.TRICKLE_LOCAL_DIR || '/tmp/.trickle';
+    // Ensure /tmp/.trickle exists (writable in Lambda, unlike /var/task)
+    try {
+        fs.mkdirSync(dir, { recursive: true });
+    }
+    catch { }
+    if (process.env.TRICKLE_BACKEND_URL) {
+        // HTTP mode: send to developer's backend (e.g. via ngrok)
+        (0, transport_1.configure)({
+            backendUrl: process.env.TRICKLE_BACKEND_URL,
+            batchIntervalMs: 100, // aggressive batching for Lambda
+            enabled: true,
+            debug,
+            environment: 'node',
+        });
+        if (debug)
+            console.log(`[trickle/lambda] HTTP mode → ${process.env.TRICKLE_BACKEND_URL}`);
+    }
+    else {
+        // Local file mode: write to /tmp/.trickle/observations.jsonl
+        process.env.TRICKLE_LOCAL = '1';
+        process.env.TRICKLE_LOCAL_DIR = dir;
+        (0, transport_1.configure)({ backendUrl: 'http://localhost:4888', batchIntervalMs: 2000, enabled: true, debug, environment: 'node' });
+        if (debug)
+            console.log(`[trickle/lambda] Local mode → ${dir}/observations.jsonl`);
+    }
+    // Initialize variable tracer (writes to variables.jsonl)
+    (0, trace_var_1.initVarTracer)({ debug });
+}
+/**
+ * Wrap a Lambda handler with trickle observability.
+ *
+ * Instruments all called functions automatically, writes type observations
+ * to /tmp/.trickle/, and flushes before Lambda freezes the process.
+ */
+function wrapLambda(handler) {
+    return async (event, context) => {
+        initOnce();
+        const debug = process.env.TRICKLE_DEBUG === '1';
+        const startMs = Date.now();
+        try {
+            const result = await handler(event, context);
+            // Flush pending HTTP observations before Lambda freezes the process.
+            // File-mode writes are already synchronous, so no flush needed there.
+            if (process.env.TRICKLE_BACKEND_URL) {
+                await (0, transport_1.flush)();
+            }
+            if (debug) {
+                const dir = process.env.TRICKLE_LOCAL_DIR || '/tmp/.trickle';
+                const elapsed = Date.now() - startMs;
+                const varsFile = path.join(dir, 'variables.jsonl');
+                try {
+                    const size = fs.statSync(varsFile).size;
+                    console.log(`[trickle/lambda] Flushed in ${elapsed}ms, observations: ${varsFile} (${size}b)`);
+                }
+                catch { }
+            }
+            return result;
+        }
+        catch (err) {
+            // Flush even on errors so partial observations are captured
+            if (process.env.TRICKLE_BACKEND_URL) {
+                await (0, transport_1.flush)().catch(() => { });
+            }
+            throw err;
+        }
+    };
+}
+/**
+ * Print the contents of the local trickle observations directory to stdout
+ * as newline-delimited JSON. Useful for inspecting Lambda observations in
+ * CloudWatch Logs when TRICKLE_BACKEND_URL is not set.
+ *
+ * Call at the end of your handler to stream observations to CloudWatch:
+ *
+ *   export const handler = wrapLambda(async (event) => {
+ *     const result = await processOrder(event.orderId);
+ *     printObservations();  // → streamed to CloudWatch Logs
+ *     return result;
+ *   });
+ */
+function printObservations() {
+    const dir = process.env.TRICKLE_LOCAL_DIR || '/tmp/.trickle';
+    for (const file of ['variables.jsonl', 'observations.jsonl']) {
+        const filePath = path.join(dir, file);
+        try {
+            const content = fs.readFileSync(filePath, 'utf-8').trim();
+            if (content) {
+                for (const line of content.split('\n')) {
+                    if (line.trim()) {
+                        // Prefix so trickle CLI can grep from CloudWatch Logs
+                        console.log(`[trickle] ${line}`);
+                    }
+                }
+            }
+        }
+        catch { /* file may not exist yet */ }
+    }
+}

package/dist/metro-transformer.d.ts

@@ -0,0 +1,28 @@
+/**
+ * trickle/metro-transformer — Metro bundler transform for React Native observability.
+ *
+ * Drop-in Metro transformer that instruments React Native components with
+ * trickle's render tracking, useState change tracking, and hook observability —
+ * the same tracking trickle's Vite plugin provides for web React apps.
+ *
+ * Setup in metro.config.js:
+ *
+ *   const { getDefaultConfig } = require('expo/metro-config');
+ *   // or: const { getDefaultConfig } = require('@react-native/metro-config');
+ *
+ *   const config = getDefaultConfig(__dirname);
+ *   config.transformer.babelTransformerPath = require.resolve('trickle-observe/metro-transformer');
+ *   module.exports = config;
+ *
+ * Environment variables:
+ *   TRICKLE_BACKEND_URL   — URL of your trickle backend (default: http://localhost:4888)
+ *                           For real device: use your machine's LAN IP, e.g. http://192.168.1.5:4888
+ *   TRICKLE_DEBUG         — Set to "1" for debug logging
+ */
+interface MetroTransformArgs {
+    src: string;
+    filename: string;
+    options: Record<string, unknown>;
+}
+export declare function transform({ src, filename, options }: MetroTransformArgs): Promise<any>;
+export {};

package/dist/metro-transformer.js

@@ -0,0 +1,67 @@
+"use strict";
+/**
+ * trickle/metro-transformer — Metro bundler transform for React Native observability.
+ *
+ * Drop-in Metro transformer that instruments React Native components with
+ * trickle's render tracking, useState change tracking, and hook observability —
+ * the same tracking trickle's Vite plugin provides for web React apps.
+ *
+ * Setup in metro.config.js:
+ *
+ *   const { getDefaultConfig } = require('expo/metro-config');
+ *   // or: const { getDefaultConfig } = require('@react-native/metro-config');
+ *
+ *   const config = getDefaultConfig(__dirname);
+ *   config.transformer.babelTransformerPath = require.resolve('trickle-observe/metro-transformer');
+ *   module.exports = config;
+ *
+ * Environment variables:
+ *   TRICKLE_BACKEND_URL   — URL of your trickle backend (default: http://localhost:4888)
+ *                           For real device: use your machine's LAN IP, e.g. http://192.168.1.5:4888
+ *   TRICKLE_DEBUG         — Set to "1" for debug logging
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.transform = transform;
+const path_1 = __importDefault(require("path"));
+const vite_plugin_1 = require("./vite-plugin");
+// The upstream Babel transformer — try Expo first, fall back to bare RN
+function getUpstreamTransformer() {
+    const candidates = [
+        '@expo/metro-config/babel-transformer',
+        'metro-react-native-babel-transformer',
+    ];
+    for (const candidate of candidates) {
+        try {
+            // eslint-disable-next-line @typescript-eslint/no-require-imports
+            return require(candidate);
+        }
+        catch {
+            // not installed, try next
+        }
+    }
+    throw new Error('[trickle/metro-transformer] Could not find a Metro Babel transformer. ' +
+        'Install either @expo/metro-config or metro-react-native-babel-transformer.');
+}
+const backendUrl = process.env.TRICKLE_BACKEND_URL ?? 'http://localhost:4888';
+const debug = process.env.TRICKLE_DEBUG === '1';
+async function transform({ src, filename, options }) {
+    const upstreamTransformer = getUpstreamTransformer();
+    // Only instrument React Native component files
+    const ext = path_1.default.extname(filename).toLowerCase();
+    const isReactFile = ext === '.tsx' || ext === '.jsx';
+    const isJsFile = ext === '.ts' || ext === '.js';
+    if ((isReactFile || isJsFile) && !filename.includes('node_modules') && !filename.includes('trickle-observe')) {
+        const moduleName = path_1.default.basename(filename).replace(/\.[jt]sx?$/, '');
+        const transformed = (0, vite_plugin_1.transformEsmSource)(src, filename, moduleName, backendUrl, debug, false);
+        if (transformed !== src) {
+            if (debug) {
+                console.log(`[trickle/metro] Instrumented ${filename}`);
+            }
+            return upstreamTransformer.transform({ src: transformed, filename, options });
+        }
+    }
+    return upstreamTransformer.transform({ src, filename, options });
+}

package/dist/trace-var.js

@@ -70,7 +70,10 @@ const MAX_BUFFER_SIZE = 100;
  */
 function initVarTracer(opts = {}) {
     debugMode = opts.debug === true;
-    const dir = process.env.TRICKLE_LOCAL_DIR || path.join(process.cwd(), '.trickle');
+    // Auto-detect Lambda: use /tmp/.trickle (writable) instead of cwd (read-only in Lambda)
+    const isLambda = !!process.env.AWS_LAMBDA_FUNCTION_NAME;
+    const defaultDir = isLambda ? '/tmp/.trickle' : path.join(process.cwd(), '.trickle');
+    const dir = process.env.TRICKLE_LOCAL_DIR || defaultDir;
     try {
         fs.mkdirSync(dir, { recursive: true });
     }

package/dist/transport.js

@@ -66,7 +66,10 @@ function configure(opts) {
     // Check for local/file-based mode
     if (process.env.TRICKLE_LOCAL === '1') {
         localMode = true;
-        const dir = process.env.TRICKLE_LOCAL_DIR || pathMod.join(process.cwd(), '.trickle');
+        // Auto-detect Lambda: use /tmp/.trickle (writable) instead of cwd (read-only in Lambda)
+        const isLambda = !!process.env.AWS_LAMBDA_FUNCTION_NAME;
+        const defaultDir = isLambda ? '/tmp/.trickle' : pathMod.join(process.cwd(), '.trickle');
+        const dir = process.env.TRICKLE_LOCAL_DIR || defaultDir;
         try {
             fs.mkdirSync(dir, { recursive: true });
         }

package/dist/vite-plugin.d.ts

@@ -37,4 +37,5 @@ export declare function tricklePlugin(options?: TricklePluginOptions): {
         map: null;
     } | null;
 };
+export declare function transformEsmSource(source: string, filename: string, moduleName: string, backendUrl: string, debug: boolean, traceVars: boolean, originalSource?: string | null): string;
 export default tricklePlugin;

package/dist/vite-plugin.js

@@ -23,6 +23,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.tricklePlugin = tricklePlugin;
+exports.transformEsmSource = transformEsmSource;
 const path_1 = __importDefault(require("path"));
 const fs_1 = __importDefault(require("fs"));
 function tricklePlugin(options = {}) {
@@ -496,8 +497,8 @@ function escapeRegexStr(str) {
 function transformEsmSource(source, filename, moduleName, backendUrl, debug, traceVars, originalSource) {
     // Detect React files for component render tracking
     const isReactFile = /\.(tsx|jsx)$/.test(filename);
-    // Match top-level and nested function declarations (including async, export)
-    const funcRegex = /^[ \t]*(?:export\s+)?(?:async\s+)?function\s+([a-zA-Z_$][a-zA-Z0-9_$]*)\s*\(/gm;
+    // Match top-level and nested function declarations (including async, export, export default)
+    const funcRegex = /^[ \t]*(?:export\s+(?:default\s+)?)?(?:async\s+)?function\s+([a-zA-Z_$][a-zA-Z0-9_$]*)\s*\(/gm;
     const funcInsertions = [];
     // Body insertions: insert at start of function body (for React render tracking)
     // propsExpr: JS expression to evaluate as the props object at render time

package/dist-esm/vite-plugin.js

@@ -487,11 +487,11 @@ function findOriginalLineDestructured(origLines, varNames, transformedLine) {
 function escapeRegexStr(str) {
     return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 }
-function transformEsmSource(source, filename, moduleName, backendUrl, debug, traceVars, originalSource) {
+export function transformEsmSource(source, filename, moduleName, backendUrl, debug, traceVars, originalSource) {
     // Detect React files for component render tracking
     const isReactFile = /\.(tsx|jsx)$/.test(filename);
-    // Match top-level and nested function declarations (including async, export)
-    const funcRegex = /^[ \t]*(?:export\s+)?(?:async\s+)?function\s+([a-zA-Z_$][a-zA-Z0-9_$]*)\s*\(/gm;
+    // Match top-level and nested function declarations (including async, export, export default)
+    const funcRegex = /^[ \t]*(?:export\s+(?:default\s+)?)?(?:async\s+)?function\s+([a-zA-Z_$][a-zA-Z0-9_$]*)\s*\(/gm;
     const funcInsertions = [];
     // Body insertions: insert at start of function body (for React render tracking)
     // propsExpr: JS expression to evaluate as the props object at render time

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "trickle-observe",
-  "version": "0.2.60",
+  "version": "0.2.62",
   "description": "Runtime type observability for JavaScript applications",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -16,11 +16,13 @@
       "import": "./dist-esm/vite-plugin.js",
       "require": "./dist/vite-plugin.js"
     },
-    "./trace-var": "./dist/trace-var.js"
+    "./trace-var": "./dist/trace-var.js",
+    "./lambda": "./dist/lambda.js",
+    "./metro-transformer": "./dist/metro-transformer.js"
   },
   "scripts": {
     "build": "tsc && tsc -p tsconfig.esm.json",
-    "test": "npm run build && node --experimental-strip-types --test src/vite-plugin.test.ts",
+    "test": "npm run build && node --experimental-strip-types --test src/vite-plugin.test.ts src/lambda.test.ts src/metro-transformer.test.ts",
     "prepublishOnly": "npm run build"
   },
   "optionalDependencies": {

package/src/lambda.test.ts

@@ -0,0 +1,147 @@
+/**
+ * Unit tests for wrapLambda and printObservations.
+ *
+ * Run with: node --experimental-strip-types --test src/lambda.test.ts
+ */
+import { describe, it, before, after } from 'node:test';
+import assert from 'node:assert/strict';
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+
+// ── wrapLambda ────────────────────────────────────────────────────────────────
+
+describe('wrapLambda', () => {
+  const makeContext = () => ({
+    functionName: 'test-fn',
+    functionVersion: '$LATEST',
+    invokedFunctionArn: 'arn:aws:lambda:us-east-1:123:function:test-fn',
+    awsRequestId: 'req-1',
+  });
+
+  let tmpDir: string;
+
+  before(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'trickle-lambda-test-'));
+    process.env.TRICKLE_LOCAL_DIR = tmpDir;
+  });
+
+  after(() => {
+    delete process.env.TRICKLE_LOCAL_DIR;
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  it('returns the handler result unchanged', async () => {
+    // Import fresh to avoid module cache issues with env vars
+    const { wrapLambda } = await import('../dist/lambda.js');
+    const handler = async (_event: unknown, _ctx: unknown) => ({ statusCode: 200, body: 'ok' });
+    const wrapped = wrapLambda(handler);
+    const result = await wrapped({ orderId: '123' }, makeContext());
+    assert.deepEqual(result, { statusCode: 200, body: 'ok' });
+  });
+
+  it('passes event and context to the handler', async () => {
+    const { wrapLambda } = await import('../dist/lambda.js');
+    let receivedEvent: unknown;
+    let receivedCtx: unknown;
+    const handler = async (event: unknown, ctx: unknown) => {
+      receivedEvent = event;
+      receivedCtx = ctx;
+      return 'done';
+    };
+    const wrapped = wrapLambda(handler);
+    const ctx = makeContext();
+    await wrapped({ hello: 'world' }, ctx);
+    assert.deepEqual(receivedEvent, { hello: 'world' });
+    assert.equal((receivedCtx as typeof ctx).awsRequestId, 'req-1');
+  });
+
+  it('re-throws errors from the handler', async () => {
+    const { wrapLambda } = await import('../dist/lambda.js');
+    const handler = async () => { throw new Error('Lambda error'); };
+    const wrapped = wrapLambda(handler);
+    await assert.rejects(() => wrapped({}, makeContext()), /Lambda error/);
+  });
+
+  it('does not throw if TRICKLE_BACKEND_URL is not set', async () => {
+    delete process.env.TRICKLE_BACKEND_URL;
+    const { wrapLambda } = await import('../dist/lambda.js');
+    const handler = async () => 42;
+    const wrapped = wrapLambda(handler);
+    const result = await wrapped({}, makeContext());
+    assert.equal(result, 42);
+  });
+});
+
+// ── printObservations ─────────────────────────────────────────────────────────
+
+describe('printObservations', () => {
+  let tmpDir: string;
+  let originalDir: string | undefined;
+  let logged: string[];
+  let origLog: typeof console.log;
+
+  before(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'trickle-print-test-'));
+    originalDir = process.env.TRICKLE_LOCAL_DIR;
+    process.env.TRICKLE_LOCAL_DIR = tmpDir;
+    // Capture console.log output
+    origLog = console.log;
+    logged = [];
+    console.log = (...args: unknown[]) => { logged.push(args.join(' ')); };
+  });
+
+  after(() => {
+    console.log = origLog;
+    if (originalDir !== undefined) {
+      process.env.TRICKLE_LOCAL_DIR = originalDir;
+    } else {
+      delete process.env.TRICKLE_LOCAL_DIR;
+    }
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  it('prints [trickle] prefixed JSON lines from variables.jsonl', async () => {
+    const record = JSON.stringify({ kind: 'var', name: 'x', value: 1 });
+    fs.writeFileSync(path.join(tmpDir, 'variables.jsonl'), record + '\n');
+
+    const { printObservations } = await import('../dist/lambda.js');
+    logged = [];
+    printObservations();
+
+    assert.ok(logged.some(l => l.startsWith('[trickle]')), 'should prefix with [trickle]');
+    assert.ok(logged.some(l => l.includes('"kind"')), 'should include JSON content');
+  });
+
+  it('does not crash when no files exist', async () => {
+    const emptyDir = fs.mkdtempSync(path.join(os.tmpdir(), 'trickle-empty-'));
+    const prevDir = process.env.TRICKLE_LOCAL_DIR;
+    process.env.TRICKLE_LOCAL_DIR = emptyDir;
+    try {
+      const { printObservations } = await import('../dist/lambda.js');
+      assert.doesNotThrow(() => printObservations());
+    } finally {
+      process.env.TRICKLE_LOCAL_DIR = prevDir;
+      fs.rmSync(emptyDir, { recursive: true, force: true });
+    }
+  });
+
+  it('prints observations from both variables.jsonl and observations.jsonl', async () => {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'trickle-both-'));
+    const prevDir = process.env.TRICKLE_LOCAL_DIR;
+    process.env.TRICKLE_LOCAL_DIR = dir;
+    try {
+      fs.writeFileSync(path.join(dir, 'variables.jsonl'), JSON.stringify({ kind: 'var' }) + '\n');
+      fs.writeFileSync(path.join(dir, 'observations.jsonl'), JSON.stringify({ kind: 'obs' }) + '\n');
+
+      const { printObservations } = await import('../dist/lambda.js');
+      logged = [];
+      printObservations();
+      const count = logged.filter(l => l.startsWith('[trickle]')).length;
+      assert.ok(count >= 2, `should print at least 2 [trickle] lines, got ${count}`);
+    } finally {
+      process.env.TRICKLE_LOCAL_DIR = prevDir;
+      fs.rmSync(dir, { recursive: true, force: true });
+    }
+  });
+});

package/src/lambda.ts

@@ -0,0 +1,160 @@
+/**
+ * trickle/lambda — Zero-config observability for AWS Lambda functions.
+ *
+ * Wraps a Lambda handler to:
+ * 1. Auto-instrument all functions with type observation
+ * 2. Write observations to /tmp/.trickle/ (Lambda's writable filesystem)
+ *    OR send to TRICKLE_BACKEND_URL if set
+ * 3. Flush all pending observations synchronously before Lambda freezes
+ *
+ * Usage:
+ *
+ *   import { wrapLambda } from 'trickle-observe/lambda';
+ *
+ *   export const handler = wrapLambda(async (event, context) => {
+ *     const result = await processOrder(event.orderId);
+ *     return { statusCode: 200, body: JSON.stringify(result) };
+ *   });
+ *
+ * OR zero-code via NODE_OPTIONS:
+ *
+ *   NODE_OPTIONS="--require trickle-observe/auto-env" TRICKLE_AUTO=1
+ *
+ * Environment variables:
+ *   TRICKLE_BACKEND_URL    — Send observations to HTTP backend (optional)
+ *   TRICKLE_LOCAL_DIR      — Override local dir (default: /tmp/.trickle)
+ *   TRICKLE_DEBUG          — Set to "1" for debug logging
+ *   TRICKLE_OBSERVE_INCLUDE — Comma-separated substrings to observe
+ *   TRICKLE_OBSERVE_EXCLUDE — Comma-separated substrings to skip
+ */
+
+import * as path from 'path';
+import * as fs from 'fs';
+import { configure, flush } from './transport';
+import { initVarTracer } from './trace-var';
+// Install Module._compile and Module._load hooks for auto-instrumentation
+import './observe-register';
+
+export type LambdaEvent = Record<string, unknown>;
+export type LambdaContext = {
+  functionName: string;
+  functionVersion: string;
+  invokedFunctionArn: string;
+  awsRequestId: string;
+  remainingTimeInMillis?: () => number;
+  [key: string]: unknown;
+};
+export type LambdaHandler<E = LambdaEvent, R = unknown> = (
+  event: E,
+  context: LambdaContext,
+) => Promise<R>;
+
+let initialized = false;
+
+function initOnce() {
+  if (initialized) return;
+  initialized = true;
+
+  const debug = process.env.TRICKLE_DEBUG === '1';
+  const dir = process.env.TRICKLE_LOCAL_DIR || '/tmp/.trickle';
+
+  // Ensure /tmp/.trickle exists (writable in Lambda, unlike /var/task)
+  try { fs.mkdirSync(dir, { recursive: true }); } catch {}
+
+  if (process.env.TRICKLE_BACKEND_URL) {
+    // HTTP mode: send to developer's backend (e.g. via ngrok)
+    configure({
+      backendUrl: process.env.TRICKLE_BACKEND_URL,
+      batchIntervalMs: 100,    // aggressive batching for Lambda
+      enabled: true,
+      debug,
+      environment: 'node',
+    });
+    if (debug) console.log(`[trickle/lambda] HTTP mode → ${process.env.TRICKLE_BACKEND_URL}`);
+  } else {
+    // Local file mode: write to /tmp/.trickle/observations.jsonl
+    process.env.TRICKLE_LOCAL = '1';
+    process.env.TRICKLE_LOCAL_DIR = dir;
+    configure({ backendUrl: 'http://localhost:4888', batchIntervalMs: 2000, enabled: true, debug, environment: 'node' });
+    if (debug) console.log(`[trickle/lambda] Local mode → ${dir}/observations.jsonl`);
+  }
+
+  // Initialize variable tracer (writes to variables.jsonl)
+  initVarTracer({ debug });
+}
+
+/**
+ * Wrap a Lambda handler with trickle observability.
+ *
+ * Instruments all called functions automatically, writes type observations
+ * to /tmp/.trickle/, and flushes before Lambda freezes the process.
+ */
+export function wrapLambda<E = LambdaEvent, R = unknown>(
+  handler: LambdaHandler<E, R>,
+): LambdaHandler<E, R> {
+  return async (event: E, context: LambdaContext): Promise<R> => {
+    initOnce();
+
+    const debug = process.env.TRICKLE_DEBUG === '1';
+    const startMs = Date.now();
+
+    try {
+      const result = await handler(event, context);
+
+      // Flush pending HTTP observations before Lambda freezes the process.
+      // File-mode writes are already synchronous, so no flush needed there.
+      if (process.env.TRICKLE_BACKEND_URL) {
+        await flush();
+      }
+
+      if (debug) {
+        const dir = process.env.TRICKLE_LOCAL_DIR || '/tmp/.trickle';
+        const elapsed = Date.now() - startMs;
+        const varsFile = path.join(dir, 'variables.jsonl');
+        try {
+          const size = fs.statSync(varsFile).size;
+          console.log(`[trickle/lambda] Flushed in ${elapsed}ms, observations: ${varsFile} (${size}b)`);
+        } catch {}
+      }
+
+      return result;
+    } catch (err) {
+      // Flush even on errors so partial observations are captured
+      if (process.env.TRICKLE_BACKEND_URL) {
+        await flush().catch(() => {});
+      }
+      throw err;
+    }
+  };
+}
+
+/**
+ * Print the contents of the local trickle observations directory to stdout
+ * as newline-delimited JSON. Useful for inspecting Lambda observations in
+ * CloudWatch Logs when TRICKLE_BACKEND_URL is not set.
+ *
+ * Call at the end of your handler to stream observations to CloudWatch:
+ *
+ *   export const handler = wrapLambda(async (event) => {
+ *     const result = await processOrder(event.orderId);
+ *     printObservations();  // → streamed to CloudWatch Logs
+ *     return result;
+ *   });
+ */
+export function printObservations(): void {
+  const dir = process.env.TRICKLE_LOCAL_DIR || '/tmp/.trickle';
+  for (const file of ['variables.jsonl', 'observations.jsonl']) {
+    const filePath = path.join(dir, file);
+    try {
+      const content = fs.readFileSync(filePath, 'utf-8').trim();
+      if (content) {
+        for (const line of content.split('\n')) {
+          if (line.trim()) {
+            // Prefix so trickle CLI can grep from CloudWatch Logs
+            console.log(`[trickle] ${line}`);
+          }
+        }
+      }
+    } catch { /* file may not exist yet */ }
+  }
+}

package/src/metro-transformer.test.ts

@@ -0,0 +1,148 @@
+/**
+ * Unit tests for the Metro transformer (React Native observability).
+ *
+ * Tests the transformation logic independently — without needing a real Metro
+ * bundler or Babel pipeline. We test that transformEsmSource is applied correctly
+ * to React Native component source files.
+ *
+ * Run with: node --experimental-strip-types --test src/metro-transformer.test.ts
+ */
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { transformEsmSource } from '../dist/vite-plugin.js';
+
+const BACKEND_URL = 'http://localhost:4888';
+
+// Helper: transform as if coming from a .tsx React Native file
+function transformRNTsx(code: string, filename = '/app/components/MyComponent.tsx'): string {
+  return transformEsmSource(code, filename, 'MyComponent', BACKEND_URL, false, false);
+}
+
+// Helper: transform as if coming from a .ts utility file
+function transformRNTs(code: string, filename = '/app/utils/helper.ts'): string {
+  return transformEsmSource(code, filename, 'helper', BACKEND_URL, false, false);
+}
+
+// ── Metro transformer: React component detection ──────────────────────────────
+
+describe('Metro transformer: React component detection', () => {
+  it('instruments uppercase components in .tsx files', () => {
+    const code = `function OrderCard({ order }) { return null; }`;
+    const out = transformRNTsx(code);
+    assert.notEqual(out, code, 'should transform');
+    assert.ok(out.includes('__trickle_rc'), 'should inject render tracker');
+  });
+
+  it('does not inject render tracker for .ts utility files', () => {
+    const code = `function formatPrice(amount) { return '$' + amount; }`;
+    const out = transformRNTs(code);
+    assert.ok(!out.includes('__trickle_rc'), 'should not inject render tracker in .ts files');
+  });
+
+  it('instruments export default function components (common React Native screen pattern)', () => {
+    const code = `export default function HomeScreen() { return null; }`;
+    const out = transformRNTsx(code);
+    assert.ok(out.includes('__trickle_rc'), 'should inject render tracker for export default function');
+  });
+
+  it('does not instrument lowercase utility functions as components', () => {
+    const code = `function formatOrder(order) { return order.id; }`;
+    const out = transformRNTsx(code);
+    if (out !== code) {
+      assert.ok(!out.includes('__trickle_rc'), 'lowercase function should not be tracked as component');
+    }
+  });
+});
+
+// ── Metro transformer: useState tracking ─────────────────────────────────────
+
+describe('Metro transformer: useState tracking in React Native', () => {
+  it('tracks useState in a React Native functional component', () => {
+    const code = [
+      `import React, { useState } from 'react';`,
+      `function Counter() {`,
+      `  const [count, setCount] = useState(0);`,
+      `  return null;`,
+      `}`,
+    ].join('\n');
+    const out = transformRNTsx(code);
+    assert.ok(out.includes('__trickle_ss'), 'should inject state setter wrapper');
+    assert.ok(out.includes('__trickle_s_setCount'), 'should rename original setter');
+    assert.ok(out.includes('"count"'), 'should include state variable name');
+  });
+
+  it('tracks multiple useState calls in a React Native screen', () => {
+    const code = [
+      `function CheckoutScreen() {`,
+      `  const [items, setItems] = useState([]);`,
+      `  const [total, setTotal] = useState(0);`,
+      `  const [loading, setLoading] = useState(false);`,
+      `  return null;`,
+      `}`,
+    ].join('\n');
+    const out = transformRNTsx(code);
+    const count = (out.match(/const \w+=__trickle_ss/g) || []).length;
+    assert.equal(count, 3, 'should wrap all 3 useState setters');
+  });
+
+  it('handles TypeScript typed useState in React Native', () => {
+    const code = [
+      `function ProfileScreen() {`,
+      `  const [user, setUser] = useState<User | null>(null);`,
+      `  return null;`,
+      `}`,
+    ].join('\n');
+    const out = transformRNTsx(code);
+    assert.ok(out.includes('__trickle_ss'), 'should track typed useState');
+    assert.ok(out.includes('"user"'), 'should include state name');
+  });
+});
+
+// ── Metro transformer: hook observability ────────────────────────────────────
+
+describe('Metro transformer: hook observability in React Native', () => {
+  it('wraps useEffect in a React Native component', () => {
+    const code = [
+      `function DataScreen() {`,
+      `  useEffect(() => {`,
+      `    fetchData();`,
+      `  }, []);`,
+      `  return null;`,
+      `}`,
+    ].join('\n');
+    const out = transformRNTsx(code);
+    assert.ok(out.includes('__trickle_hw'), 'should inject hook wrapper for useEffect');
+    assert.ok(out.includes('"useEffect"'), 'should record hook name');
+  });
+
+  it('wraps useCallback in a React Native component', () => {
+    const code = [
+      `function ListScreen() {`,
+      `  const handlePress = useCallback(() => {`,
+      `    navigate('Detail');`,
+      `  }, []);`,
+      `  return null;`,
+      `}`,
+    ].join('\n');
+    const out = transformRNTsx(code);
+    assert.ok(out.includes('__trickle_hw'), 'should inject hook wrapper for useCallback');
+    assert.ok(out.includes('"useCallback"'), 'should record hook name');
+  });
+});
+
+// ── Metro transformer: source unchanged for non-RN files ─────────────────────
+
+describe('Metro transformer: passthrough for non-component files', () => {
+  it('does not modify a plain TypeScript utility file', () => {
+    const code = `export function add(a: number, b: number): number { return a + b; }`;
+    const out = transformRNTs(code);
+    // .ts files should not get __trickle_rc (no React components)
+    assert.ok(!out.includes('__trickle_rc'), 'should not inject React tracking in .ts files');
+  });
+
+  it('does not inject useState tracking in .ts files', () => {
+    const code = `function helper() {\n  const [x, setX] = useState(0);\n  return x;\n}`;
+    const out = transformRNTs(code);
+    assert.ok(!out.includes('__trickle_ss'), 'should not track useState in .ts files');
+  });
+});

package/src/metro-transformer.ts

@@ -0,0 +1,75 @@
+/**
+ * trickle/metro-transformer — Metro bundler transform for React Native observability.
+ *
+ * Drop-in Metro transformer that instruments React Native components with
+ * trickle's render tracking, useState change tracking, and hook observability —
+ * the same tracking trickle's Vite plugin provides for web React apps.
+ *
+ * Setup in metro.config.js:
+ *
+ *   const { getDefaultConfig } = require('expo/metro-config');
+ *   // or: const { getDefaultConfig } = require('@react-native/metro-config');
+ *
+ *   const config = getDefaultConfig(__dirname);
+ *   config.transformer.babelTransformerPath = require.resolve('trickle-observe/metro-transformer');
+ *   module.exports = config;
+ *
+ * Environment variables:
+ *   TRICKLE_BACKEND_URL   — URL of your trickle backend (default: http://localhost:4888)
+ *                           For real device: use your machine's LAN IP, e.g. http://192.168.1.5:4888
+ *   TRICKLE_DEBUG         — Set to "1" for debug logging
+ */
+
+import path from 'path';
+import { transformEsmSource } from './vite-plugin';
+
+// The upstream Babel transformer — try Expo first, fall back to bare RN
+function getUpstreamTransformer() {
+  const candidates = [
+    '@expo/metro-config/babel-transformer',
+    'metro-react-native-babel-transformer',
+  ];
+  for (const candidate of candidates) {
+    try {
+      // eslint-disable-next-line @typescript-eslint/no-require-imports
+      return require(candidate);
+    } catch {
+      // not installed, try next
+    }
+  }
+  throw new Error(
+    '[trickle/metro-transformer] Could not find a Metro Babel transformer. ' +
+    'Install either @expo/metro-config or metro-react-native-babel-transformer.',
+  );
+}
+
+interface MetroTransformArgs {
+  src: string;
+  filename: string;
+  options: Record<string, unknown>;
+}
+
+const backendUrl = process.env.TRICKLE_BACKEND_URL ?? 'http://localhost:4888';
+const debug = process.env.TRICKLE_DEBUG === '1';
+
+export async function transform({ src, filename, options }: MetroTransformArgs) {
+  const upstreamTransformer = getUpstreamTransformer();
+
+  // Only instrument React Native component files
+  const ext = path.extname(filename).toLowerCase();
+  const isReactFile = ext === '.tsx' || ext === '.jsx';
+  const isJsFile = ext === '.ts' || ext === '.js';
+
+  if ((isReactFile || isJsFile) && !filename.includes('node_modules') && !filename.includes('trickle-observe')) {
+    const moduleName = path.basename(filename).replace(/\.[jt]sx?$/, '');
+    const transformed = transformEsmSource(src, filename, moduleName, backendUrl, debug, false);
+    if (transformed !== src) {
+      if (debug) {
+        console.log(`[trickle/metro] Instrumented ${filename}`);
+      }
+      return upstreamTransformer.transform({ src: transformed, filename, options });
+    }
+  }
+
+  return upstreamTransformer.transform({ src, filename, options });
+}

package/src/trace-var.ts

@@ -50,7 +50,10 @@ export interface VariableObservation {
  */
 export function initVarTracer(opts: { debug?: boolean } = {}): void {
   debugMode = opts.debug === true;
-  const dir = process.env.TRICKLE_LOCAL_DIR || path.join(process.cwd(), '.trickle');
+  // Auto-detect Lambda: use /tmp/.trickle (writable) instead of cwd (read-only in Lambda)
+  const isLambda = !!process.env.AWS_LAMBDA_FUNCTION_NAME;
+  const defaultDir = isLambda ? '/tmp/.trickle' : path.join(process.cwd(), '.trickle');
+  const dir = process.env.TRICKLE_LOCAL_DIR || defaultDir;
   try { fs.mkdirSync(dir, { recursive: true }); } catch {}
   varsFilePath = path.join(dir, 'variables.jsonl');
 

package/src/transport.ts

@@ -32,7 +32,10 @@ export function configure(opts: GlobalOpts): void {
   // Check for local/file-based mode
   if (process.env.TRICKLE_LOCAL === '1') {
     localMode = true;
-    const dir = process.env.TRICKLE_LOCAL_DIR || pathMod.join(process.cwd(), '.trickle');
+    // Auto-detect Lambda: use /tmp/.trickle (writable) instead of cwd (read-only in Lambda)
+    const isLambda = !!process.env.AWS_LAMBDA_FUNCTION_NAME;
+    const defaultDir = isLambda ? '/tmp/.trickle' : pathMod.join(process.cwd(), '.trickle');
+    const dir = process.env.TRICKLE_LOCAL_DIR || defaultDir;
     try { fs.mkdirSync(dir, { recursive: true }); } catch {}
     localFilePath = pathMod.join(dir, 'observations.jsonl');
     if (debug) {

package/src/vite-plugin.test.ts

@@ -40,6 +40,13 @@ describe('React file detection', () => {
     }
   });
 
+  it('tracks export default function components', () => {
+    const code = `export default function HomeScreen() { return null; }`;
+    const out = transformTsx(code);
+    assert.ok(out, 'should transform');
+    assert.ok(out!.includes('__trickle_rc'), 'export default function should be tracked as component');
+  });
+
   it('does not track lowercase functions as components', () => {
     const code = `function helper(x) { return x + 1; }`;
     const out = transformTsx(code);

package/src/vite-plugin.ts

@@ -481,7 +481,7 @@ function escapeRegexStr(str: string): string {
   return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 }
 
-function transformEsmSource(
+export function transformEsmSource(
   source: string,
   filename: string,
   moduleName: string,
@@ -493,8 +493,8 @@ function transformEsmSource(
   // Detect React files for component render tracking
   const isReactFile = /\.(tsx|jsx)$/.test(filename);
 
-  // Match top-level and nested function declarations (including async, export)
-  const funcRegex = /^[ \t]*(?:export\s+)?(?:async\s+)?function\s+([a-zA-Z_$][a-zA-Z0-9_$]*)\s*\(/gm;
+  // Match top-level and nested function declarations (including async, export, export default)
+  const funcRegex = /^[ \t]*(?:export\s+(?:default\s+)?)?(?:async\s+)?function\s+([a-zA-Z_$][a-zA-Z0-9_$]*)\s*\(/gm;
   const funcInsertions: Array<{ position: number; name: string; paramNames: string[] }> = [];
   // Body insertions: insert at start of function body (for React render tracking)
   // propsExpr: JS expression to evaluate as the props object at render time