Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

15.2 KB
Raw Blame
import {
  existsSync,
  mkdirSync,
  mkdtempSync,
  readFileSync,
  rmSync,
  symlinkSync,
  writeFileSync,
} from 'node:fs';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { afterAll, afterEach, beforeAll, expect, test, vi } from 'vitest';
import type { BootedServer } from './boot.ts';
import { bootCompositionRig, rawRequest } from './composition-rig.test-helper.ts';
import * as contributorTracker from './contributor-tracker.ts';

let root: string;
let server: BootedServer;
let home: string;

beforeAll(async () => {
  root = mkdtempSync(join(tmpdir(), 'ok-skill-file-contract-'));
  const builtin = join(root, '.agents/skills/open-knowledge');
  mkdirSync(builtin, { recursive: true });
  writeFileSync(
    join(builtin, 'SKILL.md'),
    '---\nname: open-knowledge\ndescription: Project instructions\n---\n\nProject.\n',
  );
  home = mkdtempSync(join(tmpdir(), 'ok-skill-file-home-'));
  mkdirSync(join(home, '.claude'));
  server = await bootCompositionRig(root, { configHomedirOverride: home });
  await server.ready;
}, 60_000);

afterEach(() => vi.restoreAllMocks());

afterAll(async () => {
  await server?.destroy();
  rmSync(root, { recursive: true, force: true });
  rmSync(home, { recursive: true, force: true });
});

async function request(path: string, method = 'GET', body?: object) {
  const response = await rawRequest(server.port, path, {
    method,
    headers: { 'Content-Type': 'application/json' },
    ...(body === undefined ? {} : { body: JSON.stringify(body) }),
  });
  expect(response.status, response.body).toBe(200);
  return JSON.parse(response.body);
}

test('reference edits and rename preserve live bytes and writer identity', async () => {
  const attribution = vi.spyOn(contributorTracker, 'recordContributor');
  const name = 'file-contract';
  const skill = await request('/api/skill', 'PUT', {
    name,
    scope: 'project',
    frontmatter: { name, description: 'File contract' },
    body: 'Body.\n',
  });
  const dir = (skill.path as string).slice(0, -9);
  const path = 'references/notes.md';
  const docName = `${dir}/${path.slice(0, -3)}`;
  await request('/api/skill-file', 'PUT', {
    name,
    scope: 'project',
    path,
    content: 'Initial.\n',
    agentId: 'file-writer',
  });
  const session = await server.serverInstance.sessionManager.getSession(
    docName,
    'agent-file-writer',
    { displayName: 'File Writer', colorSeed: 'file-writer' },
  );
  const origins: unknown[] = [];
  const observe = (event: { transaction: { origin: unknown } }) =>
    origins.push(event.transaction.origin);
  session.dc.document.getText('source').observe(observe);
  attribution.mockClear();
  const content = '## Bytes\n\nBackslash \\* and <custom>raw</custom>.  \n\n';
  try {
    const result = await request('/api/skill-file', 'PUT', {
      name,
      scope: 'project',
      path,
      content,
      agentId: 'file-writer',
    });
    expect(result).toMatchObject({ path, kind: 'reference', content: true, created: false });
    expect(session.dc.document.getText('source').toString()).toBe(content);
    expect(readFileSync(join(root, dir, path), 'utf8')).toBe(content);
    expect(origins).toContain(session.origin);
    expect(attribution.mock.calls.map(([doc, writer]) => [doc, writer])).toContainEqual([
      `${dir}/SKILL`,
      'agent-file-writer',
    ]);
  } finally {
    session.dc.document.getText('source').unobserve(observe);
  }
  const oldDocument = session.dc.document;
  attribution.mockClear();
  const renamed = await request('/api/skill-file/rename', 'POST', {
    name,
    scope: 'project',
    from: path,
    to: 'references/renamed.md',
    agentId: 'file-renamer',
  });
  expect(renamed).toMatchObject({
    from: path,
    to: 'references/renamed.md',
    fromDocName: docName,
    toDocName: `${dir}/references/renamed`,
  });
  expect(readFileSync(join(root, dir, 'references/renamed.md'), 'utf8')).toBe(content);
  expect(oldDocument.getMap('lifecycle').get('status')).toBe('deleted-upstream');
  expect(attribution.mock.calls.map(([doc, writer]) => [doc, writer])).toContainEqual([
    `${dir}/SKILL`,
    'agent-file-renamer',
  ]);
  expect((await request(`/api/skill-file?name=${name}&path=references/renamed.md`)).text).toBe(
    content,
  );
  expect(
    (
      await request(
        `/api/skill-file?name=${name}&path=references/renamed.md&agentId=file-writer`,
        'DELETE',
      )
    ).existed,
  ).toBe(true);
  expect(
    (await request(`/api/skill-file?name=${name}&path=references/renamed.md`, 'DELETE')).existed,
  ).toBe(false);
});

test('bundle-file reads retain mutation admission', async () => {
  const response = await rawRequest(server.port, '/api/skill-file?name=missing&path=notes.md', {
    headers: { Origin: 'https://untrusted.example.com' },
  });
  expect(response.status).toBe(403);
});

test('raw bundle writes preserve text, resolve sibling extensions, and reject binary reads', async () => {
  const name = 'raw-file-contract';
  const skill = await request('/api/skill', 'PUT', {
    name,
    scope: 'project',
    frontmatter: { name, description: 'Raw files' },
    body: 'Body.\n',
  });
  const dir = (skill.path as string).slice(0, -9);
  for (const [path, content, kind] of [
    ['scripts/run.sh', '#!/bin/sh\r\nprintf "hello"\r\n', 'script'],
    ['references/example.mdx', '<Example value="raw" />\n\n', 'reference'],
    ['assets/data.txt', 'Unicode: 水\t\r\n', 'file'],
  ]) {
    const written = await request('/api/skill-file', 'PUT', {
      name,
      scope: 'project',
      path,
      content,
    });
    expect(written).toMatchObject({ path, kind, content: false, created: true });
    expect(readFileSync(join(root, dir, path), 'utf8')).toBe(content);
    expect((await request(`/api/skill-file?name=${name}&path=${path}`)).text).toBe(content);
  }
  expect(await request(`/api/skill-file?name=${name}&path=references/example.md`)).toMatchObject({
    path: 'references/example.mdx',
    text: '<Example value="raw" />\n\n',
  });
  writeFileSync(join(root, dir, 'assets/binary.dat'), Buffer.from([0, 255, 10]));
  const binary = await rawRequest(
    server.port,
    `/api/skill-file?name=${name}&path=assets/binary.dat`,
    { headers: { 'X-Request-Id': 'file-binary-contract' } },
  );
  expect(binary.status).toBe(415);
  expect(binary.headers['content-type']).toContain('application/problem+json');
  expect(binary.headers['x-request-id']).toBe('file-binary-contract');
  await request('/api/skill-file/rename', 'POST', {
    name,
    scope: 'project',
    from: 'assets/binary.dat',
    to: 'assets/moved.dat',
  });
  expect(readFileSync(join(root, dir, 'assets/moved.dat'))).toEqual(Buffer.from([0, 255, 10]));
  expect(
    (await request(`/api/skill-file?name=${name}&path=assets/moved.dat`, 'DELETE')).existed,
  ).toBe(true);
});

test('bundle reads withhold VCS, package and OS-artifact entries below the skill root', async () => {
  const name = 'withheld-bundle';
  const skill = await request('/api/skill', 'PUT', {
    name,
    scope: 'project',
    frontmatter: { name, description: 'Withheld entries' },
    body: 'Body.\n',
  });
  const dir = join(root, (skill.path as string).slice(0, -9));
  const token = '[remote "origin"]\n\turl = https://user:[email protected]/r.git\n';
  for (const path of ['.git/config', 'NODE_MODULES/x.md', 'assets/.DS_Store']) {
    mkdirSync(join(dir, path, '..'), { recursive: true });
    writeFileSync(join(dir, path), token);
  }
  writeFileSync(join(dir, 'assets/keep.txt'), 'Keep.\n');

  const got = await request(`/api/skill?name=${name}&scope=project`);
  expect(got.skill.files.map((f: { path: string }) => f.path)).toEqual(['assets/keep.txt']);
  const listed = await request('/api/skills');
  expect(listed.skills.find((s: { name: string }) => s.name === name)?.filePaths).toEqual([
    'assets/keep.txt',
  ]);
  for (const path of ['.git/config', '.GIT/config', 'NODE_MODULES/x.md', 'assets/.DS_Store']) {
    const response = await rawRequest(
      server.port,
      `/api/skill-file?name=${name}&path=${encodeURIComponent(path)}`,
    );
    expect(`${path}=${response.status}`).toBe(`${path}=404`);
  }
  expect((await request(`/api/skill-file?name=${name}&path=assets/keep.txt`)).text).toBe('Keep.\n');
});

test('bundle writes refuse withheld entries below the skill root', async () => {
  const name = 'withheld-writes';
  const skill = await request('/api/skill', 'PUT', {
    name,
    scope: 'project',
    frontmatter: { name, description: 'Withheld writes' },
    body: 'Body.\n',
  });
  const dir = join(root, (skill.path as string).slice(0, -9));
  mkdirSync(join(dir, '.git'), { recursive: true });
  writeFileSync(join(dir, '.git/config'), 'Original.\n');
  await request('/api/skill-file', 'PUT', {
    name,
    scope: 'project',
    path: 'assets/keep.txt',
    content: 'Keep.\n',
  });
  const json = { 'Content-Type': 'application/json' };
  const attempts = {
    put: await rawRequest(server.port, '/api/skill-file', {
      method: 'PUT',
      headers: json,
      body: JSON.stringify({ name, scope: 'project', path: '.GIT/config', content: 'Evil.\n' }),
    }),
    delete: await rawRequest(
      server.port,
      `/api/skill-file?name=${name}&scope=project&path=.git/config`,
      { method: 'DELETE' },
    ),
    rename: await rawRequest(server.port, '/api/skill-file/rename', {
      method: 'POST',
      headers: json,
      body: JSON.stringify({
        name,
        scope: 'project',
        from: 'assets/keep.txt',
        to: 'node_modules/keep.txt',
      }),
    }),
  };
  const withheldTitle =
    'Skill file path falls under an entry Open Knowledge withholds from skill bundles (.git, node_modules, OK and editor host dirs, OS artifact files).';
  for (const [verb, response] of Object.entries(attempts)) {
    expect(`${verb}=${response.status} ${JSON.parse(response.body).title}`).toBe(
      `${verb}=400 ${withheldTitle}`,
    );
  }
  expect(readFileSync(join(dir, '.git/config'), 'utf-8')).toBe('Original.\n');
  expect(readFileSync(join(dir, 'assets/keep.txt'), 'utf-8')).toBe('Keep.\n');
});

test('bundle reads and writes refuse paths a symlink resolves into a withheld entry or out of the skill', async () => {
  const name = 'linked-bundle';
  const skill = await request('/api/skill', 'PUT', {
    name,
    scope: 'project',
    frontmatter: { name, description: 'Linked entries' },
    body: 'Body.\n',
  });
  const dir = join(root, (skill.path as string).slice(0, -9));
  const outside = mkdtempSync(join(tmpdir(), 'ok-skill-file-outside-'));
  writeFileSync(join(outside, 'secret.txt'), 'Outside.\n');
  mkdirSync(join(dir, '.git'));
  writeFileSync(join(dir, '.git/config'), 'Original.\n');
  writeFileSync(join(dir, '.git/HEAD'), 'ref: refs/heads/main\n');
  mkdirSync(join(dir, '.git/objects'));
  await request('/api/skill-file', 'PUT', {
    name,
    scope: 'project',
    path: 'assets/keep.txt',
    content: 'Keep.\n',
  });
  symlinkSync('.git', join(dir, 'cfg'), 'dir');
  symlinkSync('.git', join(dir, 'references'), 'dir');
  symlinkSync('.git/config', join(dir, 'leaf'), 'file');
  symlinkSync('.git/config', join(dir, 'notes.mdx'), 'file');
  symlinkSync(outside, join(dir, 'ext'), 'dir');
  symlinkSync('.git/newfile', join(dir, 'dangling'), 'file');
  symlinkSync('.git/objects', join(dir, 'y'), 'dir');
  symlinkSync('y/../info/attributes', join(dir, 'dotdot'), 'file');
  try {
    const reads: Record<string, number> = {};
    for (const path of ['cfg/config', 'leaf', 'notes.md', 'ext/secret.txt']) {
      const response = await rawRequest(
        server.port,
        `/api/skill-file?name=${name}&path=${encodeURIComponent(path)}`,
      );
      reads[path] = response.status;
    }
    const put = (path: string) =>
      rawRequest(server.port, '/api/skill-file', {
        method: 'PUT',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ name, scope: 'project', path, content: 'Evil.\n' }),
      });
    const rename = (from: string, to: string) =>
      rawRequest(server.port, '/api/skill-file/rename', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ name, scope: 'project', from, to }),
      });
    const writes: Record<string, number> = {
      'put cfg/config': (await put('cfg/config')).status,
      'put references/config.md': (await put('references/config.md')).status,
      'put ext/secret.txt': (await put('ext/secret.txt')).status,
      'put dangling': (await put('dangling')).status,
      'put dotdot': (await put('dotdot')).status,
      'rename to cfg/keep.txt': (await rename('assets/keep.txt', 'cfg/keep.txt')).status,
      'rename cfg/config': (await rename('cfg/config', 'assets/moved.txt')).status,
      'delete cfg/HEAD': (
        await rawRequest(server.port, `/api/skill-file?name=${name}&scope=project&path=cfg/HEAD`, {
          method: 'DELETE',
        })
      ).status,
    };
    expect({ reads, writes }).toEqual({
      reads: { 'cfg/config': 404, leaf: 404, 'notes.md': 404, 'ext/secret.txt': 400 },
      writes: {
        'put cfg/config': 400,
        'put references/config.md': 400,
        'put ext/secret.txt': 400,
        'put dangling': 400,
        'put dotdot': 400,
        'rename to cfg/keep.txt': 400,
        'rename cfg/config': 400,
        'delete cfg/HEAD': 400,
      },
    });
    expect(readFileSync(join(dir, '.git/config'), 'utf-8')).toBe('Original.\n');
    expect(existsSync(join(dir, '.git/HEAD'))).toBe(true);
    expect(existsSync(join(dir, '.git/config.md'))).toBe(false);
    expect(existsSync(join(dir, '.git/keep.txt'))).toBe(false);
    expect(existsSync(join(dir, '.git/newfile'))).toBe(false);
    expect(existsSync(join(dir, '.git/info/attributes'))).toBe(false);
    expect(existsSync(join(dir, 'info/attributes'))).toBe(false);
    expect(readFileSync(join(dir, 'assets/keep.txt'), 'utf-8')).toBe('Keep.\n');
    expect(readFileSync(join(outside, 'secret.txt'), 'utf-8')).toBe('Outside.\n');
  } finally {
    rmSync(outside, { recursive: true, force: true });
  }
});

test('bundle path and size errors leave the existing file unchanged', async () => {
  const name = 'file-errors';
  await request('/api/skill', 'PUT', {
    name,
    scope: 'project',
    frontmatter: { name, description: 'Errors' },
    body: 'Body.\n',
  });
  await request('/api/skill-file', 'PUT', {
    name,
    scope: 'project',
    path: 'assets/keep.txt',
    content: 'Keep.\n',
  });
  for (const body of [
    { path: '../outside.txt', content: 'Escape' },
    { path: 'SKILL.md', content: 'Overwrite' },
    { path: 'assets/keep.txt', content: 'x'.repeat(256 * 1024 + 1) },
  ]) {
    const response = await rawRequest(server.port, '/api/skill-file', {
      method: 'PUT',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ name, scope: 'project', ...body }),
    });
    expect(response.status, response.body).toBe(400);
    expect(response.headers['content-type']).toContain('application/problem+json');
  }
  const missing = await rawRequest(server.port, '/api/skill-file/rename', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      name,
      scope: 'project',
      from: 'assets/missing.txt',
      to: 'assets/keep.txt',
    }),
  });
  expect(missing.status).toBe(400);
  expect((await request(`/api/skill-file?name=${name}&path=assets/keep.txt`)).text).toBe('Keep.\n');
});