Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

10.2 KB
Raw Blame
import { createHash } from 'node:crypto';
import {
  existsSync,
  lstatSync,
  mkdirSync,
  mkdtempSync,
  readFileSync,
  rmSync,
  writeFileSync,
} from 'node:fs';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { InstallSkillSuccessSchema, SkillInstallSuccessSchema } from '@inkeep/open-knowledge-core';
import { afterAll, beforeAll, expect, test, vi } from 'vitest';
import { type Entry, fromBuffer } from 'yauzl';
import type { BootedServer } from './boot.ts';
import { bootCompositionRig, rawRequest } from './composition-rig.test-helper.ts';
import { readSkillStateFile } from './skill-state.ts';

const isolated = vi.hoisted(() => ({ home: '' }));
vi.mock('node:os', async (original) => ({
  ...(await original<typeof import('node:os')>()),
  homedir: () => isolated.home,
}));
let root: string;
let server: BootedServer;
beforeAll(async () => {
  isolated.home = mkdtempSync(join(tmpdir(), 'ok-install-home-'));
  root = mkdtempSync(join(tmpdir(), 'ok-install-contract-'));
  mkdirSync(join(root, '.claude'));
  mkdirSync(join(root, '.cursor'));
  server = await bootCompositionRig(root, { configHomedirOverride: isolated.home });
  await server.ready;
}, 60_000);
afterAll(async () => {
  await server?.destroy();
  rmSync(root, { recursive: true, force: true });
  rmSync(isolated.home, { recursive: true, force: true });
});
async function post(path: string, body: object) {
  return rawRequest(server.port, path, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json', 'X-Request-Id': 'install-contract' },
    body: JSON.stringify(body),
  });
}
test('handoff builds a real archive without opening and ignores force on a current installation', async () => {
  const out = join(isolated.home, 'bundle.skill');
  const first = await post('/api/install-skill', { noOpen: true, out });
  expect(first.status, first.body).toBe(200);
  const built = InstallSkillSuccessSchema.parse(JSON.parse(first.body));
  expect(built).toMatchObject({ status: 'built', outputPath: out });
  const bytes = readFileSync(out);
  expect(built).toMatchObject({
    size: bytes.length,
    sha256: createHash('sha256').update(bytes).digest('hex'),
  });
  const entries = await readArchive(bytes);
  const skill = entries.get('open-knowledge/SKILL.md');
  expect(skill).toMatch(/^name: open-knowledge$/m);
  expect(skill).toContain('OpenKnowledge');
  expect((await readSkillStateFile(isolated.home)).targets['claude-cowork']?.version).toBe(
    built.skillVersion,
  );
  const another = join(isolated.home, 'another.skill');
  const second = await post('/api/install-skill', { noOpen: true, out: another, force: true });
  expect(second.status, second.body).toBe(200);
  expect(InstallSkillSuccessSchema.parse(JSON.parse(second.body))).toMatchObject({
    status: 'skip-current',
  });
  expect(existsSync(another)).toBe(false);
  expect(SkillInstallSuccessSchema.safeParse(JSON.parse(first.body)).success).toBe(false);
  expect(first.headers['x-request-id']).toBe('install-contract');
});

const markdown = (name: string) =>
  `---\nname: ${name}\ndescription: Install contract\n---\n\nLiteral \\* and <custom>raw</custom>.  \n`;
function seed(name: string) {
  const dir = join(root, '.claude/skills', name);
  mkdirSync(join(dir, 'assets'), { recursive: true });
  writeFileSync(join(dir, 'SKILL.md'), markdown(name));
  writeFileSync(join(dir, 'assets/data.bin'), Buffer.from([0, 255, 10]));
  return dir;
}

test('catalog installation projects exact bytes and preserves placement, conversion and source outcomes', async () => {
  const name = 'catalog-contract';
  seed(name);
  const install = async (extra: object) => {
    const response = await post('/api/skill/install', { scope: 'project', name, ...extra });
    expect(response.status, response.body).toBe(200);
    return SkillInstallSuccessSchema.parse(JSON.parse(response.body));
  };
  const result = await install({ targets: ['claude', 'cursor'], mode: 'copy' });
  expect(result.hosts).toContain('cursor');
  expect(InstallSkillSuccessSchema.safeParse(result).success).toBe(false);
  expect(readFileSync(join(root, '.cursor/skills', name, 'SKILL.md'), 'utf8')).toBe(markdown(name));
  expect(readFileSync(join(root, '.cursor/skills', name, 'assets/data.bin'))).toEqual(
    Buffer.from([0, 255, 10]),
  );
  await install({ convert: { target: 'cursor', mode: 'link' } });
  expect(lstatSync(join(root, '.cursor/skills', name)).isSymbolicLink()).toBe(true);
  expect(await install({ place: { dir: 'bundles', mode: 'copy' } })).toMatchObject({
    placedAt: `bundles/${name}`,
  });
  expect(readFileSync(join(root, 'bundles', name, 'SKILL.md'), 'utf8')).toBe(markdown(name));
  await install({ unplace: { path: `bundles/${name}` } });
  expect(existsSync(join(root, 'bundles', name))).toBe(false);
  expect(await install({ source: 'cursor' })).toMatchObject({
    sourceMovedTo: `.cursor/skills/${name}`,
  });
  expect(readFileSync(join(root, '.cursor/skills', name, 'SKILL.md'), 'utf8')).toBe(markdown(name));
});

test('install contracts reject unsafe output, invalid source and conflicting operations independently', async () => {
  const name = 'negative-contract';
  seed(name);
  for (const [path, body, status, detail] of [
    ['/api/install-skill', { noOpen: true, out: join(root, 'outside.skill') }, 400, undefined],
    ['/api/skill/install', { noOpen: true }, 400, undefined],
    ['/api/skill/install', { scope: 'project', name: 'missing' }, 404, undefined],
    [
      '/api/skill/install',
      { scope: 'project', name, place: { dir: '../escape', mode: 'copy' } },
      400,
      'PLACE_PATH_INVALID',
    ],
    ['/api/skill/install', { scope: 'project', name, remove: ['claude'] }, 400, 'REMOVE_SOURCE'],
    [
      '/api/skill/install',
      { scope: 'project', name, convert: { target: 'cursor', mode: 'link' } },
      404,
      'cursor',
    ],
  ] as const) {
    const result = await post(path, body);
    expect(result.status, result.body).toBe(status);
    expect(result.headers['content-type']).toContain('application/problem+json');
    expect(result.headers['x-request-id']).toBe('install-contract');
    if (detail !== undefined) expect(JSON.parse(result.body).detail).toBe(detail);
  }
  expect(existsSync(join(root, 'outside.skill'))).toBe(false);
  const malformed = await rawRequest(server.port, '/api/install-skill', {
    method: 'POST',
    headers: { Origin: 'https://untrusted.example.com' },
    body: '{broken',
  });
  expect(malformed.status, malformed.body).toBe(403);
});

async function readArchive(bytes: Buffer): Promise<Map<string, string>> {
  return new Promise((resolve, reject) => {
    fromBuffer(bytes, { lazyEntries: true }, (error, zip) => {
      if (error) {
        reject(error);
        return;
      }
      const contents = new Map<string, string>();
      zip.on('error', reject);
      zip.on('end', () => resolve(contents));
      zip.on('entry', (entry: Entry) => {
        zip.openReadStream(entry, (streamError, stream) => {
          if (streamError) {
            zip.close();
            reject(streamError);
            return;
          }
          const chunks: Buffer[] = [];
          stream.on('error', reject);
          stream.on('data', (chunk: Buffer) => chunks.push(chunk));
          stream.on('end', () => {
            contents.set(entry.fileName, Buffer.concat(chunks).toString('utf8'));
            zip.readEntry();
          });
        });
      });
      zip.readEntry();
    });
  });
}

test.each(['convert', 'unplace'] as const)(
  '%s preserves an untouched copy after a source edit and reports divergence without assigning blame',
  async (operation) => {
    const name = `source-edit-${operation}`;
    const source = join(seed(name), 'SKILL.md');
    const copyDir = join(root, 'qa048/bundles', name);
    const placement = await post('/api/skill/install', {
      scope: 'project',
      name,
      place: { dir: 'qa048/bundles', mode: 'copy' },
    });
    expect(placement.status, placement.body).toBe(200);
    const originalCopy = readFileSync(join(copyDir, 'SKILL.md'));
    const editedSource = `${markdown(name)}\nSource-only change.\n`;
    writeFileSync(source, editedSource);
    const response = await post('/api/skill/install', {
      scope: 'project',
      name,
      ...(operation === 'convert'
        ? { convert: { target: 'qa048/bundles', mode: 'link' } }
        : { unplace: { path: `qa048/bundles/${name}` } }),
    });
    expect(response.status, response.body).toBe(409);
    expect(JSON.parse(response.body)).toMatchObject({
      type: 'urn:ok:error:doc-already-exists',
      title:
        operation === 'convert'
          ? 'This copy differs from the current source and was preserved. Inspect both versions before replacing or converting it.'
          : 'This copy differs from the current source and was preserved. Inspect both versions before removing it.',
      detail: operation === 'convert' ? 'qa048/bundles' : `qa048/bundles/${name}`,
    });
    expect(readFileSync(join(copyDir, 'SKILL.md'))).toEqual(originalCopy);
    expect(readFileSync(source, 'utf8')).toBe(editedSource);
    expect(lstatSync(copyDir).isSymbolicLink()).toBe(false);
  },
);

test('custom-root removal preserves an untouched copy after a source edit and reports divergence without assigning blame', async () => {
  const name = 'source-edit-custom-remove';
  const source = join(seed(name), 'SKILL.md');
  const copy = join(root, 'qa048/skills', name, 'SKILL.md');
  const placement = await post('/api/skill/install', {
    scope: 'project',
    name,
    place: { dir: 'qa048/skills', mode: 'copy' },
  });
  expect(placement.status, placement.body).toBe(200);
  const originalCopy = readFileSync(copy);
  const editedSource = `${markdown(name)}\nSource-only change.\n`;
  writeFileSync(source, editedSource);
  const response = await post('/api/skill/install', {
    scope: 'project',
    name,
    remove: ['qa048/skills'],
  });
  expect(response.status, response.body).toBe(200);
  expect(SkillInstallSuccessSchema.parse(JSON.parse(response.body))).toMatchObject({
    warnings: [
      `The copy at qa048/skills/${name} differs from the current source and was preserved. Inspect both versions before removing it.`,
    ],
    warningCodes: ['place-fork-refused'],
  });
  expect(readFileSync(copy)).toEqual(originalCopy);
  expect(readFileSync(source, 'utf8')).toBe(editedSource);
});