Skip to content

Open source website builder and Webflow alternative. Webstudio is an advanced visual builder that connects to any headless CMS, supports all CSS properties, and can be hosted anywhere, including with us.

69.0 KB
Raw Blame
import { mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
import { tmpdir } from "node:os";
import path from "node:path";
import { afterEach, expect, test, vi } from "vitest";
import {
  blockComponent,
  blockTemplateComponent,
  getInputJsonSchemaMetadata,
  getInputJsonSchemaProperties,
} from "@webstudio-is/sdk";
import {
  createProjectSessionMcpCore,
  getDetailedProjectSessionMcpInputSchema,
  hiddenMcpOperationCommands,
  listProjectSessionMcpTools,
} from "@webstudio-is/project-build/mcp";
import {
  createDefaultProjectSessionCompatibility,
  createProjectSession,
} from "@webstudio-is/project-build/project-session";
import {
  createBuilderStateFromSnapshot,
  createBuilderStateFreshness,
} from "@webstudio-is/project-build/state";
import { publicApiOperations } from "@webstudio-is/protocol";
import { contentEngineLimits } from "@webstudio-is/content-engine/limits";
import { ROOT_INSTANCE_ID, type Pages } from "@webstudio-is/sdk";
import { updatePersistedMcpCheckpoint } from "./mcp-checkpoint";
import {
  createCliProjectSessionStorage,
  createIssueReportFailureTracker,
  createIssueReportTargetTracker,
} from "../project-session";
import {
  __testing__,
  mcpOptions,
  mcpSingleOpCall,
  prepareMcpProjectSession,
} from "./mcp";

const {
  createIssueReportStateWriter,
  getMcpDownloadAsset,
  getIssueReportFailureFile,
  getIssueReportPageId,
  persistIssueReportFailure,
  restoreIssueReportFailure,
  assertSingleOpCallToolSupported,
  applyMcpRunOptions,
  createMcpResourceErrorPayload,
  createMcpRunCheckpointStopPayload,
  createMcpRunErrorPayload,
  createMcpSingleOpCallErrorPayload,
  createMcpStatusReporter,
  assertMcpToolServerSupport,
  getCliUpdateInstructions,
  getLoadedProjectSessionSnapshot,
  getMcpOperationInput,
  prepareTextAssetWriteFeedback,
  withTextAssetWriteFeedback,
  validateDownloadedTextAsset,
  materializeValidatedDownloadedAsset,
  reportMcpSingleOpCallTermination,
  reportMcpRunTermination,
  createMcpRunTerminationController,
  parseMcpRunCalls,
  parseMcpRunInput,
  parseMcpSingleOpCallInput,
  validateSingleOpCallInput,
  isMcpToolCallFailure,
  getMcpToolCallError,
  executeMcpRunCall,
  withMcpHost,
} = __testing__;

test("instructs connected agents to update an outdated MCP CLI", () => {
  expect(
    getCliUpdateInstructions({
      currentVersion: "0.299.0",
      latestVersion: "0.301.0",
    })
  ).toBe(
    "This MCP server runs Webstudio CLI 0.299.0, but 0.301.0 is available. Tell the user before editing and recommend restarting this MCP server with the latest CLI, for example `npx -y webstudio@latest mcp`. Do not try to update or restart the CLI yourself. The existing API compatibility check remains the authority for whether writes are supported."
  );
  expect(getCliUpdateInstructions(undefined)).toBeUndefined();
});

test("checks API contract compatibility before committing MCP edits", () => {
  const contract = {
    clientVersion: "public-api:client",
    serverVersion: "public-api:server",
    supportedOperationIds: new Set<string>(),
    missingServerOperationIds: [],
    negotiated: true,
  } as const;

  expect(() => assertMcpToolServerSupport("update-page", contract)).toThrow(
    /Restart the MCP server with the latest CLI/
  );
  expect(() =>
    assertMcpToolServerSupport("update-page", contract, true)
  ).not.toThrow();
  expect(() =>
    assertMcpToolServerSupport("list-pages", contract)
  ).not.toThrow();
});

test("disposes an MCP host when its operation fails", async () => {
  const dispose = vi.fn(async () => undefined);

  await expect(
    withMcpHost(
      async () => ({ dispose }),
      async () => {
        throw new Error("operation failed");
      }
    )
  ).rejects.toThrow("operation failed");
  expect(dispose).toHaveBeenCalledOnce();
});

test("classifies structured MCP tool failures for nonzero CLI exit", () => {
  expect(
    isMcpToolCallFailure({
      isError: true,
      structuredContent: { ok: false },
    })
  ).toBe(true);
  expect(
    isMcpToolCallFailure({
      structuredContent: { ok: false },
    })
  ).toBe(true);
  expect(
    isMcpToolCallFailure({
      structuredContent: { ok: true },
    })
  ).toBe(false);
  expect(
    getMcpToolCallError({
      isError: true,
      structuredContent: {
        ok: false,
        error: { code: "AUDIT_FAILED", message: "Capture failed." },
      },
    })
  ).toEqual({ code: "AUDIT_FAILED", message: "Capture failed." });
});

const tempDirs: string[] = [];
type CommandBuilder = (yargs: unknown) => unknown;
type CommandCall = [readonly string[], string, CommandBuilder, unknown];

const normalizeMcpJsonValueSchemas = (value: unknown): unknown => {
  if (Array.isArray(value)) {
    return value.map(normalizeMcpJsonValueSchemas);
  }
  if (value === null || typeof value !== "object") {
    return value;
  }
  const object = value as Record<string, unknown>;
  if (
    Object.keys(object).length === 1 &&
    Array.isArray(object.anyOf) &&
    JSON.stringify(object.anyOf) ===
      JSON.stringify([
        { type: "string" },
        { type: "number" },
        { type: "boolean" },
        { type: "null" },
        { type: "array", items: {} },
        { type: "object" },
      ])
  ) {
    return {};
  }
  const omitSyntheticTupleItems =
    Array.isArray(object.prefixItems) &&
    object.items !== null &&
    typeof object.items === "object" &&
    Object.keys(object.items).length === 0;
  return Object.fromEntries(
    Object.entries(object)
      .filter(([key]) => omitSyntheticTupleItems === false || key !== "items")
      .map(([key, nestedValue]) => [
        key,
        normalizeMcpJsonValueSchemas(nestedValue),
      ])
  );
};

test("keeps every MCP API tool aligned with its public API contract", () => {
  const toolsByName = new Map(
    listProjectSessionMcpTools(publicApiOperations).map((tool) => [
      tool.name,
      tool,
    ])
  );

  for (const operation of publicApiOperations) {
    if (hiddenMcpOperationCommands.has(operation.command)) {
      expect(toolsByName.has(operation.command), operation.command).toBe(false);
      continue;
    }

    const tool = toolsByName.get(operation.command);
    expect(tool, operation.command).toBeDefined();
    if (tool === undefined) {
      continue;
    }

    const schema = getDetailedProjectSessionMcpInputSchema(tool);
    const transportFields = [
      ...(operation.method === "mutation" && operation.localCapable
        ? ["dryRun"]
        : []),
      ...(operation.requiresConfirm && operation.localCapable
        ? ["confirmDestructive", "confirmationToken"]
        : []),
    ];
    const cliOwnedFields =
      operation.command === "report-issue" ? ["runtime"] : [];
    const schemaMetadata = getInputJsonSchemaMetadata(schema);
    const semanticFields = schemaMetadata.inputFields.filter(
      (field) => transportFields.includes(field) === false
    );
    expect(new Set(semanticFields), operation.command).toEqual(
      new Set(
        operation.inputFields.filter(
          (field) => cliOwnedFields.includes(field) === false
        )
      )
    );

    const apiProperties = getInputJsonSchemaProperties(operation.inputSchema);
    const mcpProperties = getInputJsonSchemaProperties(schema);
    for (const field of operation.inputFields) {
      if (cliOwnedFields.includes(field)) {
        continue;
      }
      const isRepresentationOverride =
        (operation.command === "insert-fragment" &&
          ["parentInstanceId", "fragment"].includes(field)) ||
        (operation.command === "insert-collection" && field === "itemFragment");
      if (isRepresentationOverride) {
        continue;
      }
      expect(
        normalizeMcpJsonValueSchemas(mcpProperties?.[field]),
        `${operation.command}.${field}`
      ).toEqual(apiProperties?.[field]);
    }

    const requiredFields = operation.requiredInputFields.filter(
      (field) => cliOwnedFields.includes(field) === false
    );
    if (
      operation.command === "insert-fragment" &&
      requiredFields.includes("parentInstanceId") === false
    ) {
      requiredFields.push("parentInstanceId");
    }
    expect(
      new Set(schemaMetadata.requiredInputFields),
      operation.command
    ).toEqual(new Set(requiredFields));
  }
});

afterEach(async () => {
  vi.restoreAllMocks();
  await Promise.all(
    tempDirs.splice(0).map((dir) => rm(dir, { recursive: true, force: true }))
  );
});

test("confirms a resource deletion across persisted CLI sessions only for the unchanged plan", async () => {
  const operation = publicApiOperations.find(
    ({ command }) => command === "delete-resource"
  );
  if (operation === undefined) {
    throw new Error("Expected delete-resource MCP operation");
  }
  const compatibility = createDefaultProjectSessionCompatibility("test");

  for (const change of ["none", "version", "plan"] as const) {
    const directory = await mkdtemp(
      path.join(tmpdir(), "webstudio-mcp-delete-confirmation-")
    );
    tempDirs.push(directory);
    const storagePath = path.join(directory, "project-session.json");
    const storage = createCliProjectSessionStorage(storagePath);
    const createSnapshot = (version: number, addDataSource: boolean) => {
      const state = createBuilderStateFromSnapshot({
        pages: {
          homePageId: "home",
          rootFolderId: "root",
          pages: new Map([
            [
              "home",
              {
                id: "home",
                name: "Home",
                path: "",
                title: "Home",
                rootInstanceId: "body",
                meta: {},
              },
            ],
          ]),
          folders: new Map([
            [
              "root",
              { id: "root", name: "Root", slug: "", children: ["home"] },
            ],
          ]),
        },
        instances: [
          [
            ROOT_INSTANCE_ID,
            {
              type: "instance",
              id: ROOT_INSTANCE_ID,
              component: "Root",
              children: [{ type: "id", value: "body" }],
            },
          ],
          [
            "body",
            { type: "instance", id: "body", component: "Body", children: [] },
          ],
        ],
        props: [],
        dataSources: addDataSource
          ? [
              [
                "resource-data",
                {
                  id: "resource-data",
                  name: "resourceData",
                  type: "resource",
                  resourceId: "resource",
                  scopeInstanceId: "body",
                },
              ],
            ]
          : [],
        resources: [
          [
            "resource",
            {
              id: "resource",
              name: "Test resource",
              method: "get",
              url: '"https://example.com"',
              headers: [],
            },
          ],
        ],
      });
      return {
        projectId: "project-1",
        buildId: "build-1",
        version,
        state,
        freshness: createBuilderStateFreshness({ state, version }),
        compatibilityVersion: "test",
        compatibility,
      };
    };
    await storage.save(createSnapshot(1, false), {});

    let commits = 0;
    const createCore = async () => {
      const session = createProjectSession({
        projectId: "project-1",
        storage: createCliProjectSessionStorage(storagePath),
        compatibilityVersion: "test",
        runtimeContext: { createId: () => crypto.randomUUID() },
        transport: {
          async fetchNamespaces() {
            throw new Error("The complete persisted snapshot should be used");
          },
          async commitPatch({ baseVersion }) {
            commits += 1;
            return { version: baseVersion + 1 };
          },
          async commitRestorePoint() {
            throw new Error("Resource deletion must use patch commits");
          },
          async getPermissions() {
            return {
              canView: true,
              canEdit: true,
              canBuild: true,
              canAdmin: false,
              canUseApi: true,
            };
          },
          async getCompatibility() {
            return compatibility;
          },
        },
      });
      await session.initialize();
      return createProjectSessionMcpCore({
        operations: [operation],
        createProjectSession: () => session,
        executeOperation: ({ input, dryRun }) =>
          session.mutate("resources.delete", input as { resourceId: string }, {
            dryRun,
          }),
      });
    };

    const planned = await (
      await createCore()
    ).callTool({
      name: "delete-resource",
      input: { resourceId: "resource", dryRun: true },
    });
    expect(planned.structuredContent).toMatchObject({
      ok: true,
      meta: { confirmation: { token: expect.any(String) } },
    });
    const token = planned.structuredContent.meta.confirmation?.token;
    if (token === undefined) {
      throw new Error("Expected a deletion confirmation token");
    }

    if (change !== "none") {
      const persisted = await storage.load();
      await storage.save(
        createSnapshot(change === "version" ? 2 : 1, change === "plan"),
        {
          expectedRevision: persisted?.revision,
        }
      );
    }

    const result = await (
      await createCore()
    ).callTool({
      name: "delete-resource",
      input: {
        resourceId: "resource",
        confirmDestructive: true,
        confirmationToken: token,
      },
    });
    if (change === "none") {
      expect(result.structuredContent.ok).toBe(true);
      expect(commits).toBe(1);
      expect((await storage.load())?.state.resources?.has("resource")).toBe(
        false
      );
    } else {
      expect(result.structuredContent).toMatchObject({
        ok: false,
        error: { code: "DESTRUCTIVE_CONFIRMATION_INVALID" },
      });
      expect(commits).toBe(0);
      expect((await storage.load())?.state.resources?.has("resource")).toBe(
        true
      );
    }
  }
});

test("persists sanitized issue-report failure diagnostics for the next CLI process", async () => {
  const projectRoot = await mkdtemp(
    path.join(tmpdir(), "webstudio-mcp-issue-report-")
  );
  tempDirs.push(projectRoot);
  const filePath = getIssueReportFailureFile(projectRoot, "project-1");
  const firstProcess = createIssueReportFailureTracker();
  firstProcess.record(
    "update-text",
    new Error("Unable to transform response from server"),
    125,
    { instanceId: "instance-1", text: "private customer content" }
  );

  await persistIssueReportFailure(filePath, firstProcess.snapshot());

  const secondProcess = createIssueReportFailureTracker();
  await restoreIssueReportFailure(filePath, secondProcess);
  expect(secondProcess.get()).toMatchObject({
    tool: "update-text",
    elapsedMs: 125,
    entityIds: [{ field: "instanceId", id: "instance-1" }],
  });
  expect(await readFile(filePath, "utf8")).not.toContain(
    "private customer content"
  );

  await persistIssueReportFailure(filePath, undefined);
  const clearedProcess = createIssueReportFailureTracker();
  await restoreIssueReportFailure(filePath, clearedProcess);
  expect(clearedProcess.get()).toBeUndefined();

  await writeFile(
    filePath,
    JSON.stringify({
      at: Date.now(),
      failure: { tool: "update-text", code: "MCP_TOOL_FAILED", private: true },
    })
  );
  const malformedProcess = createIssueReportFailureTracker();
  await restoreIssueReportFailure(filePath, malformedProcess);
  expect(malformedProcess.get()).toBeUndefined();
  await expect(readFile(filePath, "utf8")).rejects.toMatchObject({
    code: "ENOENT",
  });
});

test("keeps the latest issue-report state when writes overlap", async () => {
  const projectRoot = await mkdtemp(
    path.join(tmpdir(), "webstudio-mcp-issue-report-writes-")
  );
  tempDirs.push(projectRoot);
  const filePath = getIssueReportFailureFile(projectRoot, "project-1");
  const tracker = createIssueReportFailureTracker();
  tracker.record("update-text", new Error("failed"), 1, {
    instanceId: "instance-1",
  });
  let releaseFirstWrite: () => void = () => undefined;
  const firstWriteBlocked = new Promise<void>((resolve) => {
    releaseFirstWrite = resolve;
  });
  const writes: string[] = [];
  const writer = createIssueReportStateWriter(
    filePath,
    async (path, snapshot, targets) => {
      if (snapshot !== undefined) {
        await firstWriteBlocked;
      }
      writes.push(snapshot === undefined ? "clear" : "failure");
      await persistIssueReportFailure(path, snapshot, targets);
    }
  );

  const firstWrite = writer(tracker.snapshot());
  const clear = writer(undefined);
  await Promise.resolve();
  expect(writes).toEqual([]);
  releaseFirstWrite();
  await Promise.all([firstWrite, clear]);
  expect(writes).toEqual(["failure", "clear"]);
  await expect(readFile(filePath, "utf8")).rejects.toMatchObject({
    code: "ENOENT",
  });
});

test("resolves a screenshot route to a page ID without retaining its URL", () => {
  const pages = {
    homePageId: "home",
    rootFolderId: "root",
    pages: new Map([
      ["home", { id: "home", path: "" }],
      ["blog", { id: "blog", path: "/blog/:slug" }],
    ]),
    folders: new Map(),
  } as unknown as Pages;
  expect(
    getIssueReportPageId(
      "screenshot",
      { path: "/blog/private-post?authToken=secret" },
      pages
    )
  ).toBe("blog");
  expect(
    getIssueReportPageId(
      "screenshot",
      { path: "https://private.example/" },
      pages
    )
  ).toBeUndefined();
  expect(
    getIssueReportPageId(
      "screenshot",
      { path: "/blog/private-post", url: "https://private.example/" },
      pages
    )
  ).toBeUndefined();
  expect(
    getIssueReportPageId("list-pages", { path: "/blog/private-post" }, pages)
  ).toBeUndefined();
});

test("restores a successful tool target across CLI processes without private input", async () => {
  const projectRoot = await mkdtemp(
    path.join(tmpdir(), "webstudio-mcp-target-report-")
  );
  tempDirs.push(projectRoot);
  const filePath = getIssueReportFailureFile(projectRoot, "project-1");
  const firstTarget = createIssueReportTargetTracker();
  firstTarget.record(
    "screenshot",
    { path: "/blog/private-post?authToken=secret" },
    "page-1"
  );
  firstTarget.record("inspect-instance", { instanceId: "instance-1" });
  await persistIssueReportFailure(filePath, undefined, firstTarget.snapshot());
  const restoredTarget = createIssueReportTargetTracker();
  await restoreIssueReportFailure(
    filePath,
    createIssueReportFailureTracker(),
    restoredTarget
  );
  expect(restoredTarget.getAll()).toEqual([
    {
      tool: "inspect-instance",
      entityIds: [{ field: "instanceId", id: "instance-1" }],
    },
    { tool: "screenshot", entityIds: [{ field: "pageId", id: "page-1" }] },
  ]);
  expect(await readFile(filePath, "utf8")).not.toContain("private-post");
  expect(await readFile(filePath, "utf8")).not.toContain("authToken");
});

test("preserves a destructive confirmation failure reason without the token or plan", async () => {
  const projectRoot = await mkdtemp(
    path.join(tmpdir(), "webstudio-mcp-confirmation-report-")
  );
  tempDirs.push(projectRoot);
  const filePath = getIssueReportFailureFile(projectRoot, "project-1");
  const operation = publicApiOperations.find(
    ({ command }) => command === "delete-resource"
  );
  if (operation === undefined) {
    throw new Error("Expected delete-resource operation");
  }
  const core = createProjectSessionMcpCore({
    operations: [operation],
    createProjectSession: () => {
      throw new Error("Unexpected session access");
    },
    executeOperation: async () => ({
      operationId: "resources.delete",
      projectId: "project-1",
      buildId: "build-1",
      version: 1,
      source: "dry-run",
      result: { resourceId: "resource-1" },
      state: { committed: false, freshness: {} },
      namespaces: { read: [], write: [], invalidated: [], missing: [] },
      diagnostics: [],
      transaction: {
        id: "plan-1",
        payload: [
          {
            namespace: "resources",
            patches: [{ op: "remove", path: ["resource-1"] }],
          },
        ],
      },
    }),
  });
  const planned = await core.callTool({
    name: "delete-resource",
    input: { resourceId: "resource-1", dryRun: true },
  });
  const token = planned.structuredContent.meta.confirmation?.token;
  if (token === undefined) {
    throw new Error("Expected confirmation token");
  }
  const input = {
    resourceId: "resource-2",
    confirmDestructive: true,
    confirmationToken: token,
  };
  const rejected = await core.callTool({ name: "delete-resource", input });
  const firstProcess = createIssueReportFailureTracker();
  firstProcess.record(
    "delete-resource",
    getMcpToolCallError(rejected),
    100,
    input
  );
  await persistIssueReportFailure(filePath, firstProcess.snapshot());

  const secondProcess = createIssueReportFailureTracker();
  await restoreIssueReportFailure(filePath, secondProcess);
  expect(secondProcess.get()).toMatchObject({
    tool: "delete-resource",
    code: "DESTRUCTIVE_CONFIRMATION_INVALID",
    entityIds: [{ field: "resourceId", id: "resource-2" }],
    issues: [
      {
        path: ["confirmationToken"],
        code: "DESTRUCTIVE_CONFIRMATION_MISMATCH",
        constraint: "unchanged_destructive_plan",
      },
    ],
  });
  const persisted = await readFile(filePath, "utf8");
  expect(persisted).not.toContain(token);
  expect(persisted).not.toContain("resource-1");
  expect(persisted).not.toContain("plan-1");
});

const getArraySchemasWithoutItems = (schema: unknown): unknown[] => {
  if (schema === null || typeof schema !== "object") {
    return [];
  }
  if (Array.isArray(schema)) {
    return schema.flatMap(getArraySchemasWithoutItems);
  }
  const object = schema as Record<string, unknown>;
  return [
    ...(object.type === "array" &&
    object.items === undefined &&
    object.prefixItems === undefined
      ? [object]
      : []),
    ...Object.values(object).flatMap(getArraySchemasWithoutItems),
  ];
};

test("configures MCP commands and options", () => {
  const yargs = {
    command: vi.fn(() => yargs),
    option: vi.fn(() => yargs),
    example: vi.fn(() => yargs),
    epilogue: vi.fn(() => yargs),
  };

  mcpOptions(yargs as never);

  expect(yargs.option).toHaveBeenCalledWith(
    "project",
    expect.objectContaining({ type: "string" })
  );
  expect(yargs.option).toHaveBeenCalledWith(
    "tool-name-format",
    expect.objectContaining({
      choices: ["canonical", "underscores"],
      default: "canonical",
    })
  );

  expect(yargs.command).toHaveBeenCalledWith(
    ["single-op-call <tool> [input]"],
    expect.any(String),
    expect.any(Function),
    expect.any(Function)
  );
  const commandCalls = vi.mocked(yargs.command).mock
    .calls as unknown as CommandCall[];
  const singleOpBuilder = commandCalls.find(
    (call) => call[0][0] === "single-op-call <tool> [input]"
  )?.[2];
  const singleOpYargs = {
    positional: vi.fn(() => singleOpYargs),
    option: vi.fn(() => singleOpYargs),
  };
  singleOpBuilder?.(singleOpYargs as never);
  expect(singleOpYargs.positional).toHaveBeenCalledWith(
    "tool",
    expect.any(Object)
  );
  const runBuilder = commandCalls.find(
    (call) => call[0][0] === "run <input>"
  )?.[2];
  const runYargs = {
    positional: vi.fn(() => runYargs),
    option: vi.fn(() => runYargs),
  };
  runBuilder?.(runYargs as never);
  expect(runYargs.option).toHaveBeenCalledWith("dry-run", expect.any(Object));
  expect(runYargs.option).toHaveBeenCalledWith(
    "approve-mutations",
    expect.objectContaining({ default: false })
  );
  expect(runYargs.option).toHaveBeenCalledWith(
    "concurrency",
    expect.objectContaining({ type: "number" })
  );
  expect(runYargs.option).toHaveBeenCalledWith(
    "resume",
    expect.objectContaining({ default: true })
  );
  expect(yargs.command).toHaveBeenCalledWith(
    ["run <input>"],
    expect.any(String),
    expect.any(Function),
    expect.any(Function)
  );
  expect(yargs.command).toHaveBeenCalledWith(
    ["list-tools"],
    expect.any(String),
    expect.any(Function),
    expect.any(Function)
  );
  expect(yargs.command).toHaveBeenCalledWith(
    ["list-resources"],
    expect.any(String),
    expect.any(Function),
    expect.any(Function)
  );
  expect(yargs.command).toHaveBeenCalledWith(
    ["read-resource <uri>"],
    expect.any(String),
    expect.any(Function),
    expect.any(Function)
  );
});

test("preserves an existing local snapshot before serving MCP tools", async () => {
  const session = {
    snapshot: { version: 42 } as never,
    initialize: vi.fn(async () => undefined),
    markStale: vi.fn(async () => undefined),
  };

  await prepareMcpProjectSession(session);

  expect(session.initialize).toHaveBeenCalled();
  expect(session.markStale).not.toHaveBeenCalled();
});

test("preview session materialization uses the loaded local snapshot", () => {
  const snapshot = { projectId: "project", version: 42 };

  expect(
    getLoadedProjectSessionSnapshot({
      snapshot: snapshot as never,
      initialize: vi.fn(),
      markStale: vi.fn(),
    })
  ).toBe(snapshot);

  expect(() =>
    getLoadedProjectSessionSnapshot({
      snapshot: undefined,
      initialize: vi.fn(),
      markStale: vi.fn(),
    })
  ).toThrow("Project session snapshot is not loaded");
});

test("reports sparse MCP startup status lines for agents", () => {
  const lines: string[] = [];
  const reporter = createMcpStatusReporter((line) => {
    lines.push(line);
  });

  reporter.starting();
  reporter.sessionReady();
  reporter.apiContract({
    clientVersion: "public-api:client",
    serverVersion: "public-api:server",
    supportedOperationIds: new Set(),
    missingServerOperationIds: ["assets.upload"],
    negotiated: true,
  });
  reporter.ready(12);
  reporter.connectionError(new Error("connection reset"));
  reporter.connectionClosed();

  expect(lines).toEqual([
    `[webstudio mcp] starting stdio server from ${process.cwd()}`,
    "[webstudio mcp] project session initialized; existing local snapshot preserved",
    "[webstudio mcp] API contract negotiated: CLI 0.0.0-webstudio-version (public-api:client); server public-api:server; unavailable server procedures: assets.upload",
    "[webstudio mcp] ready with 12 tools; use tools/list, meta.index, or webstudio://project/guide; waiting for JSON-RPC on stdin",
    '[webstudio mcp] lifecycle {"event":"stdio_transport_error","message":"connection reset","recovery":"Reconnect the MCP client. If the error repeats, restart the CLI with npx webstudio@latest mcp."}',
    '[webstudio mcp] lifecycle {"event":"stdio_connection_closed","recovery":"Reconnect the MCP client if this was unexpected."}',
  ]);
});

test("parses empty MCP single-op-call input as an empty argument object", async () => {
  await expect(parseMcpSingleOpCallInput({})).resolves.toEqual({});
});

test("parses inline MCP single-op-call JSON input", async () => {
  await expect(
    parseMcpSingleOpCallInput({
      input: '{"brief":"radix select"}',
    })
  ).resolves.toEqual({ brief: "radix select" });
});

test("parses MCP single-op-call JSON input from a file", async () => {
  const dir = await mkdtemp(
    path.join(tmpdir(), "webstudio-mcp-single-op-call-")
  );
  tempDirs.push(dir);
  const file = path.join(dir, "input.json");
  await writeFile(file, '{"component":"Box"}');

  await expect(parseMcpSingleOpCallInput({ inputFile: file })).resolves.toEqual(
    { component: "Box" }
  );
});

test("rejects ambiguous MCP single-op-call input sources", async () => {
  await expect(
    parseMcpSingleOpCallInput({
      input: "{}",
      inputFile: "input.json",
    })
  ).rejects.toThrow("Use either input or --input-file, not both.");
});

test("reports invalid MCP single-op-call JSON with a stable error code", async () => {
  await expect(
    parseMcpSingleOpCallInput({
      input: "{bad-json",
    })
  ).rejects.toMatchObject({
    code: "INVALID_JSON",
    message: expect.stringContaining(
      "MCP single-op-call input must be valid JSON"
    ),
  });
});

test("rejects long-lived preview tools in MCP single-op-call", () => {
  expect(() => assertSingleOpCallToolSupported("preview.start")).toThrow(
    "preview.start is long-lived"
  );
  expect(() => {
    try {
      assertSingleOpCallToolSupported("preview.start");
    } catch (error) {
      expect(error).toMatchObject({ code: "BAD_REQUEST" });
      throw error;
    }
  }).toThrow();

  expect(() => assertSingleOpCallToolSupported("preview.stop")).toThrow(
    "preview.stop can only stop a preview owned by the same"
  );
  expect(() => {
    try {
      assertSingleOpCallToolSupported("preview.stop");
    } catch (error) {
      expect(error).toMatchObject({ code: "BAD_REQUEST" });
      throw error;
    }
  }).toThrow();

  expect(() => assertSingleOpCallToolSupported("preview.status")).not.toThrow();
});

test("rejects audit input conflicts before creating a project session", () => {
  for (const input of [
    { pageId: "home", pagePath: "/" },
    { rendered: true, cursor: "next" },
  ]) {
    expect(() => validateSingleOpCallInput("audit", input)).toThrow(
      "Audit input is invalid."
    );
    try {
      validateSingleOpCallInput("audit", input);
    } catch (error) {
      expect(error).toMatchObject({
        code: "INVALID_INPUT",
        issues: [
          expect.objectContaining({
            path: expect.any(Array),
            message: expect.any(String),
          }),
        ],
      });
    }
  }
});

test("preserves structured input issues in MCP shell errors", () => {
  expect(
    createMcpSingleOpCallErrorPayload({
      error: Object.assign(new Error("Audit input is invalid."), {
        code: "INVALID_INPUT",
        issues: [
          {
            code: "mutually_exclusive_fields",
            path: ["pagePath"],
            message: "pageId and pagePath are mutually exclusive.",
            constraint: "use_page_id_or_page_path",
          },
        ],
      }),
      elapsedMs: 1,
    })
  ).toMatchObject({
    ok: false,
    error: {
      code: "INVALID_INPUT",
      message:
        "Audit input is invalid.\npagePath: pageId and pagePath are mutually exclusive (use_page_id_or_page_path).",
      issues: [
        {
          code: "mutually_exclusive_fields",
          path: ["pagePath"],
          message: "pageId and pagePath are mutually exclusive.",
          constraint: "use_page_id_or_page_path",
        },
      ],
    },
  });
});

test("parses MCP run call arrays", () => {
  expect(
    parseMcpRunCalls([
      { tool: "components.coverage-plan" },
      {
        tool: "checkpoint.ack",
        input: {
          reported: true,
          continueAfterReport: true,
          summary: "reported checkpoint",
        },
      },
      { tool: "components.find", input: { brief: "button" }, dryRun: true },
    ])
  ).toEqual([
    { tool: "components.coverage-plan", input: {}, dryRun: false },
    {
      tool: "checkpoint.ack",
      input: {
        reported: true,
        continueAfterReport: true,
        summary: "reported checkpoint",
      },
      dryRun: false,
    },
    {
      tool: "components.find",
      input: { brief: "button" },
      dryRun: true,
    },
  ]);
});

test("parses MCP run call objects", () => {
  expect(
    parseMcpRunCalls({
      calls: [
        {
          tool: "insert-component",
          input: { parentInstanceId: "body", component: "Box" },
          "dry-run": true,
        },
      ],
    })
  ).toEqual([
    {
      tool: "insert-component",
      input: { parentInstanceId: "body", component: "Box" },
      dryRun: true,
    },
  ]);
});

test("applies batch dry-run to every MCP run call", () => {
  expect(
    applyMcpRunOptions(
      [
        { tool: "components.find", input: { brief: "button" }, dryRun: false },
        {
          tool: "insert-fragment",
          input: { parentInstanceId: "body", fragment: "<ws.element />" },
          dryRun: false,
        },
      ],
      { dryRun: true }
    )
  ).toEqual([
    { tool: "components.find", input: { brief: "button" }, dryRun: true },
    {
      tool: "insert-fragment",
      input: { parentInstanceId: "body", fragment: "<ws.element />" },
      dryRun: true,
    },
  ]);
});

test("checks persisted checkpoints before every MCP run call", async () => {
  const dir = await mkdtemp(
    path.join(tmpdir(), "webstudio-mcp-run-checkpoint-")
  );
  tempDirs.push(dir);
  const scope = { projectRoot: dir };
  const tools = listProjectSessionMcpTools(publicApiOperations);
  const callTool = vi.fn(async () => ({
    structuredContent: { ok: true, data: {}, meta: {} },
  }));
  const core = { listTools: () => tools, callTool };
  await updatePersistedMcpCheckpoint({
    tool: "workflow.next",
    scope,
    structuredContent: {
      data: { checkpoint: { required: true, instruction: "Report first" } },
    },
  });

  await expect(
    executeMcpRunCall({
      core: core as never,
      call: { tool: "components.get", input: {}, dryRun: false },
      scope,
    })
  ).resolves.toBeDefined();
  await expect(
    executeMcpRunCall({
      core: core as never,
      call: { tool: "create-page", input: {}, dryRun: false },
      scope,
    })
  ).rejects.toMatchObject({ code: "CHECKPOINT_REQUIRED" });
  expect(callTool).toHaveBeenCalledTimes(1);
});

test("formats MCP run checkpoint stops with partial results", () => {
  const result = createMcpRunCheckpointStopPayload({
    checkpoint: {
      tool: "components.coverage-plan",
      message:
        "Stop after this coverage-plan response and report before continuing.",
    },
    completedCalls: 1,
    totalCalls: 3,
    results: [
      {
        tool: "components.coverage-plan",
        ok: true,
        structuredContent: {
          data: {
            checkpoint: {
              required: true,
            },
          },
        },
      },
    ],
    elapsedMs: 123,
  });

  expect(result).toEqual({
    ok: false,
    error: {
      code: "CHECKPOINT_REQUIRED",
      message:
        'Stop after this coverage-plan response and report before continuing. Stop now and report the previous checkpoint to the parent/user. Only after the parent/user continues, call checkpoint.ack {"reported":true,"continueAfterReport":true,"summary":"<what you reported>"} before continuing this run.',
    },
    data: {
      completedCalls: 1,
      stoppedAfterCall: 1,
      totalCalls: 3,
      results: [
        {
          tool: "components.coverage-plan",
          ok: true,
          structuredContent: {
            data: {
              checkpoint: {
                required: true,
              },
            },
          },
        },
      ],
    },
    meta: {
      elapsedMs: 123,
    },
  });
});

test("formats MCP single-op-call failures as structured JSON payloads", () => {
  const error = Object.assign(new Error("Instance not found"), {
    code: "NOT_FOUND",
  });

  expect(
    createMcpSingleOpCallErrorPayload({
      error,
      elapsedMs: 123,
    })
  ).toEqual({
    ok: false,
    error: {
      code: "NOT_FOUND",
      message: "Instance not found",
    },
    meta: {
      elapsedMs: 123,
    },
  });
});

test("formats unknown MCP resource failures as structured JSON", () => {
  expect(
    createMcpResourceErrorPayload(
      new Error('Unknown MCP resource "webstudio://project/unknown".'),
      12
    )
  ).toEqual({
    ok: false,
    error: {
      code: "MCP_RESOURCE_FAILED",
      message: 'Unknown MCP resource "webstudio://project/unknown".',
    },
    meta: { elapsedMs: 12 },
  });
});

test("formats missing Builder API access in MCP single-op-call failures", () => {
  const error = Object.assign(new Error("The credential has been revoked"), {
    code: "INVALID_AUTH_TOKEN",
  });

  expect(
    createMcpSingleOpCallErrorPayload({
      error,
      elapsedMs: 123,
    })
  ).toEqual({
    ok: false,
    error: {
      code: "UNAUTHORIZED",
      message:
        "This project cannot be accessed through the Builder API with the current share link/token. Enable API access in the share-link settings, then relink the project with `webstudio init --link <share-link> --json`.",
    },
    meta: {
      elapsedMs: 123,
    },
  });
});

test("formats MCP run failures as structured JSON payloads", () => {
  const error = Object.assign(new Error("Invalid JSON"), {
    code: "INVALID_JSON",
  });

  expect(
    createMcpRunErrorPayload({
      error,
      completedCalls: 0,
      totalCalls: 0,
      results: [],
      elapsedMs: 12,
    })
  ).toEqual({
    ok: false,
    error: {
      code: "INVALID_JSON",
      message: "Invalid JSON",
    },
    data: {
      completedCalls: 0,
      totalCalls: 0,
      results: [],
    },
    meta: {
      elapsedMs: 12,
    },
  });
});

test("preserves specific nested query errors at single-op and run boundaries", () => {
  const error = {
    code: "BAD_REQUEST",
    message: "The Asset query index changed.",
    data: {
      code: "BAD_REQUEST",
      webstudioCode: "STALE_INDEX",
      issues: [
        {
          code: "STALE_INDEX",
          path: ["indexRevision"],
          message: "Refresh the Asset index and retry.",
          constraint: "current_index_revision",
        },
      ],
    },
  };

  expect(
    createMcpSingleOpCallErrorPayload({ error, elapsedMs: 1 }).error
  ).toMatchObject({
    code: "STALE_INDEX",
    issues: [expect.objectContaining({ path: ["indexRevision"] })],
  });
  expect(
    createMcpRunErrorPayload({
      error,
      completedCalls: 0,
      totalCalls: 1,
      results: [],
      elapsedMs: 1,
    }).error
  ).toMatchObject({
    code: "STALE_INDEX",
    issues: [expect.objectContaining({ path: ["indexRevision"] })],
  });
});

test("reports termination while inserting a styled nested SVG", async () => {
  const operation = publicApiOperations.find(
    ({ command }) => command === "insert-fragment"
  );
  if (operation === undefined) {
    throw new Error("Expected insert-fragment operation");
  }
  const executeOperation = vi.fn(async () => {
    throw new Error("Simulated interrupted operation");
  });
  const core = createProjectSessionMcpCore({
    operations: [operation],
    createProjectSession: () => {
      throw new Error("insert-fragment must use executeOperation");
    },
    executeOperation,
  });
  const fragment = `<ws.element ws:tag="a">
    <ws.element ws:tag="svg" ws:style={css\`pointer-events: none;\`}>
      <ws.element ws:tag="path" />
    </ws.element>
  </ws.element>`;

  await expect(
    core.callTool({
      name: "insert-fragment",
      input: { parentInstanceId: "body", fragment },
      dryRun: true,
    })
  ).rejects.toThrow("Simulated interrupted operation");
  expect(executeOperation).toHaveBeenCalledOnce();

  const writeResult = vi.fn();
  const setExitCode = vi.fn();
  reportMcpSingleOpCallTermination({
    termination: { type: "signal", signal: "SIGTERM" },
    tool: "insert-fragment",
    elapsedMs: 123,
    writeStatus: vi.fn(),
    writeResult,
    setExitCode,
  });

  expect(writeResult).toHaveBeenCalledWith({
    ok: false,
    error: {
      code: "MCP_CALL_TERMINATED",
      message:
        "MCP single-op-call insert-fragment terminated before returning a result.",
    },
    meta: {
      elapsedMs: 123,
      termination: { type: "signal", signal: "SIGTERM" },
    },
  });
  expect(setExitCode).not.toHaveBeenCalled();
});

test("installs termination reporting for an active MCP single-op call", async () => {
  const previousExitCode = process.exitCode;
  const consoleInfo = vi.spyOn(console, "info").mockImplementation(() => {});
  const stderrWrite = vi
    .spyOn(process.stderr, "write")
    .mockImplementation(() => true);

  try {
    const call = mcpSingleOpCall({
      tool: "insert-fragment",
      input: "{invalid-json",
      dryRun: true,
    });
    process.emit("beforeExit", 0);
    await expect(call).rejects.toBeDefined();

    const results = consoleInfo.mock.calls.map(([output]) =>
      JSON.parse(String(output))
    );
    expect(results).toEqual([
      {
        ok: false,
        error: {
          code: "MCP_CALL_TERMINATED",
          message:
            "MCP single-op-call insert-fragment terminated before returning a result.",
        },
        meta: {
          elapsedMs: expect.any(Number),
          termination: { type: "beforeExit", exitCode: 0 },
        },
      },
    ]);
    expect(stderrWrite).toHaveBeenCalledWith(
      "[webstudio mcp] single-op-call insert-fragment terminated: MCP single-op-call insert-fragment terminated before returning a result.\n"
    );
    expect(process.exitCode).toBe(1);
  } finally {
    process.exitCode = previousExitCode;
  }
});

test("preserves completed calls when a run terminates during an asset query preview", () => {
  const completedResults = [
    "status",
    "list-assets",
    "get-asset-field-catalog",
  ].map((tool) => ({
    tool,
    ok: true,
    structuredContent: { ok: true, data: {}, meta: {} },
  }));

  const writeResult = vi.fn();
  const setExitCode = vi.fn();
  reportMcpRunTermination({
    termination: { type: "beforeExit", exitCode: 0 },
    activeCall: { number: 4, tool: "preview-asset-query" },
    totalCalls: 4,
    results: completedResults,
    elapsedMs: 123,
    writeStatus: vi.fn(),
    writeResult,
    setExitCode,
  });

  expect(writeResult).toHaveBeenCalledWith({
    ok: false,
    error: {
      code: "MCP_RUN_TERMINATED",
      message:
        "MCP run terminated before call 4/4 preview-asset-query returned a result.",
    },
    data: {
      completedCalls: 3,
      unfinishedCall: { number: 4, tool: "preview-asset-query" },
      totalCalls: 4,
      results: completedResults,
    },
    meta: {
      elapsedMs: 123,
      termination: { type: "beforeExit", exitCode: 0 },
    },
  });
  expect(setExitCode).toHaveBeenCalledWith(1);
});

test("identifies a signal that terminates preview.start", () => {
  const writeResult = vi.fn();
  const setExitCode = vi.fn();
  const options = {
    termination: { type: "signal" as const, signal: "SIGTERM" as const },
    activeCall: { number: 1, tool: "preview.start" },
    totalCalls: 4,
    results: [],
    elapsedMs: 123,
    writeStatus: vi.fn(),
    writeResult,
    setExitCode,
  };

  reportMcpRunTermination(options);

  expect(writeResult).toHaveBeenCalledWith({
    ok: false,
    error: {
      code: "MCP_RUN_TERMINATED",
      message:
        "MCP run terminated before call 1/4 preview.start returned a result.",
    },
    data: {
      completedCalls: 0,
      unfinishedCall: { number: 1, tool: "preview.start" },
      totalCalls: 4,
      results: [],
    },
    meta: {
      elapsedMs: 123,
      termination: { type: "signal", signal: "SIGTERM" },
    },
  });
  expect(setExitCode).not.toHaveBeenCalled();
});

test("disposes the preview owner before completing signal termination", async () => {
  const disposeHost = vi.fn(async () => undefined);
  const reportTermination = vi.fn();
  const exitWithSignal = vi.fn();
  const controller = createMcpRunTerminationController({
    getActiveCall: () => ({ number: 1, tool: "preview.start" }),
    totalCalls: 4,
    results: [],
    startedAt: Date.now(),
    disposeHost,
    reportTermination,
    exitWithSignal,
  });

  controller.signal("SIGTERM");
  await vi.waitFor(() => expect(exitWithSignal).toHaveBeenCalledOnce());
  controller.signal("SIGINT");

  expect(reportTermination).toHaveBeenCalledWith(
    expect.objectContaining({
      termination: { type: "signal", signal: "SIGTERM" },
      activeCall: { number: 1, tool: "preview.start" },
      totalCalls: 4,
      results: [],
    })
  );
  expect(disposeHost).toHaveBeenCalledOnce();
  expect(exitWithSignal).toHaveBeenCalledWith("SIGTERM");
});

test("completes signal termination when preview cleanup stalls", async () => {
  const exitWithSignal = vi.fn();
  const controller = createMcpRunTerminationController({
    getActiveCall: () => ({ number: 1, tool: "preview.start" }),
    totalCalls: 4,
    results: [],
    startedAt: Date.now(),
    disposeHost: () => new Promise<never>(() => undefined),
    reportTermination: vi.fn(),
    cleanupTimeout: 1,
    exitWithSignal,
  });

  controller.signal("SIGTERM");

  await vi.waitFor(() =>
    expect(exitWithSignal).toHaveBeenCalledWith("SIGTERM")
  );
});

test("preserves already structured MCP run errors", () => {
  expect(
    createMcpRunErrorPayload({
      error: {
        code: "MCP_TOOL_FAILED",
        message:
          "Preview server exited before it became ready at http://127.0.0.1:5192/.",
      },
      completedCalls: 0,
      failedCall: 1,
      totalCalls: 2,
      results: [],
      elapsedMs: 12,
    })
  ).toEqual({
    ok: false,
    error: {
      code: "MCP_TOOL_FAILED",
      message:
        "Preview server exited before it became ready at http://127.0.0.1:5192/.",
    },
    data: {
      completedCalls: 0,
      failedCall: 1,
      totalCalls: 2,
      results: [],
    },
    meta: {
      elapsedMs: 12,
    },
  });
});

test("parses inline MCP run JSON input", async () => {
  await expect(
    parseMcpRunInput('[{"tool":"components.find","input":{"brief":"button"}}]')
  ).resolves.toEqual([
    {
      tool: "components.find",
      input: { brief: "button" },
      dryRun: false,
    },
  ]);
});

test("parses MCP run JSON input from a file", async () => {
  const dir = await mkdtemp(path.join(tmpdir(), "webstudio-mcp-run-"));
  tempDirs.push(dir);
  const file = path.join(dir, "calls.json");
  await writeFile(
    file,
    '{"calls":[{"tool":"components.find","input":{"brief":"button"}}]}'
  );

  await expect(parseMcpRunInput(file)).resolves.toEqual([
    {
      tool: "components.find",
      input: { brief: "button" },
      dryRun: false,
    },
  ]);
});

test("rejects invalid MCP run inputs", () => {
  expect(() => parseMcpRunCalls({})).toThrow(
    'MCP run input must be an array of calls or an object with a "calls" array.'
  );
  expect(() => parseMcpRunCalls({ calls: [] })).toThrow(
    "MCP run input must include at least one call."
  );
  expect(() => parseMcpRunCalls({ calls: [{}] })).toThrow(
    "MCP run calls[0].tool must be a non-empty string."
  );
});

test("reports resolved path and cwd for missing MCP run files", async () => {
  await expect(
    parseMcpRunInput(".temp/missing-mcp-run-file.json")
  ).rejects.toThrow(
    `MCP run input file was not found. Resolved path: ${path.resolve(
      process.cwd(),
      ".temp/missing-mcp-run-file.json"
    )}. Current working directory: ${process.cwd()}.`
  );
});

test("reports invalid MCP run JSON with a stable error code", async () => {
  await expect(parseMcpRunInput("{bad-json")).rejects.toMatchObject({
    code: "INVALID_JSON",
    message: expect.stringContaining("MCP run inline input must be valid JSON"),
  });
});

test("reports explicit MCP startup root for agents", () => {
  const lines: string[] = [];
  const reporter = createMcpStatusReporter((line) => {
    lines.push(line);
  }, "/workspace/webstudio-builder");

  reporter.starting();

  expect(lines).toEqual([
    "[webstudio mcp] starting stdio server from /workspace/webstudio-builder",
  ]);
});

test("adapts MCP upload asset input to public API upload input", () => {
  const input = getMcpOperationInput("upload-asset", {
    asset: {
      name: "image.png",
      type: "image",
      format: "png",
      folderId: "campaign",
      meta: { width: 1200, height: 630 },
    },
    assetsDir: ".webstudio/assets",
  });

  expect(input).toMatchObject({
    asset: { name: "image.png", folderId: "campaign" },
  });
  expect(input).toHaveProperty("readAssetData", expect.any(Function));
});

test("adapts MCP upload assets input to public API upload input", () => {
  const input = getMcpOperationInput("upload-assets", {
    assets: [
      {
        name: "image.png",
        type: "image",
        format: "png",
        meta: { width: 1200, height: 630 },
      },
    ],
    assetsDir: ".webstudio/assets",
  });

  expect(input).toMatchObject({
    assets: [{ name: "image.png" }],
  });
  expect(input).toHaveProperty("readAssetData", expect.any(Function));
});

test("validates font metadata before uploading", () => {
  expect(() =>
    getMcpOperationInput("upload-asset", {
      asset: {
        name: "variable.woff2",
        type: "font",
        format: "woff2",
        meta: { family: "Inter", style: "normal", weight: 400 },
      },
    })
  ).not.toThrow();

  let error: unknown;
  try {
    getMcpOperationInput("upload-assets", {
      assets: [
        {
          name: "variable.woff2",
          type: "font",
          format: "woff2",
          meta: {
            family: "Inter",
            style: "normal",
            weight: "100 900",
            subset: "latin",
          },
        },
      ],
    });
  } catch (caught) {
    error = caught;
  }

  expect(createMcpSingleOpCallErrorPayload({ error, elapsedMs: 1 })).toEqual({
    ok: false,
    error: {
      code: "INVALID_INPUT",
      message: expect.stringContaining("Asset operation input is invalid."),
      issues: expect.arrayContaining([
        expect.objectContaining({
          path: ["assets", "0", "meta", "weight"],
        }),
        expect.objectContaining({
          path: ["assets", "0", "meta", "subset"],
        }),
      ]),
    },
    meta: { elapsedMs: 1 },
  });
});

test("rejects every Markdown and MDX upload filename/format mismatch", () => {
  let error: unknown;
  try {
    getMcpOperationInput("upload-assets", {
      assets: [
        { name: "article.txt", type: "file", format: "md", meta: {} },
        { name: "page.mdx", type: "file", format: "md", meta: {} },
      ],
    });
  } catch (caught) {
    error = caught;
  }

  expect(createMcpSingleOpCallErrorPayload({ error, elapsedMs: 1 })).toEqual({
    ok: false,
    error: {
      code: "INVALID_INPUT",
      message: expect.stringContaining("Asset filename and format must match"),
      issues: [
        expect.objectContaining({ path: ["assets", "0", "format"] }),
        expect.objectContaining({ path: ["assets", "1", "format"] }),
      ],
    },
    meta: { elapsedMs: 1 },
  });
});

test("aggregates every invalid upload descriptor field before reading files", () => {
  let error: unknown;
  try {
    getMcpOperationInput("upload-assets", {
      assetsDir: 42,
      assets: [
        { type: "file" },
        {
          name: "article.md",
          type: "image",
          format: "txt",
          extra: true,
        },
      ],
    });
  } catch (caught) {
    error = caught;
  }

  expect(createMcpSingleOpCallErrorPayload({ error, elapsedMs: 1 })).toEqual({
    ok: false,
    error: {
      code: "INVALID_INPUT",
      message: expect.stringContaining("Asset operation input is invalid."),
      issues: expect.arrayContaining([
        expect.objectContaining({ path: ["assetsDir"] }),
        expect.objectContaining({ path: ["assets", "0", "name"] }),
        expect.objectContaining({ path: ["assets", "1", "extra"] }),
        expect.objectContaining({ path: ["assets", "1", "format"] }),
        expect.objectContaining({ path: ["assets", "1", "type"] }),
      ]),
    },
    meta: { elapsedMs: 1 },
  });
});

test("reports every invalid update content selector field", () => {
  let error: unknown;
  try {
    getMcpOperationInput("update-asset-content", {
      assetId: "",
      expectedName: 42,
      path: "article.md",
      content: "# duplicate source",
      extra: true,
    });
  } catch (caught) {
    error = caught;
  }

  expect(createMcpSingleOpCallErrorPayload({ error, elapsedMs: 1 })).toEqual({
    ok: false,
    error: {
      code: "INVALID_INPUT",
      message: expect.stringContaining("Asset operation input is invalid."),
      issues: expect.arrayContaining([
        expect.objectContaining({ path: ["extra"] }),
        expect.objectContaining({ path: ["assetId"] }),
        expect.objectContaining({ path: ["expectedName"] }),
        expect.objectContaining({
          path: [],
          code: "invalid_source_selection",
        }),
      ]),
    },
    meta: { elapsedMs: 1 },
  });
});

test("adapts MCP asset content input to the shared revision client", async () => {
  const input = getMcpOperationInput("update-asset-content", {
    assetId: "asset-id",
    expectedName: "settings_hash.json",
    extension: "json",
    content: '{"theme":"dark"}',
  }) as {
    assetId: string;
    expectedName: string;
    extension?: string;
    readAssetData: () => Promise<unknown>;
  };

  expect(input).toMatchObject({
    assetId: "asset-id",
    expectedName: "settings_hash.json",
    extension: "json",
  });
  await expect(input.readAssetData()).resolves.toBe('{"theme":"dark"}');
});

test("returns diagnostics without rejecting an invalid MDX Asset write", async () => {
  const source = "# Kept\n\n<ws.element";
  const operationInput = getMcpOperationInput("update-asset-content", {
    assetId: "asset-id",
    expectedName: "article_hash.mdx",
    content: source,
  });

  await expect(
    withTextAssetWriteFeedback({
      command: "update-asset-content",
      input: {
        assetId: "asset-id",
        expectedName: "article_hash.mdx",
        content: source,
      },
      operationInput,
      result: { result: { assetId: "asset-id" } },
    })
  ).resolves.toEqual({
    result: {
      assetId: "asset-id",
      source,
      diagnostics: [
        expect.objectContaining({
          code: "invalid-mdx",
          severity: "error",
        }),
      ],
    },
  });
});

test("rejects invalid UTF-8 before an Asset write can start", async () => {
  const assets = [
    { name: "article.md", type: "file", format: "md", meta: {} },
    { name: "page.mdx", type: "file", format: "mdx", meta: {} },
  ];
  const operationInput = {
    assets,
    readAssetData: vi.fn(async () => new Uint8Array([0xc3, 0x28])),
  };

  await expect(
    prepareTextAssetWriteFeedback({
      command: "upload-assets",
      input: { assets },
      operationInput,
    })
  ).rejects.toMatchObject({
    code: "CONTENT_DECODING_FAILED",
    issues: [
      expect.objectContaining({
        code: "MARKDOWN_BODY_DECODING_FAILED",
        path: ["assets", "0", "name"],
        severity: "error",
      }),
      expect.objectContaining({
        code: "invalid-mdx",
        path: ["assets", "1", "name"],
        severity: "error",
      }),
    ],
  });
  expect(operationInput.readAssetData).toHaveBeenCalledTimes(2);
});

test("rejects oversized inline Markdown before an Asset write can start", async () => {
  const input = {
    assetId: "asset-id",
    expectedName: "article_hash.md",
    content: "x".repeat(contentEngineLimits.hydratedFileBytes + 1),
  };

  await expect(
    prepareTextAssetWriteFeedback({
      command: "update-asset-content",
      input,
      operationInput: getMcpOperationInput("update-asset-content", input),
    })
  ).rejects.toMatchObject({
    code: "CONTENT_LIMIT_EXCEEDED",
    issues: [
      expect.objectContaining({
        code: "MARKDOWN_BODY_BYTES_EXCEEDED",
        path: ["content"],
        severity: "error",
      }),
    ],
  });
});

test("returns complete prepared diagnostics after an Asset write", async () => {
  const source = "{run()}";
  const input = {
    assetId: "asset-id",
    expectedName: "article_hash.mdx",
    content: source,
  };
  const operationInput = getMcpOperationInput("update-asset-content", input);
  const feedback = await prepareTextAssetWriteFeedback({
    command: "update-asset-content",
    input,
    operationInput,
  });

  await expect(
    withTextAssetWriteFeedback({
      command: "update-asset-content",
      input,
      operationInput,
      result: { result: { assetId: "asset-id" } },
      feedback,
    })
  ).resolves.toMatchObject({
    result: {
      assetId: "asset-id",
      source,
      diagnostics: [
        {
          code: "unsafe-mdx",
          severity: "warning",
          message: "Executable MDX expressions are not supported",
          nodeType: "mdxFlowExpression",
          reason: "Executable MDX expressions are not supported",
          sourceRange: {
            start: { line: 1, column: 1, offset: 0 },
            end: { line: 1, column: 8, offset: 7 },
          },
        },
      ],
    },
  });
});

test.each(["png", "woff2", "md", "mdx"])(
  "loads persisted %s assets for downloads without a prior asset query",
  async (format) => {
    const asset = {
      id: "asset-id",
      projectId: "project-id",
      name: `asset.${format}`,
      type: format === "png" ? "image" : format === "woff2" ? "font" : "file",
      format,
      size: 42,
      createdAt: "2026-09-07T00:00:00.000Z",
      updatedAt: "2026-09-07T00:00:00.000Z",
    };
    const ensureNamespaces = vi.fn(async () => ({
      state: { assets: new Map([[asset.id, asset]]) },
    }));
    const session = {
      snapshot: { state: {} },
      ensureNamespaces,
    } as unknown as Parameters<typeof getMcpDownloadAsset>[0];

    await expect(getMcpDownloadAsset(session, asset.id)).resolves.toEqual(
      asset
    );
    expect(ensureNamespaces).toHaveBeenCalledWith(["assets"]);
  }
);

test("rejects invalid UTF-8 downloads with the asset identity", async () => {
  await expect(
    validateDownloadedTextAsset({
      assetId: "asset-1",
      path: "/tmp/broken.md",
      format: "md",
      content: new Uint8Array([0xc3, 0x28]),
    })
  ).rejects.toMatchObject({
    code: "CONTENT_DECODING_FAILED",
    assetId: "asset-1",
    path: "/tmp/broken.md",
    issues: [
      expect.objectContaining({
        code: "MARKDOWN_BODY_DECODING_FAILED",
        severity: "error",
        assetId: "asset-1",
      }),
    ],
  });
});

test("materializes validated remote Asset content without overwriting a conflict", async () => {
  const directory = await mkdtemp(
    path.join(tmpdir(), "webstudio-mcp-download-")
  );
  const remotePath = path.join(directory, "remote.md");
  const localPath = path.join(directory, "local", "article.md");
  await writeFile(remotePath, "# Remote");

  await expect(
    materializeValidatedDownloadedAsset({
      assetId: "asset-1",
      remotePath,
      localPath,
      diagnostics: [],
    })
  ).resolves.toEqual(Buffer.from("# Remote"));
  await expect(readFile(localPath, "utf8")).resolves.toBe("# Remote");

  await writeFile(remotePath, "{unsafe()}");
  await expect(
    materializeValidatedDownloadedAsset({
      assetId: "asset-1",
      remotePath,
      localPath,
      diagnostics: [
        {
          code: "unsafe-mdx",
          severity: "warning",
          message: "Executable MDX expressions are not supported",
          nodeType: "mdxFlowExpression",
          reason: "Executable MDX expressions are not supported",
        },
      ],
    })
  ).rejects.toMatchObject({
    code: "CONFLICT",
    assetId: "asset-1",
    path: localPath,
    issues: [
      expect.objectContaining({
        code: "unsafe-mdx",
        assetId: "asset-1",
        file: localPath,
      }),
      expect.objectContaining({
        code: "local_asset_conflict",
        assetId: "asset-1",
        file: localPath,
      }),
    ],
  });
  await expect(readFile(localPath, "utf8")).resolves.toBe("# Remote");

  await rm(directory, { recursive: true, force: true });
});

test("returns every Markdown frontmatter diagnostic after an Asset write", async () => {
  const source = "---\na: 1\na: 2\nb: 1\nb: 2\n---\n\n# Kept\n";
  const operationInput = getMcpOperationInput("update-asset-content", {
    assetId: "asset-id",
    expectedName: "article_hash.md",
    content: source,
  });

  const response = await withTextAssetWriteFeedback({
    command: "update-asset-content",
    input: {
      assetId: "asset-id",
      expectedName: "article_hash.md",
      content: source,
    },
    operationInput,
    result: { result: { assetId: "asset-id" } },
  });

  expect(response.result).toMatchObject({
    assetId: "asset-id",
    source,
    diagnostics: [
      { code: "FRONTMATTER_INVALID", severity: "warning", line: 3 },
      { code: "FRONTMATTER_INVALID", severity: "warning", line: 5 },
    ],
  });
});

test("returns source diagnostics for every Markdown and MDX upload", async () => {
  const markdown = "---\na: 1\na: 2\n---\n";
  const mdx = "{first()}\n\n{second()}\n";
  const assets = [
    { name: "article.md", type: "file", format: "md", meta: {} },
    { name: "page.mdx", type: "file", format: "mdx", meta: {} },
  ];
  const operationInput = {
    assets,
    readAssetData: async (asset: { name: string }) =>
      asset.name === "article.md" ? markdown : mdx,
  };

  const response = await withTextAssetWriteFeedback({
    command: "upload-assets",
    input: { assets },
    operationInput,
    result: { result: { uploaded: [] } },
  });

  expect(response.result).toMatchObject({
    sourceDiagnostics: [
      {
        index: 0,
        name: "article.md",
        diagnostics: [
          { code: "FRONTMATTER_INVALID", severity: "warning", line: 3 },
        ],
      },
      {
        index: 1,
        name: "page.mdx",
        diagnostics: [
          { code: "unsafe-mdx", severity: "warning" },
          { code: "unsafe-mdx", severity: "warning" },
        ],
      },
    ],
  });
});

test("runs contextual MDX validation with every uploaded Asset id", async () => {
  const source = '<ws.element ws:name="Missing" />';
  const asset = {
    id: "uploaded-id",
    projectId: "project",
    name: "page.mdx",
    type: "file" as const,
    format: "mdx",
    size: source.length,
    createdAt: "2026-01-01T00:00:00.000Z",
  };
  const assets = [{ name: asset.name, type: "file", format: "mdx", meta: {} }];
  const operationInput = {
    assets,
    readAssetData: async () => source,
  };
  const ensureNamespaces = vi.fn(async () => ({
    projectId: "project",
    state: {
      pages: {
        meta: {},
        homePageId: "home",
        rootFolderId: "root",
        pages: new Map([
          [
            "home",
            {
              id: "home",
              name: "Home",
              path: "",
              title: '"Home"',
              meta: {},
              rootInstanceId: "block",
            },
          ],
        ]),
        folders: new Map([
          ["root", { id: "root", name: "Root", slug: "", children: ["home"] }],
        ]),
      },
      instances: new Map([
        [
          "block",
          {
            type: "instance" as const,
            id: "block",
            component: blockComponent,
            children: [{ type: "id" as const, value: "templates" }],
          },
        ],
        [
          "templates",
          {
            type: "instance" as const,
            id: "templates",
            component: blockTemplateComponent,
            children: [],
          },
        ],
      ]),
      props: new Map([
        [
          "src",
          {
            id: "src",
            instanceId: "block",
            name: "src",
            type: "asset" as const,
            value: asset.id,
          },
        ],
      ]),
      dataSources: new Map(),
      resources: new Map(),
      styleSources: new Map(),
      styleSourceSelections: new Map(),
      styles: new Map(),
      breakpoints: new Map(),
      assets: new Map([[asset.id, asset]]),
    },
  }));

  const response = await withTextAssetWriteFeedback({
    command: "upload-assets",
    input: { assets },
    operationInput,
    result: { result: { uploaded: [asset] } },
    session: { ensureNamespaces } as never,
  });

  expect(ensureNamespaces).toHaveBeenCalledOnce();
  expect(response.result).toMatchObject({
    sourceDiagnostics: [
      {
        index: 0,
        name: "page.mdx",
        diagnostics: [
          {
            code: "unresolved-template",
            severity: "warning",
            assetId: "uploaded-id",
            blockInstanceId: "block",
            templateName: "Missing",
          },
        ],
      },
    ],
  });
});

test("validates query setup with the same schema before calling MCP", () => {
  const filter = { field: ["id"], operator: "eq", value: "asset" };
  let nestedWhere: unknown = filter;
  for (let depth = 0; depth < 9; depth += 1) {
    nestedWhere = { all: [nestedWhere] };
  }
  const invalidQueries: Array<[string, unknown]> = [
    ["missing query", {}],
    ["unknown query key", { query: { unknown: true } }],
    ["result mode", { query: { result: "middle" } }],
    ["where shape", { query: { where: {} } }],
    [
      "filter count",
      { query: { where: { all: Array.from({ length: 33 }, () => filter) } } },
    ],
    ["filter depth", { query: { where: nestedWhere } }],
    [
      "empty field path",
      { query: { where: { all: [{ ...filter, field: [] }] } } },
    ],
    [
      "deep field path",
      {
        query: {
          where: {
            all: [{ ...filter, field: Array.from({ length: 10 }, () => "x") }],
          },
        },
      },
    ],
    [
      "bare properties field",
      { query: { where: { all: [{ ...filter, field: ["properties"] }] } } },
    ],
    [
      "unsupported standard field",
      { query: { where: { all: [{ ...filter, field: ["bogus"] }] } } },
    ],
    [
      "operator",
      { query: { where: { all: [{ ...filter, operator: "matches" }] } } },
    ],
    [
      "in value",
      {
        query: {
          where: { all: [{ field: ["id"], operator: "in", value: "asset" }] },
        },
      },
    ],
    [
      "in value count",
      {
        query: {
          where: {
            all: [
              {
                field: ["id"],
                operator: "in",
                value: Array.from({ length: 1_001 }, () => "asset"),
              },
            ],
          },
        },
      },
    ],
    [
      "boolean operator value",
      {
        query: {
          where: {
            all: [{ field: ["id"], operator: "exists", value: "yes" }],
          },
        },
      },
    ],
    [
      "sort count",
      {
        query: {
          sort: Array.from({ length: 9 }, () => ({
            field: ["id"],
            direction: "asc",
          })),
        },
      },
    ],
    [
      "sort direction",
      { query: { sort: [{ field: ["id"], direction: "up" }] } },
    ],
    ["first without sort", { query: { result: "first" } }],
    [
      "empty output",
      {
        query: {
          output: { mode: "fields", includeMetadata: false, fields: [] },
          content: { mode: "none" },
        },
      },
    ],
    [
      "duplicate output fields",
      {
        query: {
          output: {
            mode: "fields",
            includeMetadata: false,
            fields: [["id"], ["id"]],
          },
        },
      },
    ],
    [
      "output field count",
      {
        query: {
          output: {
            mode: "fields",
            includeMetadata: false,
            fields: Array.from({ length: 257 }, (_, index) => [
              "properties",
              String(index),
            ]),
          },
        },
      },
    ],
    ["negative limit", { query: { limit: -1 } }],
    ["fractional limit", { query: { limit: 1.5 } }],
    ["large limit", { query: { limit: 1_001 } }],
    ["negative offset", { query: { offset: -1 } }],
    ["fractional offset", { query: { offset: 1.5 } }],
    ["large offset", { query: { offset: 1_001 } }],
    ["content mode", { query: { content: { mode: "body" } } }],
    [
      "full content bytes",
      { query: { content: { mode: "full", maxBytes: 0 } } },
    ],
    [
      "large full content",
      { query: { content: { mode: "full", maxBytes: 1_048_577 } } },
    ],
    [
      "range offset",
      { query: { content: { mode: "range", offset: -1, length: 1 } } },
    ],
    [
      "range length",
      { query: { content: { mode: "range", offset: 0, length: 0 } } },
    ],
    [
      "large range",
      { query: { content: { mode: "range", offset: 0, length: 262_145 } } },
    ],
    ["empty index revision", { query: {}, indexRevision: "" }],
    ["large index revision", { query: {}, indexRevision: "x".repeat(256) }],
  ];

  for (const [label, input] of invalidQueries) {
    if (label.includes("index revision")) {
      expect(
        () => getMcpOperationInput("preview-asset-query", input),
        label
      ).toThrow();
      continue;
    }
    expect(
      () => getMcpOperationInput("validate-asset-query", input),
      label
    ).toThrow();
    expect(
      () => getMcpOperationInput("preview-asset-query", input),
      label
    ).toThrow();
  }
});

test("formats local query schema failures as structured MCP input errors", () => {
  let error: unknown;
  try {
    getMcpOperationInput("validate-asset-query", {
      query: {
        result: "first",
        limit: -1,
        output: { mode: "fields", includeMetadata: false, fields: [] },
        content: { mode: "none" },
      },
    });
  } catch (caught) {
    error = caught;
  }

  expect(createMcpSingleOpCallErrorPayload({ error, elapsedMs: 1 })).toEqual({
    ok: false,
    error: {
      code: "INVALID_INPUT",
      message: expect.stringContaining("query.limit"),
      issues: [
        expect.objectContaining({ path: ["query", "limit"] }),
        expect.objectContaining({ path: ["query"] }),
        expect.objectContaining({ path: ["query", "sort"] }),
      ],
    },
    meta: { elapsedMs: 1 },
  });
});

test("exposes asset content editing through MCP discovery", () => {
  const tool = listProjectSessionMcpTools(publicApiOperations).find(
    ({ name }) => name === "update-asset-content"
  );

  expect(tool).toMatchObject({
    name: "update-asset-content",
    inputSchema: {
      required: ["assetId", "expectedName"],
      oneOf: [{ required: ["path"] }, { required: ["content"] }],
      properties: {
        assetId: expect.any(Object),
        expectedName: expect.any(Object),
        extension: expect.any(Object),
        path: expect.any(Object),
        content: expect.any(Object),
      },
    },
  });
});

test("exposes a client-valid update-props schema", () => {
  const tool = listProjectSessionMcpTools(publicApiOperations).find(
    ({ name }) => name === "update-props"
  );

  expect(tool).toBeDefined();
  expect(getArraySchemasWithoutItems(tool?.inputSchema)).toEqual([]);
});