@lanternajs/cli 0.0.1

package/dist/args.d.ts

@@ -0,0 +1,22 @@
+export interface MeasureArgs {
+    package: string;
+    duration: number;
+    platform?: "ios" | "android";
+    device?: string;
+    output?: string;
+    baseline?: string;
+}
+export interface TestArgs extends MeasureArgs {
+    maestro: string;
+}
+export interface MonitorArgs {
+    port: number;
+}
+export interface ParsedCommand {
+    command: "measure" | "test" | "monitor";
+    args: MeasureArgs | TestArgs | MonitorArgs;
+}
+declare const HELP_TEXT: string;
+export declare function parseArgs(argv: string[]): ParsedCommand | null;
+export { HELP_TEXT };
+//# sourceMappingURL=args.d.ts.map

package/dist/args.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"args.d.ts","sourceRoot":"","sources":["../src/args.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,WAAW;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,KAAK,GAAG,SAAS,CAAC;IAC7B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,QAAS,SAAQ,WAAW;IAC5C,OAAO,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,WAAW;IAC3B,IAAI,EAAE,MAAM,CAAC;CACb;AAED,MAAM,WAAW,aAAa;IAC7B,OAAO,EAAE,SAAS,GAAG,MAAM,GAAG,SAAS,CAAC;IACxC,IAAI,EAAE,WAAW,GAAG,QAAQ,GAAG,WAAW,CAAC;CAC3C;AAED,QAAA,MAAM,SAAS,QAuCP,CAAC;AA2IT,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,aAAa,GAAG,IAAI,CAyB9D;AAED,OAAO,EAAE,SAAS,EAAE,CAAC"}

package/dist/args.js

@@ -0,0 +1,203 @@
+const HELP_TEXT = `
+lanterna — Performance profiler for React Native apps
+
+Usage:
+  lanterna measure <package> [options]
+  lanterna test --maestro <flow.yaml> [options]
+  lanterna monitor [options]
+
+Commands:
+  measure    Collect performance metrics for a running app
+  test       Run a Maestro E2E flow and collect performance metrics
+  monitor    Start live monitoring dashboard (WebSocket server)
+
+Options (measure):
+  --duration <seconds>    Measurement duration (default: 10)
+  --platform <ios|android> Force platform (auto-detect if omitted)
+  --device <id>           Target device ID (auto-select if omitted)
+  --output <path>         Export JSON report to file
+  --baseline <path>       Compare against a previous JSON report
+  --help                  Show this help message
+
+Options (test):
+  --maestro <flow.yaml>   Path to Maestro flow YAML (required)
+  --duration <seconds>    Measurement duration (default: 10)
+  --platform <ios|android> Force platform (auto-detect if omitted)
+  --device <id>           Target device ID (auto-select if omitted)
+  --output <path>         Export JSON report to file
+
+Options (monitor):
+  --port <number>         WebSocket server port (default: 8347)
+
+Examples:
+  lanterna measure com.example.app
+  lanterna measure com.example.app --duration 15
+  lanterna measure com.example.app --platform ios --output report.json
+  lanterna test --maestro login-flow.yaml
+  lanterna test --maestro login-flow.yaml --duration 30 --output report.json
+  lanterna monitor
+  lanterna monitor --port 9000
+`.trim();
+function parseDuration(value) {
+    const stripped = value.replace(/s$/, "");
+    const num = Number(stripped);
+    if (Number.isNaN(num) || num <= 0) {
+        throw new Error(`Invalid duration: "${value}". Must be a positive number (e.g., 10 or 10s).`);
+    }
+    return num;
+}
+function parseMeasureCommand(args) {
+    const result = {
+        package: "",
+        duration: 10,
+    };
+    let i = 0;
+    while (i < args.length) {
+        const arg = args[i];
+        if (arg === "--duration" || arg === "-d") {
+            i++;
+            if (i >= args.length)
+                throw new Error("--duration requires a value");
+            result.duration = parseDuration(args[i]);
+        }
+        else if (arg === "--platform" || arg === "-p") {
+            i++;
+            if (i >= args.length)
+                throw new Error("--platform requires a value");
+            const val = args[i];
+            if (val !== "ios" && val !== "android") {
+                throw new Error(`Invalid platform: "${val}". Must be "ios" or "android".`);
+            }
+            result.platform = val;
+        }
+        else if (arg === "--device") {
+            i++;
+            if (i >= args.length)
+                throw new Error("--device requires a value");
+            result.device = args[i];
+        }
+        else if (arg === "--output" || arg === "-o") {
+            i++;
+            if (i >= args.length)
+                throw new Error("--output requires a value");
+            result.output = args[i];
+        }
+        else if (arg === "--baseline" || arg === "-b") {
+            i++;
+            if (i >= args.length)
+                throw new Error("--baseline requires a value");
+            result.baseline = args[i];
+        }
+        else if (!arg.startsWith("-") && !result.package) {
+            result.package = arg;
+        }
+        else {
+            throw new Error(`Unknown option: "${arg}"`);
+        }
+        i++;
+    }
+    if (!result.package) {
+        throw new Error("Package name is required. Usage: lanterna measure <package>\n  e.g., lanterna measure com.example.app");
+    }
+    return result;
+}
+function parseTestCommand(args) {
+    const result = {
+        package: "",
+        duration: 10,
+        maestro: "",
+    };
+    let i = 0;
+    while (i < args.length) {
+        const arg = args[i];
+        if (arg === "--maestro" || arg === "-m") {
+            i++;
+            if (i >= args.length)
+                throw new Error("--maestro requires a value");
+            result.maestro = args[i];
+        }
+        else if (arg === "--duration" || arg === "-d") {
+            i++;
+            if (i >= args.length)
+                throw new Error("--duration requires a value");
+            result.duration = parseDuration(args[i]);
+        }
+        else if (arg === "--platform" || arg === "-p") {
+            i++;
+            if (i >= args.length)
+                throw new Error("--platform requires a value");
+            const val = args[i];
+            if (val !== "ios" && val !== "android") {
+                throw new Error(`Invalid platform: "${val}". Must be "ios" or "android".`);
+            }
+            result.platform = val;
+        }
+        else if (arg === "--device") {
+            i++;
+            if (i >= args.length)
+                throw new Error("--device requires a value");
+            result.device = args[i];
+        }
+        else if (arg === "--output" || arg === "-o") {
+            i++;
+            if (i >= args.length)
+                throw new Error("--output requires a value");
+            result.output = args[i];
+        }
+        else if (!arg.startsWith("-") && !result.package) {
+            result.package = arg;
+        }
+        else {
+            throw new Error(`Unknown option: "${arg}"`);
+        }
+        i++;
+    }
+    if (!result.maestro) {
+        throw new Error("--maestro flag is required for test command.\n  Usage: lanterna test --maestro <flow.yaml>");
+    }
+    // package can be auto-populated from the flow's appId, so it's not required here
+    return result;
+}
+function parseMonitorCommand(args) {
+    const result = { port: 8347 };
+    let i = 0;
+    while (i < args.length) {
+        const arg = args[i];
+        if (arg === "--port") {
+            i++;
+            if (i >= args.length)
+                throw new Error("--port requires a value");
+            const port = Number(args[i]);
+            if (Number.isNaN(port) || port <= 0 || port > 65535) {
+                throw new Error(`Invalid port: "${args[i]}". Must be 1-65535.`);
+            }
+            result.port = port;
+        }
+        else {
+            throw new Error(`Unknown option: "${arg}"`);
+        }
+        i++;
+    }
+    return result;
+}
+export function parseArgs(argv) {
+    const args = argv.slice(0);
+    if (args.length === 0 || args.includes("--help") || args.includes("-h")) {
+        console.log(HELP_TEXT);
+        return null;
+    }
+    const command = args.shift();
+    if (command === "measure") {
+        return { command: "measure", args: parseMeasureCommand(args) };
+    }
+    if (command === "test") {
+        return { command: "test", args: parseTestCommand(args) };
+    }
+    if (command === "monitor") {
+        return { command: "monitor", args: parseMonitorCommand(args) };
+    }
+    console.log(`Unknown command: "${command}"\n`);
+    console.log(HELP_TEXT);
+    return null;
+}
+export { HELP_TEXT };

package/dist/commands/measure.d.ts

@@ -0,0 +1,4 @@
+import { type CommandRunner } from "@lanternajs/core";
+import type { MeasureArgs } from "../args";
+export declare function runMeasure(args: MeasureArgs, runner?: CommandRunner): Promise<number>;
+//# sourceMappingURL=measure.d.ts.map

package/dist/commands/measure.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"measure.d.ts","sourceRoot":"","sources":["../../src/commands/measure.ts"],"names":[],"mappings":"AACA,OAAO,EACN,KAAK,aAAa,EAOlB,MAAM,kBAAkB,CAAC;AAG1B,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AA4B3C,wBAAsB,UAAU,CAC/B,IAAI,EAAE,WAAW,EACjB,MAAM,GAAE,aAA6B,GACnC,OAAO,CAAC,MAAM,CAAC,CAsGjB"}

package/dist/commands/measure.js

@@ -0,0 +1,99 @@
+import { collectAndroidMetrics } from "@lanternajs/android";
+import { calculateScore, compareScores, defaultRunner, detectDevices, ScoreCategory, } from "@lanternajs/core";
+import { collectIosMetrics } from "@lanternajs/ios";
+import { exportJson, renderComparison, renderReport } from "@lanternajs/report";
+import { Spinner } from "../spinner";
+function selectDevice(devices, args) {
+    if (args.device) {
+        const match = devices.find((d) => d.id === args.device);
+        if (!match) {
+            throw new Error(`Device "${args.device}" not found. Available devices:\n${devices.map((d) => `  ${d.id} (${d.name}, ${d.platform})`).join("\n")}`);
+        }
+        return match;
+    }
+    if (args.platform) {
+        const platformDevices = devices.filter((d) => d.platform === args.platform);
+        if (platformDevices.length === 0) {
+            throw new Error(`No ${args.platform} devices found. Run "lanterna devices" to see available devices.`);
+        }
+        return platformDevices[0];
+    }
+    // Auto-select: first available device (physical devices sorted first by detectDevices)
+    return devices[0];
+}
+export async function runMeasure(args, runner = defaultRunner) {
+    const spinner = new Spinner();
+    try {
+        // 1. Detect devices
+        spinner.start("Detecting devices...");
+        const devices = await detectDevices(runner);
+        if (devices.length === 0) {
+            spinner.fail("No devices found");
+            console.error("\nMake sure you have a device connected or simulator/emulator running.\n" +
+                "  iOS: Open Simulator or connect a physical device\n" +
+                "  Android: Start an emulator or connect via ADB");
+            return 1;
+        }
+        const device = selectDevice(devices, args);
+        spinner.stop(`Device: ${device.name} (${device.platform}, ${device.type})`);
+        // 2. Collect metrics
+        spinner.start(`Collecting metrics for ${args.duration}s on ${device.name}...`);
+        const session = device.platform === "android"
+            ? await collectAndroidMetrics(runner, device, args.package, args.duration)
+            : await collectIosMetrics(runner, device, args.package, args.duration);
+        spinner.stop(`Collection complete (${session.samples.length} samples)`);
+        // 3. Score
+        const score = calculateScore(session);
+        // 4. Report
+        const report = renderReport(session, score);
+        console.log(report);
+        // 5. Baseline comparison if requested
+        if (args.baseline) {
+            const baselineFile = Bun.file(args.baseline);
+            if (!(await baselineFile.exists())) {
+                console.error(`\nBaseline file not found: ${args.baseline}`);
+                return 1;
+            }
+            const baselineData = JSON.parse(await baselineFile.text());
+            const baselineScore = baselineData.score;
+            const comparison = compareScores({
+                overall: baselineScore.overall,
+                category: baselineScore.category,
+                perMetric: baselineScore.metrics.map((m) => ({
+                    type: m.type,
+                    value: m.value,
+                    score: m.score,
+                    category: m.category,
+                    weight: 0,
+                })),
+            }, score);
+            console.log(renderComparison({
+                overall: baselineScore.overall,
+                category: baselineScore.category,
+                perMetric: baselineScore.metrics.map((m) => ({
+                    type: m.type,
+                    value: m.value,
+                    score: m.score,
+                    category: m.category,
+                    weight: 0,
+                })),
+            }, score, comparison));
+            if (comparison.hasRegression) {
+                console.error(`\n⚠ ${comparison.regressionCount} regression(s) detected`);
+                return 1;
+            }
+        }
+        // 6. Export JSON if requested
+        if (args.output) {
+            await exportJson(session, score, args.output);
+            console.log(`\nJSON report saved to ${args.output}`);
+        }
+        // 7. Exit code
+        return score.category === ScoreCategory.POOR ? 1 : 0;
+    }
+    catch (error) {
+        spinner.fail("Measurement failed");
+        console.error(`\n${error instanceof Error ? error.message : String(error)}`);
+        return 1;
+    }
+}

package/dist/commands/monitor.d.ts

@@ -0,0 +1,9 @@
+import type { MonitorArgs } from "../args";
+/**
+ * Run the `lanterna monitor` command.
+ *
+ * Starts a WebSocket server and displays a live terminal dashboard
+ * showing connected apps and their real-time metrics.
+ */
+export declare function runMonitor(args: MonitorArgs): Promise<number>;
+//# sourceMappingURL=monitor.d.ts.map

package/dist/commands/monitor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"monitor.d.ts","sourceRoot":"","sources":["../../src/commands/monitor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAI3C;;;;;GAKG;AACH,wBAAsB,UAAU,CAAC,IAAI,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC,CAsCnE"}

package/dist/commands/monitor.js

@@ -0,0 +1,47 @@
+import { renderDashboard } from "../live-dashboard";
+import { LanternaServer } from "../ws-server";
+/**
+ * Run the `lanterna monitor` command.
+ *
+ * Starts a WebSocket server and displays a live terminal dashboard
+ * showing connected apps and their real-time metrics.
+ */
+export async function runMonitor(args) {
+    const server = new LanternaServer(args.port);
+    server.on((event) => {
+        switch (event.type) {
+            case "appConnected":
+                // Dashboard will auto-update
+                break;
+            case "appDisconnected":
+                // Dashboard will auto-update
+                break;
+            case "metricsReceived":
+                refreshDashboard(server);
+                break;
+            case "error":
+                console.error(`Error: ${event.message}`);
+                break;
+        }
+    });
+    server.startListening();
+    console.log(renderDashboard(server.connectedApps, server.serverPort, true));
+    console.log(`\nWebSocket server listening on ws://localhost:${args.port}`);
+    console.log("Waiting for apps to connect...\n");
+    // Keep process alive
+    await new Promise((resolve) => {
+        const handler = () => {
+            server.stopListening();
+            console.log("\nMonitor stopped.");
+            resolve();
+        };
+        process.on("SIGINT", handler);
+        process.on("SIGTERM", handler);
+    });
+    return 0;
+}
+function refreshDashboard(server) {
+    // Clear and redraw
+    process.stdout.write("\x1b[2J\x1b[H");
+    console.log(renderDashboard(server.connectedApps, server.serverPort, true));
+}

package/dist/commands/test.d.ts

@@ -0,0 +1,4 @@
+import { type CommandRunner } from "@lanternajs/core";
+import type { TestArgs } from "../args";
+export declare function runTest(args: TestArgs, runner?: CommandRunner): Promise<number>;
+//# sourceMappingURL=test.d.ts.map

package/dist/commands/test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"test.d.ts","sourceRoot":"","sources":["../../src/commands/test.ts"],"names":[],"mappings":"AACA,OAAO,EAEN,KAAK,aAAa,EAQlB,MAAM,kBAAkB,CAAC;AAG1B,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AA6BxC,wBAAsB,OAAO,CAC5B,IAAI,EAAE,QAAQ,EACd,MAAM,GAAE,aAA6B,GACnC,OAAO,CAAC,MAAM,CAAC,CAmJjB"}

package/dist/commands/test.js

@@ -0,0 +1,148 @@
+import { collectAndroidMetrics } from "@lanternajs/android";
+import { analyzeSession, calculateScore, defaultRunner, detectDevices, MetricType, ScoreCategory, } from "@lanternajs/core";
+import { collectIosMetrics } from "@lanternajs/ios";
+import { exportJson, renderReport } from "@lanternajs/report";
+import { parseMaestroFlow, runMaestro } from "../maestro";
+import { Spinner } from "../spinner";
+import { LanternaServer, WS_DEFAULT_PORT } from "../ws-server";
+function selectDevice(devices, args) {
+    if (args.device) {
+        const match = devices.find((d) => d.id === args.device);
+        if (!match) {
+            throw new Error(`Device "${args.device}" not found. Available devices:\n${devices.map((d) => `  ${d.id} (${d.name}, ${d.platform})`).join("\n")}`);
+        }
+        return match;
+    }
+    if (args.platform) {
+        const platformDevices = devices.filter((d) => d.platform === args.platform);
+        if (platformDevices.length === 0) {
+            throw new Error(`No ${args.platform} devices found. Run "lanterna devices" to see available devices.`);
+        }
+        return platformDevices[0];
+    }
+    return devices[0];
+}
+export async function runTest(args, runner = defaultRunner) {
+    const spinner = new Spinner();
+    try {
+        // 1. Read and parse the Maestro flow YAML
+        spinner.start(`Reading Maestro flow: ${args.maestro}...`);
+        const flowFile = Bun.file(args.maestro);
+        if (!(await flowFile.exists())) {
+            spinner.fail(`Maestro flow file not found: ${args.maestro}`);
+            return 1;
+        }
+        const yaml = await flowFile.text();
+        const flow = parseMaestroFlow(yaml);
+        spinner.stop(`Maestro flow: ${flow.name} (${flow.steps.length} step${flow.steps.length !== 1 ? "s" : ""})`);
+        // 2. Extract appId — use as package name unless --package was provided
+        const packageName = args.package || flow.appId;
+        if (!packageName) {
+            spinner.fail("No app ID found. Provide a package name or include appId in the Maestro flow.");
+            return 1;
+        }
+        // 3. Detect devices
+        spinner.start("Detecting devices...");
+        const devices = await detectDevices(runner);
+        if (devices.length === 0) {
+            spinner.fail("No devices found");
+            console.error("\nMake sure you have a device connected or simulator/emulator running.\n" +
+                "  iOS: Open Simulator or connect a physical device\n" +
+                "  Android: Start an emulator or connect via ADB");
+            return 1;
+        }
+        const device = selectDevice(devices, args);
+        spinner.stop(`Device: ${device.name} (${device.platform}, ${device.type})`);
+        // 4. Start WebSocket server for Tier 2 data from in-app module
+        const wsServer = new LanternaServer(WS_DEFAULT_PORT);
+        const tier2Samples = [];
+        wsServer.on((event) => {
+            if (event.type === "metricsReceived") {
+                const app = wsServer.getApp(event.sessionId);
+                if (!app)
+                    return;
+                const now = Date.now();
+                if (app.fps) {
+                    tier2Samples.push({
+                        type: MetricType.UI_FPS,
+                        value: app.fps.ui,
+                        timestamp: now,
+                        unit: "fps",
+                    });
+                    if (app.fps.droppedFrames > 0) {
+                        tier2Samples.push({
+                            type: MetricType.FRAME_DROPS,
+                            value: app.fps.droppedFrames,
+                            timestamp: now,
+                            unit: "frames",
+                        });
+                    }
+                }
+                if (app.memory) {
+                    tier2Samples.push({
+                        type: MetricType.MEMORY,
+                        value: app.memory.usedMb,
+                        timestamp: now,
+                        unit: "MB",
+                    });
+                }
+            }
+        });
+        wsServer.startListening();
+        // 5. Start metric collection (Tier 1) and Maestro in parallel
+        spinner.start(`Running Maestro flow and collecting metrics on ${device.name}...`);
+        const collectMetrics = device.platform === "android"
+            ? collectAndroidMetrics(runner, device, packageName, args.duration)
+            : collectIosMetrics(runner, device, packageName, args.duration);
+        const maestroResult = runMaestro(runner, args.maestro);
+        const [session, maestro] = await Promise.all([collectMetrics, maestroResult]);
+        // 6. Stop WebSocket server and merge Tier 2 data
+        wsServer.stopListening();
+        if (tier2Samples.length > 0) {
+            session.samples.push(...tier2Samples);
+        }
+        spinner.stop(`Collection complete (${session.samples.length} samples, ${tier2Samples.length} from Tier 2)`);
+        // 7. Score the session
+        const score = calculateScore(session);
+        // 8. Render report
+        const report = renderReport(session, score);
+        console.log(report);
+        // 9. Show heuristic recommendations
+        const recommendations = analyzeSession(session, score);
+        if (recommendations.length > 0) {
+            console.log("\nRecommendations:");
+            for (const rec of recommendations) {
+                const icon = rec.severity === "critical" ? "!!" : rec.severity === "warning" ? "!" : "i";
+                console.log(`  [${icon}] ${rec.title}`);
+                console.log(`      ${rec.message}`);
+                if (rec.suggestion)
+                    console.log(`      Fix: ${rec.suggestion}`);
+            }
+        }
+        // 10. Show maestro pass/fail status
+        const maestroPassed = maestro.exitCode === 0;
+        if (maestroPassed) {
+            console.log("\nMaestro: PASSED");
+        }
+        else {
+            console.error("\nMaestro: FAILED");
+            if (maestro.output) {
+                console.error(maestro.output);
+            }
+        }
+        // 11. Export JSON if --output specified
+        if (args.output) {
+            await exportJson(session, score, args.output);
+            console.log(`\nJSON report saved to ${args.output}`);
+        }
+        // 12. Return exit code (0 if both maestro passed and score is not poor)
+        if (!maestroPassed)
+            return 1;
+        return score.category === ScoreCategory.POOR ? 1 : 0;
+    }
+    catch (error) {
+        spinner.fail("Test failed");
+        console.error(`\n${error instanceof Error ? error.message : String(error)}`);
+        return 1;
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env bun
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":""}

package/dist/index.js

@@ -0,0 +1,20 @@
+#!/usr/bin/env bun
+import { parseArgs } from "./args";
+import { runMeasure } from "./commands/measure";
+import { runMonitor } from "./commands/monitor";
+import { runTest } from "./commands/test";
+const argv = process.argv.slice(2);
+const parsed = parseArgs(argv);
+if (parsed) {
+    let exitCode;
+    if (parsed.command === "test") {
+        exitCode = await runTest(parsed.args);
+    }
+    else if (parsed.command === "monitor") {
+        exitCode = await runMonitor(parsed.args);
+    }
+    else {
+        exitCode = await runMeasure(parsed.args);
+    }
+    process.exit(exitCode);
+}

package/dist/live-dashboard.d.ts

@@ -0,0 +1,9 @@
+import type { ConnectedApp } from "./ws-server";
+/**
+ * Render a live terminal dashboard showing connected apps and their metrics.
+ *
+ * Returns a string that can be printed to the terminal.
+ * Uses ANSI escape codes for formatting.
+ */
+export declare function renderDashboard(apps: ConnectedApp[], serverPort: number, isRunning: boolean): string;
+//# sourceMappingURL=live-dashboard.d.ts.map

package/dist/live-dashboard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"live-dashboard.d.ts","sourceRoot":"","sources":["../src/live-dashboard.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEhD;;;;;GAKG;AACH,wBAAgB,eAAe,CAC9B,IAAI,EAAE,YAAY,EAAE,EACpB,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,OAAO,GAChB,MAAM,CAoCR"}

package/dist/live-dashboard.js

@@ -0,0 +1,75 @@
+/**
+ * Render a live terminal dashboard showing connected apps and their metrics.
+ *
+ * Returns a string that can be printed to the terminal.
+ * Uses ANSI escape codes for formatting.
+ */
+export function renderDashboard(apps, serverPort, isRunning) {
+    const lines = [];
+    lines.push("╭─────────────────────────────────────────────╮");
+    lines.push(`│  \x1b[1mlanterna monitor\x1b[0m                            │`);
+    lines.push(`│  Port: ${serverPort}  Status: ${isRunning ? "\x1b[32m● running\x1b[0m" : "\x1b[31m○ stopped\x1b[0m"}            │`);
+    lines.push("├─────────────────────────────────────────────┤");
+    if (apps.length === 0) {
+        lines.push("│  Waiting for apps to connect...             │");
+        lines.push("│                                             │");
+        lines.push("│  Add lanterna-react-native to your app      │");
+        lines.push("│  and it will auto-connect.                  │");
+    }
+    else {
+        for (const app of apps) {
+            lines.push(`│  \x1b[1m${padRight(app.appId, 40)}\x1b[0m   │`);
+            lines.push(`│  ${padRight(`${app.deviceName} (${app.platform})`, 40)}   │`);
+            if (app.currentScreen) {
+                lines.push(`│  ${padRight(`\x1b[36m${app.currentScreen}\x1b[0m`, 40)}   │`);
+            }
+            const metricLines = formatMetrics(app);
+            for (const ml of metricLines) {
+                lines.push(`│  ${padRight(ml, 40)}   │`);
+            }
+            lines.push("│                                             │");
+        }
+    }
+    lines.push("│  Press Ctrl+C to stop                       │");
+    lines.push("╰─────────────────────────────────────────────╯");
+    return lines.join("\n");
+}
+function formatMetrics(app) {
+    const lines = [];
+    const m = app.latestMetrics;
+    if (app.fps) {
+        const uiColor = app.fps.ui >= 55 ? "\x1b[32m" : app.fps.ui >= 40 ? "\x1b[33m" : "\x1b[31m";
+        lines.push(`${uiColor}UI FPS: ${app.fps.ui.toFixed(1)}\x1b[0m  Drops: ${app.fps.droppedFrames}`);
+    }
+    if (m.ui_fps !== undefined && !app.fps) {
+        const color = m.ui_fps >= 55 ? "\x1b[32m" : m.ui_fps >= 40 ? "\x1b[33m" : "\x1b[31m";
+        lines.push(`${color}UI FPS: ${m.ui_fps.toFixed(1)}\x1b[0m`);
+    }
+    if (m.js_fps !== undefined) {
+        const color = m.js_fps >= 55 ? "\x1b[32m" : m.js_fps >= 40 ? "\x1b[33m" : "\x1b[31m";
+        lines.push(`${color}JS FPS: ${m.js_fps.toFixed(1)}\x1b[0m`);
+    }
+    if (m.cpu !== undefined) {
+        const color = m.cpu <= 30 ? "\x1b[32m" : m.cpu <= 60 ? "\x1b[33m" : "\x1b[31m";
+        lines.push(`${color}CPU: ${m.cpu.toFixed(1)}%\x1b[0m`);
+    }
+    if (app.memory) {
+        const color = app.memory.usedMb <= 300 ? "\x1b[32m" : app.memory.usedMb <= 500 ? "\x1b[33m" : "\x1b[31m";
+        lines.push(`${color}Memory: ${app.memory.usedMb} MB\x1b[0m`);
+    }
+    else if (m.memory !== undefined) {
+        const color = m.memory <= 300 ? "\x1b[32m" : m.memory <= 500 ? "\x1b[33m" : "\x1b[31m";
+        lines.push(`${color}Memory: ${m.memory.toFixed(0)} MB\x1b[0m`);
+    }
+    if (lines.length === 0) {
+        lines.push("Awaiting metrics...");
+    }
+    return lines;
+}
+function padRight(str, len) {
+    // Strip ANSI escape codes for length calculation
+    // biome-ignore lint/suspicious/noControlCharactersInRegex: ANSI escape codes are intentional
+    const stripped = str.replace(/\x1b\[[0-9;]*m/g, "");
+    const padding = Math.max(0, len - stripped.length);
+    return str + " ".repeat(padding);
+}

package/dist/maestro.d.ts

@@ -0,0 +1,23 @@
+import type { CommandRunner } from "@lanternajs/core";
+export interface MaestroStep {
+    name: string;
+    lineNumber: number;
+}
+export interface MaestroFlow {
+    name: string;
+    appId: string;
+    steps: MaestroStep[];
+}
+/**
+ * Parse a Maestro YAML flow file into a structured MaestroFlow.
+ * Extracts appId and recognized Maestro command steps.
+ */
+export declare function parseMaestroFlow(yaml: string): MaestroFlow;
+/**
+ * Run a Maestro flow file using the `maestro test` CLI command.
+ */
+export declare function runMaestro(runner: CommandRunner, flowPath: string): Promise<{
+    exitCode: number;
+    output: string;
+}>;
+//# sourceMappingURL=maestro.d.ts.map

package/dist/maestro.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"maestro.d.ts","sourceRoot":"","sources":["../src/maestro.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAEtD,MAAM,WAAW,WAAW;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,WAAW;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,WAAW,EAAE,CAAC;CACrB;AAgBD;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,CAmC1D;AAED;;GAEG;AACH,wBAAsB,UAAU,CAC/B,MAAM,EAAE,aAAa,EACrB,QAAQ,EAAE,MAAM,GACd,OAAO,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,CAM/C"}

package/dist/maestro.js

@@ -0,0 +1,57 @@
+const KNOWN_COMMANDS = new Set([
+    "tapOn",
+    "assertVisible",
+    "inputText",
+    "scrollUntilVisible",
+    "back",
+    "swipe",
+    "waitForAnimationToEnd",
+    "launchApp",
+    "clearState",
+    "runFlow",
+    "openLink",
+]);
+/**
+ * Parse a Maestro YAML flow file into a structured MaestroFlow.
+ * Extracts appId and recognized Maestro command steps.
+ */
+export function parseMaestroFlow(yaml) {
+    const lines = yaml.split("\n");
+    let appId = "";
+    const steps = [];
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        const lineNumber = i + 1;
+        // Extract appId from lines like `appId: "com.example.app"` or `appId: com.example.app`
+        const appIdMatch = line.match(/^\s*appId:\s*"?([^"\s]+)"?\s*$/);
+        if (appIdMatch) {
+            appId = appIdMatch[1];
+            continue;
+        }
+        // Extract steps: lines starting with `- ` that contain known Maestro commands
+        const stepMatch = line.match(/^\s*-\s+(\w+)(?::\s*(.*))?$/);
+        if (!stepMatch)
+            continue;
+        const command = stepMatch[1];
+        if (!KNOWN_COMMANDS.has(command))
+            continue;
+        const rawArg = stepMatch[2]?.trim() ?? "";
+        // Strip surrounding quotes from the argument
+        const arg = rawArg.replace(/^"(.*)"$/, "$1");
+        const name = arg ? `${command} "${arg}"` : command;
+        steps.push({ name, lineNumber });
+    }
+    // Derive flow name from appId or default
+    const name = appId ? `Flow: ${appId}` : "Unnamed flow";
+    return { name, appId, steps };
+}
+/**
+ * Run a Maestro flow file using the `maestro test` CLI command.
+ */
+export async function runMaestro(runner, flowPath) {
+    const result = await runner("maestro", ["test", flowPath]);
+    return {
+        exitCode: result.exitCode,
+        output: result.stdout,
+    };
+}

package/dist/spinner.d.ts

@@ -0,0 +1,9 @@
+export declare class Spinner {
+    private interval;
+    private frameIndex;
+    start(message: string): void;
+    update(message: string): void;
+    stop(message?: string): void;
+    fail(message: string): void;
+}
+//# sourceMappingURL=spinner.d.ts.map

package/dist/spinner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spinner.d.ts","sourceRoot":"","sources":["../src/spinner.ts"],"names":[],"mappings":"AAEA,qBAAa,OAAO;IACnB,OAAO,CAAC,QAAQ,CAA+C;IAC/D,OAAO,CAAC,UAAU,CAAK;IAEvB,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAS5B,MAAM,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAM7B,IAAI,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI;IAY5B,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;CAO3B"}

package/dist/spinner.js

@@ -0,0 +1,37 @@
+const FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+export class Spinner {
+    interval = null;
+    frameIndex = 0;
+    start(message) {
+        this.frameIndex = 0;
+        process.stdout.write(`\r${FRAMES[0]} ${message}`);
+        this.interval = setInterval(() => {
+            this.frameIndex = (this.frameIndex + 1) % FRAMES.length;
+            process.stdout.write(`\r${FRAMES[this.frameIndex]} ${message}`);
+        }, 80);
+    }
+    update(message) {
+        if (this.interval) {
+            process.stdout.write(`\r${FRAMES[this.frameIndex]} ${message}`);
+        }
+    }
+    stop(message) {
+        if (this.interval) {
+            clearInterval(this.interval);
+            this.interval = null;
+        }
+        if (message) {
+            process.stdout.write(`\r✓ ${message}\n`);
+        }
+        else {
+            process.stdout.write("\r\x1b[K");
+        }
+    }
+    fail(message) {
+        if (this.interval) {
+            clearInterval(this.interval);
+            this.interval = null;
+        }
+        process.stdout.write(`\r✗ ${message}\n`);
+    }
+}

package/dist/ws-server.d.ts

@@ -0,0 +1,114 @@
+/**
+ * WebSocket server for receiving real-time metrics from lanterna-react-native apps.
+ */
+/** Message types from the protocol (duplicated here to avoid dependency on react-native package). */
+export type ServerMessageType = "handshake" | "handshake_ack" | "metrics" | "control" | "disconnect" | "error";
+/** Parsed message from a connected app. */
+export interface ServerMessage {
+    type: ServerMessageType;
+    timestamp: number;
+    [key: string]: unknown;
+}
+/** A connected app session. */
+export interface ConnectedApp {
+    sessionId: string;
+    appId: string;
+    platform: "ios" | "android";
+    deviceName: string;
+    connectedAt: number;
+    lastMetricsAt: number;
+    latestMetrics: Record<string, number>;
+    fps?: {
+        ui: number;
+        js: number;
+        droppedFrames: number;
+    };
+    memory?: {
+        usedMb: number;
+    };
+    currentScreen?: string;
+}
+/** Server event listener. */
+export type ServerEventListener = (event: ServerEvent) => void;
+/** Server events. */
+export type ServerEvent = {
+    type: "appConnected";
+    app: ConnectedApp;
+} | {
+    type: "appDisconnected";
+    sessionId: string;
+    reason: string;
+} | {
+    type: "metricsReceived";
+    sessionId: string;
+    metrics: Record<string, number>;
+} | {
+    type: "serverStarted";
+    port: number;
+} | {
+    type: "serverStopped";
+} | {
+    type: "error";
+    message: string;
+};
+/** Default port for the Lanterna WebSocket server. */
+export declare const WS_DEFAULT_PORT = 8347;
+/**
+ * Lanterna WebSocket metric server.
+ *
+ * Accepts connections from instrumented apps, processes handshakes,
+ * and collects streaming metrics. Pure logic — no WebSocket runtime
+ * dependency, allowing full testing in Bun.
+ */
+export declare class LanternaServer {
+    private apps;
+    private listeners;
+    private running;
+    private port;
+    private httpServer;
+    constructor(port?: number);
+    /** Whether the server is running. */
+    get isRunning(): boolean;
+    /** Server port. */
+    get serverPort(): number;
+    /** All currently connected apps. */
+    get connectedApps(): ConnectedApp[];
+    /** Get a connected app by session ID. */
+    getApp(sessionId: string): ConnectedApp | null;
+    /**
+     * Start the server (sets running state).
+     */
+    start(): void;
+    /**
+     * Stop the server.
+     */
+    stop(): void;
+    /**
+     * Start the server with a real WebSocket listener bound to the port.
+     * Uses Bun's native WebSocket support — no external library needed.
+     */
+    startListening(): void;
+    /**
+     * Stop the server and close the WebSocket listener.
+     */
+    stopListening(): void;
+    /**
+     * Process an incoming message from a client.
+     * Returns a response message to send back, or null if no response needed.
+     */
+    handleMessage(data: string): string | null;
+    /** Subscribe to server events. Returns unsubscribe function. */
+    on(listener: ServerEventListener): () => void;
+    /** Remove all listeners. */
+    removeAllListeners(): void;
+    private handleHandshake;
+    private handleMetrics;
+    private handleDisconnect;
+    private emit;
+}
+/**
+ * Parse a raw message string into a ServerMessage.
+ * Returns null for invalid messages.
+ */
+export declare function parseServerMessage(data: string): ServerMessage | null;
+//# sourceMappingURL=ws-server.d.ts.map

package/dist/ws-server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ws-server.d.ts","sourceRoot":"","sources":["../src/ws-server.ts"],"names":[],"mappings":"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"}

package/dist/ws-server.js

@@ -0,0 +1,206 @@
+/**
+ * WebSocket server for receiving real-time metrics from lanterna-react-native apps.
+ */
+/** Default port for the Lanterna WebSocket server. */
+export const WS_DEFAULT_PORT = 8347;
+let sessionCounter = 0;
+function generateSessionId() {
+    sessionCounter++;
+    return `lanterna-${Date.now()}-${sessionCounter}`;
+}
+/**
+ * Lanterna WebSocket metric server.
+ *
+ * Accepts connections from instrumented apps, processes handshakes,
+ * and collects streaming metrics. Pure logic — no WebSocket runtime
+ * dependency, allowing full testing in Bun.
+ */
+export class LanternaServer {
+    apps = new Map();
+    listeners = new Set();
+    running = false;
+    port;
+    httpServer = null;
+    constructor(port = WS_DEFAULT_PORT) {
+        this.port = port;
+    }
+    /** Whether the server is running. */
+    get isRunning() {
+        return this.running;
+    }
+    /** Server port. */
+    get serverPort() {
+        return this.port;
+    }
+    /** All currently connected apps. */
+    get connectedApps() {
+        return [...this.apps.values()];
+    }
+    /** Get a connected app by session ID. */
+    getApp(sessionId) {
+        return this.apps.get(sessionId) ?? null;
+    }
+    /**
+     * Start the server (sets running state).
+     */
+    start() {
+        if (this.running)
+            return;
+        this.running = true;
+        this.emit({ type: "serverStarted", port: this.port });
+    }
+    /**
+     * Stop the server.
+     */
+    stop() {
+        if (!this.running)
+            return;
+        this.running = false;
+        this.apps.clear();
+        this.emit({ type: "serverStopped" });
+    }
+    /**
+     * Start the server with a real WebSocket listener bound to the port.
+     * Uses Bun's native WebSocket support — no external library needed.
+     */
+    startListening() {
+        if (this.running)
+            return;
+        const server = this;
+        this.httpServer = Bun.serve({
+            port: this.port,
+            fetch(req, bunServer) {
+                if (bunServer.upgrade(req, { data: {} }))
+                    return undefined;
+                return new Response("Lanterna WebSocket Server", { status: 200 });
+            },
+            websocket: {
+                message(ws, data) {
+                    const response = server.handleMessage(String(data));
+                    if (response)
+                        ws.send(response);
+                },
+                close(_ws) {
+                    // App disconnected without sending disconnect message
+                },
+            },
+        });
+        this.start();
+    }
+    /**
+     * Stop the server and close the WebSocket listener.
+     */
+    stopListening() {
+        this.httpServer?.stop();
+        this.httpServer = null;
+        this.stop();
+    }
+    /**
+     * Process an incoming message from a client.
+     * Returns a response message to send back, or null if no response needed.
+     */
+    handleMessage(data) {
+        const message = parseServerMessage(data);
+        if (!message) {
+            this.emit({ type: "error", message: "Invalid message received" });
+            return null;
+        }
+        switch (message.type) {
+            case "handshake":
+                return this.handleHandshake(message);
+            case "metrics":
+                this.handleMetrics(message);
+                return null;
+            case "disconnect":
+                this.handleDisconnect(message);
+                return null;
+            default:
+                return null;
+        }
+    }
+    /** Subscribe to server events. Returns unsubscribe function. */
+    on(listener) {
+        this.listeners.add(listener);
+        return () => this.listeners.delete(listener);
+    }
+    /** Remove all listeners. */
+    removeAllListeners() {
+        this.listeners.clear();
+    }
+    handleHandshake(message) {
+        const sessionId = generateSessionId();
+        const app = {
+            sessionId,
+            appId: message.appId ?? "unknown",
+            platform: message.platform ?? "android",
+            deviceName: message.deviceName ?? "unknown",
+            connectedAt: Date.now(),
+            lastMetricsAt: 0,
+            latestMetrics: {},
+        };
+        this.apps.set(sessionId, app);
+        this.emit({ type: "appConnected", app });
+        const ack = {
+            type: "handshake_ack",
+            timestamp: Date.now(),
+            sessionId,
+            config: { intervalMs: 1000, metrics: [] },
+        };
+        return JSON.stringify(ack);
+    }
+    handleMetrics(message) {
+        const sessionId = message.sessionId;
+        const app = this.apps.get(sessionId);
+        if (!app)
+            return;
+        const metrics = message.metrics ?? {};
+        app.lastMetricsAt = Date.now();
+        app.latestMetrics = metrics;
+        if (message.fps) {
+            app.fps = message.fps;
+        }
+        if (message.memory) {
+            app.memory = message.memory;
+        }
+        if (typeof message.currentScreen === "string") {
+            app.currentScreen = message.currentScreen;
+        }
+        this.emit({ type: "metricsReceived", sessionId, metrics });
+    }
+    handleDisconnect(message) {
+        const sessionId = message.sessionId;
+        const reason = message.reason ?? "client disconnected";
+        // Find and remove by sessionId or by matching
+        for (const [id, _app] of this.apps) {
+            if (id === sessionId) {
+                this.apps.delete(id);
+                this.emit({ type: "appDisconnected", sessionId: id, reason });
+                return;
+            }
+        }
+    }
+    emit(event) {
+        for (const listener of this.listeners) {
+            listener(event);
+        }
+    }
+}
+/**
+ * Parse a raw message string into a ServerMessage.
+ * Returns null for invalid messages.
+ */
+export function parseServerMessage(data) {
+    try {
+        const parsed = JSON.parse(data);
+        if (!parsed || typeof parsed !== "object")
+            return null;
+        if (typeof parsed.type !== "string")
+            return null;
+        if (typeof parsed.timestamp !== "number")
+            return null;
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@lanternajs/cli",
+  "version": "0.0.1",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "lanterna": "dist/index.js"
+  },
+  "files": ["dist"],
+  "license": "Apache-2.0",
+  "description": "CLI entry point for Lanterna — Lighthouse for mobile apps",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/nicepkg/lanterna.git",
+    "directory": "packages/cli"
+  },
+  "publishConfig": { "access": "public" },
+  "dependencies": {
+    "@lanternajs/core": "workspace:*",
+    "@lanternajs/android": "workspace:*",
+    "@lanternajs/ios": "workspace:*",
+    "@lanternajs/report": "workspace:*"
+  },
+  "scripts": {
+    "build": "tsc --project tsconfig.build.json",
+    "prepublishOnly": "npm run build",
+    "test": "bun test"
+  }
+}