Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

15.7 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 { afterEach, beforeEach, describe, expect, test } from 'vitest';
import {
  applySkillBundleFileDelete,
  applySkillBundleFileWrite,
  applySkillDelete,
  applySkillMove,
  applySkillWrite,
} from './skills-write.ts';

let root: string;
let skillsRoot: string;

beforeEach(() => {
  root = mkdtempSync(join(tmpdir(), 'ok-skills-'));
  skillsRoot = join(root, '.ok', 'skills');
});
afterEach(() => {
  rmSync(root, { recursive: true, force: true });
});

const fm = (name: string, description = 'Use when testing.') => ({ name, description });

describe('applySkillWrite', () => {
  test('creates SKILL.md with composed name+description frontmatter', () => {
    const result = applySkillWrite({
      boundary: root,
      skillsRoot,
      name: 'trip-log',
      body: '# Steps\n\nDo the thing.',
      frontmatter: fm('trip-log', 'Use when logging a fishing trip.'),
    });
    expect(result.ok).toBe(true);
    if (!result.ok) return;
    expect(result.created).toBe(true);
    expect(result.path).toBe('trip-log/SKILL.md');
    const raw = readFileSync(join(skillsRoot, 'trip-log', 'SKILL.md'), 'utf-8');
    expect(raw).toContain('name: trip-log');
    expect(raw).toContain('description: Use when logging a fishing trip.');
    expect(raw).toContain('# Steps');
    expect(raw).not.toContain('version:');
    expect(raw).not.toContain('title:');
  });

  test('second write reports created:false (overwrite)', () => {
    applySkillWrite({ boundary: root, skillsRoot, name: 's', body: 'a', frontmatter: fm('s') });
    const again = applySkillWrite({
      boundary: root,
      skillsRoot,
      name: 's',
      body: 'b',
      frontmatter: fm('s'),
    });
    expect(again.ok).toBe(true);
    if (again.ok) expect(again.created).toBe(false);
  });

  test('rejects name != directory', () => {
    const result = applySkillWrite({
      boundary: root,
      skillsRoot,
      name: 'trip-log',
      body: 'x',
      frontmatter: fm('different'),
    });
    expect(result.ok).toBe(false);
    if (!result.ok) expect(result.error.code).toBe('NAME_DIR_MISMATCH');
  });

  test('rejects XML tag in description', () => {
    const result = applySkillWrite({
      boundary: root,
      skillsRoot,
      name: 'x',
      body: 'b',
      frontmatter: fm('x', 'Use when <folder> appears.'),
    });
    expect(result.ok).toBe(false);
    if (!result.ok) expect(result.error.code).toBe('XML_TAG_IN_DESCRIPTION');
  });

  test('rejects an uppercase / dotted / spaced name', () => {
    for (const bad of ['TripLog', 'trip.log', 'trip log', 'trip/log']) {
      const result = applySkillWrite({
        boundary: root,
        skillsRoot,
        name: bad,
        body: 'b',
        frontmatter: fm(bad),
      });
      expect(result.ok).toBe(false);
      if (!result.ok) expect(result.error.code).toBe('BAD_NAME');
    }
  });

  test('vendor words in name warn but never block — the marketplace is full of claude-* skills', () => {
    const result = applySkillWrite({
      boundary: root,
      skillsRoot,
      name: 'claude-helper',
      body: 'b',
      frontmatter: fm('claude-helper'),
    });
    expect(result.ok).toBe(true);
    if (result.ok) {
      expect(result.warnings.some((w) => w.includes('"claude"'))).toBe(true);
      expect(result.warningCodes).toEqual(['skill-name-vendor-word']);
    }
  });

  test('allows empty description (draft) and rejects over-long description', () => {
    const empty = applySkillWrite({
      boundary: root,
      skillsRoot,
      name: 'a',
      body: 'b',
      frontmatter: fm('a', ''),
    });
    expect(empty.ok).toBe(true);

    const long = applySkillWrite({
      boundary: root,
      skillsRoot,
      name: 'a',
      body: 'b',
      frontmatter: fm('a', 'x'.repeat(1025)),
    });
    expect(long.ok).toBe(false);
    if (!long.ok) expect(long.error.code).toBe('DESCRIPTION_TOO_LONG');
  });

  test('warns (not errors) on a >500-line body', () => {
    const result = applySkillWrite({
      boundary: root,
      skillsRoot,
      name: 'big',
      body: Array.from({ length: 600 }, (_, i) => `line ${i}`).join('\n'),
      frontmatter: fm('big'),
    });
    expect(result.ok).toBe(true);
    if (result.ok) {
      expect(result.warnings.some((w) => w.includes('600 lines'))).toBe(true);
      expect(result.warningCodes).toEqual(['skill-body-too-long']);
    }
  });

  test('two warnings on one write keep codes positionally aligned with their text', () => {
    const result = applySkillWrite({
      boundary: root,
      skillsRoot,
      name: 'claude-helper',
      body: Array.from({ length: 600 }, (_, i) => `line ${i}`).join('\n'),
      frontmatter: fm('claude-helper'),
    });
    expect(result.ok).toBe(true);
    if (result.ok) {
      expect(result.warningCodes).toEqual(['skill-name-vendor-word', 'skill-body-too-long']);
      expect(result.warnings).toHaveLength(2);
      expect(result.warnings[0]).toContain('"claude"');
      expect(result.warnings[1]).toContain('600 lines');
    }
  });
});

describe('applySkillDelete', () => {
  test('removes the whole skill dir and reports existed', () => {
    applySkillWrite({ boundary: root, skillsRoot, name: 's', body: 'a', frontmatter: fm('s') });
    expect(existsSync(join(skillsRoot, 's'))).toBe(true);
    const result = applySkillDelete({ skillsRoot, name: 's' });
    expect(result.ok).toBe(true);
    if (result.ok) expect(result.existed).toBe(true);
    expect(existsSync(join(skillsRoot, 's'))).toBe(false);
  });

  test('no-op delete of an absent skill reports existed:false', () => {
    const result = applySkillDelete({ skillsRoot, name: 'ghost' });
    expect(result.ok).toBe(true);
    if (result.ok) expect(result.existed).toBe(false);
  });

  test('cleans an emptied .ok/skills then .ok', () => {
    applySkillWrite({
      boundary: root,
      skillsRoot,
      name: 'only',
      body: 'a',
      frontmatter: fm('only'),
    });
    applySkillDelete({ skillsRoot, name: 'only' });
    expect(existsSync(skillsRoot)).toBe(false);
    expect(existsSync(join(root, '.ok'))).toBe(false);
  });
});

describe('applySkillMove', () => {
  const fsRelocate = async (from: string, to: string) => {
    const { renameSync } = await import('node:fs');
    renameSync(from, to);
    return false;
  };

  test('renames the skill dir', async () => {
    applySkillWrite({ boundary: root, skillsRoot, name: 'old', body: 'a', frontmatter: fm('old') });
    const result = await applySkillMove({
      skillsRoot,
      fromName: 'old',
      toName: 'new',
      relocate: fsRelocate,
    });
    expect(result.ok).toBe(true);
    expect(existsSync(join(skillsRoot, 'old'))).toBe(false);
    expect(existsSync(join(skillsRoot, 'new', 'SKILL.md'))).toBe(true);
  });

  test('refuses a collision with an existing destination', async () => {
    applySkillWrite({ boundary: root, skillsRoot, name: 'a', body: 'x', frontmatter: fm('a') });
    applySkillWrite({ boundary: root, skillsRoot, name: 'b', body: 'y', frontmatter: fm('b') });
    const result = await applySkillMove({
      skillsRoot,
      fromName: 'a',
      toName: 'b',
      relocate: fsRelocate,
    });
    expect(result.ok).toBe(false);
    if (!result.ok) expect(result.error.code).toBe('SKILL_EXISTS');
  });

  test('refuses a missing source and a no-op self-move', async () => {
    const missing = await applySkillMove({
      skillsRoot,
      fromName: 'ghost',
      toName: 'x',
      relocate: fsRelocate,
    });
    expect(missing.ok).toBe(false);
    if (!missing.ok) expect(missing.error.code).toBe('SKILL_NOT_FOUND');

    applySkillWrite({
      boundary: root,
      skillsRoot,
      name: 'same',
      body: 'x',
      frontmatter: fm('same'),
    });
    const noop = await applySkillMove({
      skillsRoot,
      fromName: 'same',
      toName: 'same',
      relocate: fsRelocate,
    });
    expect(noop.ok).toBe(false);
    if (!noop.ok) expect(noop.error.code).toBe('NOOP');
  });
});

describe('applySkillBundleFileWrite / applySkillBundleFileDelete (fs-direct)', () => {
  const seedSkill = (name = 'trip-log') =>
    applySkillWrite({ boundary: root, skillsRoot, name, body: '# Steps', frontmatter: fm(name) });

  test('writes a reference + a script into an existing skill (atomic, created flag)', () => {
    seedSkill();
    const ref = applySkillBundleFileWrite({
      boundary: root,
      skillsRoot,
      name: 'trip-log',
      relPath: 'references/gear.md',
      content: '# Gear\n\nRods.',
    });
    expect(ref.ok).toBe(true);
    if (ref.ok) {
      expect(ref.created).toBe(true);
      expect(ref.path).toBe('trip-log/references/gear.md');
    }
    expect(readFileSync(join(skillsRoot, 'trip-log', 'references', 'gear.md'), 'utf-8')).toContain(
      '# Gear',
    );

    const script = applySkillBundleFileWrite({
      boundary: root,
      skillsRoot,
      name: 'trip-log',
      relPath: 'scripts/run.sh',
      content: '#!/usr/bin/env bash\necho hi\n',
    });
    expect(script.ok).toBe(true);
    if (script.ok) expect(script.created).toBe(true);

    const again = applySkillBundleFileWrite({
      boundary: root,
      skillsRoot,
      name: 'trip-log',
      relPath: 'references/gear.md',
      content: '# Gear v2',
    });
    expect(again.ok).toBe(true);
    if (again.ok) expect(again.created).toBe(false);
  });

  test('refuses a write into a skill that does not exist', () => {
    const r = applySkillBundleFileWrite({
      boundary: root,
      skillsRoot,
      name: 'ghost',
      relPath: 'references/x.md',
      content: 'x',
    });
    expect(r.ok).toBe(false);
    if (!r.ok) expect(r.error.code).toBe('SKILL_NOT_FOUND');
  });

  test('rejects an escaping path and an over-cap file', () => {
    seedSkill();
    const escaping = applySkillBundleFileWrite({
      boundary: root,
      skillsRoot,
      name: 'trip-log',
      relPath: 'references/../../escape.md',
      content: 'x',
    });
    expect(escaping.ok).toBe(false);
    if (!escaping.ok) expect(escaping.error.code).toBe('BAD_FILE_PATH');

    const tooLarge = applySkillBundleFileWrite({
      boundary: root,
      skillsRoot,
      name: 'trip-log',
      relPath: 'references/big.md',
      content: 'a'.repeat(256 * 1024 + 1),
    });
    expect(tooLarge.ok).toBe(false);
    if (!tooLarge.ok) expect(tooLarge.error.code).toBe('FILE_TOO_LARGE');
  });

  test('accepts full-directory bundle files (root, non-standard subdir, binary)', () => {
    seedSkill();
    const skillDir = join(skillsRoot, 'trip-log');

    const rootFile = applySkillBundleFileWrite({
      boundary: root,
      skillsRoot,
      name: 'trip-log',
      relPath: 'config.json',
      content: '{"a":1}',
    });
    expect(rootFile.ok).toBe(true);
    expect(readFileSync(join(skillDir, 'config.json'), 'utf-8')).toBe('{"a":1}');

    const asset = applySkillBundleFileWrite({
      boundary: root,
      skillsRoot,
      name: 'trip-log',
      relPath: 'assets/note.txt',
      content: 'hi',
    });
    expect(asset.ok).toBe(true);

    const png = new Uint8Array([0x89, 0x50, 0x00, 0xff]);
    const bin = applySkillBundleFileWrite({
      boundary: root,
      skillsRoot,
      name: 'trip-log',
      relPath: 'assets/logo.png',
      content: null,
      bytes: png,
    });
    expect(bin.ok).toBe(true);
    expect(Array.from(readFileSync(join(skillDir, 'assets', 'logo.png')))).toEqual(Array.from(png));

    const skillMd = applySkillBundleFileWrite({
      boundary: root,
      skillsRoot,
      name: 'trip-log',
      relPath: 'SKILL.md',
      content: 'nope',
    });
    expect(skillMd.ok).toBe(false);
    if (!skillMd.ok) expect(skillMd.error.code).toBe('BAD_FILE_PATH');
  });

  test('enforces the per-skill file-count cap', () => {
    seedSkill();
    for (let i = 0; i < 50; i++) {
      const r = applySkillBundleFileWrite({
        boundary: root,
        skillsRoot,
        name: 'trip-log',
        relPath: `references/r${i}.md`,
        content: `# ${i}`,
      });
      expect(r.ok).toBe(true);
    }
    const overflow = applySkillBundleFileWrite({
      boundary: root,
      skillsRoot,
      name: 'trip-log',
      relPath: 'references/one-too-many.md',
      content: 'x',
    });
    expect(overflow.ok).toBe(false);
    if (!overflow.ok) expect(overflow.error.code).toBe('TOO_MANY_FILES');
  });

  test('the file-count cap ignores withheld entries and links a caller cannot see or delete', () => {
    seedSkill();
    const skillDir = join(skillsRoot, 'trip-log');
    for (const dir of ['.git/objects', '.GIT', 'node_modules/pkg', 'assets']) {
      mkdirSync(join(skillDir, dir), { recursive: true });
    }
    for (let i = 0; i < 30; i++) writeFileSync(join(skillDir, `.git/objects/o${i}`), 'x');
    writeFileSync(join(skillDir, '.GIT/config'), 'x');
    writeFileSync(join(skillDir, 'node_modules/pkg/index.js'), 'x');
    writeFileSync(join(skillDir, 'assets/.DS_Store'), 'x');
    symlinkSync('.git', join(skillDir, 'cfg'), 'dir');
    symlinkSync('.git/objects/o0', join(skillDir, 'leaf'), 'file');
    const writes: string[] = [];
    for (let i = 0; i < 51; i++) {
      const r = applySkillBundleFileWrite({
        boundary: root,
        skillsRoot,
        name: 'trip-log',
        relPath: `references/r${i}.md`,
        content: `# ${i}`,
      });
      writes.push(r.ok ? 'ok' : r.error.code);
    }
    expect(writes).toEqual([...Array(50).fill('ok'), 'TOO_MANY_FILES']);
  });

  test('accepts an explicit bounded policy for bulk import without changing edit defaults', () => {
    seedSkill();
    for (let i = 0; i < 50; i++) {
      expect(
        applySkillBundleFileWrite({
          boundary: root,
          skillsRoot,
          name: 'trip-log',
          relPath: `references/r${i}.md`,
          content: `# ${i}`,
        }).ok,
      ).toBe(true);
    }

    const imported = applySkillBundleFileWrite({
      boundary: root,
      skillsRoot,
      name: 'trip-log',
      relPath: 'assets/large.bin',
      content: null,
      bytes: new Uint8Array(256 * 1024 + 1),
      limits: { maxFiles: 512, maxFileBytes: 16 * 1024 * 1024 },
    });
    expect(imported.ok).toBe(true);
  });

  test('deletes a bundle file and prunes the emptied dir; no-op reports existed:false', () => {
    seedSkill();
    applySkillBundleFileWrite({
      boundary: root,
      skillsRoot,
      name: 'trip-log',
      relPath: 'references/gear.md',
      content: 'x',
    });
    const del = applySkillBundleFileDelete({
      boundary: root,
      skillsRoot,
      name: 'trip-log',
      relPath: 'references/gear.md',
    });
    expect(del.ok).toBe(true);
    if (del.ok) expect(del.existed).toBe(true);
    expect(existsSync(join(skillsRoot, 'trip-log', 'references'))).toBe(false);
    expect(existsSync(join(skillsRoot, 'trip-log', 'SKILL.md'))).toBe(true);

    const noop = applySkillBundleFileDelete({
      boundary: root,
      skillsRoot,
      name: 'trip-log',
      relPath: 'references/gear.md',
    });
    expect(noop.ok).toBe(true);
    if (noop.ok) expect(noop.existed).toBe(false);
  });

  test('deletes a bundle FOLDER recursively, leaving the skill intact', () => {
    seedSkill();
    for (const rel of ['references/deep/a.md', 'references/deep/nested/b.md', 'references/keep.md'])
      applySkillBundleFileWrite({
        boundary: root,
        skillsRoot,
        name: 'trip-log',
        relPath: rel,
        content: 'x',
      });
    const del = applySkillBundleFileDelete({
      boundary: root,
      skillsRoot,
      name: 'trip-log',
      relPath: 'references/deep',
    });
    expect(del.ok).toBe(true);
    if (del.ok) expect(del.existed).toBe(true);
    expect(existsSync(join(skillsRoot, 'trip-log', 'references', 'deep'))).toBe(false);
    expect(existsSync(join(skillsRoot, 'trip-log', 'references', 'keep.md'))).toBe(true);
    expect(existsSync(join(skillsRoot, 'trip-log', 'SKILL.md'))).toBe(true);
  });
});