libretto 0.6.16 → 0.6.18

package/src/cli/cli.ts

@@ -1,16 +1,13 @@
 import { ensureLibrettoSetup } from "./core/context.js";
 import { createCLIApp } from "./router.js";
-import { warnIfInstalledSkillOutOfDate } from "./core/skill-version.js";
+import {
+  readCurrentCliVersion,
+  warnIfInstalledSkillOutOfDate,
+} from "./core/skill-version.js";
 import { loadEnv } from "../shared/env/load-env.js";
 
-function renderUsage(app: ReturnType<typeof createCLIApp>): string {
-  return `${app.renderHelp()}
-
-Options:
-  --session <name>        Use a named session (auto-generated for open/run if omitted)
-
-Docs (agent-friendly): https://libretto.sh/docs
-`;
+function renderVersion(): string {
+  return readCurrentCliVersion();
 }
 
 function printSetupAudit(): void {
@@ -35,10 +32,25 @@ function warnIfPackageManagerExec(): void {
 
 function isRootHelpRequest(rawArgs: readonly string[]): boolean {
   if (rawArgs.length === 0) return true;
-  if (rawArgs[0] === "--help" || rawArgs[0] === "-h") return true;
   return rawArgs[0] === "help" && rawArgs.length === 1;
 }
 
+function isVersionRequest(rawArgs: readonly string[]): boolean {
+  if (rawArgs.length !== 1) return false;
+  return rawArgs[0] === "--version" || rawArgs[0] === "-v";
+}
+
+function hasRootHelp(
+  message: string,
+  app: ReturnType<typeof createCLIApp>,
+): boolean {
+  return message.endsWith(app.renderHelp());
+}
+
+function hasScopedHelp(message: string): boolean {
+  return message.includes("\nUsage: ");
+}
+
 export async function runLibrettoCLI(): Promise<void> {
   const rawArgs = process.argv.slice(2);
   let exitCode = 0;
@@ -48,8 +60,13 @@ export async function runLibrettoCLI(): Promise<void> {
   const app = createCLIApp();
 
   try {
+    if (isVersionRequest(rawArgs)) {
+      console.log(renderVersion());
+      return;
+    }
+
     if (isRootHelpRequest(rawArgs)) {
-      console.log(renderUsage(app));
+      console.log(app.renderHelp());
       printSetupAudit();
       return;
     }
@@ -61,8 +78,16 @@ export async function runLibrettoCLI(): Promise<void> {
   } catch (err) {
     const message = err instanceof Error ? err.message : String(err);
     if (message.startsWith("Unknown command: ")) {
-      console.error(`${message}\n`);
-      console.log(renderUsage(app));
+      if (hasRootHelp(message, app)) {
+        const summary = message.split("\n", 1)[0] ?? message;
+        console.error(`${summary}\n`);
+        console.log(app.renderHelp());
+      } else if (hasScopedHelp(message)) {
+        console.error(message);
+      } else {
+        console.error(`${message}\n`);
+        console.log(app.renderHelp());
+      }
     } else {
       console.error(message);
     }

package/src/cli/commands/browser.ts

@@ -86,7 +86,7 @@ export const openInput = SimpleCLI.input({
       help: "Viewport size as WIDTHxHEIGHT (e.g. 1920x1080)",
     }),
     provider: SimpleCLI.option(z.string().optional(), {
-      help: "Browser provider (local, kernel, browserbase)",
+      help: "Browser provider (local, kernel, browserbase, steel)",
       aliases: ["-p"],
     }),
   },
@@ -101,8 +101,7 @@ export const openInput = SimpleCLI.input({
   );
 
 export const openCommand = SimpleCLI.command({
-  description:
-    "Launch browser and open URL (headed by default). Automatically loads a saved auth profile for the URL's domain if one exists.",
+  description: "Launch browser and open URL",
 })
   .input(openInput)
   .use(withAutoSession())

package/src/cli/commands/execution.ts

@@ -810,7 +810,7 @@ export const runInput = SimpleCLI.input({
       help: "Viewport size as WIDTHxHEIGHT (e.g. 1920x1080)",
     }),
     provider: SimpleCLI.option(z.string().optional(), {
-      help: "Browser provider (local, kernel, browserbase)",
+      help: "Browser provider (local, kernel, browserbase, steel)",
       aliases: ["-p"],
     }),
   },

package/src/cli/commands/search.ts

@@ -0,0 +1,74 @@
+import { z } from "zod";
+import { DaemonClient } from "../core/daemon/ipc.js";
+import { resolveExperiments } from "../core/experiments.js";
+import {
+  formatHtmlForSearch,
+  searchFormattedHtml,
+} from "../../shared/html-search/search-html.js";
+import { pageOption, sessionOption, withRequiredSession } from "./shared.js";
+import { SimpleCLI } from "affordance";
+
+export const searchInput = SimpleCLI.input({
+  positionals: [
+    SimpleCLI.positional("pattern", z.string().optional(), {
+      help: "JavaScript regex pattern to search for in the formatted HTML snapshot",
+    }),
+  ],
+  named: {
+    session: sessionOption(),
+    page: pageOption(),
+  },
+}).refine(
+  (input) => input.pattern !== undefined,
+  "Usage: libretto search <regex> --session <name> [--page <id>]",
+);
+
+export const searchCommand = SimpleCLI.command({
+  description: "Search the current page HTML snapshot",
+})
+  .input(searchInput)
+  .use(withRequiredSession())
+  .handle(async ({ input, ctx }) => {
+    if (!resolveExperiments().search) {
+      throw new Error(
+        [
+          'The "search" experiment is disabled.',
+          "Enable it with: libretto experiments enable search",
+        ].join("\n"),
+      );
+    }
+
+    if (!ctx.sessionState.daemonSocketPath) {
+      throw new Error(
+        `Session "${ctx.session}" has no daemon socket. Close and reopen it with: libretto open <url> --session ${ctx.session}`,
+      );
+    }
+
+    const client = await DaemonClient.connect(ctx.sessionState.daemonSocketPath);
+    try {
+      const response = await client.readonlyExec({
+        code: "return await page.content()",
+        pageId: input.page,
+      });
+      if (!response.ok) {
+        throw new Error(response.message);
+      }
+      if (typeof response.data.result !== "string") {
+        throw new Error("Expected page.content() to return an HTML string.");
+      }
+
+      const formattedHtml = formatHtmlForSearch(response.data.result);
+      const matches = searchFormattedHtml(formattedHtml, input.pattern!);
+      if (matches.length === 0) {
+        console.log(`No matches for /${input.pattern}/.`);
+        return;
+      }
+
+      for (const [index, match] of matches.entries()) {
+        if (index > 0) console.log("--");
+        console.log(match.lines.join("\n"));
+      }
+    } finally {
+      client.destroy();
+    }
+  });

package/src/cli/commands/update.ts

@@ -0,0 +1,149 @@
+import { spawnSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { SimpleCLI } from "affordance";
+
+const UPDATE_COMMAND = "curl -fsSL https://libretto.sh/install.sh | bash";
+
+type PackageManifest = {
+  version?: string;
+};
+
+function readCurrentCliVersion(): string {
+  const packageJsonPath = fileURLToPath(
+    new URL("../../../package.json", import.meta.url),
+  );
+  const manifest = JSON.parse(
+    readFileSync(packageJsonPath, "utf8"),
+  ) as PackageManifest;
+
+  if (!manifest.version) {
+    throw new Error(
+      `Unable to determine current libretto version from ${packageJsonPath}.`,
+    );
+  }
+
+  return manifest.version;
+}
+
+function readLatestNpmVersion(): string {
+  const result = spawnSync("npm", ["view", "libretto@latest", "version"], {
+    encoding: "utf8",
+  });
+
+  if (result.error) {
+    throw new Error(
+      [
+        "Error: failed to check the latest Libretto version on npm.",
+        `Known state: ${result.error.message}`,
+        "Try: npm view libretto@latest version",
+        "Help: libretto help update",
+      ].join("\n"),
+    );
+  }
+
+  if (result.status !== 0) {
+    const detail = result.stderr.trim();
+    throw new Error(
+      [
+        "Error: failed to check the latest Libretto version on npm.",
+        `Known state: npm exited with status ${result.status}.`,
+        ...(detail ? [`npm stderr: ${detail}`] : []),
+        "Try: npm view libretto@latest version",
+        "Help: libretto help update",
+      ].join("\n"),
+    );
+  }
+
+  const version = result.stdout.trim();
+  if (!version) {
+    throw new Error(
+      [
+        "Error: failed to check the latest Libretto version on npm.",
+        "Known state: npm did not print a version.",
+        "Try: npm view libretto@latest version",
+        "Help: libretto help update",
+      ].join("\n"),
+    );
+  }
+
+  return version;
+}
+
+export const updateInput = SimpleCLI.input({
+  positionals: [],
+  named: {
+    dryRun: SimpleCLI.flag({
+      name: "dry-run",
+      help: "Print the update command without running it",
+    }),
+  },
+});
+
+function formatUpdateFailure(
+  status: number | null,
+  signal: string | null,
+): string {
+  const knownState =
+    status === null
+      ? `installer was interrupted${signal ? ` by ${signal}` : ""}.`
+      : `installer exited with status ${status}.`;
+
+  return [
+    "Error: failed to update Libretto to the latest version.",
+    `Known state: ${knownState}`,
+    `Try: ${UPDATE_COMMAND}`,
+    "Help: libretto help update",
+  ].join("\n");
+}
+
+export const updateCommand = SimpleCLI.command({
+  description: "Update Libretto to the latest version",
+})
+  .input(updateInput)
+  .handle(async ({ input }) => {
+    if (input.dryRun) {
+      console.log("Update command:");
+      console.log(`  ${UPDATE_COMMAND}`);
+      console.log("No changes made.");
+      return;
+    }
+
+    const currentVersion = readCurrentCliVersion();
+    const latestVersion = readLatestNpmVersion();
+    console.log(`Current version: ${currentVersion}`);
+    console.log(`Latest version: ${latestVersion}`);
+
+    if (currentVersion === latestVersion) {
+      console.log(`Libretto is already up to date (${currentVersion}).`);
+      console.log("No further action required.");
+      return;
+    }
+
+    console.log("Updating Libretto to latest...");
+    const result = spawnSync("bash", ["-lc", UPDATE_COMMAND], {
+      stdio: "inherit",
+      env: {
+        ...process.env,
+        LIBRETTO_VERSION: "latest",
+      },
+    });
+
+    if (result.error) {
+      throw new Error(
+        [
+          "Error: failed to start the Libretto installer.",
+          `Known state: ${result.error.message}`,
+          `Try: ${UPDATE_COMMAND}`,
+          "Help: libretto help update",
+        ].join("\n"),
+      );
+    }
+
+    if (result.status !== 0) {
+      throw new Error(formatUpdateFailure(result.status, result.signal));
+    }
+
+    console.log("Libretto updated to latest.");
+    console.log("No further action required.");
+  });

package/src/cli/core/context.ts

@@ -34,6 +34,10 @@ export function getSessionNetworkLogPath(session: string): string {
   return join(getSessionDir(session), "network.jsonl");
 }
 
+export function getSessionRawNetworkDir(session: string): string {
+  return join(getSessionDir(session), "raw-network");
+}
+
 export function getSessionActionsLogPath(session: string): string {
   return join(getSessionDir(session), "actions.jsonl");
 }

package/src/cli/core/daemon/daemon.ts

@@ -39,6 +39,7 @@ import {
 import {
   createLoggerForSession,
   getSessionDir,
+  getSessionRawNetworkDir,
   getSessionNetworkLogPath,
   getSessionActionsLogPath,
   getSessionProviderClosePath,
@@ -255,6 +256,7 @@ class BrowserDaemon {
     // Telemetry — may fail on connect-mode reconnections where
     // exposeFunction bindings already exist; log and continue.
     const networkLogFile = getSessionNetworkLogPath(session);
+    const rawNetworkDir = getSessionRawNetworkDir(session);
     const actionsLogFile = getSessionActionsLogPath(session);
     const logger = createLoggerForSession(session);
 
@@ -263,6 +265,7 @@ class BrowserDaemon {
         context,
         initialPage: page,
         includeUserDomActions: true,
+        rawNetworkDir,
         logAction: (entry: TelemetryEntry) => {
           appendFileSync(actionsLogFile, JSON.stringify(entry) + "\n");
         },

package/src/cli/core/experiments.ts

@@ -11,7 +11,21 @@ export type ExperimentMetadata = {
   defaultValue: boolean;
 };
 
-export const EXPERIMENTS: Readonly<Record<string, ExperimentMetadata>> = {};
+export const EXPERIMENTS: Readonly<Record<string, ExperimentMetadata>> = {
+  search: {
+    title: "HTML Search",
+    oneSentenceDescription:
+      "Adds a search command that greps the current page's formatted HTML snapshot.",
+    docs: [
+      "Adds a search command for inspecting the current page's HTML snapshot with a JavaScript regex.",
+      "",
+      "Usage: libretto search <regex> --session <name> [--page <id>]",
+      "",
+      "The command captures page HTML through read-only execution, condenses and formats it, then prints matching regions with up to four lines of surrounding context.",
+    ].join("\n"),
+    defaultValue: false,
+  },
+};
 
 export type ExperimentName = string;
 export type Experiments = Record<ExperimentName, boolean>;

package/src/cli/core/providers/index.ts

@@ -2,12 +2,14 @@ import { readLibrettoConfig } from "../config.js";
 import { createBrowserbaseProvider } from "./browserbase.js";
 import { createKernelProvider } from "./kernel.js";
 import { createLibrettoCloudProvider } from "./libretto-cloud.js";
+import { createSteelProvider } from "./steel.js";
 import type { ProviderApi } from "./types.js";
 
 const VALID_PROVIDERS = new Set([
   "local",
   "kernel",
   "browserbase",
+  "steel",
   "libretto-cloud",
 ] as const);
 export type ProviderName =
@@ -56,12 +58,14 @@ export function getCloudProviderApi(name: string): ProviderApi {
       return createKernelProvider();
     case "browserbase":
       return createBrowserbaseProvider();
+    case "steel":
+      return createSteelProvider();
     case "libretto-cloud":
       console.warn("Note: The libretto-cloud provider is in alpha.");
       return createLibrettoCloudProvider();
     default:
       throw new Error(
-        `Unknown provider "${name}". Valid cloud providers: kernel, browserbase`,
+        `Unknown provider "${name}". Valid cloud providers: kernel, browserbase, steel`,
       );
   }
 }

package/src/cli/core/providers/steel.ts

@@ -0,0 +1,75 @@
+import type { ProviderApi } from "./types.js";
+
+const DEFAULT_STEEL_API_ENDPOINT = "https://api.steel.dev";
+const DEFAULT_STEEL_CONNECT_ENDPOINT = "wss://connect.steel.dev";
+
+type SteelSessionResponse = {
+  id: string;
+  sessionViewerUrl?: string;
+};
+
+export type SteelProviderOptions = {
+  apiKey?: string;
+};
+
+export function createSteelProvider(
+  options: SteelProviderOptions = {},
+): ProviderApi {
+  const apiKey = options.apiKey ?? process.env.STEEL_API_KEY;
+  if (!apiKey) throw new Error("STEEL_API_KEY is required for Steel provider.");
+
+  const endpoint = process.env.STEEL_BASE_URL ?? DEFAULT_STEEL_API_ENDPOINT;
+  const connectEndpoint =
+    process.env.STEEL_CONNECT_URL ?? DEFAULT_STEEL_CONNECT_ENDPOINT;
+
+  return {
+    async createSession() {
+      const resp = await fetch(`${endpoint}/v1/sessions`, {
+        method: "POST",
+        headers: {
+          "steel-api-key": apiKey,
+          "Content-Type": "application/json",
+        },
+        body: JSON.stringify({}),
+      });
+      if (!resp.ok) {
+        const body = await resp.text();
+        throw new Error(`Steel API error (${resp.status}): ${body}`);
+      }
+      const json = (await resp.json()) as SteelSessionResponse;
+      return {
+        sessionId: json.id,
+        cdpEndpoint: buildSteelCdpEndpoint(connectEndpoint, apiKey, json.id),
+        liveViewUrl: json.sessionViewerUrl,
+      };
+    },
+    async closeSession(sessionId) {
+      const resp = await fetch(`${endpoint}/v1/sessions/${sessionId}/release`, {
+        method: "POST",
+        headers: {
+          "steel-api-key": apiKey,
+          "Content-Type": "application/json",
+        },
+        body: JSON.stringify({}),
+      });
+      if (!resp.ok) {
+        const body = await resp.text();
+        throw new Error(
+          `Steel API error closing session ${sessionId} (${resp.status}): ${body}`,
+        );
+      }
+      return {};
+    },
+  };
+}
+
+function buildSteelCdpEndpoint(
+  connectEndpoint: string,
+  apiKey: string,
+  sessionId: string,
+): string {
+  const endpoint = new URL(connectEndpoint);
+  endpoint.searchParams.set("apiKey", apiKey);
+  endpoint.searchParams.set("sessionId", sessionId);
+  return endpoint.toString();
+}