@flrande/browserctl 0.5.0 → 0.6.0

package/packages/protocol/src/envelope.test.ts

@@ -1,25 +0,0 @@
-import { describe, expect, it } from "vitest";
-
-import { ErrorCode } from "./errors";
-import { createErr, createOk } from "./envelope";
-
-describe("createOk", () => {
-  it("returns a success envelope", () => {
-    expect(createOk({ value: 42 })).toEqual({
-      ok: true,
-      data: { value: 42 }
-    });
-  });
-});
-
-describe("createErr", () => {
-  it("returns an error envelope", () => {
-    expect(createErr(ErrorCode.E_INVALID_ARG, "bad input")).toEqual({
-      ok: false,
-      error: {
-        code: "E_INVALID_ARG",
-        message: "bad input"
-      }
-    });
-  });
-});

package/packages/protocol/src/envelope.ts

@@ -1,31 +0,0 @@
-import type { ErrorCode } from "./errors";
-
-export type ToolSuccessEnvelope<TData> = {
-  ok: true;
-  data: TData;
-};
-
-export type ToolErrorEnvelope = {
-  ok: false;
-  error: {
-    code: ErrorCode;
-    message: string;
-  };
-};
-
-export function createOk<TData>(data: TData): ToolSuccessEnvelope<TData> {
-  return {
-    ok: true,
-    data
-  };
-}
-
-export function createErr(code: ErrorCode, message: string): ToolErrorEnvelope {
-  return {
-    ok: false,
-    error: {
-      code,
-      message
-    }
-  };
-}

package/packages/protocol/src/errors.test.ts

@@ -1,17 +0,0 @@
-import { describe, expect, it } from "vitest";
-
-import { ErrorCode } from "./errors";
-
-describe("ErrorCode", () => {
-  it("contains the canonical error code registry", () => {
-    expect(ErrorCode).toEqual({
-      E_INVALID_ARG: "E_INVALID_ARG",
-      E_NOT_FOUND: "E_NOT_FOUND",
-      E_CONFLICT: "E_CONFLICT",
-      E_TIMEOUT: "E_TIMEOUT",
-      E_DRIVER_UNAVAILABLE: "E_DRIVER_UNAVAILABLE",
-      E_PERMISSION: "E_PERMISSION",
-      E_INTERNAL: "E_INTERNAL"
-    });
-  });
-});

package/packages/protocol/src/errors.ts

@@ -1,11 +0,0 @@
-export const ErrorCode = {
-  E_INVALID_ARG: "E_INVALID_ARG",
-  E_NOT_FOUND: "E_NOT_FOUND",
-  E_CONFLICT: "E_CONFLICT",
-  E_TIMEOUT: "E_TIMEOUT",
-  E_DRIVER_UNAVAILABLE: "E_DRIVER_UNAVAILABLE",
-  E_PERMISSION: "E_PERMISSION",
-  E_INTERNAL: "E_INTERNAL"
-} as const;
-
-export type ErrorCode = (typeof ErrorCode)[keyof typeof ErrorCode];

package/packages/protocol/src/index.ts

@@ -1,3 +0,0 @@
-export * from "./errors";
-export * from "./envelope";
-export * from "./tools";

package/packages/protocol/src/tools.ts

@@ -1,3 +0,0 @@
-import type { ToolErrorEnvelope, ToolSuccessEnvelope } from "./envelope";
-
-export type ToolResponse<TData> = ToolSuccessEnvelope<TData> | ToolErrorEnvelope;

package/packages/transport-mcp-stdio/src/index.ts

@@ -1,3 +0,0 @@
-export * from "./tool-map";
-export * from "./server";
-export * from "./sdk-server";

package/packages/transport-mcp-stdio/src/sdk-server.ts

@@ -1,139 +0,0 @@
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import type { Transport } from "@modelcontextprotocol/sdk/shared/transport.js";
-import type { CallToolResult, Implementation } from "@modelcontextprotocol/sdk/types.js";
-import { Readable, Writable } from "node:stream";
-import * as z from "zod/v4";
-
-import { ErrorCode } from "../../protocol/src/index";
-
-import {
-  createMcpStdioServer,
-  type McpStdioServer,
-  type McpToolCallEnvelope
-} from "./server";
-import { buildToolMap, type ToolMap } from "./tool-map";
-
-const UNKNOWN_TRACE_ID = "trace:unknown";
-const DEFAULT_SERVER_INFO: Implementation = {
-  name: "browserd",
-  version: "0.1.0"
-};
-
-export type McpSdkServerOptions = {
-  toolMap?: ToolMap;
-  serverInfo?: Implementation;
-};
-
-export type McpSdkStdioTransport = {
-  input?: Readable;
-  output?: Writable;
-};
-
-export type McpSdkServer = {
-  readonly mcpServer: McpServer;
-  readonly mcpStdioServer: McpStdioServer;
-  listTools(): string[];
-  connect(transport: Transport): Promise<void>;
-  connectStdio(transport?: McpSdkStdioTransport): Promise<void>;
-  close(): Promise<void>;
-};
-
-function isObjectRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-
-function resolveTraceId(rawArgs: unknown): string {
-  if (!isObjectRecord(rawArgs)) {
-    return UNKNOWN_TRACE_ID;
-  }
-
-  const traceId = rawArgs.traceId;
-  if (typeof traceId !== "string") {
-    return UNKNOWN_TRACE_ID;
-  }
-
-  const trimmedTraceId = traceId.trim();
-  return trimmedTraceId.length > 0 ? trimmedTraceId : UNKNOWN_TRACE_ID;
-}
-
-function stringifyContent(value: unknown): string {
-  if (typeof value === "string") {
-    return value;
-  }
-
-  try {
-    return JSON.stringify(value);
-  } catch {
-    return String(value);
-  }
-}
-
-function toCallToolResult(envelope: McpToolCallEnvelope): CallToolResult {
-  if (envelope.ok) {
-    return {
-      content: [
-        {
-          type: "text",
-          text: stringifyContent(envelope.data ?? {})
-        }
-      ],
-      structuredContent: envelope
-    };
-  }
-
-  const code = envelope.error?.code ?? ErrorCode.E_INTERNAL;
-  const message = envelope.error?.message ?? "Unexpected tool failure.";
-  return {
-    content: [
-      {
-        type: "text",
-        text: `${code}: ${message}`
-      }
-    ],
-    structuredContent: envelope,
-    isError: true
-  };
-}
-
-export function createMcpSdkServer(options: McpSdkServerOptions = {}): McpSdkServer {
-  const toolMap = options.toolMap ?? buildToolMap();
-  const mcpStdioServer = createMcpStdioServer(toolMap);
-  const mcpServer = new McpServer(options.serverInfo ?? DEFAULT_SERVER_INFO);
-
-  for (const toolName of mcpStdioServer.listTools()) {
-    mcpServer.registerTool(
-      toolName,
-      {
-        description: `Browser control tool: ${toolName}`,
-        inputSchema: z.object({}).passthrough()
-      },
-      async (rawArgs) => {
-        const response = await mcpStdioServer.callTool({
-          name: toolName,
-          traceId: resolveTraceId(rawArgs),
-          arguments: rawArgs
-        });
-        return toCallToolResult(response);
-      }
-    );
-  }
-
-  return {
-    mcpServer,
-    mcpStdioServer,
-    listTools() {
-      return mcpStdioServer.listTools();
-    },
-    connect(transport: Transport) {
-      return mcpServer.connect(transport);
-    },
-    connectStdio(transport: McpSdkStdioTransport = {}) {
-      const stdioTransport = new StdioServerTransport(transport.input, transport.output);
-      return mcpServer.connect(stdioTransport);
-    },
-    close() {
-      return mcpServer.close();
-    }
-  };
-}

package/packages/transport-mcp-stdio/src/server.test.ts

@@ -1,281 +0,0 @@
-import { Client } from "@modelcontextprotocol/sdk/client/index.js";
-import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
-import { describe, expect, it } from "vitest";
-
-import { ErrorCode, createOk } from "../../protocol/src/index";
-
-import { createMcpSdkServer } from "./sdk-server";
-import { createMcpStdioServer } from "./server";
-import { buildToolMap } from "./tool-map";
-
-describe("tool map", () => {
-  it("includes browser.status", () => {
-    const map = buildToolMap();
-
-    expect(map.has("browser.status")).toBe(true);
-  });
-});
-
-describe("createMcpStdioServer", () => {
-  it("returns success envelope for a successful handler result", async () => {
-    const server = createMcpStdioServer(
-      new Map([
-        [
-          "browser.status",
-          async () =>
-            createOk({
-              status: "ok"
-            })
-        ]
-      ])
-    );
-
-    const response = await server.callTool({
-      name: "browser.status",
-      traceId: "trace:test",
-      arguments: {
-        sessionId: "session:alpha",
-        profile: "profile:alpha",
-        targetId: "target:alpha"
-      }
-    });
-
-    expect(response).toEqual({
-      ok: true,
-      traceId: "trace:test",
-      sessionId: "session:alpha",
-      profile: "profile:alpha",
-      targetId: "target:alpha",
-      data: {
-        status: "ok"
-      }
-    });
-  });
-
-  it("returns validation errors through the common envelope", async () => {
-    const server = createMcpStdioServer();
-
-    const response = await server.callTool({
-      name: "browser.status",
-      traceId: "trace:validation",
-      arguments: {
-        sessionId: ""
-      }
-    });
-
-    expect(response).toEqual({
-      ok: false,
-      traceId: "trace:validation",
-      sessionId: "session:unknown",
-      error: {
-        code: ErrorCode.E_INVALID_ARG,
-        message: "sessionId is required and must be a non-empty string."
-      }
-    });
-  });
-
-  it("returns not found for unknown tools", async () => {
-    const server = createMcpStdioServer();
-
-    const response = await server.callTool({
-      name: "browser.unknown",
-      traceId: "trace:unknown",
-      arguments: {
-        sessionId: "session:alpha"
-      }
-    });
-
-    expect(response).toEqual({
-      ok: false,
-      traceId: "trace:unknown",
-      sessionId: "session:alpha",
-      error: {
-        code: ErrorCode.E_NOT_FOUND,
-        message: "Unknown tool: browser.unknown"
-      }
-    });
-  });
-
-  it("returns a dedicated code for not implemented tools", async () => {
-    const server = createMcpStdioServer();
-
-    const response = await server.callTool({
-      name: "browser.profile.list",
-      traceId: "trace:not-implemented",
-      arguments: {
-        sessionId: "session:alpha"
-      }
-    });
-
-    expect(response).toEqual({
-      ok: false,
-      traceId: "trace:not-implemented",
-      sessionId: "session:alpha",
-      error: {
-        code: ErrorCode.E_DRIVER_UNAVAILABLE,
-        message: "Tool is not implemented: browser.profile.list"
-      }
-    });
-  });
-
-  it("wraps thrown handler errors as E_INTERNAL envelopes", async () => {
-    const server = createMcpStdioServer(
-      new Map([
-        [
-          "browser.status",
-          async () => {
-            throw new Error("boom");
-          }
-        ]
-      ])
-    );
-
-    const response = await server.callTool({
-      name: "browser.status",
-      traceId: "trace:throw",
-      arguments: {
-        sessionId: "session:alpha"
-      }
-    });
-
-    expect(response).toEqual({
-      ok: false,
-      traceId: "trace:throw",
-      sessionId: "session:alpha",
-      error: {
-        code: ErrorCode.E_INTERNAL,
-        message: "boom"
-      }
-    });
-  });
-
-  it("uses the provided toolMap override instead of defaults", async () => {
-    const server = createMcpStdioServer(
-      new Map([
-        [
-          "custom.ping",
-          async () =>
-            createOk({
-              pong: true
-            })
-        ]
-      ])
-    );
-
-    expect(server.listTools()).toEqual(["custom.ping"]);
-
-    const response = await server.callTool({
-      name: "custom.ping",
-      traceId: "trace:override",
-      arguments: {
-        sessionId: "session:alpha"
-      }
-    });
-
-    expect(response).toEqual({
-      ok: true,
-      traceId: "trace:override",
-      sessionId: "session:alpha",
-      data: {
-        pong: true
-      }
-    });
-  });
-});
-
-describe("createMcpSdkServer", () => {
-  it("registers tool names and returns structured envelopes through MCP", async () => {
-    const sdkServer = createMcpSdkServer({
-      toolMap: new Map([
-        [
-          "browser.status",
-          async (args) =>
-            createOk({
-              status: "ok",
-              sessionId: args.sessionId
-            })
-        ]
-      ]),
-      serverInfo: {
-        name: "browserctl-test-server",
-        version: "0.0.0-test"
-      }
-    });
-
-    const client = new Client({
-      name: "browserctl-test-client",
-      version: "0.0.0-test"
-    });
-    const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
-    await Promise.all([sdkServer.connect(serverTransport), client.connect(clientTransport)]);
-
-    try {
-      const toolsResult = await client.listTools();
-      expect(toolsResult.tools.map((tool) => tool.name)).toEqual(["browser.status"]);
-
-      const result = await client.callTool({
-        name: "browser.status",
-        arguments: {
-          sessionId: "session:alpha",
-          traceId: "trace:alpha"
-        }
-      });
-
-      expect("structuredContent" in result).toBe(true);
-      if (!("structuredContent" in result)) {
-        throw new Error("Expected a CallToolResult payload with structuredContent.");
-      }
-
-      expect(result.isError).not.toBe(true);
-      expect(result.structuredContent).toMatchObject({
-        ok: true,
-        traceId: "trace:alpha",
-        sessionId: "session:alpha",
-        data: {
-          status: "ok",
-          sessionId: "session:alpha"
-        }
-      });
-    } finally {
-      await client.close();
-      await sdkServer.close();
-    }
-  });
-
-  it("maps envelope validation errors to MCP tool errors", async () => {
-    const sdkServer = createMcpSdkServer();
-    const client = new Client({
-      name: "browserctl-test-client",
-      version: "0.0.0-test"
-    });
-    const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
-    await Promise.all([sdkServer.connect(serverTransport), client.connect(clientTransport)]);
-
-    try {
-      const result = await client.callTool({
-        name: "browser.status",
-        arguments: {
-          sessionId: ""
-        }
-      });
-
-      expect("structuredContent" in result).toBe(true);
-      if (!("structuredContent" in result)) {
-        throw new Error("Expected a CallToolResult payload with structuredContent.");
-      }
-
-      expect(result.isError).toBe(true);
-      expect(result.structuredContent).toMatchObject({
-        ok: false,
-        sessionId: "session:unknown",
-        error: {
-          code: ErrorCode.E_INVALID_ARG,
-          message: "sessionId is required and must be a non-empty string."
-        }
-      });
-    } finally {
-      await client.close();
-      await sdkServer.close();
-    }
-  });
-});

package/packages/transport-mcp-stdio/src/server.ts

@@ -1,183 +0,0 @@
-import { ErrorCode, createErr, createOk, type ToolResponse } from "../../protocol/src/index";
-
-import { buildToolMap, type ToolCallArgs, type ToolMap } from "./tool-map";
-
-const UNKNOWN_TRACE_ID = "trace:unknown";
-const UNKNOWN_SESSION_ID = "session:unknown";
-
-export type McpToolCallRequest = {
-  name: string;
-  arguments?: unknown;
-  traceId?: string;
-};
-
-export type McpToolCallEnvelope<TData = Record<string, unknown>> = {
-  ok: boolean;
-  traceId: string;
-  sessionId: string;
-  profile?: string;
-  targetId?: string;
-  data?: TData;
-  error?: {
-    code: string;
-    message: string;
-  };
-};
-
-export type McpStdioServer = {
-  readonly toolMap: ToolMap;
-  listTools(): string[];
-  callTool(request: McpToolCallRequest): Promise<McpToolCallEnvelope>;
-};
-
-function isObjectRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-
-function resolveTraceId(value: string | undefined): string {
-  if (typeof value !== "string") {
-    return UNKNOWN_TRACE_ID;
-  }
-
-  const trimmedValue = value.trim();
-  return trimmedValue.length === 0 ? UNKNOWN_TRACE_ID : trimmedValue;
-}
-
-function toErrorMessage(error: unknown): string {
-  if (error instanceof Error) {
-    return error.message;
-  }
-
-  return "Unexpected tool failure.";
-}
-
-export function validateToolCallArgs(value: unknown): ToolResponse<ToolCallArgs> {
-  if (!isObjectRecord(value)) {
-    return createErr(ErrorCode.E_INVALID_ARG, "Tool arguments must be an object.");
-  }
-
-  const sessionIdValue = value.sessionId;
-  if (typeof sessionIdValue !== "string" || sessionIdValue.trim().length === 0) {
-    return createErr(ErrorCode.E_INVALID_ARG, "sessionId is required and must be a non-empty string.");
-  }
-
-  const profileValue = value.profile;
-  if (profileValue !== undefined && (typeof profileValue !== "string" || profileValue.trim().length === 0)) {
-    return createErr(ErrorCode.E_INVALID_ARG, "profile must be a non-empty string when provided.");
-  }
-
-  const targetIdValue = value.targetId;
-  if (targetIdValue !== undefined && (typeof targetIdValue !== "string" || targetIdValue.trim().length === 0)) {
-    return createErr(ErrorCode.E_INVALID_ARG, "targetId must be a non-empty string when provided.");
-  }
-
-  const timeoutMsValue = value.timeoutMs;
-  if (
-    timeoutMsValue !== undefined &&
-    (typeof timeoutMsValue !== "number" || !Number.isFinite(timeoutMsValue) || timeoutMsValue < 0)
-  ) {
-    return createErr(
-      ErrorCode.E_INVALID_ARG,
-      "timeoutMs must be a non-negative finite number when provided."
-    );
-  }
-
-  const normalizedArgs: ToolCallArgs = {
-    ...value,
-    sessionId: sessionIdValue.trim()
-  };
-
-  if (typeof profileValue === "string") {
-    normalizedArgs.profile = profileValue.trim();
-  }
-
-  if (typeof targetIdValue === "string") {
-    normalizedArgs.targetId = targetIdValue.trim();
-  }
-
-  if (typeof timeoutMsValue === "number") {
-    normalizedArgs.timeoutMs = timeoutMsValue;
-  }
-
-  return createOk(normalizedArgs);
-}
-
-export function adaptToolResponse<TData>(
-  context: Pick<ToolCallArgs, "sessionId" | "profile" | "targetId">,
-  traceId: string,
-  response: ToolResponse<TData>
-): McpToolCallEnvelope<TData> {
-  if (response.ok) {
-    return {
-      ok: true,
-      traceId,
-      sessionId: context.sessionId,
-      profile: context.profile,
-      targetId: context.targetId,
-      data: response.data
-    };
-  }
-
-  return {
-    ok: false,
-    traceId,
-    sessionId: context.sessionId,
-    profile: context.profile,
-    targetId: context.targetId,
-    error: response.error
-  };
-}
-
-export function createMcpStdioServer(toolMap: ToolMap = buildToolMap()): McpStdioServer {
-  return {
-    toolMap,
-    listTools() {
-      return [...toolMap.keys()];
-    },
-    async callTool(request) {
-      const traceId = resolveTraceId(request.traceId);
-      const rawToolName = request.name;
-      if (typeof rawToolName !== "string" || rawToolName.trim().length === 0) {
-        return adaptToolResponse(
-          {
-            sessionId: UNKNOWN_SESSION_ID
-          },
-          traceId,
-          createErr(ErrorCode.E_INVALID_ARG, "Tool name must be a non-empty string.")
-        );
-      }
-
-      const validatedArgs = validateToolCallArgs(request.arguments);
-      if (!validatedArgs.ok) {
-        return adaptToolResponse(
-          {
-            sessionId: UNKNOWN_SESSION_ID
-          },
-          traceId,
-          validatedArgs
-        );
-      }
-
-      const toolName = rawToolName.trim();
-      const handler = toolMap.get(toolName);
-      if (handler === undefined) {
-        return adaptToolResponse(
-          validatedArgs.data,
-          traceId,
-          createErr(ErrorCode.E_NOT_FOUND, `Unknown tool: ${toolName}`)
-        );
-      }
-
-      try {
-        const response = await handler(validatedArgs.data);
-        return adaptToolResponse(validatedArgs.data, traceId, response);
-      } catch (error) {
-        return adaptToolResponse(
-          validatedArgs.data,
-          traceId,
-          createErr(ErrorCode.E_INTERNAL, toErrorMessage(error))
-        );
-      }
-    }
-  };
-}