Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

19.2 KB
Raw Blame
import {
  existsSync,
  lstatSync,
  mkdirSync,
  mkdtempSync,
  readdirSync,
  readFileSync,
  realpathSync,
  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 {
  linkEditorSkillFolder,
  previewEditorFolderLink,
  unlinkEditorSkillFolder,
} from './skill-folder-links.ts';

const allow = (): boolean => true;

function writeSkill(root: string, rel: string, body: string): void {
  const dir = join(root, rel);
  mkdirSync(dir, { recursive: true });
  writeFileSync(
    join(dir, 'SKILL.md'),
    `---\nname: ${rel.split('/').pop()}\ndescription: d\n---\n${body}`,
  );
}

let base: string;
beforeEach(() => {
  base = mkdtempSync(join(tmpdir(), 'ok-folder-link-'));
});
afterEach(() => {
  rmSync(base, { recursive: true, force: true });
});

describe('linkEditorSkillFolder (merge-then-swap)', () => {
  test('a dangling per-skill symlink never blocks the link', () => {
    writeSkill(base, '.codex/skills/real', '# A');
    symlinkSync(join(base, 'gone-away'), join(base, '.codex/skills/open-knowledge-discovery'));

    const preview = previewEditorFolderLink({
      base,
      folderRel: '.codex/skills',
      targetRootRel: '.agents/skills',
      mayCreate: allow,
    });
    expect(preview.kind).toBe('plan');
    if (preview.kind !== 'plan') return;
    expect(preview.plan.removes).toEqual(['open-knowledge-discovery']);

    const r = linkEditorSkillFolder({
      base,
      folderRel: '.codex/skills',
      targetRootRel: '.agents/skills',
      mayCreate: allow,
    });
    expect(r.ok).toBe(true);
    expect(lstatSync(join(base, '.codex/skills')).isSymbolicLink()).toBe(true);
    expect(existsSync(join(base, '.agents/skills/real/SKILL.md'))).toBe(true);
  });

  test('moves own-only bundles, drops same-hash ones, links the folder', () => {
    writeSkill(base, '.codex/skills/only-here', '# A');
    writeSkill(base, '.codex/skills/both', '# Same');
    writeSkill(base, '.agents/skills/both', '# Same');

    const r = linkEditorSkillFolder({
      base,
      folderRel: '.codex/skills',
      targetRootRel: '.agents/skills',
      mayCreate: allow,
    });
    expect(r.ok).toBe(true);
    if (!r.ok) return;
    expect(r.moved).toEqual(['only-here']);
    expect(r.dropped).toEqual(['both']);
    expect(lstatSync(join(base, '.codex/skills')).isSymbolicLink()).toBe(true);
    expect(realpathSync(join(base, '.codex/skills'))).toBe(
      realpathSync(join(base, '.agents/skills')),
    );
    expect(readFileSync(join(base, '.agents/skills/only-here/SKILL.md'), 'utf-8')).toContain('# A');
  });

  test('a differing bundle ABORTS the whole merge with nothing written', () => {
    writeSkill(base, '.codex/skills/fork', '# Mine');
    writeSkill(base, '.codex/skills/movable', '# B');
    writeSkill(base, '.agents/skills/fork', '# Theirs DIFFERENT');

    const r = linkEditorSkillFolder({
      base,
      folderRel: '.codex/skills',
      targetRootRel: '.agents/skills',
      mayCreate: allow,
    });
    expect(r.ok).toBe(false);
    if (r.ok) return;
    expect(r.reason).toBe('conflicts');
    expect(r.conflicts).toEqual(['fork']);
    expect(lstatSync(join(base, '.codex/skills')).isDirectory()).toBe(true);
    expect(lstatSync(join(base, '.codex/skills')).isSymbolicLink()).toBe(false);
    expect(readFileSync(join(base, '.codex/skills/movable/SKILL.md'), 'utf-8')).toContain('# B');
  });

  test('a DANGLING symlink at the merge destination is replaced, not ENOTDIR-crashed', () => {
    writeSkill(base, '.codex/skills/mover', '# Bytes');
    mkdirSync(join(base, '.agents', 'skills'), { recursive: true });
    symlinkSync(join(base, 'gone-away'), join(base, '.agents/skills/mover'), 'dir');

    const r = linkEditorSkillFolder({
      base,
      folderRel: '.codex/skills',
      targetRootRel: '.agents/skills',
      mayCreate: allow,
    });
    expect(r.ok).toBe(true);
    if (!r.ok) return;
    expect(r.moved).toEqual(['mover']);
    expect(lstatSync(join(base, '.agents/skills/mover')).isDirectory()).toBe(true);
    expect(readFileSync(join(base, '.agents/skills/mover/SKILL.md'), 'utf-8')).toContain('# Bytes');
  });

  test('preserves a foreign per-skill delivery link when linking its host folder', () => {
    writeSkill(base, '.ok/skills/foreign', '# Canonical');
    mkdirSync(join(base, '.codex', 'skills'), { recursive: true });
    symlinkSync(join(base, '.ok/skills/foreign'), join(base, '.codex/skills/foreign'), 'dir');

    const r = linkEditorSkillFolder({
      base,
      folderRel: '.codex/skills',
      targetRootRel: '.agents/skills',
      mayCreate: allow,
    });

    expect(r.ok).toBe(true);
    if (!r.ok) return;
    expect(r.moved).toEqual(['foreign']);
    expect(lstatSync(join(base, '.agents/skills/foreign')).isSymbolicLink()).toBe(true);
    expect(realpathSync(join(base, '.agents/skills/foreign'))).toBe(
      realpathSync(join(base, '.ok/skills/foreign')),
    );
    expect(realpathSync(join(base, '.codex/skills/foreign'))).toBe(
      realpathSync(join(base, '.ok/skills/foreign')),
    );
  });

  test('stray (non-bundle) entries abort; an absent folder links directly', () => {
    mkdirSync(join(base, '.codex/skills'), { recursive: true });
    writeFileSync(join(base, '.codex/skills/notes.txt'), 'stray');
    const r = linkEditorSkillFolder({
      base,
      folderRel: '.codex/skills',
      targetRootRel: '.agents/skills',
      mayCreate: allow,
    });
    expect(r.ok).toBe(false);
    if (!r.ok) expect(r.reason).toBe('stray-entries');

    const r2 = linkEditorSkillFolder({
      base,
      folderRel: '.cursor/skills',
      targetRootRel: '.agents/skills',
      mayCreate: allow,
    });
    expect(r2.ok).toBe(true);
    expect(lstatSync(join(base, '.cursor/skills')).isSymbolicLink()).toBe(true);
  });

  test("a harness's own bookkeeping in its skills folder does not block LINK", () => {
    mkdirSync(join(base, '.codex/skills/foo'), { recursive: true });
    writeFileSync(join(base, '.codex/skills/foo/SKILL.md'), '# foo');
    mkdirSync(join(base, '.codex/skills/.system/imagegen'), { recursive: true });
    writeFileSync(join(base, '.codex/skills/.system/imagegen/SKILL.md'), '# vendor');
    mkdirSync(join(base, '.codex/skills/codex-primary-runtime'), { recursive: true });

    const r = linkEditorSkillFolder({
      base,
      folderRel: '.codex/skills',
      targetRootRel: '.agents/skills',
      mayCreate: allow,
    });
    expect(r.ok).toBe(true);
    expect(lstatSync(join(base, '.codex/skills')).isSymbolicLink()).toBe(true);
  });

  test('a NON-empty directory without a SKILL.md still blocks LINK', () => {
    mkdirSync(join(base, '.codex/skills/notes'), { recursive: true });
    writeFileSync(join(base, '.codex/skills/notes/thoughts.md'), '# real content');
    const r = linkEditorSkillFolder({
      base,
      folderRel: '.codex/skills',
      targetRootRel: '.agents/skills',
      mayCreate: allow,
    });
    expect(r.ok).toBe(false);
    if (!r.ok) expect(r.strays).toContain('notes');
  });

  test('benign dotfiles (.DS_Store) do not count as strays — LINK still succeeds', () => {
    mkdirSync(join(base, '.codex/skills/foo'), { recursive: true });
    writeFileSync(join(base, '.codex/skills/foo/SKILL.md'), '# foo');
    writeFileSync(join(base, '.codex/skills/.DS_Store'), 'noise');
    const r = linkEditorSkillFolder({
      base,
      folderRel: '.codex/skills',
      targetRootRel: '.agents/skills',
      mayCreate: allow,
    });
    expect(r.ok).toBe(true);
    expect(lstatSync(join(base, '.codex/skills')).isSymbolicLink()).toBe(true);
  });
});

describe('previewEditorFolderLink (what a LINK would do)', () => {
  function tree(dir: string): string[] {
    const out: string[] = [];
    const walk = (rel: string): void => {
      for (const e of readdirSync(join(dir, rel), { withFileTypes: true }).sort((a, b) =>
        a.name.localeCompare(b.name),
      )) {
        const p = rel === '' ? e.name : `${rel}/${e.name}`;
        if (e.isSymbolicLink()) {
          out.push(`L ${p}`);
          continue;
        }
        out.push(`${e.isDirectory() ? 'D' : 'F'} ${p}`);
        if (e.isDirectory()) walk(p);
      }
    };
    walk('');
    return out;
  }

  test('classifies exactly what the link then does, and writes nothing', () => {
    writeSkill(base, '.codex/skills/only-here', '# A');
    writeSkill(base, '.codex/skills/both', '# Same');
    writeSkill(base, '.agents/skills/both', '# Same');

    const before = tree(base);
    const p = previewEditorFolderLink({
      base,
      folderRel: '.codex/skills',
      targetRootRel: '.agents/skills',
      mayCreate: allow,
    });
    expect(tree(base)).toEqual(before);
    expect(p.kind).toBe('plan');
    if (p.kind !== 'plan') return;
    expect(p.plan.toMove).toEqual(['only-here']);
    expect(p.plan.toDrop).toEqual(['both']);
    expect(p.plan.removes).toEqual([]);

    const r = linkEditorSkillFolder({
      base,
      folderRel: '.codex/skills',
      targetRootRel: '.agents/skills',
      mayCreate: allow,
    });
    expect(r.ok).toBe(true);
    if (!r.ok) return;
    expect(r.moved).toEqual(p.plan.toMove);
    expect(r.dropped).toEqual(p.plan.toDrop);
  });

  test("names the harness dot-entries the link destroys — they're never moved", () => {
    mkdirSync(join(base, '.codex/skills/foo'), { recursive: true });
    writeFileSync(join(base, '.codex/skills/foo/SKILL.md'), '# foo');
    mkdirSync(join(base, '.codex/skills/.system/imagegen'), { recursive: true });
    writeFileSync(join(base, '.codex/skills/.system/imagegen/SKILL.md'), '# vendor');
    writeFileSync(join(base, '.codex/skills/.DS_Store'), 'noise');

    const p = previewEditorFolderLink({
      base,
      folderRel: '.codex/skills',
      targetRootRel: '.agents/skills',
      mayCreate: allow,
    });
    expect(p.kind).toBe('plan');
    if (p.kind !== 'plan') return;
    expect(p.plan.removes).toEqual(['.system']);

    linkEditorSkillFolder({
      base,
      folderRel: '.codex/skills',
      targetRootRel: '.agents/skills',
      mayCreate: allow,
    });
    expect(existsSync(join(base, '.agents/skills/.system'))).toBe(false);
  });

  test('a per-skill delivery link counts as a move, not a silent drop', () => {
    writeSkill(base, '.ok/skills/foreign', '# Canonical');
    mkdirSync(join(base, '.codex', 'skills'), { recursive: true });
    symlinkSync(join(base, '.ok/skills/foreign'), join(base, '.codex/skills/foreign'), 'dir');

    const p = previewEditorFolderLink({
      base,
      folderRel: '.codex/skills',
      targetRootRel: '.agents/skills',
      mayCreate: allow,
    });
    expect(p.kind).toBe('plan');
    if (p.kind !== 'plan') return;
    expect(p.plan.linkedBundlesToMove.map(({ name }) => name)).toEqual(['foreign']);
    expect(p.plan.toMove).toEqual([]);

    const r = linkEditorSkillFolder({
      base,
      folderRel: '.codex/skills',
      targetRootRel: '.agents/skills',
      mayCreate: allow,
    });
    expect(r.ok).toBe(true);
    if (!r.ok) return;
    expect(r.moved).toEqual(['foreign']);
  });

  test('a skills folder that is its own git repo discloses the .git it will destroy', () => {
    writeSkill(base, '.codex/skills/foo', '# foo');
    mkdirSync(join(base, '.codex/skills/.git/objects'), { recursive: true });
    writeFileSync(join(base, '.codex/skills/.git/HEAD'), 'ref: refs/heads/main');
    writeFileSync(join(base, '.codex/skills/.gitignore'), 'node_modules');

    const p = previewEditorFolderLink({
      base,
      folderRel: '.codex/skills',
      targetRootRel: '.agents/skills',
      mayCreate: allow,
    });
    expect(p.kind).toBe('plan');
    if (p.kind !== 'plan') return;
    expect(p.plan.removes).toEqual(['.git']);

    linkEditorSkillFolder({
      base,
      folderRel: '.codex/skills',
      targetRootRel: '.agents/skills',
      mayCreate: allow,
    });
    expect(existsSync(join(base, '.agents/skills/.git'))).toBe(false);
  });

  test('a live delivery link in the TARGET that the merge overwrites is disclosed', () => {
    writeSkill(base, '.ok/skills/shared', '# Delivered');
    writeSkill(base, '.codex/skills/shared', '# Codex own copy');
    mkdirSync(join(base, '.agents', 'skills'), { recursive: true });
    symlinkSync(join(base, '.ok/skills/shared'), join(base, '.agents/skills/shared'), 'dir');

    const p = previewEditorFolderLink({
      base,
      folderRel: '.codex/skills',
      targetRootRel: '.agents/skills',
      mayCreate: allow,
    });
    expect(p.kind).toBe('plan');
    if (p.kind !== 'plan') return;
    expect(p.plan.liveDestLinks).toEqual(['shared']);
    expect(p.plan.toMove).toEqual(['shared']);

    linkEditorSkillFolder({
      base,
      folderRel: '.codex/skills',
      targetRootRel: '.agents/skills',
      mayCreate: allow,
    });
    expect(lstatSync(join(base, '.agents/skills/shared')).isSymbolicLink()).toBe(false);
    expect(readFileSync(join(base, '.agents/skills/shared/SKILL.md'), 'utf-8')).toContain(
      '# Codex own copy',
    );
    expect(readFileSync(join(base, '.ok/skills/shared/SKILL.md'), 'utf-8')).toContain(
      '# Delivered',
    );
  });

  test('a DANGLING delivery link in the target is cleanup, not a disclosure', () => {
    writeSkill(base, '.codex/skills/mover', '# Bytes');
    mkdirSync(join(base, '.agents', 'skills'), { recursive: true });
    symlinkSync(join(base, 'gone-away'), join(base, '.agents/skills/mover'), 'dir');

    const p = previewEditorFolderLink({
      base,
      folderRel: '.codex/skills',
      targetRootRel: '.agents/skills',
      mayCreate: allow,
    });
    expect(p.kind).toBe('plan');
    if (p.kind !== 'plan') return;
    expect(p.plan.destLinks).toEqual(['mover']);
    expect(p.plan.liveDestLinks).toEqual([]);
  });

  test('reports the conflicts that would abort, without writing', () => {
    writeSkill(base, '.codex/skills/fork', '# Mine');
    writeSkill(base, '.agents/skills/fork', '# Theirs DIFFERENT');

    const before = tree(base);
    const p = previewEditorFolderLink({
      base,
      folderRel: '.codex/skills',
      targetRootRel: '.agents/skills',
      mayCreate: allow,
    });
    expect(tree(base)).toEqual(before);
    expect(p.kind).toBe('conflicts');
    if (p.kind !== 'conflicts') return;
    expect(p.conflicts).toEqual(['fork']);
  });

  test('an absent folder has nothing to disclose', () => {
    const p = previewEditorFolderLink({
      base,
      folderRel: '.cursor/skills',
      targetRootRel: '.agents/skills',
      mayCreate: allow,
    });
    expect(p.kind).toBe('absent');
    expect(existsSync(join(base, '.cursor'))).toBe(false);
  });
});

describe('unlinkEditorSkillFolder (materialize as per-skill links)', () => {
  test('replaces the folder link with a real dir of per-skill symlinks', () => {
    writeSkill(base, '.agents/skills/one', '# 1');
    writeSkill(base, '.agents/skills/two', '# 2');
    mkdirSync(join(base, '.codex'), { recursive: true });
    symlinkSync(join(base, '.agents/skills'), join(base, '.codex/skills'), 'dir');

    const r = unlinkEditorSkillFolder({ base, folderRel: '.codex/skills', mayCreate: allow });
    expect(r.ok).toBe(true);
    if (!r.ok) return;
    expect(r.linked.sort()).toEqual(['one', 'two']);
    expect(lstatSync(join(base, '.codex/skills')).isSymbolicLink()).toBe(false);
    expect(lstatSync(join(base, '.codex/skills/one')).isSymbolicLink()).toBe(true);
    expect(realpathSync(join(base, '.codex/skills/one'))).toBe(
      realpathSync(join(base, '.agents/skills/one')),
    );
  });

  test('exclude leaves the named skill OUT — "this agent should not get that skill"', () => {
    writeSkill(base, '.agents/skills/keep-a', '# A');
    writeSkill(base, '.agents/skills/keep-b', '# B');
    writeSkill(base, '.agents/skills/not-for-codex', '# X');
    mkdirSync(join(base, '.codex'), { recursive: true });
    symlinkSync(join(base, '.agents/skills'), join(base, '.codex/skills'), 'dir');

    const r = unlinkEditorSkillFolder({
      base,
      folderRel: '.codex/skills',
      exclude: ['not-for-codex'],
      mayCreate: allow,
    });
    expect(r.ok).toBe(true);
    if (!r.ok) return;
    expect(r.linked.sort()).toEqual(['keep-a', 'keep-b']);
    expect(existsSync(join(base, '.codex/skills/not-for-codex'))).toBe(false);
    expect(existsSync(join(base, '.agents/skills/not-for-codex/SKILL.md'))).toBe(true);
  });

  test('a real folder refuses to unlink', () => {
    writeSkill(base, '.codex/skills/foo', '# A');
    const r = unlinkEditorSkillFolder({ base, folderRel: '.codex/skills', mayCreate: allow });
    expect(r.ok).toBe(false);
    if (!r.ok) expect(r.reason).toBe('not-linked');
  });
});

describe('mayCreate consent gate', () => {
  let base: string;
  beforeEach(() => {
    base = mkdtempSync(join(tmpdir(), 'ok-maycreate-'));
  });
  afterEach(() => {
    rmSync(base, { recursive: true, force: true });
  });

  const deny = () => false;

  test('refuses when the TARGET root would be created', () => {
    mkdirSync(join(base, '.claude', 'skills'), { recursive: true });
    const r = linkEditorSkillFolder({
      base,
      folderRel: '.claude/skills',
      targetRootRel: '.agents/skills',
      mayCreate: deny,
    });
    expect(r.ok).toBe(false);
    expect(r.ok === false && r.reason).toBe('not-permitted');
    expect(existsSync(join(base, '.agents'))).toBe(false);
  });

  test('refuses when the FOLDER operand would be created — the half a target-only guard missed', () => {
    mkdirSync(join(base, '.agents', 'skills'), { recursive: true });
    const r = linkEditorSkillFolder({
      base,
      folderRel: '.copilot/skills',
      targetRootRel: '.agents/skills',
      mayCreate: deny,
    });
    expect(r.ok).toBe(false);
    expect(r.ok === false && r.reason).toBe('not-permitted');
    expect(existsSync(join(base, '.copilot'))).toBe(false);
  });

  test('names every root it refused, not just the first', () => {
    const p = previewEditorFolderLink({
      base,
      folderRel: '.copilot/skills',
      targetRootRel: '.agents/skills',
      mayCreate: deny,
    });
    expect(p.kind).toBe('not-permitted');
    expect(p.kind === 'not-permitted' && [...p.roots].sort()).toEqual([
      '.agents/skills',
      '.copilot/skills',
    ]);
  });

  test('bypasses the predicate entirely when neither root needs creating', () => {
    mkdirSync(join(base, '.claude', 'skills'), { recursive: true });
    mkdirSync(join(base, '.agents', 'skills'), { recursive: true });
    const r = linkEditorSkillFolder({
      base,
      folderRel: '.claude/skills',
      targetRootRel: '.agents/skills',
      mayCreate: deny,
    });
    expect(r.ok).toBe(true);
  });

  test('PERMITS and creates when the predicate allows — the common path', () => {
    mkdirSync(join(base, '.claude', 'skills'), { recursive: true });
    const r = linkEditorSkillFolder({
      base,
      folderRel: '.claude/skills',
      targetRootRel: '.agents/skills',
      mayCreate: () => true,
    });
    expect(r.ok).toBe(true);
    expect(existsSync(join(base, '.agents', 'skills'))).toBe(true);
  });

  test('asks about the skills-root rel, not an absolute path or the dotdir', () => {
    mkdirSync(join(base, '.claude', 'skills'), { recursive: true });
    const seen: string[] = [];
    linkEditorSkillFolder({
      base,
      folderRel: '.claude/skills',
      targetRootRel: '.agents/skills',
      mayCreate: (rel) => {
        seen.push(rel);
        return true;
      },
    });
    expect(seen).toEqual(['.agents/skills']);
  });
});