Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

16.3 KB
Raw Blame
import { mkdirSync, mkdtempSync, realpathSync, writeFileSync } from 'node:fs';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { describe, expect, test } from 'vitest';
import * as Y from 'yjs';
import { connectMcpTestClient } from '../../../server/src/mcp/client.test-helper.ts';
import {
  createTestClient,
  createTestServer,
  pollUntil,
  type TestClient,
  type TestServer,
} from './test-harness';

interface WriteBody {
  docName: string;
  markdown: string;
  position: 'append' | 'prepend' | 'replace';
  agentId?: string;
}

async function setupDoc(server: TestServer, docName: string): Promise<void> {
  const response = await fetch(`${server.baseUrl}/api/create-page`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ path: `${docName}.md` }),
  });
  expect(response.status).toBe(200);
}

function write(server: TestServer, body: WriteBody): Promise<Response> {
  return fetch(`${server.baseUrl}/api/agent-write-md`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(body),
  });
}

function addWysiwygParagraph(client: TestClient, text: string): void {
  const paragraph = new Y.XmlElement('paragraph');
  const leaf = new Y.XmlText();
  leaf.insert(0, text);
  paragraph.insert(0, [leaf]);
  client.fragment.push([paragraph]);
}

async function expectHumanWriteRefused(
  server: TestServer,
  docName: string,
  edit: (client: TestClient) => void,
  agentId: string | undefined = 'agent-after-human',
): Promise<void> {
  await setupDoc(server, docName);
  const client = await createTestClient(server.port, docName);
  try {
    edit(client);
    await pollUntil(() => {
      const document = server.instance.hocuspocus.documents.get(docName);
      return document?.getText('source').toString().includes('Human edit') ?? false;
    });
    const before = server.instance.hocuspocus.documents.get(docName)?.getText('source').toString();
    const response = await write(server, {
      docName,
      markdown: '# Agent replacement\n',
      position: 'replace',
      agentId,
    });
    expect(response.status).toBe(409);
    expect(server.instance.hocuspocus.documents.get(docName)?.getText('source').toString()).toBe(
      before,
    );
  } finally {
    await client.cleanup();
  }
}

describe('concurrent whole-document replace refusal', () => {
  test('two MCP sessions receive edit recovery while HTTP keeps its positional advice', async () => {
    const server = await createTestServer({ debounce: 50, maxDebounce: 200 });
    const clients: Awaited<ReturnType<typeof connectMcpTestClient>>[] = [];
    try {
      const first = await connectMcpTestClient(`${server.baseUrl}/mcp`, { name: 'writer-a' });
      clients.push(first);
      const second = await connectMcpTestClient(`${server.baseUrl}/mcp`, { name: 'writer-b' });
      clients.push(second);
      const docName = `mcp-race-${crypto.randomUUID()}`;
      expect(
        (
          await first.callTool({
            name: 'write',
            arguments: { document: { path: docName, content: '# From A\n\nAlpha.\n' } },
          })
        ).isError,
      ).toBeUndefined();
      const refused = await second.callTool({
        name: 'write',
        arguments: { document: { path: docName, content: '# From B\n', position: 'replace' } },
      });
      expect(refused.isError).toBe(true);
      expect(refused.content).toEqual(
        expect.arrayContaining([
          expect.objectContaining({ type: 'text', text: expect.stringContaining('or use edit') }),
        ]),
      );
      expect(refused.content).toEqual(
        expect.arrayContaining([
          expect.objectContaining({
            type: 'text',
            text: expect.stringContaining('Retry after 3s.'),
          }),
        ]),
      );
      const http = await write(server, {
        docName,
        markdown: '# HTTP replacement\n',
        position: 'replace',
        agentId: 'http-writer',
      });
      expect(http.status).toBe(409);
      expect(await http.json()).toMatchObject({
        detail:
          'Another writer changed this document recently. Wait a few seconds and retry. A write with position append or prepend is not refused.',
      });
      expect(
        (
          await second.callTool({
            name: 'edit',
            arguments: { document: { path: docName, find: 'Alpha.', replace: 'Targeted edit.' } },
          })
        ).isError,
      ).toBeUndefined();
      expect(
        server.instance.hocuspocus.documents.get(docName)?.getText('source').toString(),
      ).toContain('Targeted edit.');
    } finally {
      await Promise.all(clients.map((client) => client.close()));
      await server.cleanup();
    }
  });

  test('two identified agents cannot replace the same document concurrently', async () => {
    const server = await createTestServer({ debounce: 50, maxDebounce: 200 });
    try {
      const docName = `agent-race-${crypto.randomUUID()}`;
      await setupDoc(server, docName);
      const [first, second] = await Promise.all([
        write(server, {
          docName,
          markdown: '# From A\n\nAlpha.\n',
          position: 'replace',
          agentId: 'agent-a',
        }),
        write(server, {
          docName,
          markdown: '# From B\n\nBeta.\n',
          position: 'replace',
          agentId: 'agent-b',
        }),
      ]);
      expect([first.status, second.status].sort()).toEqual([200, 409]);
      const refused = first.status === 409 ? first : second;
      const problem = (await refused.json()) as Record<string, unknown>;
      expect(problem.type).toBe('urn:ok:error:concurrent-overwrite-refused');
      expect(problem.title).toBe('Concurrent overwrite refused.');
      expect(problem.status).toBe(409);
      expect(problem.file).toBe(`${docName}.md`);
      expect(problem.retryAfterSeconds).toBe(3);
      expect(refused.headers.get('Retry-After')).toBe('3');
      expect(problem).toMatchObject({ outcome: 'refused', saved: false, nextStep: 'retry' });
      expect(Object.keys(problem).sort()).toEqual([
        'detail',
        'file',
        'instance',
        'nextStep',
        'outcome',
        'retryAfterSeconds',
        'saved',
        'status',
        'title',
        'type',
      ]);
    } finally {
      await server.cleanup();
    }
  });

  test('an identified agent can replace its own recent write', async () => {
    const server = await createTestServer({ debounce: 50, maxDebounce: 200 });
    try {
      const docName = `same-agent-${crypto.randomUUID()}`;
      await setupDoc(server, docName);
      expect(
        (
          await write(server, {
            docName,
            markdown: '# First\n',
            position: 'replace',
            agentId: 'agent-solo',
          })
        ).status,
      ).toBe(200);
      expect(
        (
          await write(server, {
            docName,
            markdown: '# Second\n',
            position: 'replace',
            agentId: 'agent-solo',
          })
        ).status,
      ).toBe(200);
    } finally {
      await server.cleanup();
    }
  });

  test('an identified patch arms the refusal against a different writer', async () => {
    const server = await createTestServer({ debounce: 50, maxDebounce: 200 });
    try {
      const docName = `patch-seed-${crypto.randomUUID()}`;
      await setupDoc(server, docName);
      expect(
        (
          await write(server, {
            docName,
            markdown: '# Patch target\n\nOriginal body.\n',
            position: 'replace',
          })
        ).status,
      ).toBe(200);

      const patch = await fetch(`${server.baseUrl}/api/agent-patch`, {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({
          docName,
          find: 'Original body.',
          replace: 'Patched body.',
          agentId: 'patch-writer',
        }),
      });
      expect(patch.status).toBe(200);

      const before = server.instance.hocuspocus.documents
        .get(docName)
        ?.getText('source')
        .toString();
      const response = await write(server, {
        docName,
        markdown: '# Peer replacement\n\nReplaced.\n',
        position: 'replace',
        agentId: 'peer-writer',
      });
      expect(response.status).toBe(409);
      expect(((await response.json()) as Record<string, unknown>).type).toBe(
        'urn:ok:error:concurrent-overwrite-refused',
      );
      expect(server.instance.hocuspocus.documents.get(docName)?.getText('source').toString()).toBe(
        before,
      );
      expect(before).toContain('Patched body.');
    } finally {
      await server.cleanup();
    }
  });

  test('a write that supplies no agentId does not arm the refusal against an identified agent', async () => {
    const server = await createTestServer({ debounce: 50, maxDebounce: 200 });
    try {
      const docName = `unattributed-seed-${crypto.randomUUID()}`;
      await setupDoc(server, docName);
      expect(
        (
          await write(server, {
            docName,
            markdown: '# Unattributed seed\n\nSeeded.\n',
            position: 'replace',
          })
        ).status,
      ).toBe(200);
      const response = await write(server, {
        docName,
        markdown: '# Identified replacement\n\nReplaced.\n',
        position: 'replace',
        agentId: 'agent-after-unattributed',
      });
      expect(response.status).toBe(200);
      expect(
        server.instance.hocuspocus.documents.get(docName)?.getText('source').toString(),
      ).toContain('Identified replacement');
    } finally {
      await server.cleanup();
    }
  });

  test('a write that supplies no agentId is refused against a recent identified agent', async () => {
    const server = await createTestServer({ debounce: 50, maxDebounce: 200 });
    try {
      const docName = `identified-seed-${crypto.randomUUID()}`;
      await setupDoc(server, docName);
      expect(
        (
          await write(server, {
            docName,
            markdown: '# Identified seed\n\nSeeded.\n',
            position: 'replace',
            agentId: 'agent-before-unattributed',
          })
        ).status,
      ).toBe(200);
      const response = await write(server, {
        docName,
        markdown: '# Unattributed replacement\n\nReplaced.\n',
        position: 'replace',
      });
      expect(response.status).toBe(409);
      expect(
        server.instance.hocuspocus.documents.get(docName)?.getText('source').toString(),
      ).toContain('Identified seed');
    } finally {
      await server.cleanup();
    }
  });

  test('two writes that both supply no agentId are not refused against each other', async () => {
    const server = await createTestServer({ debounce: 50, maxDebounce: 200 });
    try {
      const docName = `unattributed-pair-${crypto.randomUUID()}`;
      await setupDoc(server, docName);
      expect(
        (
          await write(server, {
            docName,
            markdown: '# First unattributed\n\nAlpha.\n',
            position: 'replace',
          })
        ).status,
      ).toBe(200);
      const second = await write(server, {
        docName,
        markdown: '# Second unattributed\n\nBeta.\n',
        position: 'replace',
      });
      expect(second.status).toBe(200);
      expect(
        server.instance.hocuspocus.documents.get(docName)?.getText('source').toString(),
      ).toContain('Second unattributed');
    } finally {
      await server.cleanup();
    }
  });

  test('an anonymous lint fix does not arm the refusal against an anonymous replace', async () => {
    const root = realpathSync(mkdtempSync(join(tmpdir(), 'ok-anonymous-lint-')));
    mkdirSync(join(root, '.ok', 'local', 'principal.json'), { recursive: true });
    writeFileSync(
      join(root, '.ok', 'config.yml'),
      'contentRules:\n  markdownlint:\n    enabled: true\n',
      'utf-8',
    );
    const docName = `anonymous-lint-${crypto.randomUUID()}`;
    writeFileSync(join(root, `${docName}.md`), '# Doc\n\n\tindented with a hard tab\n', 'utf-8');
    const server = await createTestServer({
      contentDir: root,
      projectDir: root,
      debounce: 50,
      maxDebounce: 200,
    });
    try {
      const fix = await fetch(`${server.baseUrl}/api/lint/fix`, {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ docName }),
      });
      expect(fix.status).toBe(200);
      expect(((await fix.json()) as { fixedCount: number }).fixedCount).toBeGreaterThanOrEqual(1);
      expect(
        server.instance.sessionManager.getLiveSession(docName, 'principal-anonymous'),
      ).toBeDefined();

      const response = await write(server, {
        docName,
        markdown: '# Anonymous replacement\n\nReplaced.\n',
        position: 'replace',
      });
      expect(response.status).toBe(200);
      expect(
        server.instance.hocuspocus.documents.get(docName)?.getText('source').toString(),
      ).toContain('Anonymous replacement');
    } finally {
      await server.cleanup();
    }
  });

  test('an identified lint fix arms the refusal against an unattributed replace', async () => {
    const root = realpathSync(mkdtempSync(join(tmpdir(), 'ok-identified-lint-')));
    mkdirSync(join(root, '.ok'), { recursive: true });
    writeFileSync(
      join(root, '.ok', 'config.yml'),
      'contentRules:\n  markdownlint:\n    enabled: true\n',
      'utf-8',
    );
    const docName = `identified-lint-${crypto.randomUUID()}`;
    writeFileSync(join(root, `${docName}.md`), '# Doc\n\n\tindented with a hard tab\n', 'utf-8');
    const server = await createTestServer({
      contentDir: root,
      projectDir: root,
      debounce: 50,
      maxDebounce: 200,
    });
    try {
      const fix = await fetch(`${server.baseUrl}/api/lint/fix`, {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ docName, agentId: 'lint-writer' }),
      });
      expect(fix.status).toBe(200);
      expect(((await fix.json()) as { fixedCount: number }).fixedCount).toBeGreaterThanOrEqual(1);
      expect(
        server.instance.sessionManager.getLiveSession(docName, 'agent-lint-writer'),
      ).toBeDefined();

      const response = await write(server, {
        docName,
        markdown: '# Identified lint replacement\n\nReplaced.\n',
        position: 'replace',
      });
      expect(response.status).toBe(409);
      expect(((await response.json()) as Record<string, unknown>).type).toBe(
        'urn:ok:error:concurrent-overwrite-refused',
      );
      expect(
        server.instance.hocuspocus.documents.get(docName)?.getText('source').toString(),
      ).not.toContain('Identified lint replacement');
    } finally {
      await server.cleanup();
    }
  });

  test('a connected client that made no edit does not arm the refusal', async () => {
    const server = await createTestServer({ debounce: 50, maxDebounce: 200 });
    try {
      const docName = `idle-client-${crypto.randomUUID()}`;
      await setupDoc(server, docName);
      const client = await createTestClient(server.port, docName);
      try {
        const response = await write(server, {
          docName,
          markdown: '# Agent seed\n',
          position: 'replace',
          agentId: 'agent-after-idle-connect',
        });
        expect(response.status).toBe(200);
      } finally {
        await client.cleanup();
      }
    } finally {
      await server.cleanup();
    }
  });

  test('recent source and rich-text edits are protected', async () => {
    const server = await createTestServer({ debounce: 50, maxDebounce: 200 });
    try {
      await expectHumanWriteRefused(server, `source-human-${crypto.randomUUID()}`, (client) =>
        client.ytext.insert(client.ytext.length, '\nHuman edit in source.\n'),
      );
      await expectHumanWriteRefused(server, `wysiwyg-human-${crypto.randomUUID()}`, (client) =>
        addWysiwygParagraph(client, 'Human edit in rich text.'),
      );
    } finally {
      await server.cleanup();
    }
  });

  test('a write that supplies no agentId is still refused by a recent editor change', async () => {
    const server = await createTestServer({ debounce: 50, maxDebounce: 200 });
    try {
      await expectHumanWriteRefused(
        server,
        `source-human-unattributed-${crypto.randomUUID()}`,
        (client) => client.ytext.insert(client.ytext.length, '\nHuman edit in source.\n'),
        undefined,
      );
    } finally {
      await server.cleanup();
    }
  });
});