browse 0.8.4-alpha-3ecf09e → 0.8.4-alpha-4ee8d99

package/dist/hooks/command-not-found.js

@@ -0,0 +1,45 @@
+import { Errors } from "@oclif/core";
+import { suggestCommand } from "../lib/command-suggestions.js";
+import { captureCommandNotFound } from "../lib/telemetry.js";
+function toSpaced(commandId) {
+    return commandId.replaceAll(":", " ");
+}
+const hook = async function ({ config, id }) {
+    let attempted = "";
+    let suggestion = null;
+    try {
+        const commandIds = config.commands
+            .filter((command) => !command.hidden)
+            .map((command) => command.id);
+        const result = suggestCommand(id, commandIds);
+        attempted = result.attempted;
+        suggestion = result.suggestion;
+        if (suggestion &&
+            !config.findCommand(suggestion) &&
+            !config.findTopic(suggestion)) {
+            // Guards against alias targets drifting out of the command tree.
+            suggestion = null;
+        }
+        const displayAttempted = toSpaced(attempted || (id.split(":")[0] ?? id));
+        const didYouMean = suggestion
+            ? ` Did you mean "${config.bin} ${toSpaced(suggestion)}"?`
+            : "";
+        process.stderr.write(`"${config.bin} ${displayAttempted}" is not a ${config.bin} command.${didYouMean} Run ${config.bin} --help for all commands.\n`);
+    }
+    catch {
+        // Suggestions are best-effort and must never mask the not-found error.
+    }
+    try {
+        // Awaited so the event is delivered before the process exits; the
+        // transport aborts after a short timeout, so this cannot hang the CLI.
+        await captureCommandNotFound(config.version, attempted || null, suggestion);
+    }
+    catch {
+        // Best-effort telemetry should never affect CLI behavior.
+    }
+    // Re-throw oclif's standard not-found error. Returning normally from a
+    // command_not_found hook makes oclif treat the invocation as handled
+    // (exit 0), so this throw preserves the default error and exit code 2.
+    throw new Errors.CLIError(`command ${id} not found`);
+};
+export default hook;

package/dist/lib/command-suggestions.js

@@ -0,0 +1,112 @@
+/**
+ * Suggestion engine for unknown commands.
+ *
+ * oclif's spaced-topic parsing glues unknown leading argv tokens into the
+ * attempted command id (e.g. `browse opne https://example.com` arrives as
+ * `opne:https://example.com`), so the id may contain user-provided values.
+ * Everything here works on a sanitized token prefix and never returns raw
+ * argv content beyond the tokens that matched a known command shape.
+ */
+import { distance } from "fastest-levenshtein";
+/**
+ * Old Commander-era syntax (and common agent guesses) mapped to the current
+ * command tree. Keys and values are colon-separated oclif ids; values may
+ * also be topics (e.g. `cloud:contexts`, which prints topic help).
+ */
+export const aliasSuggestions = new Map([
+    ["sessions", "cloud:sessions:list"],
+    ["sessions:list", "cloud:sessions:list"],
+    ["sessions:create", "cloud:sessions:create"],
+    ["sessions:get", "cloud:sessions:get"],
+    ["projects", "cloud:projects:list"],
+    ["projects:list", "cloud:projects:list"],
+    ["contexts", "cloud:contexts"],
+    ["extensions", "cloud:extensions"],
+    ["search", "cloud:search"],
+    ["fetch", "cloud:fetch"],
+    ["goto", "open"],
+    ["navigate", "open"],
+]);
+const safeTokenPattern = /^[A-Za-z][A-Za-z0-9_-]*$/;
+const maxCommandTokens = 4;
+const maxSuggestionDistance = 5;
+/**
+ * Extracts the leading command-shaped tokens from an attempted id, stopping
+ * at the first token that does not look like a command word (URLs, selectors,
+ * flags, and other argument-like values).
+ */
+export function extractCommandTokens(id) {
+    const tokens = [];
+    for (const token of id.split(":")) {
+        if (tokens.length >= maxCommandTokens || !safeTokenPattern.test(token)) {
+            break;
+        }
+        tokens.push(token.toLowerCase());
+    }
+    return tokens;
+}
+function tokenThreshold(token) {
+    return Math.max(2, Math.floor(token.length / 3));
+}
+/**
+ * Segment-aligned fuzzy distance between a token prefix and a command id.
+ * Only command ids with the same number of segments are considered, and every
+ * token must be within its own edit-distance threshold of the corresponding
+ * segment. This means a trailing token can only ever be retained in the
+ * attempted command when it itself looks like a typo of a real command
+ * segment — free-form user values can never ride along.
+ */
+function prefixDistance(tokens, commandId) {
+    const segments = commandId.split(":");
+    if (segments.length !== tokens.length) {
+        return null;
+    }
+    let total = 0;
+    for (let i = 0; i < tokens.length; i++) {
+        const token = tokens[i] ?? "";
+        const segmentDistance = distance(token, segments[i] ?? "");
+        if (segmentDistance > tokenThreshold(token)) {
+            return null;
+        }
+        total += segmentDistance;
+    }
+    return total > maxSuggestionDistance ? null : total;
+}
+/**
+ * Computes a suggestion for an unknown command id. Explicit aliases win over
+ * fuzzy matches, and longer token prefixes win over shorter ones so that
+ * `auth status` resolves before `auth`. Returns only the matched prefix as
+ * `attempted` (or the first token when nothing matches) so user-provided
+ * values never escape into messaging or telemetry.
+ */
+export function suggestCommand(id, commandIds) {
+    const tokens = extractCommandTokens(id);
+    if (tokens.length === 0) {
+        return { attempted: "", suggestion: null };
+    }
+    for (let length = tokens.length; length >= 1; length--) {
+        const attempted = tokens.slice(0, length).join(":");
+        const alias = aliasSuggestions.get(attempted);
+        if (alias) {
+            return { attempted, suggestion: alias };
+        }
+    }
+    let best;
+    for (let length = tokens.length; length >= 1; length--) {
+        const prefix = tokens.slice(0, length);
+        for (const commandId of commandIds) {
+            const prefixDist = prefixDistance(prefix, commandId);
+            if (prefixDist !== null && (!best || prefixDist < best.distance)) {
+                best = {
+                    attempted: prefix.join(":"),
+                    suggestion: commandId,
+                    distance: prefixDist,
+                };
+            }
+        }
+    }
+    if (best) {
+        return { attempted: best.attempted, suggestion: best.suggestion };
+    }
+    return { attempted: tokens[0] ?? "", suggestion: null };
+}

package/dist/lib/telemetry.js

@@ -52,6 +52,25 @@ export async function captureCommandCompleted(cliVersion, error) {
         completionCapture,
     ]);
 }
+/**
+ * Captures a `cli.command_not_found` event. Privacy: only the sanitized
+ * attempted command id and the computed suggestion are sent — never raw argv,
+ * which can contain URLs, selectors, or secrets.
+ */
+export async function captureCommandNotFound(cliVersion, attemptedCommand, suggestedCommand) {
+    await getCliTelemetry(cliVersion)
+        .capture("cli.command_not_found", {
+        attempted_command: attemptedCommand
+            ? resolveCommandPath(attemptedCommand)
+            : null,
+        suggested_command: suggestedCommand
+            ? resolveCommandPath(suggestedCommand)
+            : null,
+    })
+        .catch(() => {
+        // Best-effort telemetry should never affect CLI behavior.
+    });
+}
 function createCliTelemetry(options) {
     const env = options.env ?? process.env;
     const transport = resolveTransportConfig(env);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "browse",
-  "version": "0.8.4-alpha-3ecf09e",
+  "version": "0.8.4-alpha-4ee8d99",
   "description": "Unified Browserbase CLI for browser automation and cloud APIs.",
   "type": "module",
   "private": false,
@@ -27,7 +27,8 @@
     "hooks": {
       "init": "./dist/hooks/init.js",
       "prerun": "./dist/hooks/prerun.js",
-      "finally": "./dist/hooks/finally.js"
+      "finally": "./dist/hooks/finally.js",
+      "command_not_found": "./dist/hooks/command-not-found.js"
     },
     "topicSeparator": " ",
     "topics": {
@@ -91,6 +92,7 @@
     "archiver": "^7.0.1",
     "deepmerge": "^4.3.1",
     "dotenv": "^16.5.0",
+    "fastest-levenshtein": "^1.0.16",
     "ignore": "^7.0.5",
     "node-html-markdown": "^1.3.0",
     "semver": "^7.7.4",
@@ -112,7 +114,7 @@
     "prettier": "3.5.3",
     "typescript": "^5.8.3",
     "typescript-eslint": "^8.59.3",
-    "vitest": "^4.1.6"
+    "vitest": "^4.1.9"
   },
   "scripts": {
     "build": "node -e \"const fs = require('fs'); fs.rmSync('dist', { recursive: true, force: true }); fs.rmSync('oclif.manifest.json', { force: true })\" && tsc -p tsconfig.json && pnpm manifest",