Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
import type { IncomingMessage, ServerResponse } from 'node:http';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { Readable } from 'node:stream';
import { Hocuspocus } from '@hocuspocus/server';
import { afterEach, beforeEach, describe, expect, test } from 'vitest';
import {
AGENT_WRITE_ORIGIN,
AgentSessionManager,
applyAgentMarkdownWrite,
} from './agent-sessions.ts';
import { createApiExtension } from './api-extension.test-helper.ts';
interface CapturedResponse {
status: number;
body: string;
}
interface LinkAdvisoryBody {
brokenLinks?: { href: string }[];
brokenLinkSuppression?: { reason: string; count: number };
}
function makeJsonPostReq(url: string, body: unknown): IncomingMessage {
const readable = Readable.from(Buffer.from(JSON.stringify(body))) as unknown as IncomingMessage;
readable.method = 'POST';
readable.url = url;
readable.headers = { host: 'localhost', 'content-type': 'application/json' };
return readable;
}
function makeRes(): { res: ServerResponse; captured: CapturedResponse } {
const captured: CapturedResponse = { status: 0, body: '' };
const res = {
writeHead(status: number) {
captured.status = status;
},
end(body?: string) {
captured.body = body ?? '';
},
} as unknown as ServerResponse;
return { res, captured };
}
const TWO_BROKEN_FORMS = '# Log\n\nSee [[ghost-doc]].\n\n\n';
let projectDir: string;
let contentDir: string;
let hocuspocus: Hocuspocus;
let sessionManager: AgentSessionManager;
beforeEach(() => {
projectDir = mkdtempSync(join(tmpdir(), 'ok-write-link-policy-'));
contentDir = join(projectDir, 'content');
mkdirSync(contentDir, { recursive: true });
hocuspocus = new Hocuspocus({ quiet: true });
sessionManager = new AgentSessionManager(hocuspocus);
});
afterEach(async () => {
await sessionManager.closeAll();
rmSync(projectDir, { recursive: true, force: true });
});
async function post(
url: string,
body: unknown,
options: { suppressLogLinkAdvisories?: boolean } = {},
): Promise<CapturedResponse> {
const ext = createApiExtension({
hocuspocus,
sessionManager,
contentDir,
getFileIndex: () => new Map(),
...(options.suppressLogLinkAdvisories === undefined
? {}
: {
getLinkAdvisoryPolicy: () => ({
links: 'warning' as const,
suppressLogLinkAdvisories: options.suppressLogLinkAdvisories as boolean,
}),
}),
});
const req = makeJsonPostReq(url, 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 writeMd(
docName: string,
markdown: string,
options?: { suppressLogLinkAdvisories?: boolean },
): Promise<LinkAdvisoryBody> {
const response = await post(
'/api/agent-write-md',
{ docName, markdown, position: 'replace', agentId: 'claude-1', agentName: 'Claude' },
options,
);
expect(response.status).toBe(200);
return JSON.parse(response.body) as LinkAdvisoryBody;
}
async function seed(docName: string, markdown: string): Promise<void> {
const session = await sessionManager.getSession(docName);
session.dc.document.transact(() => {
applyAgentMarkdownWrite(session.dc.document, markdown, 'replace');
}, AGENT_WRITE_ORIGIN);
}
describe('write-time broken-link advisories under the reserved-log policy', () => {
test('a reserved log withholds every detected link and reports how many were omitted', async () => {
const body = await writeMd('log', TWO_BROKEN_FORMS);
expect(body.brokenLinks).toEqual([]);
expect(body.brokenLinkSuppression).toEqual({ reason: 'reserved-log-policy', count: 2 });
});
test('an ordinary document keeps its repair candidates and carries no suppression', async () => {
const body = await writeMd('journal', TWO_BROKEN_FORMS);
expect(body.brokenLinks?.map((link) => link.href)).toEqual([
'[[ghost-doc]]',
'./ghost-image.png',
]);
expect(body.brokenLinkSuppression).toBeUndefined();
});
test('the same reserved log reports its links again once the policy is switched off', async () => {
const body = await writeMd('log', TWO_BROKEN_FORMS, { suppressLogLinkAdvisories: false });
expect(body.brokenLinks?.map((link) => link.href)).toEqual([
'[[ghost-doc]]',
'./ghost-image.png',
]);
expect(body.brokenLinkSuppression).toBeUndefined();
});
test('reserved identity is exact: a nested log is suppressed, an uppercase LOG is not', async () => {
const nested = await writeMd('notes/2026/log', TWO_BROKEN_FORMS);
expect(nested.brokenLinks).toEqual([]);
expect(nested.brokenLinkSuppression).toEqual({ reason: 'reserved-log-policy', count: 2 });
const upper = await writeMd('notes/LOG', TWO_BROKEN_FORMS);
expect(upper.brokenLinks).toHaveLength(2);
expect(upper.brokenLinkSuppression).toBeUndefined();
});
test('a reserved log whose links all resolve reports no suppression', async () => {
const body = await writeMd('log', '# Log\n\nNothing unresolved here.\n');
expect(body.brokenLinks).toEqual([]);
expect(body.brokenLinkSuppression).toBeUndefined();
});
test('the count is the post-dedup entry count, not the number of occurrences', async () => {
const body = await writeMd(
'log',
'# Log\n\n[[ghost-doc]] and [[ghost-doc]] again, plus [[ghost-doc]].\n',
);
expect(body.brokenLinks).toEqual([]);
expect(body.brokenLinkSuppression).toEqual({ reason: 'reserved-log-policy', count: 1 });
});
test('a patch to a reserved log projects the post-edit links the same way', async () => {
await seed('log', TWO_BROKEN_FORMS);
const response = await post('/api/agent-patch', {
docName: 'log',
find: 'See',
replace: 'Still see',
agentId: 'claude-1',
agentName: 'Claude',
});
expect(response.status).toBe(200);
const body = JSON.parse(response.body) as LinkAdvisoryBody;
expect(body.brokenLinks).toEqual([]);
expect(body.brokenLinkSuppression).toEqual({ reason: 'reserved-log-policy', count: 2 });
});
test('a frontmatter patch to a reserved log projects the body links the same way', async () => {
await seed('log', TWO_BROKEN_FORMS);
const response = await post('/api/frontmatter-patch', {
docName: 'log',
patch: { title: 'Change log' },
agentId: 'claude-1',
agentName: 'Claude',
});
expect(response.status).toBe(200);
const body = JSON.parse(response.body) as LinkAdvisoryBody;
expect(body.brokenLinks).toEqual([]);
expect(body.brokenLinkSuppression).toEqual({ reason: 'reserved-log-policy', count: 2 });
});
test('every batch entry is projected by its own source document', async () => {
const response = await post('/api/agent-write-batch', {
docs: [
{ docName: 'log', markdown: TWO_BROKEN_FORMS, position: 'replace' },
{ docName: 'notes/log', markdown: TWO_BROKEN_FORMS, position: 'replace' },
{ docName: 'journal', markdown: TWO_BROKEN_FORMS, position: 'replace' },
],
agentId: 'claude-1',
agentName: 'Claude',
});
expect(response.status).toBe(200);
const results = (JSON.parse(response.body) as { results: LinkAdvisoryBody[] }).results;
expect(results.map((entry) => entry.brokenLinkSuppression)).toEqual([
{ reason: 'reserved-log-policy', count: 2 },
{ reason: 'reserved-log-policy', count: 2 },
undefined,
]);
expect(results.map((entry) => entry.brokenLinks?.length)).toEqual([0, 0, 2]);
});
test('a policy change during assembly cannot split one batch response', async () => {
let effectivePolicy = true;
let policyReads = 0;
const ext = createApiExtension({
hocuspocus,
sessionManager,
contentDir,
getFileIndex: () => {
effectivePolicy = false;
return new Map();
},
getLinkAdvisoryPolicy: () => {
policyReads += 1;
return {
links: 'warning',
suppressLogLinkAdvisories: effectivePolicy,
};
},
});
const req = makeJsonPostReq('/api/agent-write-batch', {
docs: [
{ docName: 'log', markdown: TWO_BROKEN_FORMS, position: 'replace' },
{ docName: 'notes/log', markdown: TWO_BROKEN_FORMS, position: 'replace' },
],
agentId: 'claude-1',
agentName: 'Claude',
});
const { res, captured } = makeRes();
await (
ext as {
onRequest: (ctx: { request: IncomingMessage; response: ServerResponse }) => Promise<void>;
}
).onRequest({ request: req, response: res });
expect(captured.status).toBe(200);
const results = (JSON.parse(captured.body) as { results: LinkAdvisoryBody[] }).results;
expect(policyReads).toBe(1);
expect(effectivePolicy).toBe(false);
expect(results.map((entry) => entry.brokenLinkSuppression)).toEqual([
{ reason: 'reserved-log-policy', count: 2 },
{ reason: 'reserved-log-policy', count: 2 },
]);
});
test('switching link validation off does not empty an ordinary write advisory', async () => {
const ext = createApiExtension({
hocuspocus,
sessionManager,
contentDir,
getFileIndex: () => new Map(),
getLinkAdvisoryPolicy: () => ({
links: 'off',
suppressLogLinkAdvisories: true,
}),
});
const req = makeJsonPostReq('/api/agent-write-md', {
docName: 'journal',
markdown: TWO_BROKEN_FORMS,
position: 'replace',
agentId: 'claude-1',
agentName: 'Claude',
});
const { res, captured } = makeRes();
await (
ext as {
onRequest: (ctx: { request: IncomingMessage; response: ServerResponse }) => Promise<void>;
}
).onRequest({ request: req, response: res });
expect(captured.status).toBe(200);
const body = JSON.parse(captured.body) as LinkAdvisoryBody;
expect(body.brokenLinks).toHaveLength(2);
expect(body.brokenLinkSuppression).toBeUndefined();
});
});
describe('write-time advisories for links to folders that hold no document', () => {
const CAFE_NFC = 'Café'.normalize('NFC');
const CAFE_NFD = 'Café'.normalize('NFD');
async function postWithFolders(
url: string,
body: Record<string, unknown>,
folders: string[],
): Promise<LinkAdvisoryBody> {
const ext = createApiExtension({
hocuspocus,
sessionManager,
contentDir,
getFileIndex: () => new Map(),
getFolderIndex: () =>
new Map(
folders.map((folder) => [
folder,
{ size: 0 as const, modified: '', canonicalPath: join(contentDir, folder), inode: '' },
]),
),
});
const req = makeJsonPostReq(url, { ...body, agentId: 'claude-1', agentName: 'Claude' });
const { res, captured } = makeRes();
await (
ext as {
onRequest: (ctx: { request: IncomingMessage; response: ServerResponse }) => Promise<void>;
}
).onRequest({ request: req, response: res });
expect(captured.status).toBe(200);
return JSON.parse(captured.body) as LinkAdvisoryBody;
}
test('a link spelled in the other normalization form names the existing folder', async () => {
const body = await postWithFolders(
'/api/agent-write-md',
{
docName: 'Probe',
markdown: `See [dir](${CAFE_NFD}) and [[${CAFE_NFD}]] and [[Nope]].\n`,
position: 'replace',
},
[CAFE_NFC],
);
expect((body.brokenLinks ?? []).map((link) => link.href)).toEqual(['[[Nope]]']);
});
const LINKS_TO_AN_ASSET_FOLDER = '# Probe\n\nSee [dir](assets) and [[assets]] and [[Nope]].\n';
test('a frontmatter patch resolves a link to a folder that holds only assets', async () => {
await seed('Probe', LINKS_TO_AN_ASSET_FOLDER);
const body = await postWithFolders(
'/api/frontmatter-patch',
{ docName: 'Probe', patch: { title: 'Probe' } },
['assets'],
);
expect((body.brokenLinks ?? []).map((link) => link.href)).toEqual(['[[Nope]]']);
});
test('an agent patch resolves a link to a folder that holds only assets', async () => {
await seed('Probe', LINKS_TO_AN_ASSET_FOLDER);
const body = await postWithFolders(
'/api/agent-patch',
{ docName: 'Probe', find: 'See', replace: 'Still see' },
['assets'],
);
expect((body.brokenLinks ?? []).map((link) => link.href)).toEqual(['[[Nope]]']);
});
});
describe('write-time advisories for slash-free wiki asset embeds', () => {
test('a basename that names no tracked file is reported, one that names a tracked file is not', async () => {
mkdirSync(join(contentDir, 'media'), { recursive: true });
writeFileSync(join(contentDir, 'media', 'photo.png'), 'png');
const ext = createApiExtension({
hocuspocus,
sessionManager,
contentDir,
getFileIndex: () => new Map(),
getAllFilesIndex: () =>
new Map([
[
'media/photo.png',
{
size: 3,
modified: '',
canonicalPath: join(contentDir, 'media', 'photo.png'),
inode: '',
aliases: [],
kind: 'file' as const,
},
],
]),
});
const req = makeJsonPostReq('/api/agent-write-md', {
docName: 'notes/Probe',
markdown: 'See ![[photo.png]], ![[PHOTO.png]], ![[ghost.png]] and ![[media/gone.png]].\n',
position: 'replace',
agentId: 'claude-1',
agentName: 'Claude',
});
const { res, captured } = makeRes();
await (
ext as {
onRequest: (ctx: { request: IncomingMessage; response: ServerResponse }) => Promise<void>;
}
).onRequest({ request: req, response: res });
expect(captured.status).toBe(200);
const body = JSON.parse(captured.body) as LinkAdvisoryBody;
expect((body.brokenLinks ?? []).map((link) => link.href).sort()).toEqual([
'ghost.png',
'media/gone.png',
]);
});
});