Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

29.7 KB
Raw Blame
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);
  });
});