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,
readdirSync,
readFileSync,
rmSync,
statSync,
symlinkSync,
writeFileSync,
} from 'node:fs';
import type { IncomingMessage, ServerResponse } from 'node:http';
import { tmpdir } from 'node:os';
import { join, resolve } from 'node:path';
import { Readable } from 'node:stream';
import { Hocuspocus } from '@hocuspocus/server';
import { filesystemIdentity } from '@inkeep/open-knowledge-core/server';
import simpleGit from 'simple-git';
import { afterEach, describe, expect, test, vi } from 'vitest';
import type * as Y from 'yjs';
import { configureTestGitRepository } from '../../../test-support/configure-git-fixture.test-helper.ts';
import {
createApiExtension,
createDerivedDocumentIndexApiPortStub,
} from './api-extension.test-helper.ts';
import { BacklinkIndex } from './backlink-index.ts';
import { type ContentFilter, createContentFilter } from './content-filter.ts';
import type { DerivedDocumentIndexApiPort } from './derived-document-index.ts';
import { _resetDocExtensionsForTests, getDocExtension } from './doc-extensions.ts';
import type { FileIndexEntry, FolderIndexEntry } from './file-watcher.ts';
function makeReq(url: string, method: string, body: unknown): IncomingMessage {
const raw = body === undefined ? '' : JSON.stringify(body);
const readable = Readable.from(Buffer.from(raw)) as unknown as IncomingMessage;
readable.method = method;
readable.url = url;
readable.headers = { host: 'localhost' };
return readable;
}
interface CapturedResponse {
status: number;
headers: Record<string, string>;
body: string;
}
function makeRes(): { res: ServerResponse; captured: CapturedResponse } {
const captured: CapturedResponse = { status: 0, headers: {}, body: '' };
const res = {
writeHead(status: number, headers?: Record<string, string>) {
captured.status = status;
if (headers) Object.assign(captured.headers, headers);
},
end(body?: string) {
captured.body = body ?? '';
},
} as unknown as ServerResponse;
return { res, captured };
}
function buildFileIndex(contentDir: string): ReadonlyMap<string, FileIndexEntry> {
const index = new Map<string, FileIndexEntry>();
function walk(dir: string) {
for (const entry of readdirSync(dir, { withFileTypes: true })) {
const fullPath = resolve(dir, entry.name);
if (entry.isDirectory()) {
walk(fullPath);
continue;
}
if (!entry.isFile() || !entry.name.endsWith('.md')) continue;
const stat = statSync(fullPath);
const statIdentity = filesystemIdentity(statSync(fullPath, { bigint: true }));
const docName = fullPath.slice(contentDir.length + 1).replace(/\.md$/, '');
index.set(docName, {
size: stat.size,
modified: stat.mtime.toISOString(),
canonicalPath: fullPath,
inode: statIdentity,
aliases: [],
});
}
}
walk(contentDir);
return index;
}
function buildFolderIndex(contentDir: string): ReadonlyMap<string, FolderIndexEntry> {
const index = new Map<string, FolderIndexEntry>();
function walk(dir: string) {
for (const entry of readdirSync(dir, { withFileTypes: true })) {
if (!entry.isDirectory()) continue;
const fullPath = resolve(dir, entry.name);
const stat = statSync(fullPath);
const statIdentity = filesystemIdentity(statSync(fullPath, { bigint: true }));
const folderPath = fullPath.slice(contentDir.length + 1);
index.set(folderPath, {
size: 0,
modified: stat.mtime.toISOString(),
canonicalPath: fullPath,
inode: statIdentity,
});
walk(fullPath);
}
}
walk(contentDir);
return index;
}
async function buildBacklinkIndex(contentDir: string): Promise<BacklinkIndex> {
const index = new BacklinkIndex({
projectDir: contentDir,
contentDir,
});
await index.rebuildFromDisk();
return index;
}
type CallApiOptions = {
backlinkIndex?: BacklinkIndex | Promise<BacklinkIndex> | null;
hocuspocus?: Parameters<typeof createApiExtension>[0]['hocuspocus'];
sessionManager?: Parameters<typeof createApiExtension>[0]['sessionManager'];
getFileIndex?: () => ReadonlyMap<string, FileIndexEntry>;
getFolderIndex?: () => ReadonlyMap<string, FolderIndexEntry>;
mutateFileIndex?: Parameters<typeof createApiExtension>[0]['mutateFileIndex'];
onReferencedAssetsCacheInvalidator?: Parameters<
typeof createApiExtension
>[0]['onReferencedAssetsCacheInvalidator'];
signalChannel?: Parameters<typeof createApiExtension>[0]['signalChannel'];
projectDir?: string;
contentFilter?: ContentFilter;
derivedDocumentIndex?: DerivedDocumentIndexApiPort;
};
async function createTestApiExtension(contentDir: string, options?: CallApiOptions) {
const resolvedBacklinkIndex =
options && Object.hasOwn(options, 'backlinkIndex')
? await (options.backlinkIndex ?? undefined)
: await buildBacklinkIndex(contentDir);
return createApiExtension({
hocuspocus:
options?.hocuspocus ??
({
documents: new Map(),
closeConnections() {},
unloadDocument: async () => {},
} as unknown as Parameters<typeof createApiExtension>[0]['hocuspocus']),
sessionManager:
options?.sessionManager ??
({
closeSession: async () => {},
closeAllForDoc: async () => {},
} as unknown as Parameters<typeof createApiExtension>[0]['sessionManager']),
contentDir,
getFileIndex: options?.getFileIndex ?? (() => buildFileIndex(contentDir)),
getFolderIndex: options?.getFolderIndex ?? (() => buildFolderIndex(contentDir)),
mutateFileIndex: options?.mutateFileIndex,
onReferencedAssetsCacheInvalidator: options?.onReferencedAssetsCacheInvalidator,
backlinkIndex: resolvedBacklinkIndex,
signalChannel: options?.signalChannel,
projectDir: options?.projectDir,
contentFilter: options?.contentFilter,
derivedDocumentIndex: options?.derivedDocumentIndex,
});
}
function createClosedDerivedDocumentIndexPort(): DerivedDocumentIndexApiPort {
const rejectClosed = async (): Promise<never> => {
const error = new Error('Derived document index is closed');
error.name = 'DerivedDocumentIndexClosedError';
throw error;
};
return createDerivedDocumentIndexApiPortStub({
recordDirectMutations: rejectClosed,
recordDirectDocument: rejectClosed,
});
}
async function callApiExtension(
ext: Awaited<ReturnType<typeof createTestApiExtension>>,
url: string,
method: string,
body: unknown,
): Promise<CapturedResponse> {
const req = makeReq(url, method, body);
const { res, captured } = makeRes();
await (
ext as {
onRequest: (ctx: { request: IncomingMessage; response: ServerResponse }) => Promise<void>;
}
).onRequest({ request: req, response: res });
return captured;
}
async function callApi(
contentDir: string,
url: string,
method: string,
body: unknown,
options?: CallApiOptions,
): Promise<CapturedResponse> {
const ext = await createTestApiExtension(contentDir, options);
return callApiExtension(ext, url, method, body);
}
function assetPathsFromDocumentList(response: CapturedResponse): string[] {
const body = JSON.parse(response.body) as {
documents: Array<{ kind: string; path?: string }>;
};
return body.documents
.filter((entry) => entry.kind === 'asset')
.map((entry) => entry.path)
.filter((path): path is string => typeof path === 'string');
}
let tmpDir: string;
function setupTmpDir(): string {
tmpDir = mkdtempSync(join(tmpdir(), 'ok-file-ops-'));
return tmpDir;
}
afterEach(() => {
vi.restoreAllMocks();
_resetDocExtensionsForTests();
if (tmpDir) {
rmSync(tmpDir, { recursive: true, force: true });
}
});
describe('file operation API routes', () => {
test('managed rename rewrites inbound wiki-links and markdown links', async () => {
const dir = setupTmpDir();
mkdirSync(join(dir, 'nested'), { recursive: true });
writeFileSync(join(dir, 'notes.md'), '# Notes\n', 'utf-8');
writeFileSync(
join(dir, 'journal.md'),
'# Journal\n\nSee [[notes]] and [Notes](./notes.md).\n',
'utf-8',
);
writeFileSync(
join(dir, 'nested/child.md'),
'# Child\n\nJump to [Notes](../notes.md#intro "Section").\n',
'utf-8',
);
const result = await callApi(
dir,
'/api/rename-path',
'POST',
{
kind: 'file',
fromPath: 'notes',
toPath: 'renamed-notes',
},
{ backlinkIndex: buildBacklinkIndex(dir) },
);
expect(result.status).toBe(200);
expect(existsSync(join(dir, 'notes.md'))).toBe(false);
expect(readFileSync(join(dir, 'renamed-notes.md'), 'utf-8')).toBe('# Notes\n');
expect(readFileSync(join(dir, 'journal.md'), 'utf-8')).toBe(
'# Journal\n\nSee [[renamed-notes|notes]] and [Notes](./renamed-notes.md).\n',
);
expect(readFileSync(join(dir, 'nested/child.md'), 'utf-8')).toBe(
'# Child\n\nJump to [Notes](../renamed-notes.md#intro "Section").\n',
);
const body = JSON.parse(result.body) as {
ok: boolean;
renamed: Array<{ fromDocName: string; toDocName: string }>;
rewrittenDocs: Array<{ docName: string; rewrites: number }>;
};
expect(body.ok).toBeUndefined();
expect(body.renamed).toEqual([{ fromDocName: 'notes', toDocName: 'renamed-notes' }]);
expect(body.rewrittenDocs).toEqual([
{ docName: 'journal', rewrites: 2 },
{ docName: 'nested/child', rewrites: 1 },
]);
});
test('renames the selected .md sibling when .md and .mdx share a stem', async () => {
const dir = setupTmpDir();
writeFileSync(join(dir, 'foo.md'), '# Markdown sibling\n', 'utf-8');
writeFileSync(join(dir, 'foo.mdx'), '# MDX sibling\n', 'utf-8');
const result = await callApi(
dir,
'/api/rename-path',
'POST',
{
kind: 'file',
fromPath: 'foo.md',
toPath: 'renamed.md',
},
{ backlinkIndex: buildBacklinkIndex(dir) },
);
expect(result.status).toBe(200);
expect(existsSync(join(dir, 'foo.md'))).toBe(false);
expect(readFileSync(join(dir, 'renamed.md'), 'utf-8')).toBe('# Markdown sibling\n');
expect(readFileSync(join(dir, 'foo.mdx'), 'utf-8')).toBe('# MDX sibling\n');
const body = JSON.parse(result.body) as {
renamed: Array<{ fromDocName: string; toDocName: string }>;
};
expect(body.renamed).toEqual([{ fromDocName: 'foo.md', toDocName: 'renamed' }]);
});
test('renames a folder containing same-stem .md and .mdx siblings', async () => {
const dir = setupTmpDir();
mkdirSync(join(dir, 'docs'), { recursive: true });
writeFileSync(join(dir, 'docs/foo.md'), '# Markdown sibling\n', 'utf-8');
writeFileSync(join(dir, 'docs/foo.mdx'), '# MDX sibling\n', 'utf-8');
const result = await callApi(
dir,
'/api/rename-path',
'POST',
{
kind: 'folder',
fromPath: 'docs',
toPath: 'archive',
},
{ backlinkIndex: buildBacklinkIndex(dir) },
);
expect(result.status).toBe(200);
expect(existsSync(join(dir, 'docs'))).toBe(false);
expect(readFileSync(join(dir, 'archive/foo.md'), 'utf-8')).toBe('# Markdown sibling\n');
expect(readFileSync(join(dir, 'archive/foo.mdx'), 'utf-8')).toBe('# MDX sibling\n');
const body = JSON.parse(result.body) as {
renamed: Array<{ fromDocName: string; toDocName: string }>;
};
expect(body.renamed).toEqual([
{ fromDocName: 'docs/foo.md', toDocName: 'archive/foo.md' },
{ fromDocName: 'docs/foo.mdx', toDocName: 'archive/foo.mdx' },
]);
});
test('renames into an explicit destination sibling stem without collapsing identity', async () => {
const dir = setupTmpDir();
writeFileSync(join(dir, 'foo.md'), '# Source\n', 'utf-8');
writeFileSync(join(dir, 'bar.mdx'), '# Existing MDX sibling\n', 'utf-8');
const result = await callApi(
dir,
'/api/rename-path',
'POST',
{
kind: 'file',
fromPath: 'foo.md',
toPath: 'bar.md',
},
{ backlinkIndex: buildBacklinkIndex(dir) },
);
expect(result.status).toBe(200);
expect(existsSync(join(dir, 'foo.md'))).toBe(false);
expect(readFileSync(join(dir, 'bar.md'), 'utf-8')).toBe('# Source\n');
expect(readFileSync(join(dir, 'bar.mdx'), 'utf-8')).toBe('# Existing MDX sibling\n');
const body = JSON.parse(result.body) as {
renamed: Array<{ fromDocName: string; toDocName: string }>;
};
expect(body.renamed).toEqual([{ fromDocName: 'foo', toDocName: 'bar.md' }]);
});
test('deletes the selected .md sibling without purging the .mdx sibling identity', async () => {
const dir = setupTmpDir();
writeFileSync(join(dir, 'foo.md'), '# Markdown sibling\n', 'utf-8');
writeFileSync(join(dir, 'foo.mdx'), '# MDX sibling\n', 'utf-8');
const indexEvents: Array<{ kind: string; path?: string; docName?: string }> = [];
const result = await callApi(
dir,
'/api/delete-path',
'POST',
{
kind: 'file',
path: 'foo.md',
},
{
mutateFileIndex: (event) => {
indexEvents.push(event as (typeof indexEvents)[number]);
},
},
);
expect(result.status).toBe(200);
expect(existsSync(join(dir, 'foo.md'))).toBe(false);
expect(readFileSync(join(dir, 'foo.mdx'), 'utf-8')).toBe('# MDX sibling\n');
const body = JSON.parse(result.body) as { deletedDocNames: string[] };
expect(body.deletedDocNames).toEqual(['foo.md']);
expect(indexEvents).toContainEqual({
kind: 'delete',
path: join(dir, 'foo.md'),
docName: 'foo.md',
});
});
test('managed rename updates an already-loaded referring document', async () => {
const dir = setupTmpDir();
writeFileSync(join(dir, 'notes.md'), '# Notes\n', 'utf-8');
writeFileSync(join(dir, 'journal.md'), '# Journal\n\nSee [[notes]].\n', 'utf-8');
const hocuspocus = new Hocuspocus({ quiet: true });
const conn = await hocuspocus.openDirectConnection('journal');
const document = (conn as unknown as { document: Y.Doc }).document;
const ytext = document.getText('source');
document.transact(() => {
ytext.insert(0, '# Journal\n\nSee [[notes]].\n');
});
try {
const result = await callApi(
dir,
'/api/rename-path',
'POST',
{
kind: 'file',
fromPath: 'notes',
toPath: 'renamed-notes',
},
{
backlinkIndex: buildBacklinkIndex(dir),
hocuspocus,
},
);
expect(result.status).toBe(200);
expect(document.getText('source').toString()).toBe(
'# Journal\n\nSee [[renamed-notes|notes]].\n',
);
expect(readFileSync(join(dir, 'journal.md'), 'utf-8')).toBe(
'# Journal\n\nSee [[renamed-notes|notes]].\n',
);
} finally {
await conn.disconnect();
}
});
test('GET /api/document returns 404 for missing docs (does not create a phantom Y.Doc)', async () => {
const dir = setupTmpDir();
writeFileSync(join(dir, 'real-doc.md'), '# Real\n', 'utf-8');
const hocuspocus = new Hocuspocus({ quiet: true });
expect(hocuspocus.documents.has('nonexistent-doc')).toBe(false);
const result = await callApi(
dir,
'/api/document?docName=nonexistent-doc',
'GET',
{},
{ hocuspocus },
);
expect(result.status).toBe(404);
const parsed = JSON.parse(result.body) as Record<string, unknown>;
expect(parsed.type).toBe('urn:ok:error:doc-not-found');
expect(parsed.title).toContain('Document not found');
expect(parsed.title).toContain('nonexistent-doc');
expect(hocuspocus.documents.has('nonexistent-doc')).toBe(false);
const ok = await callApi(dir, '/api/document?docName=real-doc', 'GET', {}, { hocuspocus });
expect(ok.status).toBe(200);
expect((JSON.parse(ok.body) as { docName: string }).docName).toBe('real-doc');
});
test('rename does NOT materialize a phantom file for an in-memory-only backlink source', async () => {
const dir = setupTmpDir();
writeFileSync(join(dir, 'notes.md'), '# Notes\n', 'utf-8');
writeFileSync(join(dir, 'journal.md'), '# Journal\n\nSee [[notes]].\n', 'utf-8');
const backlinkIndex = await buildBacklinkIndex(dir);
backlinkIndex.updateDocumentFromMarkdown('phantom-doc', '# Phantom\n\nSee [[notes]].\n');
expect(
backlinkIndex.getBacklinks('notes').some((entry) => entry.source === 'phantom-doc'),
).toBe(true);
const hocuspocus = new Hocuspocus({ quiet: true });
const conn = await hocuspocus.openDirectConnection('phantom-doc');
const document = (conn as unknown as { document: Y.Doc }).document;
document.transact(() => {
document.getText('source').insert(0, '# Phantom\n\nSee [[notes]].\n');
});
try {
const result = await callApi(
dir,
'/api/rename-path',
'POST',
{
kind: 'file',
fromPath: 'notes',
toPath: 'renamed-notes',
},
{ backlinkIndex, hocuspocus },
);
expect(result.status).toBe(200);
expect(existsSync(join(dir, 'renamed-notes.md'))).toBe(true);
expect(readFileSync(join(dir, 'journal.md'), 'utf-8')).toBe(
'# Journal\n\nSee [[renamed-notes|notes]].\n',
);
expect(existsSync(join(dir, 'phantom-doc.md'))).toBe(false);
expect(
backlinkIndex.getBacklinks('renamed-notes').some((entry) => entry.source === 'phantom-doc'),
).toBe(false);
} finally {
await conn.disconnect();
}
});
test('cross-folder file move rewrites outbound links without duplicating content', async () => {
const dir = setupTmpDir();
mkdirSync(join(dir, 'artists'), { recursive: true });
writeFileSync(join(dir, 'artists/picasso.md'), '# Picasso\n', 'utf-8');
const sourceBody = [
'# Some File',
'',
'See [Picasso](./picasso.md) and [[artists/picasso]].',
'',
'A second paragraph with [Other](./other.md).',
'',
'```md',
'[Code link](./picasso.md) — should not rewrite',
'```',
'',
'End of file.',
'',
].join('\n');
writeFileSync(join(dir, 'artists/some-file.md'), sourceBody, 'utf-8');
const result = await callApi(dir, '/api/rename-path', 'POST', {
kind: 'file',
fromPath: 'artists/some-file',
toPath: 'venues/some-file',
});
expect(result.status).toBe(200);
expect(existsSync(join(dir, 'artists/some-file.md'))).toBe(false);
const destContent = readFileSync(join(dir, 'venues/some-file.md'), 'utf-8');
const expectedDest = [
'# Some File',
'',
'See [Picasso](../artists/picasso.md) and [[artists/picasso]].',
'',
'A second paragraph with [Other](../artists/other.md).',
'',
'```md',
'[Code link](./picasso.md) — should not rewrite',
'```',
'',
'End of file.',
'',
].join('\n');
expect(destContent).toBe(expectedDest);
expect(destContent.length).toBe(expectedDest.length);
expect(destContent.match(/# Some File/g)?.length).toBe(1);
expect(destContent.match(/End of file\./g)?.length).toBe(1);
expect(destContent.match(/A second paragraph/g)?.length).toBe(1);
});
test('cross-folder file move with frontmatter + image refs does not duplicate content', async () => {
const dir = setupTmpDir();
mkdirSync(join(dir, 'docs'), { recursive: true });
writeFileSync(join(dir, 'docs/photo.png'), 'fakebytes', 'utf-8');
const sourceBody = [
'---',
'title: Meeting Notes',
'date: 2026-04-30',
'---',
'',
'# Meeting Notes',
'',
'',
'',
'[See agenda](./agenda.md)',
'',
'Closing paragraph.',
'',
].join('\n');
writeFileSync(join(dir, 'docs/meeting.md'), sourceBody, 'utf-8');
const result = await callApi(dir, '/api/rename-path', 'POST', {
kind: 'file',
fromPath: 'docs/meeting',
toPath: 'archive/2026/meeting',
});
expect(result.status).toBe(200);
const destContent = readFileSync(join(dir, 'archive/2026/meeting.md'), 'utf-8');
const expected = [
'---',
'title: Meeting Notes',
'date: 2026-04-30',
'---',
'',
'# Meeting Notes',
'',
'',
'',
'[See agenda](../../docs/agenda.md)',
'',
'Closing paragraph.',
'',
].join('\n');
expect(destContent).toBe(expected);
expect(destContent.match(/# Meeting Notes/g)?.length).toBe(1);
expect(destContent.match(/Closing paragraph\./g)?.length).toBe(1);
expect(destContent.match(/title: Meeting Notes/g)?.length).toBe(1);
});
test('cross-folder file move with currently-loaded Y.Doc does not duplicate content', async () => {
const dir = setupTmpDir();
mkdirSync(join(dir, 'artists'), { recursive: true });
writeFileSync(join(dir, 'artists/picasso.md'), '# Picasso\n', 'utf-8');
const initialBody = [
'# Some File',
'',
'See [Picasso](./picasso.md).',
'',
'Body content.',
'',
].join('\n');
writeFileSync(join(dir, 'artists/some-file.md'), initialBody, 'utf-8');
const hocuspocus = new Hocuspocus({ quiet: true });
const conn = await hocuspocus.openDirectConnection('artists/some-file');
const document = (conn as unknown as { document: Y.Doc }).document;
const ytext = document.getText('source');
document.transact(() => {
ytext.insert(0, initialBody);
});
try {
const result = await callApi(
dir,
'/api/rename-path',
'POST',
{
kind: 'file',
fromPath: 'artists/some-file',
toPath: 'venues/some-file',
},
{
backlinkIndex: buildBacklinkIndex(dir),
hocuspocus,
},
);
expect(result.status).toBe(200);
const destContent = readFileSync(join(dir, 'venues/some-file.md'), 'utf-8');
const expected = [
'# Some File',
'',
'See [Picasso](../artists/picasso.md).',
'',
'Body content.',
'',
].join('\n');
expect(destContent).toBe(expected);
expect(destContent.match(/# Some File/g)?.length).toBe(1);
expect(destContent.match(/Body content\./g)?.length).toBe(1);
} finally {
await conn.disconnect();
}
});
test('managed rename rejects destination collisions without changing files', async () => {
const dir = setupTmpDir();
writeFileSync(join(dir, 'notes.md'), '# Notes\n', 'utf-8');
writeFileSync(join(dir, 'renamed-notes.md'), '# Existing\n', 'utf-8');
writeFileSync(join(dir, 'journal.md'), '# Journal\n\nSee [[notes]].\n', 'utf-8');
const result = await callApi(
dir,
'/api/rename-path',
'POST',
{
kind: 'file',
fromPath: 'notes',
toPath: 'renamed-notes',
},
{ backlinkIndex: buildBacklinkIndex(dir) },
);
expect(result.status).toBe(409);
expect(readFileSync(join(dir, 'notes.md'), 'utf-8')).toBe('# Notes\n');
expect(readFileSync(join(dir, 'renamed-notes.md'), 'utf-8')).toBe('# Existing\n');
expect(readFileSync(join(dir, 'journal.md'), 'utf-8')).toBe('# Journal\n\nSee [[notes]].\n');
const body = JSON.parse(result.body) as Record<string, unknown>;
expect(body.type).toBe('urn:ok:error:doc-already-exists');
expect(body.title).toContain('Destination already exists');
});
test('managed rename returns no-op success when source and destination match', async () => {
const dir = setupTmpDir();
writeFileSync(join(dir, 'notes.md'), '# Notes\n', 'utf-8');
const result = await callApi(
dir,
'/api/rename-path',
'POST',
{
kind: 'file',
fromPath: 'notes',
toPath: 'notes',
},
{ backlinkIndex: buildBacklinkIndex(dir) },
);
expect(result.status).toBe(200);
expect(readFileSync(join(dir, 'notes.md'), 'utf-8')).toBe('# Notes\n');
expect(JSON.parse(result.body)).toEqual({
renamed: [],
renamedAssets: [],
rewrittenDocs: [],
});
});
test('managed rename rejects reserved document names', async () => {
const dir = setupTmpDir();
writeFileSync(join(dir, 'notes.md'), '# Notes\n', 'utf-8');
const result = await callApi(
dir,
'/api/rename-path',
'POST',
{
kind: 'file',
fromPath: 'notes',
toPath: '__system__',
},
{ backlinkIndex: buildBacklinkIndex(dir) },
);
expect(result.status).toBe(400);
const reservedBody = JSON.parse(result.body) as Record<string, unknown>;
expect(reservedBody.type).toBe('urn:ok:error:reserved-doc-name');
expect(reservedBody.title).toContain('Reserved document names cannot be renamed');
});
test('managed rename with kind:folder on an existing file returns 400 (type mismatch)', async () => {
const dir = setupTmpDir();
writeFileSync(join(dir, 'notes.md'), '# Notes\n', 'utf-8');
const result = await callApi(
dir,
'/api/rename-path',
'POST',
{
kind: 'folder',
fromPath: 'notes.md',
toPath: 'renamed-notes',
},
{ backlinkIndex: buildBacklinkIndex(dir) },
);
expect(result.status).toBe(400);
{
const parsed = JSON.parse(result.body) as Record<string, unknown>;
expect(parsed.type).toBe('urn:ok:error:invalid-request');
expect(parsed.title).toContain('Source path is not a folder');
}
});
test('managed rename with kind:file on a .md-named directory returns 400 (type mismatch)', async () => {
const dir = setupTmpDir();
mkdirSync(join(dir, 'looks-like.md'));
const result = await callApi(
dir,
'/api/rename-path',
'POST',
{
kind: 'file',
fromPath: 'looks-like.md',
toPath: 'renamed.md',
},
{ backlinkIndex: buildBacklinkIndex(dir) },
);
expect(result.status).toBe(400);
{
const parsed = JSON.parse(result.body) as Record<string, unknown>;
expect(parsed.type).toBe('urn:ok:error:invalid-request');
expect(parsed.title).toContain('Source path is not a file');
}
});
test('managed rename rejects .ok as a destination (reserved directory)', async () => {
const dir = setupTmpDir();
mkdirSync(join(dir, 'project'));
writeFileSync(join(dir, 'project', 'index.md'), '# Index\n', 'utf-8');
const result = await callApi(
dir,
'/api/rename-path',
'POST',
{
kind: 'folder',
fromPath: 'project',
toPath: '.ok',
},
{ backlinkIndex: buildBacklinkIndex(dir) },
);
expect(result.status).toBe(400);
{
const parsed = JSON.parse(result.body) as Record<string, unknown>;
expect(parsed.type).toBe('urn:ok:error:reserved-doc-name');
expect(parsed.title).toContain('.ok and .git are reserved directories');
}
});
test('managed rename rejects .ok subpath as a destination', async () => {
const dir = setupTmpDir();
writeFileSync(join(dir, 'notes.md'), '# Notes\n', 'utf-8');
const result = await callApi(
dir,
'/api/rename-path',
'POST',
{
kind: 'file',
fromPath: 'notes',
toPath: '.ok/secret',
},
{ backlinkIndex: buildBacklinkIndex(dir) },
);
expect(result.status).toBe(400);
{
const parsed = JSON.parse(result.body) as Record<string, unknown>;
expect(parsed.type).toBe('urn:ok:error:reserved-doc-name');
expect(parsed.title).toContain('.ok and .git are reserved directories');
}
});
test('managed rename returns 404 when the source document is missing', async () => {
const dir = setupTmpDir();
const result = await callApi(
dir,
'/api/rename-path',
'POST',
{
kind: 'file',
fromPath: 'notes',
toPath: 'renamed-notes',
},
{ backlinkIndex: buildBacklinkIndex(dir) },
);
expect(result.status).toBe(404);
const notFoundBody = JSON.parse(result.body) as Record<string, unknown>;
expect(notFoundBody.type).toBe('urn:ok:error:doc-not-found');
expect(typeof notFoundBody.title).toBe('string');
expect(String(notFoundBody.title).toLowerCase()).toContain('does not exist');
});
test('managed rename does not register explicit missing source extensions', async () => {
const dir = setupTmpDir();
const result = await callApi(
dir,
'/api/rename-path',
'POST',
{
kind: 'file',
fromPath: 'missing.mdx',
toPath: 'renamed.mdx',
},
{ backlinkIndex: buildBacklinkIndex(dir) },
);
expect(result.status).toBe(404);
expect(getDocExtension('missing')).toBe('.md');
});
test.skipIf(process.platform === 'win32')(
'managed rename surfaces actionable symlink escape errors',
async () => {
const root = setupTmpDir();
const contentDir = join(root, 'content');
const outside = join(root, 'outside');
mkdirSync(contentDir);
mkdirSync(outside);
symlinkSync(join('..', 'outside'), join(contentDir, 'evil'), 'dir');
writeFileSync(join(contentDir, 'safe.md'), '# Safe\n', 'utf-8');
const result = await callApi(
contentDir,
'/api/rename-path',
'POST',
{
kind: 'file',
fromPath: 'safe',
toPath: 'evil/captured',
},
{ backlinkIndex: buildBacklinkIndex(contentDir) },
);
expect(result.status).toBe(400);
const symlinkBody = JSON.parse(result.body) as Record<string, unknown>;
expect(symlinkBody.type).toBe('urn:ok:error:path-escape');
expect(symlinkBody.title).toBe('symlink-escape: path resolves outside content directory.');
},
);
test('renames a file and returns the old-to-new mapping', async () => {
const dir = setupTmpDir();
writeFileSync(join(dir, 'notes.md'), '# Notes\n', 'utf-8');
const result = await callApi(dir, '/api/rename-path', 'POST', {
kind: 'file',
fromPath: 'notes',
toPath: 'renamed-notes',
});
expect(result.status).toBe(200);
expect(existsSync(join(dir, 'notes.md'))).toBe(false);
expect(readFileSync(join(dir, 'renamed-notes.md'), 'utf-8')).toBe('# Notes\n');
const body = JSON.parse(result.body) as { ok: boolean; renamed: Array<Record<string, string>> };
expect(body.ok).toBeUndefined();
expect(body.renamed).toEqual([{ fromDocName: 'notes', toDocName: 'renamed-notes' }]);
});
test('keeps a document rename successful when the derived index closes after disk commit', async () => {
const dir = setupTmpDir();
writeFileSync(join(dir, 'notes.md'), '# Notes\n', 'utf-8');
const result = await callApi(
dir,
'/api/rename-path',
'POST',
{
kind: 'file',
fromPath: 'notes',
toPath: 'renamed-notes',
},
{ derivedDocumentIndex: createClosedDerivedDocumentIndexPort() },
);
expect(result.status).toBe(200);
expect(existsSync(join(dir, 'notes.md'))).toBe(false);
expect(readFileSync(join(dir, 'renamed-notes.md'), 'utf-8')).toBe('# Notes\n');
});
test('renames a folder and returns descendant mappings', async () => {
const dir = setupTmpDir();
mkdirSync(join(dir, 'docs/nested'), { recursive: true });
writeFileSync(join(dir, 'docs/index.md'), '# Docs\n', 'utf-8');
writeFileSync(join(dir, 'docs/nested/page.md'), '# Nested\n', 'utf-8');
const result = await callApi(dir, '/api/rename-path', 'POST', {
kind: 'folder',
fromPath: 'docs',
toPath: 'guides',
});
expect(result.status).toBe(200);
expect(existsSync(join(dir, 'docs'))).toBe(false);
expect(readFileSync(join(dir, 'guides/index.md'), 'utf-8')).toBe('# Docs\n');
expect(readFileSync(join(dir, 'guides/nested/page.md'), 'utf-8')).toBe('# Nested\n');
const body = JSON.parse(result.body) as {
ok: boolean;
renamed: Array<{ fromDocName: string; toDocName: string }>;
};
expect(body.ok).toBeUndefined();
expect(body.renamed).toEqual([
{ fromDocName: 'docs/index', toDocName: 'guides/index' },
{ fromDocName: 'docs/nested/page', toDocName: 'guides/nested/page' },
]);
});
test('case-only folder rename returns descendant mappings', async () => {
const dir = setupTmpDir();
mkdirSync(join(dir, 'Docs/nested'), { recursive: true });
writeFileSync(join(dir, 'Docs/index.md'), '# Docs\n', 'utf-8');
writeFileSync(join(dir, 'Docs/nested/Page.md'), '# Nested\n', 'utf-8');
const result = await callApi(dir, '/api/rename-path', 'POST', {
kind: 'folder',
fromPath: 'Docs',
toPath: 'docs',
});
expect(result.status).toBe(200);
expect(readdirSync(dir)).toContain('docs');
expect(readdirSync(dir)).not.toContain('Docs');
expect(readFileSync(join(dir, 'docs/index.md'), 'utf-8')).toBe('# Docs\n');
expect(readFileSync(join(dir, 'docs/nested/Page.md'), 'utf-8')).toBe('# Nested\n');
const body = JSON.parse(result.body) as {
renamed: Array<{ fromDocName: string; toDocName: string }>;
};
expect(body.renamed).toEqual([
{ fromDocName: 'Docs/index', toDocName: 'docs/index' },
{ fromDocName: 'Docs/nested/Page', toDocName: 'docs/nested/Page' },
]);
});
test('folder rename updates the in-memory index before /api/pages reads it', async () => {
const dir = setupTmpDir();
mkdirSync(join(dir, 'docs/nested'), { recursive: true });
writeFileSync(join(dir, 'docs/index.md'), '# Docs\n', 'utf-8');
writeFileSync(join(dir, 'docs/nested/page.md'), '# Nested\n', 'utf-8');
const fileIndex = new Map(buildFileIndex(dir));
const signals: string[] = [];
const renameResult = await callApi(
dir,
'/api/rename-path',
'POST',
{
kind: 'folder',
fromPath: 'docs',
toPath: 'guides',
},
{
backlinkIndex: buildBacklinkIndex(dir),
getFileIndex: () => fileIndex,
signalChannel: (channel) => signals.push(channel),
},
);
expect(renameResult.status).toBe(200);
expect(fileIndex.has('docs/index')).toBe(false);
expect(fileIndex.has('docs/nested/page')).toBe(false);
expect(fileIndex.has('guides/index')).toBe(true);
expect(fileIndex.has('guides/nested/page')).toBe(true);
expect(signals).toEqual(expect.arrayContaining(['files', 'backlinks', 'graph']));
const pagesResult = await callApi(
dir,
'/api/pages',
'GET',
{},
{
backlinkIndex: buildBacklinkIndex(dir),
getFileIndex: () => fileIndex,
},
);
expect(pagesResult.status).toBe(200);
const body = JSON.parse(pagesResult.body) as {
ok: boolean;
pages: Array<{ docName: string; title: string }>;
};
expect(body.ok).toBeUndefined();
expect(body.pages).toEqual(
expect.arrayContaining([
expect.objectContaining({ docName: 'guides/index', title: 'Docs' }),
expect.objectContaining({ docName: 'guides/nested/page', title: 'Nested' }),
]),
);
expect(body.pages.map((page) => page.docName)).not.toContain('docs/index');
expect(body.pages.map((page) => page.docName)).not.toContain('docs/nested/page');
});
test('folder rename uses git mv for tracked files', async () => {
const dir = setupTmpDir();
mkdirSync(join(dir, 'docs/nested'), { recursive: true });
writeFileSync(join(dir, 'docs/index.md'), '# Docs\n', 'utf-8');
writeFileSync(join(dir, 'docs/nested/page.md'), '# Nested\n', 'utf-8');
const git = simpleGit(dir);
await git.init();
configureTestGitRepository(dir);
await git.raw('config', 'user.name', 'Test');
await git.raw('config', 'user.email', '[email protected]');
await git.add('.');
await git.commit('Initial');
const result = await callApi(
dir,
'/api/rename-path',
'POST',
{
kind: 'folder',
fromPath: 'docs',
toPath: 'guides',
},
{
backlinkIndex: buildBacklinkIndex(dir),
projectDir: dir,
},
);
expect(result.status).toBe(200);
const status = await git.raw('status', '--short');
expect(status).toContain('R docs/index.md -> guides/index.md');
expect(status).toContain('R docs/nested/page.md -> guides/nested/page.md');
expect(status).not.toContain(' D docs/index.md');
expect(status).not.toContain('?? guides/');
});
test('case-only folder rename uses git mv for tracked files', async () => {
const dir = setupTmpDir();
mkdirSync(join(dir, 'Docs/nested'), { recursive: true });
writeFileSync(join(dir, 'Docs/index.md'), '# Docs\n', 'utf-8');
writeFileSync(join(dir, 'Docs/nested/Page.md'), '# Nested\n', 'utf-8');
const git = simpleGit(dir);
await git.init();
configureTestGitRepository(dir);
await git.raw('config', 'user.name', 'Test');
await git.raw('config', 'user.email', '[email protected]');
await git.add('.');
await git.commit('Initial');
const result = await callApi(
dir,
'/api/rename-path',
'POST',
{
kind: 'folder',
fromPath: 'Docs',
toPath: 'docs',
},
{
backlinkIndex: buildBacklinkIndex(dir),
projectDir: dir,
},
);
expect(result.status).toBe(200);
expect(readdirSync(dir)).toContain('docs');
expect(readdirSync(dir)).not.toContain('Docs');
const body = JSON.parse(result.body) as {
renamed: Array<{ fromDocName: string; toDocName: string }>;
};
expect(body.renamed).toEqual([
{ fromDocName: 'Docs/index', toDocName: 'docs/index' },
{ fromDocName: 'Docs/nested/Page', toDocName: 'docs/nested/Page' },
]);
const status = await git.raw('status', '--short');
expect(status).toContain('R Docs/index.md -> docs/index.md');
expect(status).toContain('R Docs/nested/Page.md -> docs/nested/Page.md');
expect(status).not.toContain(' D Docs/index.md');
expect(status).not.toContain('?? docs/');
});
test('file rename uses git mv for tracked files', async () => {
const dir = setupTmpDir();
writeFileSync(join(dir, 'old-name.md'), '# Doc\\n', 'utf-8');
const git = simpleGit(dir);
await git.init();
configureTestGitRepository(dir);
await git.raw('config', 'user.name', 'Test');
await git.raw('config', 'user.email', '[email protected]');
await git.add('.');
await git.commit('Initial');
const result = await callApi(
dir,
'/api/rename-path',
'POST',
{ kind: 'file', fromPath: 'old-name', toPath: 'new-name' },
{ backlinkIndex: buildBacklinkIndex(dir), projectDir: dir },
);
expect(result.status).toBe(200);
const status = await git.raw('status', '--short');
expect(status).toContain('old-name.md -> new-name.md');
});
test('case-only file rename uses git mv for tracked files', async () => {
const dir = setupTmpDir();
writeFileSync(join(dir, 'CaseName.md'), '# Doc\n', 'utf-8');
const git = simpleGit(dir);
await git.init();
configureTestGitRepository(dir);
await git.raw('config', 'user.name', 'Test');
await git.raw('config', 'user.email', '[email protected]');
await git.add('.');
await git.commit('Initial');
const result = await callApi(
dir,
'/api/rename-path',
'POST',
{ kind: 'file', fromPath: 'CaseName', toPath: 'casename' },
{ backlinkIndex: buildBacklinkIndex(dir), projectDir: dir },
);
expect(result.status).toBe(200);
expect(readdirSync(dir)).toContain('casename.md');
expect(readdirSync(dir)).not.toContain('CaseName.md');
const body = JSON.parse(result.body) as {
renamed: Array<{ fromDocName: string; toDocName: string }>;
};
expect(body.renamed).toEqual([{ fromDocName: 'CaseName', toDocName: 'casename' }]);
const status = await git.raw('status', '--short');
expect(status).toContain('CaseName.md -> casename.md');
});
test.skipIf(process.platform === 'darwin' || process.platform === 'win32')(
'case-only file rename rejects distinct destination file on case-sensitive filesystems',
async () => {
const dir = setupTmpDir();
writeFileSync(join(dir, 'Notes.md'), '# Upper\n', 'utf-8');
writeFileSync(join(dir, 'notes.md'), '# Lower\n', 'utf-8');
const result = await callApi(
dir,
'/api/rename-path',
'POST',
{ kind: 'file', fromPath: 'Notes', toPath: 'notes' },
{ backlinkIndex: buildBacklinkIndex(dir), projectDir: dir },
);
expect(result.status).toBe(409);
expect(readFileSync(join(dir, 'Notes.md'), 'utf-8')).toBe('# Upper\n');
expect(readFileSync(join(dir, 'notes.md'), 'utf-8')).toBe('# Lower\n');
},
);
test.skipIf(process.platform === 'darwin' || process.platform === 'win32')(
'case-only folder rename rejects distinct destination folder on case-sensitive filesystems',
async () => {
const dir = setupTmpDir();
mkdirSync(join(dir, 'Docs'), { recursive: true });
mkdirSync(join(dir, 'docs'), { recursive: true });
writeFileSync(join(dir, 'Docs/index.md'), '# Upper\n', 'utf-8');
writeFileSync(join(dir, 'docs/index.md'), '# Lower\n', 'utf-8');
const result = await callApi(
dir,
'/api/rename-path',
'POST',
{ kind: 'folder', fromPath: 'Docs', toPath: 'docs' },
{ backlinkIndex: buildBacklinkIndex(dir), projectDir: dir },
);
expect(result.status).toBe(409);
expect(readFileSync(join(dir, 'Docs/index.md'), 'utf-8')).toBe('# Upper\n');
expect(readFileSync(join(dir, 'docs/index.md'), 'utf-8')).toBe('# Lower\n');
},
);
test('deletes a file and reports the removed doc name', async () => {
const dir = setupTmpDir();
writeFileSync(join(dir, 'trash-me.md'), '# Delete me\n', 'utf-8');
const result = await callApi(dir, '/api/delete-path', 'POST', {
kind: 'file',
path: 'trash-me',
});
expect(result.status).toBe(200);
expect(existsSync(join(dir, 'trash-me.md'))).toBe(false);
const body = JSON.parse(result.body) as { ok: boolean; deletedDocNames: string[] };
expect(body.ok).toBeUndefined();
expect(body.deletedDocNames).toEqual(['trash-me']);
});
test('keeps a durable delete successful when relationship projection fails', async () => {
const dir = setupTmpDir();
writeFileSync(join(dir, 'trash-me.md'), '# Delete me\n', 'utf-8');
const failingBacklinkIndex = {
deleteDocument: () => {
throw new Error('projection failed');
},
} as unknown as BacklinkIndex;
const result = await callApi(
dir,
'/api/delete-path',
'POST',
{ kind: 'file', path: 'trash-me' },
{ backlinkIndex: failingBacklinkIndex },
);
expect(result.status).toBe(200);
expect(existsSync(join(dir, 'trash-me.md'))).toBe(false);
expect(JSON.parse(result.body)).toMatchObject({ deletedDocNames: ['trash-me'] });
});
test('delete accepts asset-shaped markdown paths as document deletes', async () => {
const dir = setupTmpDir();
writeFileSync(join(dir, 'trash-me.md'), '# Delete me\n', 'utf-8');
const result = await callApi(dir, '/api/delete-path', 'POST', {
kind: 'asset',
path: 'trash-me.md',
});
expect(result.status).toBe(200);
expect(existsSync(join(dir, 'trash-me.md'))).toBe(false);
const body = JSON.parse(result.body) as { deletedDocNames: string[] };
expect(body.deletedDocNames).toEqual(['trash-me']);
});
test('renames an asset and rewrites markdown references', async () => {
const dir = setupTmpDir();
mkdirSync(join(dir, 'docs/media'), { recursive: true });
writeFileSync(join(dir, 'docs/media/diagram.png'), 'fake image bytes', 'utf-8');
writeFileSync(
join(dir, 'docs/guide.md'),
[
'# Guide',
'',
'',
'[download](./media/diagram.png?dl=1#hash)',
'![[media/diagram.png|Diagram]]',
'[[media/diagram.png#page=2|Diagram]]',
'',
'',
'``',
'',
'```md',
'',
'```',
'',
].join('\n'),
'utf-8',
);
const contentFilter = createContentFilter({ projectDir: dir, contentDir: dir });
const result = await callApi(
dir,
'/api/rename-path',
'POST',
{
kind: 'asset',
fromPath: 'docs/media/diagram.png',
toPath: 'docs/assets/hero.png',
},
{
contentFilter,
},
);
expect(result.status).toBe(200);
expect(existsSync(join(dir, 'docs/media/diagram.png'))).toBe(false);
expect(readFileSync(join(dir, 'docs/assets/hero.png'), 'utf-8')).toBe('fake image bytes');
expect(readFileSync(join(dir, 'docs/guide.md'), 'utf-8')).toBe(
[
'# Guide',
'',
'',
'[download](./assets/hero.png?dl=1#hash)',
'![[assets/hero.png|Diagram]]',
'[[assets/hero.png#page=2|Diagram]]',
'',
'',
'``',
'',
'```md',
'',
'```',
'',
].join('\n'),
);
const body = JSON.parse(result.body) as {
renamedAssets: Array<{ fromPath: string; toPath: string }>;
renamed: unknown[];
rewrittenDocs: Array<{ docName: string; rewrites: number }>;
};
expect(body.renamed).toEqual([]);
expect(body.renamedAssets).toEqual([
{ fromPath: 'docs/media/diagram.png', toPath: 'docs/assets/hero.png' },
]);
expect(body.rewrittenDocs).toEqual([{ docName: 'docs/guide', rewrites: 5 }]);
});
test('keeps an asset rename successful when the derived index closes after disk commit', async () => {
const dir = setupTmpDir();
mkdirSync(join(dir, 'docs/media'), { recursive: true });
writeFileSync(join(dir, 'docs/media/diagram.png'), 'fake image bytes', 'utf-8');
writeFileSync(join(dir, 'docs/guide.md'), '\n', 'utf-8');
const result = await callApi(
dir,
'/api/rename-path',
'POST',
{
kind: 'asset',
fromPath: 'docs/media/diagram.png',
toPath: 'docs/assets/diagram.png',
},
{ derivedDocumentIndex: createClosedDerivedDocumentIndexPort() },
);
expect(result.status).toBe(200);
expect(existsSync(join(dir, 'docs/media/diagram.png'))).toBe(false);
expect(readFileSync(join(dir, 'docs/assets/diagram.png'), 'utf-8')).toBe('fake image bytes');
expect(readFileSync(join(dir, 'docs/guide.md'), 'utf-8')).toBe(
'\n',
);
});
test('asset rename rejects destinations excluded by content config', async () => {
const dir = setupTmpDir();
mkdirSync(join(dir, 'docs/media'), { recursive: true });
writeFileSync(join(dir, 'docs/media/diagram.png'), 'fake image bytes', 'utf-8');
writeFileSync(join(dir, 'docs/guide.md'), '# Guide\n', 'utf-8');
writeFileSync(join(dir, '.okignore'), 'private-assets/\n', 'utf-8');
const contentFilter = createContentFilter({ projectDir: dir, contentDir: dir });
const result = await callApi(
dir,
'/api/rename-path',
'POST',
{
kind: 'asset',
fromPath: 'docs/media/diagram.png',
toPath: 'private-assets/hero.png',
},
{ contentFilter },
);
expect(result.status).toBe(400);
expect(existsSync(join(dir, 'docs/media/diagram.png'))).toBe(true);
expect(existsSync(join(dir, 'private-assets/hero.png'))).toBe(false);
expect(JSON.parse(result.body)).toMatchObject({
type: 'urn:ok:error:invalid-request',
title: 'Destination asset is excluded by the project content config.',
status: 400,
});
});
test('asset rename preserves the source extension when the destination omits it', async () => {
const dir = setupTmpDir();
mkdirSync(join(dir, 'docs/media'), { recursive: true });
writeFileSync(join(dir, 'docs/media/diagram.png'), 'fake image bytes', 'utf-8');
writeFileSync(join(dir, 'docs/guide.md'), '\n', 'utf-8');
const contentFilter = createContentFilter({ projectDir: dir, contentDir: dir });
const result = await callApi(
dir,
'/api/rename-path',
'POST',
{
kind: 'asset',
fromPath: 'docs/media/diagram.png',
toPath: 'docs/media/hero',
},
{ contentFilter },
);
expect(result.status).toBe(200);
expect(existsSync(join(dir, 'docs/media/diagram.png'))).toBe(false);
expect(readFileSync(join(dir, 'docs/media/hero.png'), 'utf-8')).toBe('fake image bytes');
expect(readFileSync(join(dir, 'docs/guide.md'), 'utf-8')).toBe(
'\n',
);
const body = JSON.parse(result.body) as {
renamedAssets: Array<{ fromPath: string; toPath: string }>;
rewrittenDocs: Array<{ docName: string; rewrites: number }>;
};
expect(body.renamedAssets).toEqual([
{ fromPath: 'docs/media/diagram.png', toPath: 'docs/media/hero.png' },
]);
expect(body.rewrittenDocs).toEqual([{ docName: 'docs/guide', rewrites: 1 }]);
});
test('asset rename allows arbitrary source extensions', async () => {
const dir = setupTmpDir();
mkdirSync(join(dir, 'docs/media'), { recursive: true });
writeFileSync(join(dir, 'docs/media/archive.xyz'), 'fake bytes', 'utf-8');
const result = await callApi(dir, '/api/rename-path', 'POST', {
kind: 'asset',
fromPath: 'docs/media/archive.xyz',
toPath: 'docs/media/archive.png',
});
expect(result.status).toBe(200);
expect(existsSync(join(dir, 'docs/media/archive.xyz'))).toBe(false);
expect(readFileSync(join(dir, 'docs/media/archive.png'), 'utf-8')).toBe('fake bytes');
});
test('asset rename allows arbitrary destination extensions', async () => {
const dir = setupTmpDir();
mkdirSync(join(dir, 'docs/media'), { recursive: true });
writeFileSync(join(dir, 'docs/media/diagram.png'), 'fake image bytes', 'utf-8');
const result = await callApi(dir, '/api/rename-path', 'POST', {
kind: 'asset',
fromPath: 'docs/media/diagram.png',
toPath: 'docs/media/diagram.pngg',
});
expect(result.status).toBe(200);
expect(existsSync(join(dir, 'docs/media/diagram.png'))).toBe(false);
expect(readFileSync(join(dir, 'docs/media/diagram.pngg'), 'utf-8')).toBe('fake image bytes');
});
test('asset rename allows markdown documents to become arbitrary files', async () => {
const dir = setupTmpDir();
mkdirSync(join(dir, 'docs/media'), { recursive: true });
writeFileSync(join(dir, 'docs/guide.md'), '# Guide\n', 'utf-8');
writeFileSync(join(dir, 'docs/index.md'), '[Guide](./guide.md)\n', 'utf-8');
const backlinkIndex = await buildBacklinkIndex(dir);
const backlinkSave = vi.spyOn(backlinkIndex, 'saveToDisk');
const signals: string[] = [];
const result = await callApi(
dir,
'/api/rename-path',
'POST',
{
kind: 'asset',
fromPath: 'docs/guide.md',
toPath: 'docs/media/guide.custom',
},
{
backlinkIndex,
signalChannel: (channel) => signals.push(channel),
},
);
expect(result.status).toBe(200);
expect(existsSync(join(dir, 'docs/guide.md'))).toBe(false);
expect(readFileSync(join(dir, 'docs/media/guide.custom'), 'utf-8')).toBe('# Guide\n');
expect(readFileSync(join(dir, 'docs/index.md'), 'utf-8')).toBe(
'[Guide](./media/guide.custom)\n',
);
const body = JSON.parse(result.body) as {
renamed: Array<{ fromDocName: string; toDocName: string }>;
renamedAssets: Array<{ fromPath: string; toPath: string }>;
rewrittenDocs: Array<{ docName: string; rewrites: number }>;
};
expect(body.renamed).toEqual([]);
expect(body.renamedAssets).toEqual([
{
fromPath: 'docs/guide.md',
toPath: 'docs/media/guide.custom',
},
]);
expect(body.rewrittenDocs).toEqual([{ docName: 'docs/index', rewrites: 1 }]);
expect(backlinkSave).toHaveBeenCalledTimes(1);
expect(signals.filter((channel) => channel !== 'files')).toEqual([
'backlinks',
'graph',
'tags',
]);
});
test('document-to-file rename carries live Y.Doc content to the destination file', async () => {
const dir = setupTmpDir();
writeFileSync(join(dir, 'live.md'), '# Stale\n', 'utf-8');
const hocuspocus = new Hocuspocus({ quiet: true });
const conn = await hocuspocus.openDirectConnection('live');
const document = (conn as unknown as { document: Y.Doc }).document;
const ytext = document.getText('source');
document.transact(() => {
ytext.insert(0, '# Live\n');
});
try {
const result = await callApi(
dir,
'/api/rename-path',
'POST',
{
kind: 'asset',
fromPath: 'live.md',
toPath: 'live.txt',
},
{
backlinkIndex: buildBacklinkIndex(dir),
hocuspocus,
},
);
expect(result.status).toBe(200);
expect(existsSync(join(dir, 'live.md'))).toBe(false);
expect(readFileSync(join(dir, 'live.txt'), 'utf-8')).toBe('# Live\n');
} finally {
await conn.disconnect().catch(() => {});
}
});
test('keeps a document-to-file rename successful when the derived index closes', async () => {
const dir = setupTmpDir();
writeFileSync(join(dir, 'guide.md'), '# Guide\n', 'utf-8');
const result = await callApi(
dir,
'/api/rename-path',
'POST',
{
kind: 'asset',
fromPath: 'guide.md',
toPath: 'guide.txt',
},
{ derivedDocumentIndex: createClosedDerivedDocumentIndexPort() },
);
expect(result.status).toBe(200);
expect(existsSync(join(dir, 'guide.md'))).toBe(false);
expect(readFileSync(join(dir, 'guide.txt'), 'utf-8')).toBe('# Guide\n');
});
test('document-to-file rename returns 404 when the source document is missing', async () => {
const dir = setupTmpDir();
const result = await callApi(
dir,
'/api/rename-path',
'POST',
{
kind: 'asset',
fromPath: 'missing.md',
toPath: 'missing.txt',
},
{ backlinkIndex: buildBacklinkIndex(dir) },
);
expect(result.status).toBe(404);
expect(existsSync(join(dir, 'missing.txt'))).toBe(false);
expect(JSON.parse(result.body)).toMatchObject({
type: 'urn:ok:error:doc-not-found',
status: 404,
});
});
test('document-to-file rename returns 409 when the destination file exists', async () => {
const dir = setupTmpDir();
writeFileSync(join(dir, 'guide.md'), '# Guide\n', 'utf-8');
writeFileSync(join(dir, 'guide.txt'), 'existing\n', 'utf-8');
const result = await callApi(
dir,
'/api/rename-path',
'POST',
{
kind: 'asset',
fromPath: 'guide.md',
toPath: 'guide.txt',
},
{ backlinkIndex: buildBacklinkIndex(dir) },
);
expect(result.status).toBe(409);
expect(readFileSync(join(dir, 'guide.md'), 'utf-8')).toBe('# Guide\n');
expect(readFileSync(join(dir, 'guide.txt'), 'utf-8')).toBe('existing\n');
});
test('document-to-file rename requires a backlink index', async () => {
const dir = setupTmpDir();
writeFileSync(join(dir, 'guide.md'), '# Guide\n', 'utf-8');
const result = await callApi(
dir,
'/api/rename-path',
'POST',
{
kind: 'asset',
fromPath: 'guide.md',
toPath: 'guide.txt',
},
{ backlinkIndex: null },
);
expect(result.status).toBe(503);
expect(JSON.parse(result.body)).toMatchObject({
type: 'urn:ok:error:backlink-index-not-configured',
status: 503,
});
expect(readFileSync(join(dir, 'guide.md'), 'utf-8')).toBe('# Guide\n');
});
test('asset rename allows arbitrary files to use markdown extensions', async () => {
const dir = setupTmpDir();
mkdirSync(join(dir, 'docs/media'), { recursive: true });
writeFileSync(join(dir, 'docs/media/guide.custom'), '# Guide\n', 'utf-8');
writeFileSync(join(dir, 'docs/index.md'), '[Guide](./media/guide.custom)\n', 'utf-8');
const result = await callApi(
dir,
'/api/rename-path',
'POST',
{
kind: 'asset',
fromPath: 'docs/media/guide.custom',
toPath: 'docs/guide.md',
},
{ backlinkIndex: buildBacklinkIndex(dir) },
);
expect(result.status).toBe(200);
expect(existsSync(join(dir, 'docs/media/guide.custom'))).toBe(false);
expect(readFileSync(join(dir, 'docs/guide.md'), 'utf-8')).toBe('# Guide\n');
expect(readFileSync(join(dir, 'docs/index.md'), 'utf-8')).toBe('[Guide](./guide.md)\n');
const body = JSON.parse(result.body) as {
renamed: Array<{ fromDocName: string; toDocName: string }>;
renamedAssets: Array<{ fromPath: string; toPath: string }>;
rewrittenDocs: Array<{ docName: string; rewrites: number }>;
};
expect(body.renamed).toEqual([]);
expect(body.renamedAssets).toEqual([
{
fromPath: 'docs/media/guide.custom',
toPath: 'docs/guide.md',
},
]);
expect(body.rewrittenDocs).toEqual([{ docName: 'docs/index', rewrites: 1 }]);
});
test('asset rename to markdown extension returns 404 when the source file is missing', async () => {
const dir = setupTmpDir();
const result = await callApi(
dir,
'/api/rename-path',
'POST',
{
kind: 'asset',
fromPath: 'missing.txt',
toPath: 'missing.md',
},
{ backlinkIndex: buildBacklinkIndex(dir) },
);
expect(result.status).toBe(404);
expect(existsSync(join(dir, 'missing.md'))).toBe(false);
expect(JSON.parse(result.body)).toMatchObject({
type: 'urn:ok:error:doc-not-found',
title: 'Asset does not exist.',
status: 404,
});
});
test('asset rename to markdown extension returns 409 when the destination exists', async () => {
const dir = setupTmpDir();
writeFileSync(join(dir, 'guide.txt'), '# Guide\n', 'utf-8');
writeFileSync(join(dir, 'guide.md'), '# Existing\n', 'utf-8');
const result = await callApi(
dir,
'/api/rename-path',
'POST',
{
kind: 'asset',
fromPath: 'guide.txt',
toPath: 'guide.md',
},
{ backlinkIndex: buildBacklinkIndex(dir) },
);
expect(result.status).toBe(409);
expect(readFileSync(join(dir, 'guide.txt'), 'utf-8')).toBe('# Guide\n');
expect(readFileSync(join(dir, 'guide.md'), 'utf-8')).toBe('# Existing\n');
});
test('asset rename to markdown extension requires a backlink index', async () => {
const dir = setupTmpDir();
writeFileSync(join(dir, 'guide.txt'), '# Guide\n', 'utf-8');
const result = await callApi(
dir,
'/api/rename-path',
'POST',
{
kind: 'asset',
fromPath: 'guide.txt',
toPath: 'guide.md',
},
{ backlinkIndex: null },
);
expect(result.status).toBe(503);
expect(JSON.parse(result.body)).toMatchObject({
type: 'urn:ok:error:backlink-index-not-configured',
status: 503,
});
expect(readFileSync(join(dir, 'guide.txt'), 'utf-8')).toBe('# Guide\n');
});
test('asset rename allows binary input to use a markdown extension', async () => {
const dir = setupTmpDir();
writeFileSync(join(dir, 'binary.bin'), Buffer.from([0x23, 0x00, 0xff]));
const result = await callApi(
dir,
'/api/rename-path',
'POST',
{
kind: 'asset',
fromPath: 'binary.bin',
toPath: 'binary.md',
},
{ backlinkIndex: buildBacklinkIndex(dir) },
);
expect(result.status).toBe(200);
expect(existsSync(join(dir, 'binary.bin'))).toBe(false);
expect(readFileSync(join(dir, 'binary.md'))).toEqual(Buffer.from([0x23, 0x00, 0xff]));
});
test('asset-shaped markdown rename uses the document rename path', async () => {
const dir = setupTmpDir();
mkdirSync(join(dir, 'docs'), { recursive: true });
writeFileSync(join(dir, 'docs/guide.md'), '# Guide\n', 'utf-8');
const result = await callApi(
dir,
'/api/rename-path',
'POST',
{
kind: 'asset',
fromPath: 'docs/guide.md',
toPath: 'docs/guide.mdx',
},
{ backlinkIndex: buildBacklinkIndex(dir) },
);
expect(result.status).toBe(200);
expect(existsSync(join(dir, 'docs/guide.md'))).toBe(false);
expect(readFileSync(join(dir, 'docs/guide.mdx'), 'utf-8')).toBe('# Guide\n');
});
test('asset rename returns 404 when the source asset is missing', async () => {
const dir = setupTmpDir();
mkdirSync(join(dir, 'docs/media'), { recursive: true });
const result = await callApi(dir, '/api/rename-path', 'POST', {
kind: 'asset',
fromPath: 'docs/media/missing.png',
toPath: 'docs/media/hero.png',
});
expect(result.status).toBe(404);
expect(existsSync(join(dir, 'docs/media/hero.png'))).toBe(false);
expect(JSON.parse(result.body)).toMatchObject({
type: 'urn:ok:error:doc-not-found',
title: 'Asset does not exist.',
status: 404,
});
});
test('asset rename returns 409 when the destination asset exists', async () => {
const dir = setupTmpDir();
mkdirSync(join(dir, 'docs/media'), { recursive: true });
writeFileSync(join(dir, 'docs/media/diagram.png'), 'fake image bytes', 'utf-8');
writeFileSync(join(dir, 'docs/media/hero.png'), 'existing image bytes', 'utf-8');
const result = await callApi(dir, '/api/rename-path', 'POST', {
kind: 'asset',
fromPath: 'docs/media/diagram.png',
toPath: 'docs/media/hero.png',
});
expect(result.status).toBe(409);
expect(readFileSync(join(dir, 'docs/media/diagram.png'), 'utf-8')).toBe('fake image bytes');
expect(readFileSync(join(dir, 'docs/media/hero.png'), 'utf-8')).toBe('existing image bytes');
expect(JSON.parse(result.body)).toMatchObject({
type: 'urn:ok:error:doc-already-exists',
title: 'Destination already exists.',
status: 409,
});
});
test('asset rename rejects a supported-extension directory as the source', async () => {
const dir = setupTmpDir();
mkdirSync(join(dir, 'docs/media/folder.png'), { recursive: true });
const result = await callApi(dir, '/api/rename-path', 'POST', {
kind: 'asset',
fromPath: 'docs/media/folder.png',
toPath: 'docs/media/hero.png',
});
expect(result.status).toBe(400);
expect(existsSync(join(dir, 'docs/media/folder.png'))).toBe(true);
expect(existsSync(join(dir, 'docs/media/hero.png'))).toBe(false);
expect(JSON.parse(result.body)).toMatchObject({
type: 'urn:ok:error:invalid-request',
title: 'Source path is not an asset file.',
status: 400,
});
});
test('asset rename rejects case-only renames before touching disk', async () => {
const dir = setupTmpDir();
mkdirSync(join(dir, 'docs/media'), { recursive: true });
writeFileSync(join(dir, 'docs/media/diagram.png'), 'fake image bytes', 'utf-8');
const result = await callApi(dir, '/api/rename-path', 'POST', {
kind: 'asset',
fromPath: 'docs/media/diagram.png',
toPath: 'docs/media/Diagram.png',
});
expect(result.status).toBe(400);
expect(readFileSync(join(dir, 'docs/media/diagram.png'), 'utf-8')).toBe('fake image bytes');
expect(JSON.parse(result.body)).toMatchObject({
type: 'urn:ok:error:invalid-request',
title: 'Case-only renames are not supported.',
status: 400,
});
});
test.skipIf(process.platform === 'win32')(
'asset rename rejects destination symlink escapes',
async () => {
const root = setupTmpDir();
const contentDir = join(root, 'content');
const outside = join(root, 'outside');
mkdirSync(join(contentDir, 'assets'), { recursive: true });
mkdirSync(outside);
symlinkSync(join('..', 'outside'), join(contentDir, 'evil'), 'dir');
writeFileSync(join(contentDir, 'assets/source.png'), 'fake image bytes', 'utf-8');
const result = await callApi(contentDir, '/api/rename-path', 'POST', {
kind: 'asset',
fromPath: 'assets/source.png',
toPath: 'evil/captured.png',
});
expect(result.status).toBe(400);
expect(readFileSync(join(contentDir, 'assets/source.png'), 'utf-8')).toBe('fake image bytes');
expect(existsSync(join(outside, 'captured.png'))).toBe(false);
expect(JSON.parse(result.body)).toMatchObject({
type: 'urn:ok:error:path-escape',
title: 'symlink-escape: path resolves outside content directory.',
status: 400,
});
},
);
test('asset rename maps missing backlink index to the managed-rename 503', async () => {
const dir = setupTmpDir();
mkdirSync(join(dir, 'docs/media'), { recursive: true });
writeFileSync(join(dir, 'docs/media/diagram.png'), 'fake image bytes', 'utf-8');
const result = await callApi(
dir,
'/api/rename-path',
'POST',
{
kind: 'asset',
fromPath: 'docs/media/diagram.png',
toPath: 'docs/media/hero.png',
},
{ backlinkIndex: null },
);
expect(result.status).toBe(503);
const body = JSON.parse(result.body) as { type: string; title: string };
expect(body.type).toBe('urn:ok:error:backlink-index-not-configured');
expect(body.title).toBe('Managed rename requires backlink index support.');
});
test('renames an asset-only folder and rewrites markdown references', async () => {
const dir = setupTmpDir();
mkdirSync(join(dir, 'media'), { recursive: true });
writeFileSync(join(dir, 'media/diagram.png'), 'fake image bytes', 'utf-8');
writeFileSync(
join(dir, 'index.md'),
['# Index', '', '', '![[media/diagram.png]]', ''].join('\n'),
'utf-8',
);
const result = await callApi(dir, '/api/rename-path', 'POST', {
kind: 'folder',
fromPath: 'media',
toPath: 'assets',
});
expect(result.status).toBe(200);
expect(existsSync(join(dir, 'media/diagram.png'))).toBe(false);
expect(readFileSync(join(dir, 'assets/diagram.png'), 'utf-8')).toBe('fake image bytes');
expect(readFileSync(join(dir, 'index.md'), 'utf-8')).toBe(
['# Index', '', '', '![[assets/diagram.png]]', ''].join('\n'),
);
const body = JSON.parse(result.body) as {
renamed: Array<{ fromDocName: string; toDocName: string }>;
renamedAssets: Array<{ fromPath: string; toPath: string }>;
rewrittenDocs: Array<{ docName: string; rewrites: number }>;
};
expect(body.renamed).toEqual([]);
expect(body.renamedAssets).toEqual([
{ fromPath: 'media/diagram.png', toPath: 'assets/diagram.png' },
]);
expect(body.rewrittenDocs).toEqual([{ docName: 'index', rewrites: 2 }]);
});
test('keeps an asset-only folder rename successful when the derived index closes', async () => {
const dir = setupTmpDir();
mkdirSync(join(dir, 'media'), { recursive: true });
writeFileSync(join(dir, 'media/diagram.png'), 'fake image bytes', 'utf-8');
writeFileSync(join(dir, 'index.md'), '\n', 'utf-8');
const result = await callApi(
dir,
'/api/rename-path',
'POST',
{
kind: 'folder',
fromPath: 'media',
toPath: 'assets',
},
{ derivedDocumentIndex: createClosedDerivedDocumentIndexPort() },
);
expect(result.status).toBe(200);
expect(existsSync(join(dir, 'media'))).toBe(false);
expect(readFileSync(join(dir, 'assets/diagram.png'), 'utf-8')).toBe('fake image bytes');
expect(readFileSync(join(dir, 'index.md'), 'utf-8')).toBe('\n');
});
test('folder rename rewrites references to assets that move with markdown docs', async () => {
const dir = setupTmpDir();
mkdirSync(join(dir, 'docs/media'), { recursive: true });
writeFileSync(join(dir, 'docs/media/diagram.png'), 'fake image bytes', 'utf-8');
writeFileSync(
join(dir, 'docs/guide.md'),
['# Guide', '', '', ''].join('\n'),
'utf-8',
);
writeFileSync(
join(dir, 'index.md'),
[
'# Index',
'',
'',
'',
'![[docs/media/diagram.png]]',
'',
].join('\n'),
'utf-8',
);
const result = await callApi(dir, '/api/rename-path', 'POST', {
kind: 'folder',
fromPath: 'docs',
toPath: 'guides',
});
expect(result.status).toBe(200);
expect(existsSync(join(dir, 'docs/media/diagram.png'))).toBe(false);
expect(readFileSync(join(dir, 'guides/media/diagram.png'), 'utf-8')).toBe('fake image bytes');
expect(readFileSync(join(dir, 'guides/guide.md'), 'utf-8')).toBe(
['# Guide', '', '', ''].join('\n'),
);
expect(readFileSync(join(dir, 'index.md'), 'utf-8')).toBe(
[
'# Index',
'',
'',
'',
'![[guides/media/diagram.png]]',
'',
].join('\n'),
);
const body = JSON.parse(result.body) as {
renamed: Array<{ fromDocName: string; toDocName: string }>;
renamedAssets: Array<{ fromPath: string; toPath: string }>;
rewrittenDocs: Array<{ docName: string; rewrites: number }>;
};
expect(body.renamed).toEqual([{ fromDocName: 'docs/guide', toDocName: 'guides/guide' }]);
expect(body.renamedAssets).toEqual([
{ fromPath: 'docs/media/diagram.png', toPath: 'guides/media/diagram.png' },
]);
expect(body.rewrittenDocs).toEqual([
{ docName: 'guides/guide', rewrites: 2 },
{ docName: 'index', rewrites: 3 },
]);
});
test('deletes an asset and reports no deleted doc names', async () => {
const dir = setupTmpDir();
mkdirSync(join(dir, 'assets'), { recursive: true });
writeFileSync(join(dir, 'assets/trash-me.png'), 'fake image bytes', 'utf-8');
const result = await callApi(dir, '/api/delete-path', 'POST', {
kind: 'asset',
path: 'assets/trash-me.png',
});
expect(result.status).toBe(200);
expect(existsSync(join(dir, 'assets/trash-me.png'))).toBe(false);
const body = JSON.parse(result.body) as { deletedDocNames: string[] };
expect(body.deletedDocNames).toEqual([]);
});
test('asset delete invalidates the cached document list asset row', async () => {
const dir = setupTmpDir();
mkdirSync(join(dir, 'docs'), { recursive: true });
writeFileSync(join(dir, 'docs/guide.md'), '\n', 'utf-8');
writeFileSync(join(dir, 'docs/foo.png'), 'fake image bytes', 'utf-8');
const fileIndex = new Map(buildFileIndex(dir));
const api = await createTestApiExtension(dir, {
getFileIndex: () => fileIndex,
});
const before = await callApiExtension(api, '/api/documents', 'GET', undefined);
expect(before.status).toBe(200);
expect(assetPathsFromDocumentList(before)).toContain('docs/foo.png');
const result = await callApiExtension(api, '/api/delete-path', 'POST', {
kind: 'asset',
path: 'docs/foo.png',
});
expect(result.status).toBe(200);
expect(existsSync(join(dir, 'docs/foo.png'))).toBe(false);
const after = await callApiExtension(api, '/api/documents', 'GET', undefined);
expect(after.status).toBe(200);
expect(assetPathsFromDocumentList(after)).not.toContain('docs/foo.png');
});
test('registered asset cache invalidator refreshes referenced assets after markdown writes', async () => {
const dir = setupTmpDir();
mkdirSync(join(dir, 'docs'), { recursive: true });
writeFileSync(join(dir, 'docs/guide.md'), '\n', 'utf-8');
writeFileSync(join(dir, 'docs/foo.png'), 'fake image bytes', 'utf-8');
writeFileSync(join(dir, 'docs/bar.png'), 'new image bytes', 'utf-8');
const fileIndex = new Map(buildFileIndex(dir));
let invalidate: (() => void) | null = null;
const api = await createTestApiExtension(dir, {
getFileIndex: () => fileIndex,
onReferencedAssetsCacheInvalidator: (registered) => {
invalidate = registered;
},
});
const before = await callApiExtension(api, '/api/documents', 'GET', undefined);
expect(before.status).toBe(200);
expect(assetPathsFromDocumentList(before)).toContain('docs/foo.png');
expect(assetPathsFromDocumentList(before)).not.toContain('docs/bar.png');
writeFileSync(join(dir, 'docs/guide.md'), '\n', 'utf-8');
const stale = await callApiExtension(api, '/api/documents', 'GET', undefined);
expect(stale.status).toBe(200);
expect(assetPathsFromDocumentList(stale)).toContain('docs/foo.png');
expect(assetPathsFromDocumentList(stale)).not.toContain('docs/bar.png');
expect(invalidate).not.toBeNull();
invalidate?.();
const after = await callApiExtension(api, '/api/documents', 'GET', undefined);
expect(after.status).toBe(200);
expect(assetPathsFromDocumentList(after)).not.toContain('docs/foo.png');
expect(assetPathsFromDocumentList(after)).toContain('docs/bar.png');
});
test('cached canonical asset is excluded without a generation change', async () => {
const dir = setupTmpDir();
const a = join(dir, 'a.csv');
const b = join(dir, 'b.csv');
const linked = join(dir, 'linked.csv');
const source = join(dir, 'source.md');
const ignore = join(dir, '.okignore');
const sourceContent = '# Source\n\n[A](a.csv)\n\n[Linked](linked.csv)\n';
writeFileSync(a, 'a,admitted\n');
writeFileSync(b, 'b,admitted\n');
symlinkSync(b, linked);
writeFileSync(source, sourceContent);
writeFileSync(ignore, '');
const sourceStat = statSync(source);
const bStat = statSync(b);
const filter = createContentFilter({ projectDir: dir, contentDir: dir });
const fileIndex = new Map(buildFileIndex(dir));
const indexedSource = fileIndex.get('source');
expect(indexedSource).toBeDefined();
expect(fileIndex.has('b.csv')).toBe(false);
const api = await createTestApiExtension(dir, {
contentFilter: filter,
getFileIndex: () => fileIndex,
});
const before = await callApiExtension(api, '/api/documents', 'GET', undefined);
expect(before.status).toBe(200);
const listed = (response: CapturedResponse) =>
(
JSON.parse(response.body) as {
documents: Array<{
kind: string;
path?: string;
size?: number;
modified?: string;
referencedBy?: string[];
}>;
}
).documents;
expect(listed(before).filter((row) => row.path === 'a.csv')).toEqual([
expect.objectContaining({ kind: 'asset', path: 'a.csv', referencedBy: ['source'] }),
]);
expect(listed(before).filter((row) => row.path === 'b.csv')).toEqual([
expect.objectContaining({
kind: 'asset',
path: 'b.csv',
size: bStat.size,
modified: bStat.mtime.toISOString(),
referencedBy: ['source'],
}),
]);
writeFileSync(ignore, 'b.csv\n');
expect((await filter.rebuildIgnorePatterns()).ok).toBe(true);
expect(filter.isPathIgnored('b.csv')).toBe(true);
expect(filter.isPathIgnored('linked.csv')).toBe(false);
expect(filter.isPathIgnored('a.csv')).toBe(false);
expect(fileIndex.get('source')).toBe(indexedSource);
const after = await callApiExtension(api, '/api/documents', 'GET', undefined);
expect(after.status).toBe(200);
expect.soft(listed(after).filter((row) => row.path === 'b.csv')).toEqual([]);
expect
.soft(listed(after).filter((row) => row.path === 'a.csv'))
.toEqual([
expect.objectContaining({ kind: 'asset', path: 'a.csv', referencedBy: ['source'] }),
]);
expect(readFileSync(source, 'utf8')).toBe(sourceContent);
expect(statSync(source).size).toBe(sourceStat.size);
expect(statSync(source).mtimeMs).toBe(sourceStat.mtimeMs);
expect(readFileSync(a, 'utf8')).toBe('a,admitted\n');
expect(readFileSync(b, 'utf8')).toBe('b,admitted\n');
expect(readFileSync(linked, 'utf8')).toBe('b,admitted\n');
expect(statSync(linked).ino).toBe(statSync(b).ino);
});
test('configured filter retains explicit referenced-asset invalidation', async () => {
const dir = setupTmpDir();
const source = join(dir, 'source.md');
const foo = join(dir, 'foo.png');
const bar = join(dir, 'bar.png');
writeFileSync(source, '\n');
writeFileSync(foo, 'foo bytes');
writeFileSync(bar, 'bar bytes');
writeFileSync(join(dir, '.okignore'), '');
const filter = createContentFilter({ projectDir: dir, contentDir: dir });
const fileIndex = new Map(buildFileIndex(dir));
const indexedSource = fileIndex.get('source');
let invalidate: (() => void) | null = null;
const api = await createTestApiExtension(dir, {
contentFilter: filter,
getFileIndex: () => fileIndex,
onReferencedAssetsCacheInvalidator: (registered) => {
invalidate = registered;
},
});
const before = await callApiExtension(api, '/api/documents', 'GET', undefined);
expect(before.status).toBe(200);
expect(assetPathsFromDocumentList(before)).toEqual(['foo.png']);
writeFileSync(source, '\n');
expect(fileIndex.get('source')).toBe(indexedSource);
expect(filter.isPathIgnored('foo.png')).toBe(false);
expect(filter.isPathIgnored('bar.png')).toBe(false);
const stale = await callApiExtension(api, '/api/documents', 'GET', undefined);
expect(stale.status).toBe(200);
expect(assetPathsFromDocumentList(stale)).toEqual(['foo.png']);
expect(invalidate).not.toBeNull();
invalidate?.();
const after = await callApiExtension(api, '/api/documents', 'GET', undefined);
expect(after.status).toBe(200);
expect(assetPathsFromDocumentList(after)).toEqual(['bar.png']);
expect(readFileSync(foo, 'utf8')).toBe('foo bytes');
expect(readFileSync(bar, 'utf8')).toBe('bar bytes');
});
test('asset trash cleanup invalidates the cached document list asset row', async () => {
const dir = setupTmpDir();
mkdirSync(join(dir, 'docs'), { recursive: true });
writeFileSync(join(dir, 'docs/guide.md'), '\n', 'utf-8');
writeFileSync(join(dir, 'docs/foo.png'), 'fake image bytes', 'utf-8');
const fileIndex = new Map(buildFileIndex(dir));
const api = await createTestApiExtension(dir, {
getFileIndex: () => fileIndex,
});
const before = await callApiExtension(api, '/api/documents', 'GET', undefined);
expect(before.status).toBe(200);
expect(assetPathsFromDocumentList(before)).toContain('docs/foo.png');
rmSync(join(dir, 'docs/foo.png'));
const result = await callApiExtension(api, '/api/trash/cleanup', 'POST', {
kind: 'asset',
path: 'docs/foo.png',
});
expect(result.status).toBe(200);
const after = await callApiExtension(api, '/api/documents', 'GET', undefined);
expect(after.status).toBe(200);
expect(assetPathsFromDocumentList(after)).not.toContain('docs/foo.png');
});
test('trash cleanup accepts asset-shaped markdown paths as document cleanup', async () => {
const dir = setupTmpDir();
mkdirSync(join(dir, 'docs'), { recursive: true });
writeFileSync(join(dir, 'docs/guide.md'), '# Guide\n', 'utf-8');
const fileIndex = new Map(buildFileIndex(dir));
const api = await createTestApiExtension(dir, {
getFileIndex: () => fileIndex,
});
rmSync(join(dir, 'docs/guide.md'));
const result = await callApiExtension(api, '/api/trash/cleanup', 'POST', {
kind: 'asset',
path: 'docs/guide.md',
});
expect(result.status).toBe(200);
const body = JSON.parse(result.body) as { deletedDocNames: string[] };
expect(body.deletedDocNames).toEqual(['docs/guide']);
expect(fileIndex.has('docs/guide')).toBe(false);
});
test('asset-only folder trash cleanup invalidates the cached document list asset row', async () => {
const dir = setupTmpDir();
mkdirSync(join(dir, 'docs/media'), { recursive: true });
writeFileSync(join(dir, 'docs/guide.md'), '\n', 'utf-8');
writeFileSync(join(dir, 'docs/media/foo.png'), 'fake image bytes', 'utf-8');
const fileIndex = new Map(buildFileIndex(dir));
const api = await createTestApiExtension(dir, {
getFileIndex: () => fileIndex,
});
const before = await callApiExtension(api, '/api/documents', 'GET', undefined);
expect(before.status).toBe(200);
expect(assetPathsFromDocumentList(before)).toContain('docs/media/foo.png');
rmSync(join(dir, 'docs/media'), { recursive: true });
const result = await callApiExtension(api, '/api/trash/cleanup', 'POST', {
kind: 'folder',
path: 'docs/media',
});
expect(result.status).toBe(200);
const after = await callApiExtension(api, '/api/documents', 'GET', undefined);
expect(after.status).toBe(200);
expect(assetPathsFromDocumentList(after)).not.toContain('docs/media/foo.png');
});
test('deletes an asset when the request path omits the extension', async () => {
const dir = setupTmpDir();
mkdirSync(join(dir, 'assets'), { recursive: true });
writeFileSync(join(dir, 'assets/trash-me.png'), 'fake image bytes', 'utf-8');
const result = await callApi(dir, '/api/delete-path', 'POST', {
kind: 'asset',
path: 'assets/trash-me',
});
expect(result.status).toBe(200);
expect(existsSync(join(dir, 'assets/trash-me.png'))).toBe(false);
const body = JSON.parse(result.body) as { deletedDocNames: string[] };
expect(body.deletedDocNames).toEqual([]);
});
test('rejects an extensionless asset delete when multiple supported assets match', async () => {
const dir = setupTmpDir();
mkdirSync(join(dir, 'assets'), { recursive: true });
writeFileSync(join(dir, 'assets/trash-me.png'), 'fake image bytes', 'utf-8');
writeFileSync(join(dir, 'assets/trash-me.jpg'), 'fake image bytes', 'utf-8');
const result = await callApi(dir, '/api/delete-path', 'POST', {
kind: 'asset',
path: 'assets/trash-me',
});
expect(result.status).toBe(400);
expect(existsSync(join(dir, 'assets/trash-me.png'))).toBe(true);
expect(existsSync(join(dir, 'assets/trash-me.jpg'))).toBe(true);
expect(JSON.parse(result.body)).toMatchObject({
type: 'urn:ok:error:invalid-request',
title: 'Asset path without an extension matches multiple files.',
status: 400,
});
});
test('deletes a folder recursively and reports descendant doc names', async () => {
const dir = setupTmpDir();
mkdirSync(join(dir, 'archive/old'), { recursive: true });
writeFileSync(join(dir, 'archive/index.md'), '# Archive\n', 'utf-8');
writeFileSync(join(dir, 'archive/old/entry.md'), '# Entry\n', 'utf-8');
const result = await callApi(dir, '/api/delete-path', 'POST', {
kind: 'folder',
path: 'archive',
});
expect(result.status).toBe(200);
expect(existsSync(join(dir, 'archive'))).toBe(false);
const body = JSON.parse(result.body) as { ok: boolean; deletedDocNames: string[] };
expect(body.ok).toBeUndefined();
expect(body.deletedDocNames).toEqual(['archive/index', 'archive/old/entry']);
});
test('creates an empty folder without materializing index.md', async () => {
const dir = setupTmpDir();
const result = await callApi(dir, '/api/create-folder', 'POST', {
path: 'New Folder',
});
expect(result.status).toBe(200);
expect(existsSync(join(dir, 'New Folder'))).toBe(true);
expect(existsSync(join(dir, 'New Folder/index.md'))).toBe(false);
const body = JSON.parse(result.body) as { path: string };
expect(body.path).toBe('New Folder');
expect((body as Record<string, unknown>).ok).toBeUndefined();
});
test('indexes intermediate folders created recursively', async () => {
const dir = setupTmpDir();
const folderIndex = new Map<string, FolderIndexEntry>();
const getFolderIndex = () => folderIndex;
const result = await callApi(
dir,
'/api/create-folder',
'POST',
{
path: 'a/b/c',
},
{ getFolderIndex },
);
expect(result.status).toBe(200);
expect(existsSync(join(dir, 'a/b/c'))).toBe(true);
const docsResult = await callApi(dir, '/api/documents', 'GET', undefined, { getFolderIndex });
const body = JSON.parse(docsResult.body) as {
ok: boolean;
documents: Array<{ kind: string; path?: string }>;
};
const folderPaths = body.documents
.filter((entry) => entry.kind === 'folder')
.map((entry) => entry.path);
expect(folderPaths).toEqual(expect.arrayContaining(['a', 'a/b', 'a/b/c']));
});
test('duplicates a file next to the source with a unique copy name', async () => {
const dir = setupTmpDir();
writeFileSync(join(dir, 'notes.md'), '# Notes\n', 'utf-8');
writeFileSync(join(dir, 'notes copy.md'), '# Existing copy\n', 'utf-8');
const signals: string[] = [];
const result = await callApi(
dir,
'/api/duplicate-path',
'POST',
{
kind: 'file',
path: 'notes',
},
{ signalChannel: (channel) => signals.push(channel) },
);
expect(result.status).toBe(200);
expect(readFileSync(join(dir, 'notes copy 2.md'), 'utf-8')).toBe('# Notes\n');
expect(signals).toEqual(expect.arrayContaining(['files', 'backlinks', 'graph']));
const body = JSON.parse(result.body) as {
kind: string;
path: string;
duplicatedDocNames: string[];
};
expect(body).toMatchObject({
kind: 'file',
path: 'notes copy 2',
duplicatedDocNames: ['notes copy 2'],
});
});
test('duplicates the selected .md sibling when .md and .mdx share a stem', async () => {
const dir = setupTmpDir();
writeFileSync(join(dir, 'foo.md'), '# Markdown sibling\n', 'utf-8');
writeFileSync(join(dir, 'foo.mdx'), '# MDX sibling\n', 'utf-8');
const result = await callApi(dir, '/api/duplicate-path', 'POST', {
kind: 'file',
path: 'foo.md',
});
expect(result.status).toBe(200);
expect(readFileSync(join(dir, 'foo copy.md'), 'utf-8')).toBe('# Markdown sibling\n');
expect(readFileSync(join(dir, 'foo.mdx'), 'utf-8')).toBe('# MDX sibling\n');
const body = JSON.parse(result.body) as {
kind: string;
path: string;
duplicatedDocNames: string[];
};
expect(body).toMatchObject({
kind: 'file',
path: 'foo copy',
duplicatedDocNames: ['foo copy'],
});
});
test('duplicates a folder containing same-stem .md and .mdx siblings', async () => {
const dir = setupTmpDir();
mkdirSync(join(dir, 'docs'), { recursive: true });
writeFileSync(join(dir, 'docs/foo.md'), '# Markdown sibling\n', 'utf-8');
writeFileSync(join(dir, 'docs/foo.mdx'), '# MDX sibling\n', 'utf-8');
const result = await callApi(dir, '/api/duplicate-path', 'POST', {
kind: 'folder',
path: 'docs',
});
expect(result.status).toBe(200);
expect(readFileSync(join(dir, 'docs copy/foo.md'), 'utf-8')).toBe('# Markdown sibling\n');
expect(readFileSync(join(dir, 'docs copy/foo.mdx'), 'utf-8')).toBe('# MDX sibling\n');
const body = JSON.parse(result.body) as {
kind: string;
path: string;
duplicatedDocNames: string[];
};
expect(body).toMatchObject({
kind: 'folder',
path: 'docs copy',
duplicatedDocNames: ['docs copy/foo.md', 'docs copy/foo.mdx'],
});
});
test('duplicates a folder recursively and reports copied markdown docs', async () => {
const dir = setupTmpDir();
mkdirSync(join(dir, 'archive/old'), { recursive: true });
writeFileSync(join(dir, 'archive/index.md'), '# Archive\n', 'utf-8');
writeFileSync(join(dir, 'archive/old/entry.md'), '# Entry\n', 'utf-8');
writeFileSync(join(dir, 'archive/old/asset.png'), 'png-ish', 'utf-8');
const signals: string[] = [];
const result = await callApi(
dir,
'/api/duplicate-path',
'POST',
{
kind: 'folder',
path: 'archive',
},
{ signalChannel: (channel) => signals.push(channel) },
);
expect(result.status).toBe(200);
expect(readFileSync(join(dir, 'archive copy/index.md'), 'utf-8')).toBe('# Archive\n');
expect(readFileSync(join(dir, 'archive copy/old/entry.md'), 'utf-8')).toBe('# Entry\n');
expect(readFileSync(join(dir, 'archive copy/old/asset.png'), 'utf-8')).toBe('png-ish');
expect(signals).toEqual(expect.arrayContaining(['files', 'backlinks', 'graph']));
const body = JSON.parse(result.body) as {
kind: string;
path: string;
duplicatedDocNames: string[];
};
expect(body.kind).toBe('folder');
expect(body.path).toBe('archive copy');
expect(body.duplicatedDocNames).toEqual(['archive copy/index', 'archive copy/old/entry']);
});
test('keeps a copied folder when the derived index closes after registration', async () => {
const dir = setupTmpDir();
mkdirSync(join(dir, 'archive'), { recursive: true });
writeFileSync(join(dir, 'archive/index.mdx'), '# Archive\n', 'utf-8');
const fileIndex = new Map(buildFileIndex(dir));
const folderIndex = new Map(buildFolderIndex(dir));
const contentFilter = createContentFilter({ projectDir: dir, contentDir: dir });
const result = await callApi(
dir,
'/api/duplicate-path',
'POST',
{
kind: 'folder',
path: 'archive',
},
{
derivedDocumentIndex: createClosedDerivedDocumentIndexPort(),
contentFilter,
getFileIndex: () => fileIndex,
getFolderIndex: () => folderIndex,
mutateFileIndex: (event) => {
if (event.kind === 'create') {
fileIndex.set(event.docName, {
size: event.content.length,
modified: new Date(0).toISOString(),
canonicalPath: event.path,
inode: '',
aliases: [],
});
} else if (event.kind === 'delete') {
fileIndex.delete(event.docName);
}
},
},
);
expect(result.status).toBe(200);
expect(readFileSync(join(dir, 'archive copy/index.mdx'), 'utf-8')).toBe('# Archive\n');
expect(fileIndex.has('archive copy/index')).toBe(true);
expect([...folderIndex.keys()].some((path) => path.startsWith('archive copy'))).toBe(true);
expect(getDocExtension('archive copy/index')).toBe('.mdx');
expect(JSON.parse(result.body)).toMatchObject({
kind: 'folder',
path: 'archive copy',
duplicatedDocNames: ['archive copy/index'],
});
});
test('keeps a copied file when the derived index closes after registration', async () => {
const dir = setupTmpDir();
writeFileSync(join(dir, 'notes.mdx'), '# Notes\n', 'utf-8');
const result = await callApi(
dir,
'/api/duplicate-path',
'POST',
{
kind: 'file',
path: 'notes',
},
{
derivedDocumentIndex: createClosedDerivedDocumentIndexPort(),
getFileIndex: () => new Map(),
},
);
expect(result.status).toBe(200);
expect(readFileSync(join(dir, 'notes copy.mdx'), 'utf-8')).toBe('# Notes\n');
expect(getDocExtension('notes copy')).toBe('.mdx');
expect(JSON.parse(result.body)).toMatchObject({
kind: 'file',
path: 'notes copy',
duplicatedDocNames: ['notes copy'],
});
});
test('rolls back a copied folder when synchronous registration fails', async () => {
const dir = setupTmpDir();
mkdirSync(join(dir, 'archive'), { recursive: true });
writeFileSync(join(dir, 'archive/index.md'), '# Archive\n', 'utf-8');
const result = await callApi(
dir,
'/api/duplicate-path',
'POST',
{
kind: 'folder',
path: 'archive',
},
{
mutateFileIndex: (event) => {
if (event.kind === 'create') throw new Error('registration failed');
},
},
);
expect(result.status).toBe(500);
expect(existsSync(join(dir, 'archive copy'))).toBe(false);
});
test('rolls back a copied file when synchronous registration fails', async () => {
const dir = setupTmpDir();
writeFileSync(join(dir, 'notes.md'), '# Notes\n', 'utf-8');
const result = await callApi(
dir,
'/api/duplicate-path',
'POST',
{
kind: 'file',
path: 'notes',
},
{
mutateFileIndex: (event) => {
if (event.kind === 'create') throw new Error('registration failed');
},
},
);
expect(result.status).toBe(500);
expect(existsSync(join(dir, 'notes copy.md'))).toBe(false);
});
test('returns 409 when duplicate-path folder destination appears before copy', async () => {
const dir = setupTmpDir();
mkdirSync(join(dir, 'archive'), { recursive: true });
writeFileSync(join(dir, 'archive/index.md'), '# Archive\n', 'utf-8');
const racingContentFilter = {
isExcluded: () => false,
isDirExcluded: (relativePath: string) => {
writeFileSync(join(dir, relativePath), 'occupied', 'utf-8');
return false;
},
isPathIgnored: () => false,
getWatcherIgnoreGlobs: () => [],
incrementMdDir: () => {},
decrementMdDir: () => {},
getMdDirRefcounts: () => new Map<string, number>(),
} as ContentFilter;
const result = await callApi(
dir,
'/api/duplicate-path',
'POST',
{
kind: 'folder',
path: 'archive',
},
{ contentFilter: racingContentFilter, backlinkIndex: {} as BacklinkIndex },
);
expect(result.status).toBe(409);
expect(existsSync(join(dir, 'archive copy'))).toBe(true);
expect(existsSync(join(dir, 'archive copy/index.md'))).toBe(false);
expect(JSON.parse(result.body)).toMatchObject({
type: 'urn:ok:error:doc-already-exists',
title: 'A folder at the duplicate destination already exists.',
status: 409,
});
});
test('rejects duplicate-path reserved source paths', async () => {
const dir = setupTmpDir();
const okResult = await callApi(dir, '/api/duplicate-path', 'POST', {
kind: 'folder',
path: '.ok/local',
});
const configFolderResult = await callApi(dir, '/api/duplicate-path', 'POST', {
kind: 'folder',
path: '__config__',
});
const configDocResult = await callApi(dir, '/api/duplicate-path', 'POST', {
kind: 'file',
path: '__config__/project',
});
for (const result of [okResult, configFolderResult, configDocResult]) {
expect(result.status).toBe(400);
expect(JSON.parse(result.body)).toMatchObject({
type: 'urn:ok:error:reserved-doc-name',
status: 400,
});
}
});
test('rejects duplicate-path traversal paths', async () => {
const dir = setupTmpDir();
const result = await callApi(dir, '/api/duplicate-path', 'POST', {
kind: 'file',
path: '../outside',
});
expect(result.status).toBe(400);
expect(JSON.parse(result.body)).toMatchObject({
type: 'urn:ok:error:invalid-request',
title: 'path must be a relative content path.',
status: 400,
});
});
test('returns 404 when duplicate-path source does not exist', async () => {
const dir = setupTmpDir();
const result = await callApi(dir, '/api/duplicate-path', 'POST', {
kind: 'file',
path: 'ghost',
});
expect(result.status).toBe(404);
expect(JSON.parse(result.body)).toMatchObject({
type: 'urn:ok:error:doc-not-found',
title: 'file does not exist.',
status: 404,
});
});
test('returns 409 when duplicate-path name slots are exhausted', async () => {
const dir = setupTmpDir();
writeFileSync(join(dir, 'notes.md'), '# Notes\n', 'utf-8');
for (let attempt = 1; attempt <= 10_000; attempt += 1) {
const basename = attempt === 1 ? 'notes copy' : `notes copy ${attempt}`;
writeFileSync(join(dir, `${basename}.md`), '# Occupied\n', 'utf-8');
}
const result = await callApi(
dir,
'/api/duplicate-path',
'POST',
{
kind: 'file',
path: 'notes',
},
{ backlinkIndex: {} as BacklinkIndex, getFileIndex: () => new Map() },
);
expect(result.status).toBe(409);
expect(JSON.parse(result.body)).toMatchObject({
type: 'urn:ok:error:doc-already-exists',
title: 'All available duplicate name slots are occupied for this path.',
status: 409,
});
});
test('returns 400 when duplicate-path source kind does not match disk', async () => {
const dir = setupTmpDir();
mkdirSync(join(dir, 'myfolder'), { recursive: true });
const result = await callApi(dir, '/api/duplicate-path', 'POST', {
kind: 'file',
path: 'myfolder',
});
expect(result.status).toBe(400);
expect(JSON.parse(result.body)).toMatchObject({
type: 'urn:ok:error:invalid-request',
title: 'Target path is not a file.',
status: 400,
});
});
test('rejects duplicate-path requests with non-string summary', async () => {
const dir = setupTmpDir();
writeFileSync(join(dir, 'notes.md'), '# Notes\n', 'utf-8');
const result = await callApi(dir, '/api/duplicate-path', 'POST', {
kind: 'file',
path: 'notes',
summary: 42,
});
expect(result.status).toBe(400);
expect(existsSync(join(dir, 'notes copy.md'))).toBe(false);
expect(JSON.parse(result.body)).toMatchObject({
type: 'urn:ok:error:invalid-request',
title: 'Request body is invalid.',
status: 400,
});
});
test('rejects duplicate-path destinations excluded by content config', async () => {
const dir = setupTmpDir();
writeFileSync(join(dir, 'notes.md'), '# Notes\n', 'utf-8');
writeFileSync(join(dir, '.okignore'), 'notes copy.md\n', 'utf-8');
const contentFilter = createContentFilter({ projectDir: dir, contentDir: dir });
const result = await callApi(
dir,
'/api/duplicate-path',
'POST',
{
kind: 'file',
path: 'notes',
},
{ contentFilter },
);
expect(result.status).toBe(400);
expect(existsSync(join(dir, 'notes copy.md'))).toBe(false);
expect(JSON.parse(result.body)).toMatchObject({
type: 'urn:ok:error:invalid-request',
title: 'Duplicated document destination is excluded by the project content config.',
status: 400,
});
});
test('rejects duplicate-path folder destinations excluded by content config', async () => {
const dir = setupTmpDir();
mkdirSync(join(dir, 'archive'), { recursive: true });
writeFileSync(join(dir, 'archive/index.md'), '# Archive\n', 'utf-8');
writeFileSync(join(dir, '.okignore'), 'archive copy/\n', 'utf-8');
const contentFilter = createContentFilter({ projectDir: dir, contentDir: dir });
const result = await callApi(
dir,
'/api/duplicate-path',
'POST',
{
kind: 'folder',
path: 'archive',
},
{ contentFilter },
);
expect(result.status).toBe(400);
expect(existsSync(join(dir, 'archive copy'))).toBe(false);
expect(JSON.parse(result.body)).toMatchObject({
type: 'urn:ok:error:invalid-request',
title: 'Duplicated folder destination is excluded by the project content config.',
status: 400,
});
});
test('rejects create-folder without a path', async () => {
const dir = setupTmpDir();
const result = await callApi(dir, '/api/create-folder', 'POST', {});
expect(result.status).toBe(400);
expect(JSON.parse(result.body)).toMatchObject({
type: 'urn:ok:error:invalid-request',
status: 400,
});
});
test('rejects create-folder traversal paths', async () => {
const dir = setupTmpDir();
const result = await callApi(dir, '/api/create-folder', 'POST', {
path: '../outside',
});
expect(result.status).toBe(400);
expect(JSON.parse(result.body)).toMatchObject({
type: 'urn:ok:error:invalid-request',
title: 'path must be a relative content path.',
status: 400,
});
});
test('rejects create-folder destinations inside .ok even without content filter', async () => {
const dir = setupTmpDir();
const result = await callApi(dir, '/api/create-folder', 'POST', {
path: '.ok/local/cache',
});
expect(result.status).toBe(400);
expect(existsSync(join(dir, '.ok/local/cache'))).toBe(false);
expect(JSON.parse(result.body)).toMatchObject({
type: 'urn:ok:error:reserved-doc-name',
title: '.ok and .git are reserved directories.',
status: 400,
});
});
test('rejects create-folder requests with non-string summary', async () => {
const dir = setupTmpDir();
const result = await callApi(dir, '/api/create-folder', 'POST', {
path: 'notes',
summary: 42,
});
expect(result.status).toBe(400);
expect(existsSync(join(dir, 'notes'))).toBe(false);
expect(JSON.parse(result.body)).toMatchObject({
type: 'urn:ok:error:invalid-request',
status: 400,
});
});
test('rejects create-folder destinations excluded by content config', async () => {
const dir = setupTmpDir();
writeFileSync(join(dir, '.okignore'), 'ignored/\n', 'utf-8');
const contentFilter = createContentFilter({ projectDir: dir, contentDir: dir });
const result = await callApi(
dir,
'/api/create-folder',
'POST',
{
path: 'ignored/new',
},
{ contentFilter },
);
expect(result.status).toBe(400);
expect(JSON.parse(result.body)).toMatchObject({
type: 'urn:ok:error:invalid-request',
title: 'Destination folder is excluded by the workspace content config.',
status: 400,
});
});
test('rejects create-folder collisions', async () => {
const dir = setupTmpDir();
mkdirSync(join(dir, 'existing'), { recursive: true });
const result = await callApi(dir, '/api/create-folder', 'POST', {
path: 'existing',
});
expect(result.status).toBe(409);
expect(JSON.parse(result.body)).toMatchObject({
type: 'urn:ok:error:doc-already-exists',
title: 'Folder already exists.',
status: 409,
});
});
test('lists empty folders from /api/documents', async () => {
const dir = setupTmpDir();
const folderIndex = new Map<string, FolderIndexEntry>([
[
'empty',
{
size: 0,
modified: '2026-01-01T00:00:00.000Z',
canonicalPath: join(dir, 'empty'),
inode: '0:1',
},
],
]);
const result = await callApi(dir, '/api/documents', 'GET', undefined, {
getFolderIndex: () => folderIndex,
});
expect(result.status).toBe(200);
const body = JSON.parse(result.body) as {
documents: Array<{ kind: string; path?: string }>;
};
expect((body as Record<string, unknown>).ok).toBeUndefined();
expect(body.documents).toContainEqual(
expect.objectContaining({ kind: 'folder', path: 'empty' }),
);
});
test('renames an empty folder on disk', async () => {
const dir = setupTmpDir();
mkdirSync(join(dir, 'empty'), { recursive: true });
const result = await callApi(dir, '/api/rename-path', 'POST', {
kind: 'folder',
fromPath: 'empty',
toPath: 'renamed',
});
expect(result.status).toBe(200);
expect(existsSync(join(dir, 'empty'))).toBe(false);
expect(existsSync(join(dir, 'renamed'))).toBe(true);
const body = JSON.parse(result.body) as { renamed: unknown[] };
expect((body as Record<string, unknown>).ok).toBeUndefined();
expect(body.renamed).toEqual([]);
});
test('deletes an empty folder and reports no deleted docs', async () => {
const dir = setupTmpDir();
mkdirSync(join(dir, 'empty'), { recursive: true });
const result = await callApi(dir, '/api/delete-path', 'POST', {
kind: 'folder',
path: 'empty',
});
expect(result.status).toBe(200);
expect(existsSync(join(dir, 'empty'))).toBe(false);
const body = JSON.parse(result.body) as { deletedDocNames: string[] };
expect((body as Record<string, unknown>).ok).toBeUndefined();
expect(body.deletedDocNames).toEqual([]);
});
test('rejects traversal attempts', async () => {
const dir = setupTmpDir();
writeFileSync(join(dir, 'notes.md'), '# Notes\n', 'utf-8');
const result = await callApi(dir, '/api/rename-path', 'POST', {
kind: 'file',
fromPath: 'notes',
toPath: '../escape',
});
expect(result.status).toBe(400);
const body = JSON.parse(result.body) as Record<string, unknown>;
expect(body.type).toBe('urn:ok:error:invalid-request');
expect(body.title).toContain('relative content paths');
});
test.skipIf(process.platform === 'win32')(
'rejects delete when path resolves outside content via symlink',
async () => {
const root = setupTmpDir();
const contentDir = join(root, 'content');
const outside = join(root, 'outside');
mkdirSync(contentDir);
mkdirSync(outside);
const victim = join(outside, 'victim.md');
writeFileSync(victim, '# Victim\n', 'utf-8');
symlinkSync(join('..', 'outside'), join(contentDir, 'evil'), 'dir');
const result = await callApi(contentDir, '/api/delete-path', 'POST', {
kind: 'file',
path: 'evil/victim',
});
expect(result.status).toBe(400);
expect((JSON.parse(result.body) as { type?: string }).type).toBe('urn:ok:error:path-escape');
expect(existsSync(victim)).toBe(true);
},
);
test.skipIf(process.platform === 'win32')(
'rejects rename into destination that resolves outside content via symlink',
async () => {
const root = setupTmpDir();
const contentDir = join(root, 'content');
const outside = join(root, 'outside');
mkdirSync(contentDir);
mkdirSync(outside);
symlinkSync(join('..', 'outside'), join(contentDir, 'evil'), 'dir');
writeFileSync(join(contentDir, 'safe.md'), '# Safe\n', 'utf-8');
const result = await callApi(contentDir, '/api/rename-path', 'POST', {
kind: 'file',
fromPath: 'safe',
toPath: 'evil/captured',
});
expect(result.status).toBe(400);
expect(readFileSync(join(contentDir, 'safe.md'), 'utf-8')).toBe('# Safe\n');
expect(existsSync(join(outside, 'captured.md'))).toBe(false);
},
);
});
describe('managed rename discovers JSX-src-only referencing documents', () => {
const BOARD_JSON = '{"type":"excalidraw","version":2,"elements":[]}\n';
test('root-relative Excalidraw src in a JSX-only doc is rewritten on board rename', async () => {
const dir = setupTmpDir();
mkdirSync(join(dir, 'diagrams'), { recursive: true });
writeFileSync(join(dir, 'diagrams/board.excalidraw'), BOARD_JSON, 'utf-8');
writeFileSync(
join(dir, 'embeds-only.md'),
'# Embeds\n\n<Excalidraw src="/diagrams/board.excalidraw" />\n',
'utf-8',
);
const result = await callApi(
dir,
'/api/rename-path',
'POST',
{
kind: 'file',
fromPath: 'diagrams/board.excalidraw',
toPath: 'diagrams/renamed-board.excalidraw',
},
{ backlinkIndex: buildBacklinkIndex(dir) },
);
expect(result.status).toBe(200);
expect(existsSync(join(dir, 'diagrams/board.excalidraw'))).toBe(false);
expect(readFileSync(join(dir, 'diagrams/renamed-board.excalidraw'), 'utf-8')).toBe(BOARD_JSON);
expect(readFileSync(join(dir, 'embeds-only.md'), 'utf-8')).toBe(
'# Embeds\n\n<Excalidraw src="/diagrams/renamed-board.excalidraw" />\n',
);
const body = JSON.parse(result.body) as {
renamed: Array<{ fromDocName: string; toDocName: string }>;
rewrittenDocs: Array<{ docName: string; rewrites: number }>;
};
expect(body.renamed).toEqual([
{
fromDocName: 'diagrams/board.excalidraw',
toDocName: 'diagrams/renamed-board.excalidraw',
},
]);
expect(body.rewrittenDocs).toEqual([{ docName: 'embeds-only', rewrites: 1 }]);
});
test('doc-relative Excalidraw src in a JSX-only doc is rewritten on board rename', async () => {
const dir = setupTmpDir();
mkdirSync(join(dir, 'diagrams'), { recursive: true });
writeFileSync(join(dir, 'diagrams/board.excalidraw'), BOARD_JSON, 'utf-8');
writeFileSync(
join(dir, 'diagrams/notes.md'),
'# Notes\n\n<Excalidraw src="board.excalidraw" />\n',
'utf-8',
);
const result = await callApi(
dir,
'/api/rename-path',
'POST',
{
kind: 'file',
fromPath: 'diagrams/board.excalidraw',
toPath: 'diagrams/renamed-board.excalidraw',
},
{ backlinkIndex: buildBacklinkIndex(dir) },
);
expect(result.status).toBe(200);
expect(readFileSync(join(dir, 'diagrams/notes.md'), 'utf-8')).toBe(
'# Notes\n\n<Excalidraw src="renamed-board.excalidraw" />\n',
);
const body = JSON.parse(result.body) as {
rewrittenDocs: Array<{ docName: string; rewrites: number }>;
};
expect(body.rewrittenDocs).toEqual([{ docName: 'diagrams/notes', rewrites: 1 }]);
});
test('a Mirror-only doc is rewritten when the mirrored source doc is renamed', async () => {
const dir = setupTmpDir();
writeFileSync(join(dir, 'api-spec.md'), '# API Spec\n', 'utf-8');
writeFileSync(
join(dir, 'mirror-only.md'),
'# Mirrors\n\n<Mirror src="api-spec" anchor="deprecation" />\n',
'utf-8',
);
const result = await callApi(
dir,
'/api/rename-path',
'POST',
{
kind: 'file',
fromPath: 'api-spec',
toPath: 'api-reference',
},
{ backlinkIndex: buildBacklinkIndex(dir) },
);
expect(result.status).toBe(200);
expect(readFileSync(join(dir, 'mirror-only.md'), 'utf-8')).toBe(
'# Mirrors\n\n<Mirror src="api-reference" anchor="deprecation" />\n',
);
const body = JSON.parse(result.body) as {
rewrittenDocs: Array<{ docName: string; rewrites: number }>;
};
expect(body.rewrittenDocs).toEqual([{ docName: 'mirror-only', rewrites: 1 }]);
});
});