libretto 0.6.16 → 0.6.17

package/dist/cli/cli.js

@@ -1,15 +1,12 @@
 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) {
-  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() {
+  return readCurrentCliVersion();
 }
 function printSetupAudit() {
   warnIfInstalledSkillOutOfDate();
@@ -29,9 +26,18 @@ function warnIfPackageManagerExec() {
 }
 function isRootHelpRequest(rawArgs) {
   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) {
+  if (rawArgs.length !== 1) return false;
+  return rawArgs[0] === "--version" || rawArgs[0] === "-v";
+}
+function hasRootHelp(message, app) {
+  return message.endsWith(app.renderHelp());
+}
+function hasScopedHelp(message) {
+  return message.includes("\nUsage: ");
+}
 async function runLibrettoCLI() {
   const rawArgs = process.argv.slice(2);
   let exitCode = 0;
@@ -40,8 +46,12 @@ async function runLibrettoCLI() {
   ensureLibrettoSetup();
   const app = createCLIApp();
   try {
+    if (isVersionRequest(rawArgs)) {
+      console.log(renderVersion());
+      return;
+    }
     if (isRootHelpRequest(rawArgs)) {
-      console.log(renderUsage(app));
+      console.log(app.renderHelp());
       printSetupAudit();
       return;
     }
@@ -52,9 +62,18 @@ async function runLibrettoCLI() {
   } catch (err) {
     const message = err instanceof Error ? err.message : String(err);
     if (message.startsWith("Unknown command: ")) {
-      console.error(`${message}
+      if (hasRootHelp(message, app)) {
+        const summary = message.split("\n", 1)[0] ?? message;
+        console.error(`${summary}
+`);
+        console.log(app.renderHelp());
+      } else if (hasScopedHelp(message)) {
+        console.error(message);
+      } else {
+        console.error(`${message}
 `);
-      console.log(renderUsage(app));
+        console.log(app.renderHelp());
+      }
     } else {
       console.error(message);
     }

package/dist/cli/commands/browser.js

@@ -74,7 +74,7 @@ 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"]
     })
   }
@@ -86,7 +86,7 @@ const openInput = SimpleCLI.input({
   "Cannot pass both --read-only and --write-access."
 );
 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()).use(withExperiments()).handle(async ({ input, ctx }) => {
   warnIfInstalledSkillOutOfDate();
   assertSessionAvailableForStart(ctx.session, ctx.logger);

package/dist/cli/commands/execution.js

@@ -645,7 +645,7 @@ 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/dist/cli/commands/search.js

@@ -0,0 +1,69 @@
+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";
+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 !== void 0,
+  "Usage: libretto search <regex> --session <name> [--page <id>]"
+);
+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();
+  }
+});
+export {
+  searchCommand,
+  searchInput
+};

package/dist/cli/commands/update.js

@@ -0,0 +1,122 @@
+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";
+function readCurrentCliVersion() {
+  const packageJsonPath = fileURLToPath(
+    new URL("../../../package.json", import.meta.url)
+  );
+  const manifest = JSON.parse(
+    readFileSync(packageJsonPath, "utf8")
+  );
+  if (!manifest.version) {
+    throw new Error(
+      `Unable to determine current libretto version from ${packageJsonPath}.`
+    );
+  }
+  return manifest.version;
+}
+function readLatestNpmVersion() {
+  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;
+}
+const updateInput = SimpleCLI.input({
+  positionals: [],
+  named: {
+    dryRun: SimpleCLI.flag({
+      name: "dry-run",
+      help: "Print the update command without running it"
+    })
+  }
+});
+function formatUpdateFailure(status, signal) {
+  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");
+}
+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.");
+});
+export {
+  updateCommand,
+  updateInput
+};

package/dist/cli/core/context.js

@@ -27,6 +27,9 @@ function getSessionLogsPath(session) {
 function getSessionNetworkLogPath(session) {
   return join(getSessionDir(session), "network.jsonl");
 }
+function getSessionRawNetworkDir(session) {
+  return join(getSessionDir(session), "raw-network");
+}
 function getSessionActionsLogPath(session) {
   return join(getSessionDir(session), "actions.jsonl");
 }
@@ -79,6 +82,7 @@ export {
   getSessionLogsPath,
   getSessionNetworkLogPath,
   getSessionProviderClosePath,
+  getSessionRawNetworkDir,
   getSessionSnapshotRunDir,
   getSessionSnapshotsDir,
   getSessionStatePath,

package/dist/cli/core/daemon/daemon.js

@@ -14,6 +14,7 @@ import {
 import {
   createLoggerForSession,
   getSessionDir,
+  getSessionRawNetworkDir,
   getSessionNetworkLogPath,
   getSessionActionsLogPath,
   getSessionProviderClosePath,
@@ -155,6 +156,7 @@ class BrowserDaemon {
     } = args;
     await mkdir(getSessionDir(session), { recursive: true });
     const networkLogFile = getSessionNetworkLogPath(session);
+    const rawNetworkDir = getSessionRawNetworkDir(session);
     const actionsLogFile = getSessionActionsLogPath(session);
     const logger = createLoggerForSession(session);
     try {
@@ -162,6 +164,7 @@ class BrowserDaemon {
         context,
         initialPage: page,
         includeUserDomActions: true,
+        rawNetworkDir,
         logAction: (entry) => {
           appendFileSync(actionsLogFile, JSON.stringify(entry) + "\n");
         },

package/dist/cli/core/experiments.js

@@ -2,7 +2,20 @@ import {
   readLibrettoConfig,
   writeLibrettoConfig
 } from "./config.js";
-const EXPERIMENTS = {};
+const EXPERIMENTS = {
+  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
+  }
+};
 function isExperimentName(name) {
   return Object.hasOwn(EXPERIMENTS, name);
 }

package/dist/cli/core/providers/index.js

@@ -2,10 +2,12 @@ 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";
 const VALID_PROVIDERS = /* @__PURE__ */ new Set([
   "local",
   "kernel",
   "browserbase",
+  "steel",
   "libretto-cloud"
 ]);
 const DEFAULT_PROVIDER_STARTUP_TIMEOUT_MS = 6e4;
@@ -38,12 +40,14 @@ function getCloudProviderApi(name) {
       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/dist/cli/core/providers/steel.js

@@ -0,0 +1,56 @@
+const DEFAULT_STEEL_API_ENDPOINT = "https://api.steel.dev";
+const DEFAULT_STEEL_CONNECT_ENDPOINT = "wss://connect.steel.dev";
+function createSteelProvider(options = {}) {
+  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();
+      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, apiKey, sessionId) {
+  const endpoint = new URL(connectEndpoint);
+  endpoint.searchParams.set("apiKey", apiKey);
+  endpoint.searchParams.set("sessionId", sessionId);
+  return endpoint.toString();
+}
+export {
+  createSteelProvider
+};

package/dist/cli/core/session-telemetry.js

@@ -1,3 +1,6 @@
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { gzipSync } from "node:zlib";
 import {
   filterSemanticClasses,
   INTERACTIVE_ROLE_NAMES,
@@ -6,13 +9,42 @@ import {
   TEST_ATTRIBUTE_NAMES,
   TRUSTED_ATTRIBUTE_NAMES
 } from "../../shared/dom-semantics.js";
+const BODY_PREVIEW_CHARS = 4096;
+const MAX_SAVED_BODY_BYTES = 10 * 1024 * 1024;
+const LOG_RESOURCE_TYPES = /* @__PURE__ */ new Set(["document", "xhr", "fetch"]);
+const SKIP_RESOURCE_TYPES = /* @__PURE__ */ new Set(["image", "font", "media", "stylesheet"]);
+const NOISE_URL_RE = /(google-analytics|googletagmanager|googleadservices|googlesyndication|doubleclick|facebook\.com\/tr|pinterest|criteo|snapchat|2mdn\.net|adtrafficquality|safeframe|recaptcha|analytics|beacon|pixel|\/ads?\/|\/collect|\/event|\/pagead\/|\/gmp\/conversion|\/ccm\/|\/rmkt\/|favicon|\.map(?:\?|$))/i;
+const TEXT_CONTENT_TYPE_RE = /json|html|text|xml|graphql|javascript|x-www-form-urlencoded/i;
+function shouldLogNetworkEntry(method, url, resourceType) {
+  if (url.startsWith("chrome-extension://")) return false;
+  if (NOISE_URL_RE.test(url)) return false;
+  if (resourceType === "ping") return false;
+  if (LOG_RESOURCE_TYPES.has(resourceType)) return true;
+  if (["POST", "PUT", "PATCH", "DELETE"].includes(method)) return true;
+  if (SKIP_RESOURCE_TYPES.has(resourceType)) return false;
+  return false;
+}
+function isTextLikeContentType(contentType) {
+  return contentType !== null && TEXT_CONTENT_TYPE_RE.test(contentType);
+}
+function bodyPreview(value) {
+  return value.slice(0, BODY_PREVIEW_CHARS);
+}
+function saveBodySidecar(rawNetworkDir, id, kind, contentType, body) {
+  if (!rawNetworkDir) return null;
+  mkdirSync(rawNetworkDir, { recursive: true });
+  const ext = contentType?.includes("json") ? "json" : contentType?.includes("html") ? "html" : "txt";
+  const filename = `${String(id).padStart(6, "0")}.${kind}.${ext}.gz`;
+  writeFileSync(join(rawNetworkDir, filename), gzipSync(body));
+  return `raw-network/${filename}`;
+}
 async function installSessionTelemetry(options) {
-  const STATIC_EXT_RE = /\.(css|js|png|jpg|jpeg|gif|woff|woff2|ttf|ico|svg)(\?|$)/i;
-  const { context, initialPage, logAction, logNetwork } = options;
+  const { context, initialPage, logAction, logNetwork, rawNetworkDir } = options;
   const includeUserDomActions = options.includeUserDomActions ?? false;
   const pageIdCache = /* @__PURE__ */ new WeakMap();
   const wrappedPages = /* @__PURE__ */ new WeakSet();
   const exposedPages = /* @__PURE__ */ new WeakSet();
+  let networkId = 0;
   const resolvePageId = async (page) => {
     if (pageIdCache.has(page)) return pageIdCache.get(page);
     const cdpSession = await context.newCDPSession(page);
@@ -698,15 +730,119 @@ async function installSessionTelemetry(options) {
     page.on("response", async (response) => {
       const request = response.request();
       const url = request.url();
-      if (STATIC_EXT_RE.test(url) || url.startsWith("chrome-extension://"))
-        return;
+      const method = request.method();
+      const resourceType = request.resourceType();
+      if (!shouldLogNetworkEntry(method, url, resourceType)) return;
+      const id = ++networkId;
+      const requestHeaders = request.headers();
+      const responseHeaders = response.headers();
+      const contentType = responseHeaders["content-type"] ?? null;
+      const requestContentType = requestHeaders["content-type"] ?? null;
+      const requestBody = request.postData();
+      const requestBodyBytes = requestBody === null ? null : Buffer.byteLength(requestBody);
+      let requestBodyPath = null;
+      let requestBodyOmittedReason = null;
+      let responseBodyPreview = null;
+      let responseBodyPath = null;
+      let responseBodyBytes = null;
+      let responseBodyTruncated = false;
+      let responseBodyOmittedReason = null;
+      let errorText = null;
+      if (requestBody === null) {
+        requestBodyOmittedReason = "no-request-body";
+      } else if (!isTextLikeContentType(requestContentType)) {
+        requestBodyOmittedReason = "binary-content-type";
+      } else if (requestBodyBytes !== null && requestBodyBytes > MAX_SAVED_BODY_BYTES) {
+        requestBodyOmittedReason = "body-too-large";
+      } else {
+        requestBodyPath = saveBodySidecar(
+          rawNetworkDir,
+          id,
+          "request",
+          requestContentType,
+          requestBody
+        );
+      }
+      if (!isTextLikeContentType(contentType) || !LOG_RESOURCE_TYPES.has(resourceType)) {
+        responseBodyOmittedReason = "binary-content-type";
+      } else {
+        try {
+          const responseBody = await response.text();
+          responseBodyBytes = Buffer.byteLength(responseBody);
+          responseBodyPreview = bodyPreview(responseBody);
+          if (responseBodyBytes > MAX_SAVED_BODY_BYTES) {
+            responseBodyTruncated = true;
+            responseBodyOmittedReason = "body-too-large";
+          } else {
+            responseBodyPath = saveBodySidecar(
+              rawNetworkDir,
+              id,
+              "response",
+              contentType,
+              responseBody
+            );
+          }
+        } catch (error) {
+          responseBodyOmittedReason = "read-error";
+          errorText = error?.message ?? String(error);
+        }
+      }
       emitNetwork({
+        id,
         pageId,
-        method: request.method(),
+        method,
         url,
+        resourceType,
         status: response.status(),
-        contentType: response.headers()["content-type"] ?? null,
-        postData: request.method() === "POST" || request.method() === "PUT" || request.method() === "PATCH" ? (request.postData() ?? "").substring(0, 2e3) : void 0,
+        statusText: response.statusText(),
+        contentType,
+        requestHeaders,
+        responseHeaders,
+        requestBodyPreview: requestBody ? bodyPreview(requestBody) : null,
+        requestBodyPath,
+        requestBodyBytes,
+        requestBodyTruncated: requestBody !== null && requestBodyBytes !== null && requestBodyBytes > MAX_SAVED_BODY_BYTES,
+        requestBodyOmittedReason,
+        responseBodyPreview,
+        responseBodyPath,
+        responseBodyBytes,
+        responseBodyTruncated,
+        responseBodyOmittedReason,
+        errorText,
+        postData: requestBody ? bodyPreview(requestBody) : void 0,
+        responseBody: null,
+        size: null,
+        durationMs: null
+      });
+    });
+    page.on("requestfailed", async (request) => {
+      const url = request.url();
+      const method = request.method();
+      const resourceType = request.resourceType();
+      if (!shouldLogNetworkEntry(method, url, resourceType)) return;
+      const id = ++networkId;
+      emitNetwork({
+        id,
+        pageId,
+        method,
+        url,
+        resourceType,
+        status: null,
+        statusText: null,
+        contentType: null,
+        requestHeaders: request.headers(),
+        responseHeaders: null,
+        requestBodyPreview: null,
+        requestBodyPath: null,
+        requestBodyBytes: null,
+        requestBodyTruncated: false,
+        requestBodyOmittedReason: null,
+        responseBodyPreview: null,
+        responseBodyPath: null,
+        responseBodyBytes: null,
+        responseBodyTruncated: false,
+        responseBodyOmittedReason: "request-failed",
+        errorText: request.failure()?.errorText ?? null,
         responseBody: null,
         size: null,
         durationMs: null

package/dist/cli/core/skill-version.js

@@ -69,5 +69,6 @@ function warnIfInstalledSkillOutOfDate() {
   }
 }
 export {
+  readCurrentCliVersion,
   warnIfInstalledSkillOutOfDate
 };

package/dist/cli/router.js

@@ -7,11 +7,13 @@ import { experimentsCommand } from "./commands/experiments.js";
 import { setupCommand } from "./commands/setup.js";
 import { statusCommand } from "./commands/status.js";
 import { snapshotCommand } from "./commands/snapshot.js";
+import { searchCommand } from "./commands/search.js";
+import { updateCommand } from "./commands/update.js";
 import { SimpleCLI } from "affordance";
 const cliRoutes = {
   ...browserCommands,
   cloud: SimpleCLI.group({
-    description: "Libretto Cloud commands",
+    description: "Deploy workflows and manage hosted Libretto",
     routes: {
       deploy: deployCommand,
       auth: authCommands,
@@ -20,12 +22,21 @@ const cliRoutes = {
   }),
   experiments: experimentsCommand,
   ...executionCommands,
+  search: searchCommand,
   setup: setupCommand,
   status: statusCommand,
-  snapshot: snapshotCommand
+  snapshot: snapshotCommand,
+  update: updateCommand
 };
 function createCLIApp() {
-  return SimpleCLI.define("libretto", cliRoutes);
+  return SimpleCLI.define("libretto", cliRoutes, {
+    appendHelpText: [
+      "Options:",
+      "  --session <name>  Required for session-scoped commands",
+      "  -h, --help",
+      "  -v, --version"
+    ].join("\n")
+  });
 }
 export {
   cliRoutes,

package/dist/shared/html-search/search-html.d.ts

@@ -0,0 +1,9 @@
+type SearchHtmlMatch = {
+    startLine: number;
+    endLine: number;
+    lines: string[];
+};
+declare function formatHtmlForSearch(html: string): string;
+declare function searchFormattedHtml(formattedHtml: string, pattern: string, contextLines?: number, matchLimit?: number): SearchHtmlMatch[];
+
+export { type SearchHtmlMatch, formatHtmlForSearch, searchFormattedHtml };