Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
import { existsSync, mkdirSync, mkdtempSync, rmSync, symlinkSync, writeFileSync } from 'node:fs';
import { mkdtemp, rm } from 'node:fs/promises';
import { tmpdir } from 'node:os';
import { join, resolve } from 'node:path';
import { afterEach, beforeEach, describe, expect, test } from 'vitest';
import {
healUnservableSkillAdmission,
indexedSkillContentPath,
type SkillAdmissionHealState,
safeSubdir,
sanitizeFilename,
} from './api-extension.test-helper.ts';
import { listenOnLoopback } from './loopback-rig-test-helpers.ts';
describe('safeSubdir', () => {
const baseDir = '/home/user/content';
test('resolves a valid subdirectory', () => {
expect(safeSubdir(baseDir, 'notes')).toBe(resolve(baseDir, 'notes'));
});
test('resolves nested subdirectories', () => {
expect(safeSubdir(baseDir, 'notes/meetings')).toBe(resolve(baseDir, 'notes/meetings'));
});
test('allows the base directory itself (empty string)', () => {
expect(safeSubdir(baseDir, '')).toBe(baseDir);
});
test('allows "." as the subdirectory', () => {
expect(safeSubdir(baseDir, '.')).toBe(baseDir);
});
test('rejects path traversal with ..', () => {
expect(() => safeSubdir(baseDir, '..')).toThrow('Invalid directory');
});
test('rejects path traversal with ../sibling', () => {
expect(() => safeSubdir(baseDir, '../etc')).toThrow('Invalid directory');
});
test('rejects traversal via nested ../..', () => {
expect(() => safeSubdir(baseDir, 'sub/../../..')).toThrow('Invalid directory');
});
test('rejects absolute paths outside base', () => {
expect(() => safeSubdir(baseDir, '/etc/passwd')).toThrow('Invalid directory');
});
});
describe('sanitizeFilename', () => {
test('strips path separators', () => {
expect(sanitizeFilename('foo/bar.png')).toBe('foobar.png');
expect(sanitizeFilename('foo\\bar.png')).toBe('foobar.png');
});
test('preserves whitelisted characters (space, dot, dash, underscore)', () => {
expect(sanitizeFilename('my file (1).png')).toBe('my file _1_.png');
});
test('preserves simple alphanumeric names byte-identical', () => {
expect(sanitizeFilename('screenshot-2024.png')).toBe('screenshot-2024.png');
});
test('falls back to "upload" for truly empty name', () => {
expect(sanitizeFilename('')).toBe('upload');
});
test('CJK (Japanese) characters preserved', () => {
expect(sanitizeFilename('会議メモ.pdf')).toBe('会議メモ.pdf');
});
test('CJK (Chinese) characters preserved', () => {
expect(sanitizeFilename('文件.docx')).toBe('文件.docx');
});
test('CJK (Korean) characters preserved', () => {
expect(sanitizeFilename('문서.pdf')).toBe('문서.pdf');
});
test('Arabic characters preserved', () => {
expect(sanitizeFilename('قصة.pdf')).toBe('قصة.pdf');
});
test('Cyrillic characters preserved', () => {
expect(sanitizeFilename('Проект.docx')).toBe('Проект.docx');
});
test('emoji preserved — Finder/macOS ergonomics', () => {
expect(sanitizeFilename('emoji 🎉.png')).toBe('emoji 🎉.png');
});
test('combining marks (Vietnamese tone, Devanagari) preserved', () => {
expect(sanitizeFilename('ghi chú.pdf')).toBe('ghi chú.pdf');
});
test('path-escape attempt ../etc/passwd is flattened — no traversal survives', () => {
expect(sanitizeFilename('../etc/passwd')).toBe('etcpasswd');
});
test('Windows-style path traversal stripped', () => {
expect(sanitizeFilename('..\\Windows\\System32\\evil.exe')).toBe('WindowsSystem32evil.exe');
});
test('null byte stripped', () => {
expect(sanitizeFilename('foo\x00bar.png')).toBe('foobar.png');
});
test('CRLF stripped', () => {
expect(sanitizeFilename('foo\r\nbar.png')).toBe('foobar.png');
});
test('control characters stripped', () => {
expect(sanitizeFilename('foo\x01\x02\x1fbar.png')).toBe('foobar.png');
});
test('DEL (0x7f) stripped', () => {
expect(sanitizeFilename('foo\x7fbar.png')).toBe('foobar.png');
});
test('hidden file leading dot trimmed', () => {
expect(sanitizeFilename('.env')).toBe('env');
});
test('multiple leading dots trimmed', () => {
expect(sanitizeFilename('...config')).toBe('config');
});
test('trailing dots stripped (Windows portability)', () => {
expect(sanitizeFilename('foo.png...')).toBe('foo.png');
});
test('consecutive underscores collapsed', () => {
expect(sanitizeFilename('foo!!!bar.png')).toBe('foo_bar.png');
});
test('dot-only input falls back to upload', () => {
expect(sanitizeFilename('...')).toBe('upload');
});
test('single dot falls back to upload', () => {
expect(sanitizeFilename('.')).toBe('upload');
});
test('long adversarial extension falls back to upload', () => {
expect(sanitizeFilename(`x.${'a'.repeat(300)}`)).toBe('upload');
});
test('pure unsafe-character input falls back to upload', () => {
expect(sanitizeFilename('!!!')).toBe('upload');
});
test('mixed script preserved', () => {
expect(sanitizeFilename('会議-notes-Проект.pdf')).toBe('会議-notes-Проект.pdf');
});
});
describe('handleUploadAsset', () => {
let tmpDir: string;
let contentDir: string;
let server: import('node:http').Server;
let port: number;
let attachmentFolderPath: string;
let getAttachmentFolderPath: () => string;
beforeEach(async () => {
tmpDir = await mkdtemp(join(tmpdir(), 'upload-test-'));
contentDir = join(tmpDir, 'content');
attachmentFolderPath = './';
getAttachmentFolderPath = () => attachmentFolderPath;
mkdirSync(contentDir, { recursive: true });
mkdirSync(join(contentDir, 'docs'), { recursive: true });
writeFileSync(join(contentDir, 'docs', 'guide.md'), '# Guide');
const { Hocuspocus } = await import('@hocuspocus/server');
const { AgentSessionManager } = await import('./agent-sessions.ts');
const { createApiExtension } = await import('./api-extension.test-helper.ts');
const hocuspocus = new Hocuspocus({ quiet: true });
const sessionManager = new AgentSessionManager(hocuspocus);
const ext = createApiExtension({
hocuspocus,
sessionManager,
contentDir,
getFileIndex: () => new Map(),
getAttachmentFolderPath: () => getAttachmentFolderPath(),
serverInstanceId: 'test-instance',
});
const { createServer } = await import('node:http');
server = createServer((req, res) => {
// biome-ignore lint/suspicious/noExplicitAny: test harness
hocuspocus.hooks('onRequest', { request: req, response: res } as any).catch(() => {
if (!res.writableEnded) {
res.writeHead(500);
res.end('Error');
}
});
});
hocuspocus.configuration.extensions.push(ext);
({ port } = await listenOnLoopback(server));
});
afterEach(async () => {
await new Promise<void>((res) => server.close(() => res()));
await rm(tmpDir, { recursive: true, force: true });
});
function createPngBuffer(): Buffer {
return Buffer.from(
'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAAC0lEQVQI12NgAAIABQABNjN9GQAAAABJRElEQrkJggg==',
'base64',
);
}
function createSvgBuffer(): Buffer {
return Buffer.from(
'<svg xmlns="http://www.w3.org/2000/svg"><rect width="1" height="1"/></svg>',
);
}
async function uploadImage(
file: Buffer,
filename: string,
parentDocName: string,
placement?: 'configured-attachments' | 'parent-dir',
): Promise<Response> {
const formData = new FormData();
formData.append('parentDocName', parentDocName);
if (placement !== undefined) formData.append('placement', placement);
formData.append('file', new Blob([file]), filename);
return fetch(`http://127.0.0.1:${port}/api/upload`, {
method: 'POST',
body: formData,
});
}
test('happy path: sibling upload with parentDocName', async () => {
const res = await uploadImage(createPngBuffer(), 'screenshot.png', 'docs/guide.md');
const body = (await res.json()) as { src: string; path: string; deduped: boolean };
expect(res.status).toBe(200);
expect(res.headers.get('content-type')).toBe('application/json');
expect(body.src).toBe('screenshot.png');
expect(body.path).toBe('docs/screenshot.png');
expect(body.deduped).toBe(false);
expect(existsSync(join(contentDir, 'docs', 'screenshot.png'))).toBe(true);
expect((body as Record<string, unknown>).ok).toBeUndefined();
});
test('configured content-root folder stores upload under fixed attachments directory', async () => {
attachmentFolderPath = '/attachments';
const res = await uploadImage(createPngBuffer(), 'diagram.png', 'docs/guide.md');
const body = (await res.json()) as { src: string; path: string; deduped: boolean };
expect(res.status).toBe(200);
expect(body.src).toBe('diagram.png');
expect(body.path).toBe('attachments/diagram.png');
expect(body.deduped).toBe(false);
expect(existsSync(join(contentDir, 'attachments', 'diagram.png'))).toBe(true);
expect(existsSync(join(contentDir, 'docs', 'diagram.png'))).toBe(false);
});
test('configured current-folder subfolder stores upload beside current document folder', async () => {
attachmentFolderPath = './attachments';
const res = await uploadImage(createPngBuffer(), 'diagram.png', 'docs/guide.md');
const body = (await res.json()) as { src: string; path: string };
expect(res.status).toBe(200);
expect(body.path).toBe('docs/attachments/diagram.png');
expect(existsSync(join(contentDir, 'docs', 'attachments', 'diagram.png'))).toBe(true);
});
test('configured content-root sentinel stores upload at the content root', async () => {
attachmentFolderPath = '/';
const res = await uploadImage(createPngBuffer(), 'rooted.png', 'docs/guide.md');
const body = (await res.json()) as { src: string; path: string };
expect(res.status).toBe(200);
expect(body.path).toBe('rooted.png');
expect(existsSync(join(contentDir, 'rooted.png'))).toBe(true);
});
test('invalid configured attachment folder is rejected before final upload write', async () => {
attachmentFolderPath = '../escape';
const res = await uploadImage(createPngBuffer(), 'escape.png', 'docs/guide.md');
const body = (await res.json()) as { type: string; status: number };
expect(res.status).toBe(400);
expect(body.type).toBe('urn:ok:error:invalid-request');
expect(body.status).toBe(400);
expect(existsSync(join(tmpDir, 'escape', 'escape.png'))).toBe(false);
expect(existsSync(join(contentDir, 'docs', 'escape.png'))).toBe(false);
});
test('throwing attachment config reader reports a server configuration error', async () => {
getAttachmentFolderPath = () => {
throw new Error('invalid project config');
};
const res = await uploadImage(createPngBuffer(), 'config-error.png', 'docs/guide.md');
const body = (await res.json()) as { type: string; status: number; title: string };
expect(res.status).toBe(500);
expect(body.type).toBe('urn:ok:error:internal-server-error');
expect(body.status).toBe(500);
expect(body.title).toBe('Server configuration error: invalid attachment folder path.');
expect(existsSync(join(contentDir, 'docs', 'config-error.png'))).toBe(false);
});
test('a configured attachmentFolderPath naming .ok is refused at the resolved destination', async () => {
attachmentFolderPath = '/.ok/skills';
const res = await uploadImage(createPngBuffer(), 'planted.png', 'docs/guide.md');
const body = (await res.json()) as { type: string; status: number };
expect(res.status).toBe(400);
expect(body.type).toBe('urn:ok:error:reserved-doc-name');
expect(existsSync(join(contentDir, '.ok', 'skills', 'planted.png'))).toBe(false);
});
test('parent-dir placement keeps explicit sidebar folder drops in the target folder', async () => {
attachmentFolderPath = '/attachments';
const res = await uploadImage(createPngBuffer(), 'clip.png', 'docs/guide.md', 'parent-dir');
const body = (await res.json()) as { src: string; path: string };
expect(res.status).toBe(200);
expect(body.path).toBe('docs/clip.png');
expect(existsSync(join(contentDir, 'docs', 'clip.png'))).toBe(true);
expect(existsSync(join(contentDir, 'attachments', 'clip.png'))).toBe(false);
});
test('rejects missing parentDocName', async () => {
const formData = new FormData();
formData.append('file', new Blob([createPngBuffer()]), 'test.png');
const res = await fetch(`http://127.0.0.1:${port}/api/upload`, {
method: 'POST',
body: formData,
});
expect(res.status).toBe(400);
expect(res.headers.get('content-type')).toBe('application/problem+json');
const body = (await res.json()) as {
type: string;
title: string;
status: number;
instance: string;
};
expect(body.type).toBe('urn:ok:error:invalid-request');
expect(body.status).toBe(400);
expect(body.title.length).toBeGreaterThan(0);
expect(body.instance).toMatch(
/^urn:uuid:[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i,
);
});
test('rejects parentDocName with .. traversal', async () => {
const res = await uploadImage(createPngBuffer(), 'test.png', '../../etc/passwd.md');
expect(res.status).toBe(400);
expect(res.headers.get('content-type')).toBe('application/problem+json');
const body = (await res.json()) as { type: string; status: number };
expect(body.type).toBe('urn:ok:error:path-escape');
expect(body.status).toBe(400);
});
test('rejects absolute parentDocName', async () => {
const res = await uploadImage(createPngBuffer(), 'test.png', '/etc/passwd.md');
expect(res.status).toBe(400);
expect(res.headers.get('content-type')).toBe('application/problem+json');
const body = (await res.json()) as { type: string };
expect(body.type).toBe('urn:ok:error:path-escape');
});
test('rejects parentDocName with NUL byte', async () => {
const res = await uploadImage(createPngBuffer(), 'test.png', 'docs/\x00evil.md');
expect(res.status).toBe(400);
expect(res.headers.get('content-type')).toBe('application/problem+json');
const body = (await res.json()) as { type: string };
expect(body.type).toBe('urn:ok:error:path-escape');
});
test('paste timestamp-stem synthesis for generic filename', async () => {
const res = await uploadImage(createPngBuffer(), 'image.png', 'docs/guide.md');
const body = (await res.json()) as { src: string; path: string };
expect(res.status).toBe(200);
expect(body.src).toMatch(/^pasted-\d{8}-\d{6}\.png$/);
expect(body.path).toMatch(/^docs\/pasted-\d{8}-\d{6}\.png$/);
});
test('D-M accept-all: spoofed MIME no longer rejects, file is stored under sanitized name', async () => {
const exeBuffer = Buffer.from('MZexecutable content here');
const res = await uploadImage(exeBuffer, 'malicious.png', 'docs/guide.md');
expect(res.status).toBe(200);
const body = (await res.json()) as { src: string; deduped: boolean };
expect(body.src).toBe('malicious.png');
expect(body.deduped).toBe(false);
});
test('SVG accepted with image/svg+xml', async () => {
const res = await uploadImage(createSvgBuffer(), 'diagram.svg', 'docs/guide.md');
const body = (await res.json()) as { src: string; path: string };
expect(res.status).toBe(200);
expect(body.src).toBe('diagram.svg');
expect(body.path).toBe('docs/diagram.svg');
});
test('numeric suffix collision handling — distinct bytes, same filename', async () => {
writeFileSync(join(contentDir, 'docs', 'screenshot.png'), Buffer.from('different bytes'));
const res = await uploadImage(createPngBuffer(), 'screenshot.png', 'docs/guide.md');
const body = (await res.json()) as { src: string; path: string };
expect(res.status).toBe(200);
expect(body.src).toBe('screenshot-1.png');
expect(body.path).toBe('docs/screenshot-1.png');
});
test('symlink escape rejected', async () => {
const escapeTarget = join(tmpDir, 'outside');
mkdirSync(escapeTarget, { recursive: true });
symlinkSync(escapeTarget, join(contentDir, 'docs', 'escape'));
const res = await uploadImage(createPngBuffer(), 'test.png', 'docs/escape/x.md');
expect(res.status).toBe(400);
expect(res.headers.get('content-type')).toBe('application/problem+json');
const body = (await res.json()) as { type: string };
expect(body.type).toBe('urn:ok:error:path-escape');
});
test('parent-symlink escape rejected before mkdir creates a directory outside contentDir', async () => {
const escapeTarget = join(tmpDir, 'outside-mkdir-target');
mkdirSync(escapeTarget, { recursive: true });
symlinkSync(escapeTarget, join(contentDir, 'link'));
const res = await uploadImage(createPngBuffer(), 'test.png', 'link/sub/x.md');
expect(res.status).toBe(400);
const body = (await res.json()) as { type: string };
expect(body.type).toBe('urn:ok:error:path-escape');
expect(existsSync(join(escapeTarget, 'sub'))).toBe(false);
});
test('FR-8: /api/upload (new primary endpoint) accepts the same payload', async () => {
const formData = new FormData();
formData.append('parentDocName', 'docs/guide.md');
formData.append('file', new Blob([createPngBuffer()]), 'screenshot.png');
const res = await fetch(`http://127.0.0.1:${port}/api/upload`, {
method: 'POST',
body: formData,
});
expect(res.status).toBe(200);
const body = (await res.json()) as { src: string; deduped: boolean };
expect(body.src).toBe('screenshot.png');
expect(body.deduped).toBe(false);
expect(existsSync(join(contentDir, 'docs', 'screenshot.png'))).toBe(true);
});
test('D-M: PDF accepts and stores under sanitized name', async () => {
const pdfBuffer = Buffer.from('%PDF-1.4\n%fake pdf content for test');
const formData = new FormData();
formData.append('parentDocName', 'docs/guide.md');
formData.append('file', new Blob([pdfBuffer]), 'draft.pdf');
const res = await fetch(`http://127.0.0.1:${port}/api/upload`, {
method: 'POST',
body: formData,
});
expect(res.status).toBe(200);
const body = (await res.json()) as { src: string };
expect(body.src).toBe('draft.pdf');
expect(existsSync(join(contentDir, 'docs', 'draft.pdf'))).toBe(true);
});
test('D-M: non-sniffable text file (CSV) accepts under client filename', async () => {
const csvBuffer = Buffer.from('a,b,c\n1,2,3\n', 'utf-8');
const formData = new FormData();
formData.append('parentDocName', 'docs/guide.md');
formData.append('file', new Blob([csvBuffer]), 'data.csv');
const res = await fetch(`http://127.0.0.1:${port}/api/upload`, {
method: 'POST',
body: formData,
});
expect(res.status).toBe(200);
const body = (await res.json()) as { src: string };
expect(body.src).toBe('data.csv');
expect(existsSync(join(contentDir, 'docs', 'data.csv'))).toBe(true);
});
test('NFR-3: SVG extension-fallback preserved — sniff returns image/svg+xml', async () => {
const res = await uploadImage(createSvgBuffer(), 'diagram.svg', 'docs/guide.md');
expect(res.status).toBe(200);
expect(existsSync(join(contentDir, 'docs', 'diagram.svg'))).toBe(true);
});
test('response shape always carries the deduped flag (US-006 forward-compat)', async () => {
const res = await uploadImage(createPngBuffer(), 'shot.png', 'docs/guide.md');
const body = (await res.json()) as Record<string, unknown>;
expect(body).toHaveProperty('deduped');
expect(body.deduped).toBe(false);
});
});
describe('handleUploadAsset — same-dir sha256 dedup (FR-2)', () => {
let tmpDir: string;
let contentDir: string;
let server: import('node:http').Server;
let port: number;
beforeEach(async () => {
tmpDir = await mkdtemp(join(tmpdir(), 'upload-dedup-'));
contentDir = join(tmpDir, 'content');
mkdirSync(contentDir, { recursive: true });
mkdirSync(join(contentDir, 'docs'), { recursive: true });
mkdirSync(join(contentDir, 'archive'), { recursive: true });
writeFileSync(join(contentDir, 'docs', 'guide.md'), '# Guide');
writeFileSync(join(contentDir, 'archive', 'old.md'), '# Old');
const { Hocuspocus } = await import('@hocuspocus/server');
const { AgentSessionManager } = await import('./agent-sessions.ts');
const { createApiExtension } = await import('./api-extension.test-helper.ts');
const hocuspocus = new Hocuspocus({ quiet: true });
const sessionManager = new AgentSessionManager(hocuspocus);
const ext = createApiExtension({
hocuspocus,
sessionManager,
contentDir,
getFileIndex: () => new Map(),
getAttachmentFolderPath: () => './',
});
const { createServer } = await import('node:http');
server = createServer((req, res) => {
// biome-ignore lint/suspicious/noExplicitAny: test harness
hocuspocus.hooks('onRequest', { request: req, response: res } as any).catch(() => {
if (!res.writableEnded) {
res.writeHead(500);
res.end('Error');
}
});
});
hocuspocus.configuration.extensions.push(ext);
({ port } = await listenOnLoopback(server));
});
afterEach(async () => {
await new Promise<void>((res) => server.close(() => res()));
await rm(tmpDir, { recursive: true, force: true });
});
function pngFixture(): Buffer {
return Buffer.from(
'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAAC0lEQVQI12NgAAIABQABNjN9GQAAAABJRElEQrkJggg==',
'base64',
);
}
async function postUpload(buf: Buffer, filename: string, parent: string): Promise<Response> {
const formData = new FormData();
formData.append('parentDocName', parent);
formData.append('file', new Blob([buf]), filename);
return fetch(`http://127.0.0.1:${port}/api/upload`, { method: 'POST', body: formData });
}
test('second upload of identical bytes into same dir → deduped:true, single file on disk', async () => {
const buf = pngFixture();
const first = (await (await postUpload(buf, 'shot.png', 'docs/guide.md')).json()) as {
ok: boolean;
src: string;
deduped: boolean;
};
expect(first.deduped).toBe(false);
expect(first.src).toBe('shot.png');
expect(existsSync(join(contentDir, 'docs', 'shot.png'))).toBe(true);
const second = (await (await postUpload(buf, 'shot.png', 'docs/guide.md')).json()) as {
ok: boolean;
src: string;
deduped: boolean;
};
expect(second.deduped).toBe(true);
expect(second.src).toBe('shot.png');
expect(existsSync(join(contentDir, 'docs', 'shot.png'))).toBe(true);
expect(existsSync(join(contentDir, 'docs', 'shot-1.png'))).toBe(false);
});
test('dedup matches across rename — second drop with a different filename returns the existing basename', async () => {
const buf = pngFixture();
await postUpload(buf, 'shot.png', 'docs/guide.md');
const second = (await (
await postUpload(buf, 'completely-different.png', 'docs/guide.md')
).json()) as {
ok: boolean;
src: string;
deduped: boolean;
};
expect(second.deduped).toBe(true);
expect(second.src).toBe('shot.png');
});
test('cross-dir upload with same bytes does NOT dedup (D-D / FR-2 same-dir scope)', async () => {
const buf = pngFixture();
const inDocs = (await (await postUpload(buf, 'shot.png', 'docs/guide.md')).json()) as {
ok: boolean;
src: string;
deduped: boolean;
};
const inArchive = (await (await postUpload(buf, 'shot.png', 'archive/old.md')).json()) as {
ok: boolean;
src: string;
deduped: boolean;
};
expect(inDocs.deduped).toBe(false);
expect(inArchive.deduped).toBe(false);
expect(existsSync(join(contentDir, 'docs', 'shot.png'))).toBe(true);
expect(existsSync(join(contentDir, 'archive', 'shot.png'))).toBe(true);
});
test('dedup ignores non-asset files (markdown sibling does not trigger a hash hit)', async () => {
writeFileSync(join(contentDir, 'docs', 'sibling.md'), 'irrelevant');
const buf = pngFixture();
const res = (await (await postUpload(buf, 'shot.png', 'docs/guide.md')).json()) as {
ok: boolean;
src: string;
deduped: boolean;
};
expect(res.deduped).toBe(false);
});
});
describe('indexedSkillContentPath', () => {
let contentDir: string;
beforeEach(() => {
contentDir = mkdtempSync(join(tmpdir(), 'ok-skill-canonical-'));
});
afterEach(() => {
rmSync(contentDir, { recursive: true, force: true });
});
function bundle(rel: string): string {
const dir = join(contentDir, rel);
mkdirSync(dir, { recursive: true });
writeFileSync(join(dir, 'SKILL.md'), '---\nname: x\ndescription: d\n---\n');
return join(dir, 'SKILL.md');
}
test('resolves a skill mounted through a directory symlink to its indexed doc', () => {
bundle('plugins/ok/skills/demo');
mkdirSync(join(contentDir, '.agents/skills'), { recursive: true });
symlinkSync(
join(contentDir, 'plugins/ok/skills/demo'),
join(contentDir, '.agents/skills/demo'),
);
expect(
indexedSkillContentPath(join(contentDir, '.agents/skills/demo/SKILL.md'), contentDir),
).toBe('plugins/ok/skills/demo/SKILL.md');
});
test('resolves a symlinked SKILL.md file, not just a symlinked dir', () => {
bundle('plugins/ok/skills/demo');
mkdirSync(join(contentDir, '.agents/skills/demo'), { recursive: true });
symlinkSync(
join(contentDir, 'plugins/ok/skills/demo/SKILL.md'),
join(contentDir, '.agents/skills/demo/SKILL.md'),
);
expect(
indexedSkillContentPath(join(contentDir, '.agents/skills/demo/SKILL.md'), contentDir),
).toBe('plugins/ok/skills/demo/SKILL.md');
});
test('an unlinked bundle indexes at its own path (caller emits no redirect)', () => {
const real = bundle('.agents/skills/plain');
expect(indexedSkillContentPath(real, contentDir)).toBe('.agents/skills/plain/SKILL.md');
});
test('null when the link escapes contentDir — no canonical content doc exists', () => {
const outside = mkdtempSync(join(tmpdir(), 'ok-skill-outside-'));
try {
mkdirSync(join(outside, 'demo'), { recursive: true });
writeFileSync(join(outside, 'demo/SKILL.md'), '---\nname: x\ndescription: d\n---\n');
mkdirSync(join(contentDir, '.agents/skills'), { recursive: true });
symlinkSync(join(outside, 'demo'), join(contentDir, '.agents/skills/demo'));
expect(
indexedSkillContentPath(join(contentDir, '.agents/skills/demo/SKILL.md'), contentDir),
).toBeNull();
} finally {
rmSync(outside, { recursive: true, force: true });
}
});
test('null for a dangling link rather than throwing', () => {
mkdirSync(join(contentDir, '.agents/skills'), { recursive: true });
symlinkSync(join(contentDir, 'gone'), join(contentDir, '.agents/skills/demo'));
expect(
indexedSkillContentPath(join(contentDir, '.agents/skills/demo/SKILL.md'), contentDir),
).toBeNull();
});
});
describe('healUnservableSkillAdmission', () => {
function makeFilter(excluded: Set<string>) {
const rebuilds: number[] = [];
return {
rebuilds,
filter: {
isExcluded: (p: string) => excluded.has(p),
rebuildIgnorePatterns: async () => {
rebuilds.push(1);
excluded.clear();
},
},
};
}
test('rebuilds when a listed skill dir is not servable', async () => {
const { filter, rebuilds } = makeFilter(new Set(['.claude/skills/new/SKILL.md']));
const state: SkillAdmissionHealState = { lastKey: null };
await expect(
healUnservableSkillAdmission(['.claude/skills/new/SKILL.md'], filter, state),
).resolves.toBe(true);
expect(rebuilds.length).toBe(1);
});
test('does not rebuild when every listed skill is already servable', async () => {
const { filter, rebuilds } = makeFilter(new Set());
const state: SkillAdmissionHealState = { lastKey: null };
await expect(
healUnservableSkillAdmission(['.claude/skills/ok/SKILL.md'], filter, state),
).resolves.toBe(false);
expect(rebuilds.length).toBe(0);
});
test('rebuilds at most once per skill-dir set, then again when the set changes', async () => {
const excluded = new Set(['.claude/skills/ignored/SKILL.md']);
const rebuilds: number[] = [];
const filter = {
isExcluded: (p: string) => excluded.has(p),
rebuildIgnorePatterns: async () => {
rebuilds.push(1);
},
};
const state: SkillAdmissionHealState = { lastKey: null };
const paths = ['.claude/skills/ignored/SKILL.md'];
await healUnservableSkillAdmission(paths, filter, state);
await healUnservableSkillAdmission(paths, filter, state);
await healUnservableSkillAdmission([...paths], filter, state);
expect(rebuilds.length).toBe(1);
excluded.add('.claude/skills/fresh/SKILL.md');
await healUnservableSkillAdmission([...paths, '.claude/skills/fresh/SKILL.md'], filter, state);
expect(rebuilds.length).toBe(2);
});
test('ordering of the listed paths does not count as a changed set', async () => {
const excluded = new Set(['b/SKILL.md']);
const rebuilds: number[] = [];
const filter = {
isExcluded: (p: string) => excluded.has(p),
rebuildIgnorePatterns: async () => {
rebuilds.push(1);
},
};
const state: SkillAdmissionHealState = { lastKey: null };
await healUnservableSkillAdmission(['a/SKILL.md', 'b/SKILL.md'], filter, state);
await healUnservableSkillAdmission(['b/SKILL.md', 'a/SKILL.md'], filter, state);
expect(rebuilds.length).toBe(1);
});
test('a failing rebuild is swallowed, and no filter at all is a no-op', async () => {
const state: SkillAdmissionHealState = { lastKey: null };
const filter = {
isExcluded: () => true,
rebuildIgnorePatterns: () => Promise.reject(new Error('boom')),
};
await expect(healUnservableSkillAdmission(['x/SKILL.md'], filter, state)).resolves.toBe(false);
await expect(
healUnservableSkillAdmission(['x/SKILL.md'], null, { lastKey: null }),
).resolves.toBe(false);
});
});