@mlola/browser-cli 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MLola
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,19 @@
+# @mlola/browser-cli
+
+The `mlola browser` command line interface for the
+[MLola Browser Runtime](https://mlola.com/browser-runtime).
+
+```bash
+npm install -g @mlola/browser-cli
+
+mlola browser doctor
+mlola browser run --goal "Download my latest invoice" --url https://billing.example.com/invoices
+mlola browser sessions
+mlola browser trace show <runId>
+mlola browser eval --suite core
+mlola browser daemon start
+```
+
+```bash
+export TYPESAFE_API_KEY=…   # fast path (https://typesafe.ai)
+```

package/dist/args.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Minimal argument parser. No dependency on a CLI framework: the surface is
+ * small, and the runtime keeps its dependency graph tight on purpose.
+ */
+export interface ParsedArgs {
+    command: string[];
+    flags: Record<string, string | boolean>;
+    positional: string[];
+}
+export declare const parseArgs: (argv: string[]) => ParsedArgs;
+export declare const flagString: (flags: Record<string, string | boolean>, key: string) => string | undefined;
+export declare const flagBool: (flags: Record<string, string | boolean>, key: string) => boolean;
+export declare const flagNumber: (flags: Record<string, string | boolean>, key: string) => number | undefined;
+//# 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;;;GAGG;AAEH,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC;IACxC,UAAU,EAAE,MAAM,EAAE,CAAC;CACtB;AAED,eAAO,MAAM,SAAS,GAAI,MAAM,MAAM,EAAE,KAAG,UAqC1C,CAAC;AAEF,eAAO,MAAM,UAAU,GAAI,OAAO,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,EAAE,KAAK,MAAM,KAAG,MAAM,GAAG,SAG1F,CAAC;AAEF,eAAO,MAAM,QAAQ,GAAI,OAAO,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,EAAE,KAAK,MAAM,KAAG,OACZ,CAAC;AAErE,eAAO,MAAM,UAAU,GAAI,OAAO,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,EAAE,KAAK,MAAM,KAAG,MAAM,GAAG,SAK1F,CAAC"}

package/dist/args.js

@@ -0,0 +1,58 @@
+/**
+ * Minimal argument parser. No dependency on a CLI framework: the surface is
+ * small, and the runtime keeps its dependency graph tight on purpose.
+ */
+export const parseArgs = (argv) => {
+    const flags = {};
+    const positional = [];
+    let i = 0;
+    while (i < argv.length) {
+        const arg = argv[i];
+        if (arg === "--") {
+            positional.push(...argv.slice(i + 1));
+            break;
+        }
+        if (arg.startsWith("--")) {
+            const eq = arg.indexOf("=");
+            if (eq > 0) {
+                flags[arg.slice(2, eq)] = arg.slice(eq + 1);
+            }
+            else {
+                const key = arg.slice(2);
+                const next = argv[i + 1];
+                if (next !== undefined && !next.startsWith("-")) {
+                    flags[key] = next;
+                    i += 1;
+                }
+                else {
+                    flags[key] = true;
+                }
+            }
+            i += 1;
+            continue;
+        }
+        if (arg.startsWith("-") && arg.length > 1) {
+            const keys = arg.slice(1).split("");
+            for (const key of keys)
+                flags[key] = true;
+            i += 1;
+            continue;
+        }
+        positional.push(arg);
+        i += 1;
+    }
+    return { command: [], flags, positional };
+};
+export const flagString = (flags, key) => {
+    const value = flags[key];
+    return typeof value === "string" ? value : undefined;
+};
+export const flagBool = (flags, key) => flags[key] === true || flags[key] === "true" || flags[key] === "1";
+export const flagNumber = (flags, key) => {
+    const value = flagString(flags, key);
+    if (value === undefined)
+        return undefined;
+    const parsed = Number(value);
+    return Number.isFinite(parsed) ? parsed : undefined;
+};
+//# sourceMappingURL=args.js.map

package/dist/args.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"args.js","sourceRoot":"","sources":["../src/args.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAQH,MAAM,CAAC,MAAM,SAAS,GAAG,CAAC,IAAc,EAAc,EAAE;IACtD,MAAM,KAAK,GAAqC,EAAE,CAAC;IACnD,MAAM,UAAU,GAAa,EAAE,CAAC;IAChC,IAAI,CAAC,GAAG,CAAC,CAAC;IACV,OAAO,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC;QACvB,MAAM,GAAG,GAAG,IAAI,CAAC,CAAC,CAAE,CAAC;QACrB,IAAI,GAAG,KAAK,IAAI,EAAE,CAAC;YACjB,UAAU,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;YACtC,MAAM;QACR,CAAC;QACD,IAAI,GAAG,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;YACzB,MAAM,EAAE,GAAG,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;YAC5B,IAAI,EAAE,GAAG,CAAC,EAAE,CAAC;gBACX,KAAK,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,GAAG,CAAC,KAAK,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC;YAC9C,CAAC;iBAAM,CAAC;gBACN,MAAM,GAAG,GAAG,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;gBACzB,MAAM,IAAI,GAAG,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;gBACzB,IAAI,IAAI,KAAK,SAAS,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;oBAChD,KAAK,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC;oBAClB,CAAC,IAAI,CAAC,CAAC;gBACT,CAAC;qBAAM,CAAC;oBACN,KAAK,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC;gBACpB,CAAC;YACH,CAAC;YACD,CAAC,IAAI,CAAC,CAAC;YACP,SAAS;QACX,CAAC;QACD,IAAI,GAAG,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC1C,MAAM,IAAI,GAAG,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;YACpC,KAAK,MAAM,GAAG,IAAI,IAAI;gBAAE,KAAK,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC;YAC1C,CAAC,IAAI,CAAC,CAAC;YACP,SAAS;QACX,CAAC;QACD,UAAU,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QACrB,CAAC,IAAI,CAAC,CAAC;IACT,CAAC;IACD,OAAO,EAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,UAAU,EAAE,CAAC;AAC5C,CAAC,CAAC;AAEF,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,KAAuC,EAAE,GAAW,EAAsB,EAAE;IACrG,MAAM,KAAK,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC;IACzB,OAAO,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC;AACvD,CAAC,CAAC;AAEF,MAAM,CAAC,MAAM,QAAQ,GAAG,CAAC,KAAuC,EAAE,GAAW,EAAW,EAAE,CACxF,KAAK,CAAC,GAAG,CAAC,KAAK,IAAI,IAAI,KAAK,CAAC,GAAG,CAAC,KAAK,MAAM,IAAI,KAAK,CAAC,GAAG,CAAC,KAAK,GAAG,CAAC;AAErE,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,KAAuC,EAAE,GAAW,EAAsB,EAAE;IACrG,MAAM,KAAK,GAAG,UAAU,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;IACrC,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IAC1C,MAAM,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;IAC7B,OAAO,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC;AACtD,CAAC,CAAC"}

package/dist/bin.d.ts

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+/**
+ * `mlola` executable. The product surface is `mlola browser <command>`;
+ * `mlola <command>` is accepted as shorthand.
+ */
+export {};
+//# sourceMappingURL=bin.d.ts.map

package/dist/bin.d.ts.map

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

package/dist/bin.js

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+/**
+ * `mlola` executable. The product surface is `mlola browser <command>`;
+ * `mlola <command>` is accepted as shorthand.
+ */
+import { run } from "./main.js";
+run(process.argv.slice(2))
+    .then((code) => {
+    process.exitCode = code;
+})
+    .catch((error) => {
+    process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+    process.exitCode = 1;
+});
+//# sourceMappingURL=bin.js.map

package/dist/bin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bin.js","sourceRoot":"","sources":["../src/bin.ts"],"names":[],"mappings":";AACA;;;GAGG;AAEH,OAAO,EAAE,GAAG,EAAE,MAAM,WAAW,CAAC;AAEhC,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;KACvB,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE;IACb,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC;AAC1B,CAAC,CAAC;KACD,KAAK,CAAC,CAAC,KAAc,EAAE,EAAE;IACxB,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IACpF,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;AACvB,CAAC,CAAC,CAAC"}

package/dist/commands/daemon.d.ts

@@ -0,0 +1,6 @@
+/**
+ * `mlola browser daemon` — manage mlola-browserd (PRD §59).
+ */
+import { type ParsedArgs } from "../args.ts";
+export declare const daemonCommand: (args: ParsedArgs) => Promise<number>;
+//# sourceMappingURL=daemon.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"daemon.d.ts","sourceRoot":"","sources":["../../src/commands/daemon.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAc,KAAK,UAAU,EAAE,MAAM,YAAY,CAAC;AAGzD,eAAO,MAAM,aAAa,GAAU,MAAM,UAAU,KAAG,OAAO,CAAC,MAAM,CAgDpE,CAAC"}

package/dist/commands/daemon.js

@@ -0,0 +1,58 @@
+/**
+ * `mlola browser daemon` — manage mlola-browserd (PRD §59).
+ */
+import { flagString } from "../args.js";
+import { c, heading, kv, out } from "../ui.js";
+export const daemonCommand = async (args) => {
+    const sub = args.positional[0] ?? "status";
+    const { startDaemon, stopDaemon, daemonStatus, readDaemonState } = await import("@mlola/browser-daemon");
+    const port = flagString(args.flags, "port");
+    switch (sub) {
+        case "start": {
+            const started = await startDaemon({
+                ...(port ? { port: Number(port) } : {}),
+                ...(args.flags["foreground"] === true ? { foreground: true } : {}),
+            });
+            heading("mlola-browserd");
+            kv("status", started.started ? c.green("started") : c.yellow("already running"));
+            kv("url", started.url);
+            kv("pid", String(started.pid));
+            kv("token", c.dim(started.tokenPath));
+            out("");
+            return 0;
+        }
+        case "stop": {
+            const stopped = await stopDaemon();
+            heading("mlola-browserd");
+            kv("status", stopped.stopped ? c.green("stopped") : c.yellow("not running"));
+            if (stopped.forced)
+                kv("note", "sent SIGKILL after the graceful timeout");
+            out("");
+            return stopped.stopped ? 0 : 1;
+        }
+        case "status": {
+            const status = await daemonStatus();
+            const state = readDaemonState();
+            heading("mlola-browserd");
+            kv("status", status.running ? c.green("running") : c.dim("not running"));
+            if (state) {
+                kv("url", `http://127.0.0.1:${state.port}`);
+                kv("pid", String(state.pid));
+                kv("started", new Date(state.startedAt).toISOString());
+                kv("token", c.dim(state.tokenPath));
+            }
+            if (status.version)
+                kv("version", status.version);
+            if (status.protocol)
+                kv("protocol", status.protocol);
+            if (status.sessions !== undefined)
+                kv("sessions", String(status.sessions));
+            out("");
+            return 0;
+        }
+        default:
+            out("usage: mlola browser daemon <start|stop|status> [--port N] [--foreground]");
+            return 2;
+    }
+};
+//# sourceMappingURL=daemon.js.map

package/dist/commands/daemon.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"daemon.js","sourceRoot":"","sources":["../../src/commands/daemon.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,UAAU,EAAmB,MAAM,YAAY,CAAC;AACzD,OAAO,EAAE,CAAC,EAAE,OAAO,EAAE,EAAE,EAAE,GAAG,EAAE,MAAM,UAAU,CAAC;AAE/C,MAAM,CAAC,MAAM,aAAa,GAAG,KAAK,EAAE,IAAgB,EAAmB,EAAE;IACvE,MAAM,GAAG,GAAG,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,IAAI,QAAQ,CAAC;IAC3C,MAAM,EAAE,WAAW,EAAE,UAAU,EAAE,YAAY,EAAE,eAAe,EAAE,GAAG,MAAM,MAAM,CAAC,uBAAuB,CAAC,CAAC;IACzG,MAAM,IAAI,GAAG,UAAU,CAAC,IAAI,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;IAE5C,QAAQ,GAAG,EAAE,CAAC;QACZ,KAAK,OAAO,CAAC,CAAC,CAAC;YACb,MAAM,OAAO,GAAG,MAAM,WAAW,CAAC;gBAChC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;gBACvC,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,KAAK,IAAI,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;aACnE,CAAC,CAAC;YACH,OAAO,CAAC,gBAAgB,CAAC,CAAC;YAC1B,EAAE,CAAC,QAAQ,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,iBAAiB,CAAC,CAAC,CAAC;YACjF,EAAE,CAAC,KAAK,EAAE,OAAO,CAAC,GAAG,CAAC,CAAC;YACvB,EAAE,CAAC,KAAK,EAAE,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC;YAC/B,EAAE,CAAC,OAAO,EAAE,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC;YACtC,GAAG,CAAC,EAAE,CAAC,CAAC;YACR,OAAO,CAAC,CAAC;QACX,CAAC;QACD,KAAK,MAAM,CAAC,CAAC,CAAC;YACZ,MAAM,OAAO,GAAG,MAAM,UAAU,EAAE,CAAC;YACnC,OAAO,CAAC,gBAAgB,CAAC,CAAC;YAC1B,EAAE,CAAC,QAAQ,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC,CAAC;YAC7E,IAAI,OAAO,CAAC,MAAM;gBAAE,EAAE,CAAC,MAAM,EAAE,yCAAyC,CAAC,CAAC;YAC1E,GAAG,CAAC,EAAE,CAAC,CAAC;YACR,OAAO,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QACjC,CAAC;QACD,KAAK,QAAQ,CAAC,CAAC,CAAC;YACd,MAAM,MAAM,GAAG,MAAM,YAAY,EAAE,CAAC;YACpC,MAAM,KAAK,GAAG,eAAe,EAAE,CAAC;YAChC,OAAO,CAAC,gBAAgB,CAAC,CAAC;YAC1B,EAAE,CAAC,QAAQ,EAAE,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC,CAAC;YACzE,IAAI,KAAK,EAAE,CAAC;gBACV,EAAE,CAAC,KAAK,EAAE,oBAAoB,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC;gBAC5C,EAAE,CAAC,KAAK,EAAE,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC;gBAC7B,EAAE,CAAC,SAAS,EAAE,IAAI,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC;gBACvD,EAAE,CAAC,OAAO,EAAE,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC;YACtC,CAAC;YACD,IAAI,MAAM,CAAC,OAAO;gBAAE,EAAE,CAAC,SAAS,EAAE,MAAM,CAAC,OAAO,CAAC,CAAC;YAClD,IAAI,MAAM,CAAC,QAAQ;gBAAE,EAAE,CAAC,UAAU,EAAE,MAAM,CAAC,QAAQ,CAAC,CAAC;YACrD,IAAI,MAAM,CAAC,QAAQ,KAAK,SAAS;gBAAE,EAAE,CAAC,UAAU,EAAE,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC;YAC3E,GAAG,CAAC,EAAE,CAAC,CAAC;YACR,OAAO,CAAC,CAAC;QACX,CAAC;QACD;YACE,GAAG,CAAC,2EAA2E,CAAC,CAAC;YACjF,OAAO,CAAC,CAAC;IACb,CAAC;AACH,CAAC,CAAC"}

package/dist/commands/doctor.d.ts

@@ -0,0 +1,6 @@
+/**
+ * `mlola browser doctor` — environment and readiness checks.
+ */
+import { type ParsedArgs } from "../args.ts";
+export declare const doctorCommand: (args: ParsedArgs) => Promise<number>;
+//# sourceMappingURL=doctor.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"doctor.d.ts","sourceRoot":"","sources":["../../src/commands/doctor.ts"],"names":[],"mappings":"AAAA;;GAEG;AAKH,OAAO,EAAY,KAAK,UAAU,EAAE,MAAM,YAAY,CAAC;AAUvD,eAAO,MAAM,aAAa,GAAU,MAAM,UAAU,KAAG,OAAO,CAAC,MAAM,CAuHpE,CAAC"}

package/dist/commands/doctor.js

@@ -0,0 +1,125 @@
+/**
+ * `mlola browser doctor` — environment and readiness checks.
+ */
+import { existsSync, mkdirSync, writeFileSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { resolveHome, daemonPaths } from "@mlola/browser-trace";
+import { flagBool } from "../args.js";
+import { c, heading, kv, out } from "../ui.js";
+export const doctorCommand = async (args) => {
+    const json = flagBool(args.flags, "json");
+    const checks = [];
+    checks.push({
+        name: "node",
+        ok: Number(process.versions.node.split(".")[0]) >= 22,
+        detail: `v${process.versions.node}`,
+        fix: "upgrade to Node 22.18+ (24 recommended)",
+    });
+    // Fast path credentials.
+    const typesafeKey = process.env["TYPESAFE_API_KEY"];
+    checks.push({
+        name: "Jev fast path",
+        ok: typesafeKey ? true : "warn",
+        detail: typesafeKey
+            ? `TYPESAFE_API_KEY is set (${typesafeKey.slice(0, 4)}…, ${typesafeKey.length} chars)`
+            : "TYPESAFE_API_KEY is not set — the fast path cannot run",
+        fix: "export TYPESAFE_API_KEY=… (https://typesafe.ai). Offline demos can use --provider keyword",
+    });
+    // Planner / text helper (optional).
+    const plannerKey = process.env["MLOLA_PLANNER_API_KEY"] ?? process.env["OPENAI_API_KEY"];
+    checks.push({
+        name: "planner (optional)",
+        ok: plannerKey ? true : "warn",
+        detail: plannerKey ? "an OpenAI-compatible planner key is set" : "no planner configured",
+        fix: "set MLOLA_PLANNER_API_KEY + MLOLA_PLANNER_BASE_URL + MLOLA_PLANNER_MODEL to enable planning and fallback",
+    });
+    // Playwright + Chrome.
+    try {
+        const playwright = await import("playwright-core");
+        checks.push({ name: "playwright-core", ok: true, detail: `loaded (chromium ${playwright.chromium.name()})` });
+        const channel = process.env["MLOLA_CHROME_CHANNEL"] ?? "chrome";
+        let launched = false;
+        let launchDetail = "";
+        try {
+            const browser = await playwright.chromium.launch({ channel, headless: true });
+            launched = true;
+            launchDetail = `launched ${channel} ${browser.version()}`;
+            await browser.close();
+        }
+        catch (error) {
+            launchDetail = `${channel} launch failed: ${error instanceof Error ? error.message.split("\n")[0] : String(error)}`;
+        }
+        checks.push({
+            name: "browser",
+            ok: launched ? true : "warn",
+            detail: launched ? launchDetail : `${launchDetail} — falling back to bundled chromium`,
+            fix: "install Google Chrome, or run: npx playwright install chromium",
+        });
+    }
+    catch (error) {
+        checks.push({
+            name: "playwright-core",
+            ok: false,
+            detail: `not importable: ${String(error)}`,
+            fix: "npm install (the workspace declares playwright-core)",
+        });
+    }
+    // Runtime home.
+    const home = resolveHome();
+    try {
+        mkdirSync(home, { recursive: true });
+        const probe = join(home, `.doctor-${process.pid}`);
+        writeFileSync(probe, "ok");
+        rmSync(probe, { force: true });
+        checks.push({ name: "runtime home", ok: true, detail: `${home} is writable` });
+    }
+    catch (error) {
+        checks.push({
+            name: "runtime home",
+            ok: false,
+            detail: `${home} is not writable: ${String(error)}`,
+            fix: "set MLOLA_HOME to a writable directory",
+        });
+    }
+    // Daemon.
+    const paths = daemonPaths(home);
+    if (existsSync(paths.statePath)) {
+        try {
+            const state = JSON.parse(await import("node:fs/promises").then((fs) => fs.readFile(paths.statePath, "utf8")));
+            checks.push({
+                name: "daemon",
+                ok: "warn",
+                detail: `state file found (port ${state.port ?? "?"}, pid ${state.pid ?? "?"}) — verify with: mlola browser daemon status`,
+            });
+        }
+        catch {
+            checks.push({ name: "daemon", ok: "warn", detail: "state file exists but could not be read" });
+        }
+    }
+    else {
+        checks.push({
+            name: "daemon",
+            ok: "warn",
+            detail: "not running (optional; needed for background runs and extension sessions)",
+            fix: "mlola browser daemon start",
+        });
+    }
+    if (json) {
+        out(JSON.stringify({ checks }, null, 2));
+    }
+    else {
+        heading("mlola browser doctor");
+        for (const check of checks) {
+            const mark = check.ok === true ? c.green("✔") : check.ok === "warn" ? c.yellow("!") : c.red("✖");
+            out(`${mark} ${c.bold(check.name.padEnd(20))} ${check.detail}`);
+            if (check.fix && check.ok !== true)
+                out(`  ${c.dim(`fix: ${check.fix}`)}`);
+        }
+        out("");
+        const blocking = checks.filter((check) => check.ok === false);
+        kv("result", blocking.length === 0 ? c.green("ready") : c.red(`${blocking.length} blocking issue(s)`));
+        out("");
+    }
+    return checks.some((check) => check.ok === false) ? 1 : 0;
+};
+//# sourceMappingURL=doctor.js.map

package/dist/commands/doctor.js.map

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

package/dist/commands/eval.d.ts

@@ -0,0 +1,6 @@
+/**
+ * `mlola browser eval` — deterministic eval suites (PRD §49, §50).
+ */
+import { type ParsedArgs } from "../args.ts";
+export declare const evalCommand: (args: ParsedArgs) => Promise<number>;
+//# sourceMappingURL=eval.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"eval.d.ts","sourceRoot":"","sources":["../../src/commands/eval.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAwB,KAAK,UAAU,EAAE,MAAM,YAAY,CAAC;AAGnE,eAAO,MAAM,WAAW,GAAU,MAAM,UAAU,KAAG,OAAO,CAAC,MAAM,CAsDlE,CAAC"}

package/dist/commands/eval.js

@@ -0,0 +1,51 @@
+/**
+ * `mlola browser eval` — deterministic eval suites (PRD §49, §50).
+ */
+import { flagBool, flagString } from "../args.js";
+import { c, heading, kv, out } from "../ui.js";
+export const evalCommand = async (args) => {
+    const suite = (flagString(args.flags, "suite") ?? args.positional[0] ?? "core");
+    const filter = flagString(args.flags, "filter");
+    const provider = (flagString(args.flags, "provider") ?? "scripted");
+    const json = flagBool(args.flags, "json");
+    const headless = flagBool(args.flags, "headless") || true;
+    const { runSuites } = await import("@mlola/browser-evals");
+    if (!json) {
+        heading(`mlola browser eval  ${c.dim(`${suite} · ${provider}`)}`);
+        kv("provider", provider === "typesafe" ? "TypeSafe Jev (live)" : `${provider} (offline, deterministic)`);
+        if (filter)
+            kv("filter", filter);
+        out("");
+    }
+    const report = await runSuites({
+        suite,
+        ...(filter ? { filter } : {}),
+        provider,
+        headless,
+        onProgress: json ? undefined : (line) => out(`  ${line}`),
+    });
+    if (json) {
+        out(JSON.stringify(report, null, 2));
+    }
+    else {
+        out("");
+        const mark = report.failed === 0 ? c.green("PASS") : c.red("FAIL");
+        kv("result", `${mark}  ${report.passed} passed, ${report.failed} failed, ${report.blocked} blocked, ${report.unverified} unverified (${report.cases.length} cases)`);
+        kv("duration", `${(report.durationMs / 1000).toFixed(1)}s`);
+        if (report.failed > 0) {
+            out("");
+            out(c.red("  failures"));
+            for (const failure of report.cases.filter((x) => x.status === "failed")) {
+                out(`    ${failure.name}: ${failure.detail}`);
+            }
+        }
+        if (report.fastPathShare !== undefined) {
+            kv("fast path", `${Math.round(report.fastPathShare * 100)}% of steps`);
+        }
+        for (const line of report.notes ?? [])
+            out(c.dim(`  note: ${line}`));
+        out("");
+    }
+    return report.failed === 0 ? 0 : 1;
+};
+//# sourceMappingURL=eval.js.map

package/dist/commands/eval.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"eval.js","sourceRoot":"","sources":["../../src/commands/eval.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,QAAQ,EAAE,UAAU,EAAmB,MAAM,YAAY,CAAC;AACnE,OAAO,EAAE,CAAC,EAAE,OAAO,EAAE,EAAE,EAAE,GAAG,EAAE,MAAM,UAAU,CAAC;AAE/C,MAAM,CAAC,MAAM,WAAW,GAAG,KAAK,EAAE,IAAgB,EAAmB,EAAE;IACrE,MAAM,KAAK,GAAG,CAAC,UAAU,CAAC,IAAI,CAAC,KAAK,EAAE,OAAO,CAAC,IAAI,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,IAAI,MAAM,CAMrE,CAAC;IACV,MAAM,MAAM,GAAG,UAAU,CAAC,IAAI,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;IAChD,MAAM,QAAQ,GAAG,CAAC,UAAU,CAAC,IAAI,CAAC,KAAK,EAAE,UAAU,CAAC,IAAI,UAAU,CAAwC,CAAC;IAC3G,MAAM,IAAI,GAAG,QAAQ,CAAC,IAAI,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;IAC1C,MAAM,QAAQ,GAAG,QAAQ,CAAC,IAAI,CAAC,KAAK,EAAE,UAAU,CAAC,IAAI,IAAI,CAAC;IAE1D,MAAM,EAAE,SAAS,EAAE,GAAG,MAAM,MAAM,CAAC,sBAAsB,CAAC,CAAC;IAC3D,IAAI,CAAC,IAAI,EAAE,CAAC;QACV,OAAO,CAAC,uBAAuB,CAAC,CAAC,GAAG,CAAC,GAAG,KAAK,MAAM,QAAQ,EAAE,CAAC,EAAE,CAAC,CAAC;QAClE,EAAE,CAAC,UAAU,EAAE,QAAQ,KAAK,UAAU,CAAC,CAAC,CAAC,qBAAqB,CAAC,CAAC,CAAC,GAAG,QAAQ,2BAA2B,CAAC,CAAC;QACzG,IAAI,MAAM;YAAE,EAAE,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;QACjC,GAAG,CAAC,EAAE,CAAC,CAAC;IACV,CAAC;IAED,MAAM,MAAM,GAAG,MAAM,SAAS,CAAC;QAC7B,KAAK;QACL,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC7B,QAAQ;QACR,QAAQ;QACR,UAAU,EAAE,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,GAAG,CAAC,KAAK,IAAI,EAAE,CAAC;KAC1D,CAAC,CAAC;IAEH,IAAI,IAAI,EAAE,CAAC;QACT,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;IACvC,CAAC;SAAM,CAAC;QACN,GAAG,CAAC,EAAE,CAAC,CAAC;QACR,MAAM,IAAI,GAAG,MAAM,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;QACnE,EAAE,CACA,QAAQ,EACR,GAAG,IAAI,KAAK,MAAM,CAAC,MAAM,YAAY,MAAM,CAAC,MAAM,YAAY,MAAM,CAAC,OAAO,aAAa,MAAM,CAAC,UAAU,gBAAgB,MAAM,CAAC,KAAK,CAAC,MAAM,SAAS,CACvJ,CAAC;QACF,EAAE,CAAC,UAAU,EAAE,GAAG,CAAC,MAAM,CAAC,UAAU,GAAG,IAAI,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;QAC5D,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACtB,GAAG,CAAC,EAAE,CAAC,CAAC;YACR,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC,CAAC;YACzB,KAAK,MAAM,OAAO,IAAI,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,KAAK,QAAQ,CAAC,EAAE,CAAC;gBACxE,GAAG,CAAC,OAAO,OAAO,CAAC,IAAI,KAAK,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;YAChD,CAAC;QACH,CAAC;QACD,IAAI,MAAM,CAAC,aAAa,KAAK,SAAS,EAAE,CAAC;YACvC,EAAE,CAAC,WAAW,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,aAAa,GAAG,GAAG,CAAC,YAAY,CAAC,CAAC;QACzE,CAAC;QACD,KAAK,MAAM,IAAI,IAAI,MAAM,CAAC,KAAK,IAAI,EAAE;YAAE,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,WAAW,IAAI,EAAE,CAAC,CAAC,CAAC;QACrE,GAAG,CAAC,EAAE,CAAC,CAAC;IACV,CAAC;IAED,OAAO,MAAM,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AACrC,CAAC,CAAC"}

package/dist/commands/inspect.d.ts

@@ -0,0 +1,9 @@
+/**
+ * `mlola browser trace` / `mlola browser sessions` — inspect local runs.
+ *
+ * The event log is the source of truth: these commands only read it.
+ */
+import { type ParsedArgs } from "../args.ts";
+export declare const sessionsCommand: (args: ParsedArgs) => Promise<number>;
+export declare const traceCommand: (args: ParsedArgs) => Promise<number>;
+//# sourceMappingURL=inspect.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"inspect.d.ts","sourceRoot":"","sources":["../../src/commands/inspect.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAoC,KAAK,UAAU,EAAE,MAAM,YAAY,CAAC;AAY/E,eAAO,MAAM,eAAe,GAAU,MAAM,UAAU,KAAG,OAAO,CAAC,MAAM,CAoEtE,CAAC;AAEF,eAAO,MAAM,YAAY,GAAU,MAAM,UAAU,KAAG,OAAO,CAAC,MAAM,CAqCnE,CAAC"}

package/dist/commands/inspect.js

@@ -0,0 +1,178 @@
+/**
+ * `mlola browser trace` / `mlola browser sessions` — inspect local runs.
+ *
+ * The event log is the source of truth: these commands only read it.
+ */
+import { flagBool, flagNumber, flagString } from "../args.js";
+import { c, formatAge, formatDuration, heading, kv, out, table } from "../ui.js";
+import { computeMetrics, listRuns, readRunEvents, readRunMeta, readRunSummary, resolveHome, } from "@mlola/browser-trace";
+export const sessionsCommand = async (args) => {
+    const sub = args.positional[0] ?? "list";
+    const json = flagBool(args.flags, "json");
+    if (sub === "list" || sub === "ls") {
+        const runs = listRuns(resolveHome(), flagNumber(args.flags, "limit") ?? 25);
+        if (json) {
+            out(JSON.stringify(runs, null, 2));
+            return 0;
+        }
+        heading("recent runs");
+        if (runs.length === 0) {
+            out(c.dim("  (no runs yet)"));
+            out("");
+            return 0;
+        }
+        table(runs.map((run) => [
+            run.runId,
+            statusColor(run.status),
+            String(run.steps ?? "?"),
+            formatAge(run.modifiedAt),
+            truncate(run.goal, 60),
+        ]), ["run", "status", "steps", "when", "goal"]);
+        out("");
+        return 0;
+    }
+    const runId = args.positional[1] ?? flagString(args.flags, "run");
+    if (!runId) {
+        out("usage: mlola browser sessions show <runId>");
+        return 2;
+    }
+    const meta = readRunMeta(runId, resolveHome());
+    const summary = readRunSummary(runId, resolveHome());
+    const events = readRunEvents(runId, resolveHome());
+    const metrics = computeMetrics(events);
+    if (json) {
+        out(JSON.stringify({ meta, summary, metrics }, null, 2));
+        return 0;
+    }
+    heading(`run ${runId}`);
+    if (meta) {
+        kv("goal", meta.goal);
+        kv("backend", meta.backend);
+        kv("started", new Date(meta.startedAt).toISOString());
+    }
+    if (summary) {
+        kv("status", statusColor(summary.status));
+        kv("reason", summary.reason);
+        kv("steps", `${summary.steps} in ${formatDuration(summary.durationMs)}`);
+        if (summary.artifacts.length > 0) {
+            kv("artifacts", summary.artifacts.map((a) => `${a.id}:${a.name}`).join(", "));
+        }
+        if (summary.verification) {
+            kv("verification", `${summary.verification.status} — ${summary.verification.evidence[0]?.detail ?? ""}`);
+        }
+    }
+    out("");
+    out(c.bold("  metrics"));
+    for (const line of formatMetricsLines(metrics))
+        out(`    ${line}`);
+    out("");
+    return 0;
+};
+export const traceCommand = async (args) => {
+    const sub = args.positional[0] ?? "show";
+    const runId = args.positional[1] ?? flagString(args.flags, "run") ?? latestRunId();
+    if (!runId) {
+        out("usage: mlola browser trace show <runId> [--type EVENT] [--limit N]");
+        return 2;
+    }
+    const events = readRunEvents(runId, resolveHome());
+    if (events.length === 0) {
+        out(c.dim(`no events found for run ${runId}`));
+        return 1;
+    }
+    if (sub === "show" || sub === "list") {
+        const typeFilter = flagString(args.flags, "type");
+        const limit = flagNumber(args.flags, "limit") ?? 40;
+        const json = flagBool(args.flags, "json");
+        const filtered = (typeFilter ? events.filter((e) => e.type.includes(typeFilter.toUpperCase())) : events).slice(-limit);
+        if (json) {
+            out(JSON.stringify(filtered, null, 2));
+            return 0;
+        }
+        heading(`trace ${runId}`);
+        for (const event of filtered)
+            out(formatEvent(event));
+        out("");
+        return 0;
+    }
+    if (sub === "summary") {
+        const metrics = computeMetrics(events);
+        out(JSON.stringify({ runId, metrics }, null, 2));
+        return 0;
+    }
+    out(`unknown trace subcommand: ${sub}`);
+    return 2;
+};
+const formatEvent = (event) => {
+    const when = new Date(event.ts).toISOString().slice(11, 23);
+    const seq = String(event.seq).padStart(4, " ");
+    const detail = describeEvent(event);
+    const type = event.type.padEnd(22);
+    return `${c.dim(`${seq} ${when}`)} ${typeColor(event.type, type)} ${detail}`;
+};
+const describeEvent = (event) => {
+    switch (event.type) {
+        case "RUN_CREATED":
+            return `goal: ${event.payload.goal}`;
+        case "SNAPSHOT_CAPTURED":
+            return `${event.payload.nodeCount} nodes · ${Math.round(event.payload.latencyMs)}ms · ${truncate(event.payload.url, 60)}`;
+        case "DECISION_RECEIVED":
+            return `${event.payload.decision.operation}${event.payload.decision.target ? ` → ${event.payload.decision.target}` : ""} conf=${event.payload.decision.operationConfidence.toFixed(2)} ${Math.round(event.payload.decision.latencyMs)}ms`;
+        case "DECISION_INVALID":
+            return truncate(event.payload.reason, 100);
+        case "ACTION_EXECUTED":
+            return `${event.payload.action} ${Math.round(event.payload.latencyMs)}ms${event.payload.detail ? ` — ${truncate(event.payload.detail, 60)}` : ""}`;
+        case "ACTION_FAILED":
+            return `${event.payload.action}: ${event.payload.failure.code} ${truncate(event.payload.failure.message, 60)}`;
+        case "POLICY_ALLOWED":
+        case "POLICY_DENIED":
+            return `${event.payload.outcome.mode} (${event.payload.outcome.risk}) ${truncate(event.payload.summary, 60)}`;
+        case "RECOVERY_STARTED":
+            return `${event.payload.strategy} for ${event.payload.failure.code}`;
+        case "VERIFICATION_RESULT":
+            return `${event.payload.verification.status}: ${truncate(event.payload.verification.evidence[0]?.detail ?? "", 80)}`;
+        case "DOWNLOAD_COMPLETED":
+            return `${event.payload.artifact.name} (${event.payload.artifact.documentType ?? event.payload.artifact.mimeType})`;
+        case "UPLOAD_COMPLETED":
+            return `${event.payload.artifactId}: ${truncate(event.payload.evidence, 60)}`;
+        case "RUN_COMPLETED":
+            return c.green("completed");
+        case "RUN_FAILED":
+            return c.red(`${event.payload.failure.code}: ${truncate(event.payload.failure.message, 60)}`);
+        case "NOTE":
+            return truncate(event.payload.text, 90);
+        default:
+            return "";
+    }
+};
+const typeColor = (type, text) => {
+    if (type.startsWith("RUN_FAILED") || type.includes("FAILED") || type.includes("DENIED"))
+        return c.red(text);
+    if (type.includes("RECOVERY") || type.includes("WARNING") || type.includes("LOOP"))
+        return c.yellow(text);
+    if (type.includes("COMPLETED") || type.includes("VERIFIED"))
+        return c.green(text);
+    if (type.includes("DECISION"))
+        return c.cyan(text);
+    return text;
+};
+const statusColor = (status) => {
+    if (status === "completed")
+        return c.green(status);
+    if (status === "failed")
+        return c.red(status);
+    if (status === "running")
+        return c.cyan(status);
+    return c.dim(status);
+};
+const formatMetricsLines = (metrics) => [
+    `steps ${metrics.steps} · snapshots ${metrics.snapshots} · decision calls ${metrics.decisionCalls}`,
+    `decision latency p50 ${Math.round(metrics.decisionLatencyMs.p50)}ms p95 ${Math.round(metrics.decisionLatencyMs.p95)}ms`,
+    `snapshot p50 ${Math.round(metrics.snapshotLatencyMs.p50)}ms · action p50 ${Math.round(metrics.browserLatencyMs.p50)}ms`,
+    `fast-path share ${Math.round(metrics.fastPathShare * 100)}% · fallbacks ${metrics.fallbacks}`,
+    `recoveries ${metrics.recoveries} (ok ${metrics.recoveriesSucceeded}) · loops ${metrics.loopDetections} · policy denials ${metrics.policyDenials}`,
+    `artifacts ${metrics.artifacts} · downloads ${metrics.downloads} · uploads ${metrics.uploads} · cost $${metrics.costUsd.toFixed(4)}`,
+];
+const latestRunId = () => listRuns(resolveHome(), 1)[0]?.runId;
+const truncate = (s, n) => (s.length <= n ? s : `${s.slice(0, n - 1)}…`);
+//# sourceMappingURL=inspect.js.map