@flrande/browserctl 0.1.0-dev.7.1

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@flrande/browserctl",
+  "version": "0.1.0-dev.7.1",
+  "private": false,
+  "bin": {
+    "browserctl": "bin/browserctl.cjs",
+    "browserd": "bin/browserd.cjs"
+  },
+  "files": [
+    "apps/browserctl/src",
+    "apps/browserd/src",
+    "packages/core/src",
+    "packages/driver-chrome-relay/src",
+    "packages/driver-managed/src",
+    "packages/driver-remote-cdp/src",
+    "packages/protocol/src",
+    "packages/transport-mcp-stdio/src",
+    "extensions/chrome-relay",
+    "scripts/smoke.ps1",
+    "bin",
+    "README.md",
+    "README-CN.md",
+    "LICENSE",
+    "!**/*.test.ts",
+    "!**/vitest.config.ts",
+    "!**/node_modules/**",
+    "!**/.vite/**"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.17.4",
+    "playwright-core": "^1.52.0",
+    "tsx": "^4.21.0",
+    "ws": "^8.19.0",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@types/node": "^22.15.30",
+    "typescript": "^5.6.3",
+    "vitest": "^2.1.8"
+  },
+  "scripts": {
+    "test": "pnpm run test:unit",
+    "test:unit": "vitest run --config vitest.config.ts",
+    "test:contract": "vitest run --config vitest.contract.config.ts",
+    "test:e2e": "vitest run --config vitest.e2e.config.ts",
+    "test:all": "pnpm run test:unit && pnpm run test:contract && pnpm run test:e2e",
+    "build": "pnpm publish --dry-run --no-git-checks",
+    "typecheck": "pnpm exec tsc --noEmit -p tsconfig.typecheck.json",
+    "lint": "node ./scripts/lint.mjs"
+  }
+}

package/packages/core/src/bootstrap.test.ts

@@ -0,0 +1,10 @@
+import { describe, expect, it } from "vitest";
+
+describe("workspace bootstrap", () => {
+  it("loads test runner", () => {
+    const state = expect.getState();
+
+    expect(state.currentTestName).toContain("loads test runner");
+    expect(state.testPath).toContain("bootstrap.test.ts");
+  });
+});

package/packages/core/src/driver-registry.test.ts

@@ -0,0 +1,45 @@
+import { describe, expect, it } from "vitest";
+
+import type { BrowserDriver } from "./driver";
+import { DriverRegistry } from "./driver-registry";
+
+function createDriver(): BrowserDriver {
+  return {
+    status: async () => ({ kind: "test" }),
+    listProfiles: async () => [],
+    listTabs: async () => [],
+    openTab: async () => "target:1",
+    focusTab: async () => {},
+    closeTab: async () => {},
+    snapshot: async () => ({ html: "" }),
+    act: async () => ({ ok: true }),
+    armUpload: async () => {},
+    armDialog: async () => {},
+    waitDownload: async () => ({ path: "download.bin" }),
+    triggerDownload: async () => {}
+  };
+}
+
+describe("DriverRegistry", () => {
+  it("returns a registered driver", () => {
+    const registry = new DriverRegistry();
+    const driver = createDriver();
+
+    registry.register("managed", driver);
+
+    expect(registry.get("managed")).toBe(driver);
+  });
+
+  it("throws when registering a duplicate driver name", () => {
+    const registry = new DriverRegistry();
+    registry.register("managed", createDriver());
+
+    expect(() => registry.register("managed", createDriver())).toThrowError("Driver already registered: managed");
+  });
+
+  it("throws when the requested driver is not registered", () => {
+    const registry = new DriverRegistry();
+
+    expect(() => registry.get("missing")).toThrowError("Unknown driver: missing");
+  });
+});

package/packages/core/src/driver-registry.ts

@@ -0,0 +1,22 @@
+import type { BrowserDriver } from "./driver";
+
+export class DriverRegistry {
+  readonly #drivers = new Map<string, BrowserDriver>();
+
+  register(name: string, driver: BrowserDriver): void {
+    if (this.#drivers.has(name)) {
+      throw new Error(`Driver already registered: ${name}`);
+    }
+
+    this.#drivers.set(name, driver);
+  }
+
+  get(name: string): BrowserDriver {
+    const driver = this.#drivers.get(name);
+    if (!driver) {
+      throw new Error(`Unknown driver: ${name}`);
+    }
+
+    return driver;
+  }
+}

package/packages/core/src/driver.ts

@@ -0,0 +1,47 @@
+import type { ProfileId, TargetId } from "./types";
+
+export type DriverScalar = string | number | boolean | null;
+export type DriverValue = DriverScalar | DriverObject | DriverValue[];
+export type DriverObject = { [key: string]: DriverValue };
+
+export type DriverStatus = DriverObject;
+export type DriverSnapshot = DriverObject;
+export type DriverActionPayload = DriverObject;
+export type DriverActionResult = DriverObject;
+export type DriverDownloadResult = DriverObject;
+export type DriverScreenshot = DriverObject;
+
+export type DriverAction<TPayload extends DriverObject = DriverActionPayload> = {
+  type: string;
+  payload?: TPayload;
+};
+
+export type BrowserDriverScreenshot<
+  TScreenshot extends DriverObject = DriverScreenshot
+> = {
+  screenshot(targetId: TargetId, profile?: ProfileId): Promise<TScreenshot>;
+};
+
+export interface BrowserDriver<
+  TStatus extends DriverObject = DriverStatus,
+  TSnapshot extends DriverObject = DriverSnapshot,
+  TAction extends DriverAction = DriverAction,
+  TActionResult extends DriverObject = DriverActionResult,
+  TDownload extends DriverObject = DriverDownloadResult
+> {
+  status(): Promise<TStatus>;
+  listProfiles(): Promise<ProfileId[]>;
+  listTabs(profile?: ProfileId): Promise<TargetId[]>;
+
+  openTab(url: string, profile?: ProfileId): Promise<TargetId>;
+  focusTab(targetId: TargetId, profile?: ProfileId): Promise<void>;
+  closeTab(targetId: TargetId, profile?: ProfileId): Promise<void>;
+
+  snapshot(targetId: TargetId, profile?: ProfileId): Promise<TSnapshot>;
+  act(action: TAction, targetId: TargetId, profile?: ProfileId): Promise<TActionResult>;
+
+  armUpload(targetId: TargetId, files: string[], profile?: ProfileId): Promise<void>;
+  armDialog(targetId: TargetId, profile?: ProfileId): Promise<void>;
+  waitDownload(targetId: TargetId, profile?: ProfileId): Promise<TDownload>;
+  triggerDownload(targetId: TargetId, profile?: ProfileId): Promise<void>;
+}

package/packages/core/src/index.ts

@@ -0,0 +1,5 @@
+export * from "./types";
+export * from "./session-store";
+export * from "./ref-cache";
+export * from "./driver";
+export * from "./driver-registry";

package/packages/core/src/ref-cache.test.ts

@@ -0,0 +1,61 @@
+import { describe, expect, it } from "vitest";
+
+import { RefCache, createRefKey } from "./ref-cache";
+
+describe("RefCache", () => {
+  it("uses sessionId|profile|targetId as cache key", () => {
+    const cache = new RefCache<string>();
+
+    cache.set("session:a", "managed", "target:1", "value-a");
+    cache.set("session:a", "managed", "target:2", "value-b");
+    cache.set("session:a", "chrome-relay", "target:1", "value-c");
+
+    expect(cache.get("session:a", "managed", "target:1")).toBe("value-a");
+    expect(cache.get("session:a", "managed", "target:2")).toBe("value-b");
+    expect(cache.get("session:a", "chrome-relay", "target:1")).toBe("value-c");
+  });
+
+  it("does not collide across sessionIds", () => {
+    const cache = new RefCache<string>();
+
+    cache.set("session:a", "managed", "target:1", "value-a");
+    cache.set("session:b", "managed", "target:1", "value-b");
+
+    expect(cache.get("session:a", "managed", "target:1")).toBe("value-a");
+    expect(cache.get("session:b", "managed", "target:1")).toBe("value-b");
+  });
+
+  it("escapes key segments before joining with |", () => {
+    expect(createRefKey("session|a", "managed|x", "target|1")).toBe("session%7Ca|managed%7Cx|target%7C1");
+  });
+
+  it("does not collide when identifiers contain |", () => {
+    const cache = new RefCache<string>();
+
+    cache.set("session|a", "managed", "target", "value-a");
+    cache.set("session", "a|managed", "target", "value-b");
+
+    expect(cache.get("session|a", "managed", "target")).toBe("value-a");
+    expect(cache.get("session", "a|managed", "target")).toBe("value-b");
+  });
+
+  it("returns undefined for unknown key", () => {
+    const cache = new RefCache<string>();
+
+    expect(cache.get("missing", "managed", "target:1")).toBeUndefined();
+  });
+
+  it("deletes an existing key", () => {
+    const cache = new RefCache<string>();
+    cache.set("session:a", "managed", "target:1", "value-a");
+
+    expect(cache.delete("session:a", "managed", "target:1")).toBe(true);
+    expect(cache.get("session:a", "managed", "target:1")).toBeUndefined();
+  });
+
+  it("returns false when deleting an unknown key", () => {
+    const cache = new RefCache<string>();
+
+    expect(cache.delete("missing", "managed", "target:1")).toBe(false);
+  });
+});

package/packages/core/src/ref-cache.ts

@@ -0,0 +1,28 @@
+import type { ProfileId, SessionId, TargetId } from "./types";
+
+function escapeKeySegment(value: string): string {
+  return encodeURIComponent(value);
+}
+
+export function createRefKey(sessionId: SessionId, profile: ProfileId, targetId: TargetId): string {
+  return `${escapeKeySegment(sessionId)}|${escapeKeySegment(profile)}|${escapeKeySegment(targetId)}`;
+}
+
+export class RefCache<TValue> {
+  private readonly refs = new Map<string, TValue>();
+
+  get(sessionId: SessionId, profile: ProfileId, targetId: TargetId): TValue | undefined {
+    const key = createRefKey(sessionId, profile, targetId);
+    return this.refs.get(key);
+  }
+
+  set(sessionId: SessionId, profile: ProfileId, targetId: TargetId, value: TValue): void {
+    const key = createRefKey(sessionId, profile, targetId);
+    this.refs.set(key, value);
+  }
+
+  delete(sessionId: SessionId, profile: ProfileId, targetId: TargetId): boolean {
+    const key = createRefKey(sessionId, profile, targetId);
+    return this.refs.delete(key);
+  }
+}

package/packages/core/src/session-store.test.ts

@@ -0,0 +1,49 @@
+import { describe, expect, it } from "vitest";
+
+import { SessionStore } from "./session-store";
+
+describe("SessionStore", () => {
+  it("binds profile to session", () => {
+    const store = new SessionStore();
+
+    store.useProfile("cli:local", "managed");
+
+    expect(store.get("cli:local")?.profile).toBe("managed");
+  });
+
+  it("uses sessionId as the only store key", () => {
+    const store = new SessionStore();
+
+    store.useProfile("session:a", "managed");
+    store.useProfile("session:b", "chrome-relay");
+
+    expect(store.get("session:a")).toEqual({
+      sessionId: "session:a",
+      profile: "managed"
+    });
+    expect(store.get("session:b")).toEqual({
+      sessionId: "session:b",
+      profile: "chrome-relay"
+    });
+  });
+
+  it("returns undefined for unknown session", () => {
+    const store = new SessionStore();
+
+    expect(store.get("missing")).toBeUndefined();
+  });
+
+  it("deletes an existing session", () => {
+    const store = new SessionStore();
+    store.useProfile("cli:local", "managed");
+
+    expect(store.delete("cli:local")).toBe(true);
+    expect(store.get("cli:local")).toBeUndefined();
+  });
+
+  it("returns false when deleting an unknown session", () => {
+    const store = new SessionStore();
+
+    expect(store.delete("missing")).toBe(false);
+  });
+});

package/packages/core/src/session-store.ts

@@ -0,0 +1,33 @@
+import type { ProfileId, SessionId, SessionState, TargetId } from "./types";
+
+function createEmptySession(sessionId: SessionId): SessionState {
+  return { sessionId };
+}
+
+export class SessionStore {
+  private readonly sessions = new Map<SessionId, SessionState>();
+
+  get(sessionId: SessionId): SessionState | undefined {
+    return this.sessions.get(sessionId);
+  }
+
+  useProfile(sessionId: SessionId, profile: ProfileId): SessionState {
+    const current = this.sessions.get(sessionId) ?? createEmptySession(sessionId);
+    const next = { ...current, profile };
+
+    this.sessions.set(sessionId, next);
+    return next;
+  }
+
+  useTarget(sessionId: SessionId, targetId: TargetId): SessionState {
+    const current = this.sessions.get(sessionId) ?? createEmptySession(sessionId);
+    const next = { ...current, targetId };
+
+    this.sessions.set(sessionId, next);
+    return next;
+  }
+
+  delete(sessionId: SessionId): boolean {
+    return this.sessions.delete(sessionId);
+  }
+}

package/packages/core/src/types.ts

@@ -0,0 +1,9 @@
+export type SessionId = string;
+export type ProfileId = string;
+export type TargetId = string;
+
+export type SessionState = {
+  sessionId: SessionId;
+  profile?: ProfileId;
+  targetId?: TargetId;
+};