[STG-1692] feat: resolve context labels in browse --context-id

.changeset/warm-contexts-shine.md

@@ -0,0 +1,5 @@
+---
+"@browserbasehq/browse-cli": patch
+---
+
+Add context label resolution for --context-id flag

packages/cli/src/index.ts

@@ -168,6 +168,10 @@ function getLocalInfoPath(session: string): string {
   return path.join(SOCKET_DIR, `browse-${session}.local-info`);
 }
 
+// ==================== CONTEXT LABEL RESOLUTION ====================
+
+import { resolveContextLabel } from "./resolve-context";
+
 // ==================== LOCAL STRATEGY CONFIG ====================
 
 type LocalStrategy = "auto" | "isolated" | "cdp";
@@ -2163,8 +2167,14 @@ program
           process.exit(1);
         }
 
+        // Resolve named labels (e.g. "latest", "work") to actual context IDs
+        const resolvedContextId = await resolveContextLabel(cmdOpts.contextId);
+        if (resolvedContextId !== cmdOpts.contextId) {
+          console.error(`Resolved context "${cmdOpts.contextId}" → ${resolvedContextId}`);
+        }
+
         const newConfig = JSON.stringify({
-          id: cmdOpts.contextId,
+          id: resolvedContextId,
           persist: cmdOpts.persist ?? false,
         });
 

packages/cli/src/resolve-context.ts

@@ -0,0 +1,33 @@
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import * as os from "node:os";
+
+/**
+ * Resolve a --context-id value that may be a named label.
+ *
+ * Label files live at:
+ *   <configDir>/contexts/<label>  →  raw UUID
+ *
+ * The base path respects BROWSERBASE_CONFIG_DIR env var.
+ */
+export async function resolveContextLabel(value: string): Promise<string> {
+  // Raw UUIDs and ctx_ prefixes pass through
+  if (/^[0-9a-f-]{36}$/i.test(value) || value.startsWith("ctx_")) {
+    return value;
+  }
+  // Look up as a label file
+  const configDir =
+    process.env.BROWSERBASE_CONFIG_DIR ||
+    path.join(os.homedir(), ".config", "browserbase");
+  const labelPath = path.join(configDir, "contexts", value);
+  try {
+    const id = (await fs.readFile(labelPath, "utf-8")).trim();
+    if (id) {
+      return id;
+    }
+  } catch {
+    // Label file doesn't exist – fall through
+  }
+  // Return as-is (might be a raw ID in a format we don't recognize)
+  return value;
+}

packages/cli/tests/resolve-context.test.ts

@@ -0,0 +1,63 @@
+import { describe, it, expect, beforeAll, afterAll } from "vitest";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as os from "node:os";
+import { resolveContextLabel } from "../src/resolve-context";
+
+let tmpDir: string;
+let contextsDir: string;
+const originalEnv = process.env.BROWSERBASE_CONFIG_DIR;
+
+beforeAll(() => {
+  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "browse-ctx-test-"));
+  contextsDir = path.join(tmpDir, "contexts");
+  fs.mkdirSync(contextsDir, { recursive: true });
+  process.env.BROWSERBASE_CONFIG_DIR = tmpDir;
+
+  // Write test label files
+  fs.writeFileSync(
+    path.join(contextsDir, "latest"),
+    "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
+  );
+  fs.writeFileSync(
+    path.join(contextsDir, "work"),
+    "11111111-2222-3333-4444-555555555555\n",
+  );
+  fs.writeFileSync(path.join(contextsDir, "empty"), "");
+});
+
+afterAll(() => {
+  process.env.BROWSERBASE_CONFIG_DIR = originalEnv;
+  fs.rmSync(tmpDir, { recursive: true, force: true });
+});
+
+describe("resolveContextLabel", () => {
+  it("passes through raw UUIDs unchanged", async () => {
+    const uuid = "a1b2c3d4-e5f6-7890-abcd-ef1234567890";
+    expect(await resolveContextLabel(uuid)).toBe(uuid);
+  });
+
+  it("passes through ctx_ prefixed IDs unchanged", async () => {
+    expect(await resolveContextLabel("ctx_abc123")).toBe("ctx_abc123");
+  });
+
+  it("resolves a label to its context ID", async () => {
+    expect(await resolveContextLabel("latest")).toBe(
+      "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
+    );
+  });
+
+  it("trims whitespace from label file contents", async () => {
+    expect(await resolveContextLabel("work")).toBe(
+      "11111111-2222-3333-4444-555555555555",
+    );
+  });
+
+  it("returns the value as-is when label file does not exist", async () => {
+    expect(await resolveContextLabel("nonexistent")).toBe("nonexistent");
+  });
+
+  it("returns the value as-is when label file is empty", async () => {
+    expect(await resolveContextLabel("empty")).toBe("empty");
+  });
+});