Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
import { randomUUID } from 'node:crypto';
import { mkdirSync, mkdtempSync, readFileSync, realpathSync, rmSync, writeFileSync } from 'node:fs';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { afterAll, beforeAll, expect, test } from 'vitest';
import { HARNESS_BOOT_TIMEOUT_MS } from './harness-boot-timeout';
import { awaitFileWatcherIndexed, createTestServer, type TestServer } from './test-harness.ts';
const MCP_PROTOCOL_VERSION = '2025-06-18';
interface InitializedSession {
sessionId: string;
protocolVersion: string;
}
interface LocalTargetEvidence {
href: string;
targetKind: string;
role: string;
sourceForm: string;
resolvedTarget: string | null;
reason: string;
resolutionMethod: string;
definition?: { line: number; label: string };
}
interface BrokenLink {
href: string;
resolvedTo: string | null;
reason: 'no-such-doc' | 'no-such-file' | 'unresolvable' | 'excluded';
localTarget?: LocalTargetEvidence;
}
async function openMcpSession(port: number): Promise<InitializedSession> {
const init = await fetch(`http://127.0.0.1:${port}/mcp`, {
method: 'POST',
headers: { accept: 'application/json, text/event-stream', 'content-type': 'application/json' },
body: JSON.stringify({
jsonrpc: '2.0',
id: 1,
method: 'initialize',
params: {
protocolVersion: MCP_PROTOCOL_VERSION,
capabilities: {},
clientInfo: { name: 'Claude', version: '1.0.0' },
},
}),
});
expect(init.status).toBe(200);
const sessionId = init.headers.get('mcp-session-id');
expect(sessionId).toBeTruthy();
const initBody = (await init.json()) as { result?: { protocolVersion?: string } };
const protocolVersion = initBody.result?.protocolVersion ?? MCP_PROTOCOL_VERSION;
const initialized = await fetch(`http://127.0.0.1:${port}/mcp`, {
method: 'POST',
headers: {
accept: 'application/json, text/event-stream',
'content-type': 'application/json',
'mcp-session-id': sessionId as string,
'mcp-protocol-version': protocolVersion,
},
body: JSON.stringify({ jsonrpc: '2.0', method: 'notifications/initialized' }),
});
expect(initialized.status).toBe(202);
return { sessionId: sessionId as string, protocolVersion };
}
let nextId = 100;
async function callTool(
port: number,
session: InitializedSession,
name: string,
args: Record<string, unknown>,
cwd: string,
): Promise<{ isError?: boolean; structuredContent?: Record<string, unknown> }> {
nextId += 1;
const res = await fetch(`http://127.0.0.1:${port}/mcp`, {
method: 'POST',
headers: {
accept: 'application/json, text/event-stream',
'content-type': 'application/json',
'mcp-session-id': session.sessionId,
'mcp-protocol-version': session.protocolVersion,
},
body: JSON.stringify({
jsonrpc: '2.0',
id: nextId,
method: 'tools/call',
params: { name, arguments: { ...args, cwd } },
}),
});
expect(res.status).toBe(200);
const body = (await res.json()) as {
result?: { isError?: boolean; structuredContent?: Record<string, unknown> };
error?: unknown;
};
if (body.error) throw new Error(`tools/call error: ${JSON.stringify(body.error)}`);
return body.result ?? {};
}
function docResult(structured: Record<string, unknown> | undefined): Record<string, unknown> {
expect(structured).toBeDefined();
const doc = structured?.document as Record<string, unknown> | undefined;
expect(doc).toBeDefined();
return doc as Record<string, unknown>;
}
let server: TestServer;
beforeAll(async () => {
server = await createTestServer({ debounce: 50, maxDebounce: 200 });
}, HARNESS_BOOT_TIMEOUT_MS);
afterAll(async () => {
await server.cleanup();
});
test('write surfaces broken outbound links (doubling + escape-root + broken wiki) in the same response', async () => {
const session = await openMcpSession(server.port);
const folder = `wiki-${randomUUID().slice(0, 8)}`;
const docName = `${folder}/OVERVIEW`;
const content = [
'# Wiki Overview',
'',
`See [tasks](./${folder}/modules/tasks) for the task module.`,
'A bad [escape](../../../way-out.md) link.',
'And a [[Ghost Page]] wiki reference.',
'',
].join('\n');
const result = await callTool(
server.port,
session,
'write',
{ document: { path: docName, content, position: 'replace' } },
server.contentDir,
);
expect(result.isError ?? false).toBe(false);
const doc = docResult(result.structuredContent);
const broken = doc.brokenLinks as BrokenLink[];
expect(broken).toEqual([
{
href: `./${folder}/modules/tasks`,
resolvedTo: `${folder}/${folder}/modules/tasks`,
reason: 'no-such-doc',
},
{ href: '../../../way-out.md', resolvedTo: null, reason: 'unresolvable' },
{ href: '[[Ghost Page]]', resolvedTo: 'Ghost Page', reason: 'no-such-doc' },
]);
const stored = readFileSync(join(server.contentDir, `${docName}.md`), 'utf-8');
expect(stored).toContain(`[tasks](./${folder}/modules/tasks)`);
expect(stored).toContain('[escape](../../../way-out.md)');
expect(stored).toContain('[[Ghost Page]]');
});
test('a write whose links all resolve returns brokenLinks: [] (positive confirmation)', async () => {
const session = await openMcpSession(server.port);
const docName = `clean-${randomUUID().slice(0, 8)}`;
const content = [
'# Clean',
'',
`Back to [self](./${docName.split('/').pop()}.md).`,
'An [external](https://example.com) site and an [anchor](#clean).',
'',
].join('\n');
const result = await callTool(
server.port,
session,
'write',
{ document: { path: docName, content, position: 'replace' } },
server.contentDir,
);
expect(result.isError ?? false).toBe(false);
const doc = docResult(result.structuredContent);
expect(doc.brokenLinks).toEqual([]);
});
test('write validates links to any file on disk, not just docs (source-file depth)', async () => {
const session = await openMcpSession(server.port);
const uid = randomUUID().slice(0, 8);
const relFile = `src/probe-${uid}.py`;
mkdirSync(join(server.contentDir, 'src'), { recursive: true });
writeFileSync(join(server.contentDir, relFile), 'def probe(): ...\n');
const docName = `wiki-${uid}/modules/m`;
const content = [
'# Module',
'',
`Correct depth: [probe](../../${relFile}).`,
`Over-deep: [probe again](../../../${relFile}).`,
`Missing: [gone](../../src/missing-${uid}.py).`,
'',
].join('\n');
const result = await callTool(
server.port,
session,
'write',
{ document: { path: docName, content, position: 'replace' } },
server.contentDir,
);
expect(result.isError ?? false).toBe(false);
const broken = docResult(result.structuredContent).brokenLinks as BrokenLink[];
expect(broken).toEqual([
{ href: `../../../${relFile}`, resolvedTo: null, reason: 'unresolvable' },
{
href: `../../src/missing-${uid}.py`,
resolvedTo: `src/missing-${uid}.py`,
reason: 'no-such-file',
},
]);
});
test.each(['write', 'edit'] as const)(
'%s accepts a source-file link beneath a built-in skip directory',
async (tool) => {
const session = await openMcpSession(server.port);
const uid = randomUUID().slice(0, 8);
const existing = `Applications/probe-${uid}.java`;
const missing = `Applications/missing-${uid}.java`;
const image = `dist/logo-${uid}.png`;
const documents = [`Applications/readme-${uid}.md`, `Applications/readme-${uid}.mdx`];
mkdirSync(join(server.contentDir, 'Applications'), { recursive: true });
writeFileSync(join(server.contentDir, existing), 'class Probe {}\n');
mkdirSync(join(server.contentDir, 'dist'), { recursive: true });
writeFileSync(join(server.contentDir, image), 'image\n');
for (const document of documents) {
writeFileSync(join(server.contentDir, document), '# Reference\n');
}
const docName = `wiki-${uid}/index`;
const links = [
`See [source](../${existing}), [missing](../${missing}) and [image file](../${image}).`,
...documents.map((path) => `[document](../${path})`),
``,
].join('\n');
if (tool === 'edit') {
const seeded = await callTool(
server.port,
session,
'write',
{ document: { path: docName, content: '# Module\n\nPlaceholder.\n', position: 'replace' } },
server.contentDir,
);
expect(seeded.isError ?? false).toBe(false);
}
const document =
tool === 'write'
? { path: docName, content: `# Module\n\n${links}\n`, position: 'replace' }
: { path: docName, find: 'Placeholder.', replace: links };
const result = await callTool(server.port, session, tool, { document }, server.contentDir);
expect(result.isError ?? false).toBe(false);
expect(docResult(result.structuredContent).brokenLinks).toEqual([
{ href: `../${missing}`, resolvedTo: missing, reason: 'no-such-file' },
...documents.map((path) => ({
href: `../${path}`,
resolvedTo: path.replace(/\.mdx?$/, ''),
reason: 'no-such-doc',
})),
{
href: `../${image}`,
resolvedTo: image,
reason: 'no-such-file',
localTarget: {
href: `../${image}`,
targetKind: 'file',
role: 'image',
sourceForm: 'markdown-inline',
resolvedTarget: image,
reason: 'no-such-file',
resolutionMethod: 'source-relative',
},
},
]);
},
);
test.each(['write', 'edit'] as const)(
'%s retains excluded advisories for links and images hidden by ignore files',
async (tool) => {
const contentDir = realpathSync(mkdtempSync(join(tmpdir(), 'ok-link-advisory-ignored-')));
let ignoredServer: TestServer | undefined;
try {
mkdirSync(join(contentDir, '.ok'));
writeFileSync(join(contentDir, '.ok', 'config.yml'), '');
writeFileSync(join(contentDir, '.gitignore'), 'ignored-by-git/\n');
writeFileSync(join(contentDir, '.okignore'), 'ignored-by-ok/\n');
for (const folder of ['ignored-by-git', 'ignored-by-ok']) {
mkdirSync(join(contentDir, folder));
writeFileSync(join(contentDir, folder, 'notice.txt'), 'Notice\n');
}
ignoredServer = await createTestServer({ contentDir, debounce: 50, maxDebounce: 200 });
const session = await openMcpSession(ignoredServer.port);
const docName = `wiki-${randomUUID().slice(0, 8)}/index`;
const links = [
'[git](../ignored-by-git/notice.txt)',
'[ok](../ignored-by-ok/notice.txt)',
'',
].join('\n');
if (tool === 'edit') {
const seeded = await callTool(
ignoredServer.port,
session,
'write',
{
document: { path: docName, content: '# Module\n\nPlaceholder.\n', position: 'replace' },
},
contentDir,
);
expect(seeded.isError ?? false).toBe(false);
}
const document =
tool === 'write'
? { path: docName, content: `# Module\n\n${links}\n`, position: 'replace' }
: { path: docName, find: 'Placeholder.', replace: links };
const result = await callTool(ignoredServer.port, session, tool, { document }, contentDir);
expect(result.isError ?? false).toBe(false);
const broken = docResult(result.structuredContent).brokenLinks as BrokenLink[];
expect(
broken.map(({ href, reason, localTarget }) => ({
href,
reason,
role: localTarget?.role ?? 'link',
})),
).toEqual([
{ href: '../ignored-by-git/notice.txt', reason: 'excluded', role: 'link' },
{ href: '../ignored-by-ok/notice.txt', reason: 'excluded', role: 'link' },
{ href: '../ignored-by-git/notice.txt', reason: 'excluded', role: 'image' },
]);
} finally {
try {
await ignoredServer?.cleanup();
} finally {
rmSync(contentDir, { recursive: true, force: true });
}
}
},
HARNESS_BOOT_TIMEOUT_MS + 30_000,
);
test('edit (body find/replace) reports a broken link introduced by the edit', async () => {
const session = await openMcpSession(server.port);
const docName = `edited-${randomUUID().slice(0, 8)}`;
await callTool(
server.port,
session,
'write',
{ document: { path: docName, content: '# Edited\n\nPlaceholder.\n', position: 'replace' } },
server.contentDir,
);
const edited = await callTool(
server.port,
session,
'edit',
{
document: {
path: docName,
find: 'Placeholder.',
replace: 'See [gone](./does-not-exist.md).',
},
},
server.contentDir,
);
expect(edited.isError ?? false).toBe(false);
const doc = docResult(edited.structuredContent);
expect(doc.brokenLinks).toEqual([
{ href: './does-not-exist.md', resolvedTo: 'does-not-exist', reason: 'no-such-doc' },
]);
});
test('the HTTP /api/agent-write-md response carries brokenLinks directly', async () => {
const docName = `http-${randomUUID().slice(0, 8)}`;
const res = await fetch(`http://127.0.0.1:${server.port}/api/agent-write-md`, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
docName,
position: 'replace',
markdown: 'Broken [ref](./nope.md) here.\n',
}),
});
expect(res.status).toBe(200);
const body = (await res.json()) as { brokenLinks?: BrokenLink[] };
expect(body.brokenLinks).toEqual([
{ href: './nope.md', resolvedTo: 'nope', reason: 'no-such-doc' },
]);
});
test('write surfaces missing image + reference-style targets with local-target evidence', async () => {
const session = await openMcpSession(server.port);
const docName = `pics-${randomUUID().slice(0, 8)}`;
const content = [
'# Pics',
'',
'',
'',
'See [the spec][spec].',
'',
'[spec]: ./spec.pdf',
'',
].join('\n');
const result = await callTool(
server.port,
session,
'write',
{ document: { path: docName, content, position: 'replace' } },
server.contentDir,
);
expect(result.isError ?? false).toBe(false);
const doc = docResult(result.structuredContent);
const broken = doc.brokenLinks as BrokenLink[];
expect(broken.find((l) => l.href === './logo.png')).toEqual({
href: './logo.png',
resolvedTo: 'logo.png',
reason: 'no-such-file',
localTarget: {
href: './logo.png',
targetKind: 'file',
role: 'image',
sourceForm: 'markdown-inline',
resolvedTarget: 'logo.png',
reason: 'no-such-file',
resolutionMethod: 'source-relative',
},
});
expect(broken.find((l) => l.href === './spec.pdf')).toEqual({
href: './spec.pdf',
resolvedTo: 'spec.pdf',
reason: 'no-such-file',
localTarget: {
href: './spec.pdf',
targetKind: 'file',
role: 'link',
sourceForm: 'markdown-reference',
resolvedTarget: 'spec.pdf',
reason: 'no-such-file',
resolutionMethod: 'source-relative',
definition: { line: 6, label: 'spec' },
},
});
const warnings = (doc.warnings ?? []) as Array<{
kind: string;
localTarget?: LocalTargetEvidence;
}>;
const imageViolation = warnings.find(
(w) => w.kind === 'lint-violation' && w.localTarget?.role === 'image',
);
expect(imageViolation?.localTarget?.resolvedTarget).toBe('logo.png');
const stored = readFileSync(join(server.contentDir, `${docName}.md`), 'utf-8');
expect(stored).toContain('');
expect(stored).toContain('[spec]: ./spec.pdf');
});
test('a link to a doc that actually exists is not flagged (admitted-set membership)', async () => {
const session = await openMcpSession(server.port);
const suffix = randomUUID().slice(0, 8);
const target = `guides-${suffix}/install`;
const sourceDoc = `guides-${suffix}/index`;
await callTool(
server.port,
session,
'write',
{ document: { path: target, content: '# Install\n\nSteps.\n', position: 'replace' } },
server.contentDir,
);
await awaitFileWatcherIndexed(server, target);
const result = await callTool(
server.port,
session,
'write',
{
document: {
path: sourceDoc,
content: `# Index\n\nSee [install](./install.md).\n`,
position: 'replace',
},
},
server.contentDir,
);
expect(result.isError ?? false).toBe(false);
const doc = docResult(result.structuredContent);
expect(doc.brokenLinks).toEqual([]);
});
test('bare-name wiki links are validated the way the editor navigates them', async () => {
const session = await openMcpSession(server.port);
const suffix = randomUUID().slice(0, 8);
const folder = `vault-${suffix}`;
const dotted = `${folder}/acp.daemon`;
const plain = `${folder}/analysis`;
const sourceDoc = `notes-${suffix}/index`;
for (const target of [dotted, plain]) {
await callTool(
server.port,
session,
'write',
{ document: { path: target, content: '# Target\n\nBody.\n', position: 'replace' } },
server.contentDir,
);
await awaitFileWatcherIndexed(server, target);
}
const result = await callTool(
server.port,
session,
'write',
{
document: {
path: sourceDoc,
content: `# Index\n\nSee [[acp.daemon]], [[analysis]], and [[nowhere-${suffix}]].\n`,
position: 'replace',
},
},
server.contentDir,
);
expect(result.isError ?? false).toBe(false);
const doc = docResult(result.structuredContent);
expect(doc.brokenLinks).toEqual([
{ href: `[[nowhere-${suffix}]]`, resolvedTo: `nowhere-${suffix}`, reason: 'no-such-doc' },
]);
});
test('write-time wiki validation accepts explicit Markdown suffixes and keeps true misses', async () => {
const session = await openMcpSession(server.port);
const suffix = randomUUID().slice(0, 8);
const folder = `suffix-${suffix}`;
const sourceDoc = `${folder}/source`;
const beta = `beta-${suffix}`;
mkdirSync(join(server.contentDir, folder), { recursive: true });
for (const target of [`${folder}/${beta}`, `${folder}/dotted.md`, `${folder}/reports/index`]) {
if (target.endsWith('.md')) {
writeFileSync(join(server.contentDir, `${target}.md`), '# Target\n\nBody.\n');
await awaitFileWatcherIndexed(server, target);
continue;
}
await callTool(
server.port,
session,
'write',
{ document: { path: `${target}.md`, content: '# Target\n\nBody.\n', position: 'replace' } },
server.contentDir,
);
await awaitFileWatcherIndexed(server, target);
}
const missing = `${folder}/missing.md`;
const result = await callTool(
server.port,
session,
'write',
{
document: {
path: sourceDoc,
content: `# Source\n\n[[${folder}/${beta}.md]] [[${beta}.mdx#body|Alias]] [[${folder}/dotted.md.md]] [[${folder}/reports.md]] [[${missing}]].\n`,
position: 'replace',
},
},
server.contentDir,
);
expect(result.isError ?? false).toBe(false);
expect(docResult(result.structuredContent).brokenLinks).toEqual([
{ href: `[[${missing}]]`, resolvedTo: missing, reason: 'no-such-doc' },
]);
});