Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
import { existsSync, renameSync, rmSync, unlinkSync, writeFileSync } from 'node:fs';
import { join } from 'node:path';
import { setTimeout as wait } from 'node:timers/promises';
import { HocuspocusProvider } from '@hocuspocus/provider';
import {
type CC1DerivedViewPayload,
CC1DerivedViewPayloadSchema,
SYSTEM_DOC_NAME,
} from '@inkeep/open-knowledge-core';
import { applyExternalChange, BacklinkIndex, reconcile } from '@inkeep/open-knowledge-server';
import * as encoding from 'lib0/encoding';
import { afterAll, beforeAll, describe, expect, test } from 'vitest';
import * as Y from 'yjs';
import { HARNESS_BOOT_TIMEOUT_MS } from './harness-boot-timeout';
import { createTestServer, pollUntil, type TestServer, waitForSync } from './test-harness';
let server: TestServer;
beforeAll(async () => {
server = await createTestServer();
}, HARNESS_BOOT_TIMEOUT_MS);
afterAll(async () => {
await server.cleanup();
});
function connectSystemDoc(
port: number,
channels: ReadonlySet<string> = new Set(['files']),
): {
provider: HocuspocusProvider;
signals: CC1DerivedViewPayload[];
destroy: () => void;
} {
const doc = new Y.Doc();
const signals: CC1DerivedViewPayload[] = [];
const provider = new HocuspocusProvider({
url: `ws://127.0.0.1:${port}/collab`,
name: SYSTEM_DOC_NAME,
document: doc,
connect: true,
onStateless: ({ payload }) => {
let raw: unknown;
try {
raw = JSON.parse(payload);
} catch {
return;
}
const result = CC1DerivedViewPayloadSchema.safeParse(raw);
if (result.success && channels.has(result.data.ch)) {
signals.push(result.data);
}
},
});
return {
provider,
signals,
destroy: () => {
provider.destroy();
doc.destroy();
},
};
}
describe('CC1 broadcast — L1 integration', () => {
test('disk write triggers onStateless with valid CC1 signal', async () => {
const { provider, signals, destroy } = connectSystemDoc(server.port);
try {
await waitForSync(provider);
await wait(100);
const fileName = `cc1-test-${crypto.randomUUID()}.md`;
writeFileSync(join(server.contentDir, fileName), '# hello\n', 'utf-8');
await wait(500);
expect(signals.length).toBeGreaterThanOrEqual(1);
const signal = signals[0];
expect(signal.v).toBe(1);
expect(signal.ch).toBe('files');
expect(typeof signal.seq).toBe('number');
expect(signal.seq).toBeGreaterThanOrEqual(1);
} finally {
destroy();
}
});
test('accepted lint config writes advance their intended system channels', async () => {
const { provider, signals, destroy } = connectSystemDoc(
server.port,
new Set(['files', 'lint-config']),
);
const markdownlintFile = join(server.contentDir, '.markdownlint.json');
const schemaFile = `.ok/schemas/cc1-${crypto.randomUUID()}.schema.json`;
const schemaPath = join(server.contentDir, schemaFile);
try {
await waitForSync(provider);
const lintBefore = Math.max(
0,
...signals.filter((signal) => signal.ch === 'lint-config').map((signal) => signal.seq),
);
const markdown = await fetch(`http://127.0.0.1:${server.port}/api/lint/markdownlint-config`, {
method: 'POST',
headers: { 'content-type': 'application/json' },
body: JSON.stringify({ ruleId: 'MD012', value: false }),
});
expect(markdown.status).toBe(200);
await pollUntil(
() => signals.some((signal) => signal.ch === 'lint-config' && signal.seq > lintBefore),
5_000,
20,
);
const filesBefore = Math.max(
0,
...signals.filter((signal) => signal.ch === 'files').map((signal) => signal.seq),
);
const nextLintBefore = Math.max(
0,
...signals.filter((signal) => signal.ch === 'lint-config').map((signal) => signal.seq),
);
const frontmatter = await fetch(
`http://127.0.0.1:${server.port}/api/lint/frontmatter-schema`,
{
method: 'POST',
headers: { 'content-type': 'application/json' },
body: JSON.stringify({ file: schemaFile }),
},
);
expect(frontmatter.status).toBe(200);
await pollUntil(
() =>
signals.some((signal) => signal.ch === 'files' && signal.seq > filesBefore) &&
signals.some((signal) => signal.ch === 'lint-config' && signal.seq > nextLintBefore),
5_000,
20,
);
expect(
Math.max(...signals.filter((signal) => signal.ch === 'files').map((signal) => signal.seq)),
).toBeGreaterThan(filesBefore);
expect(
Math.max(
...signals.filter((signal) => signal.ch === 'lint-config').map((signal) => signal.seq),
),
).toBeGreaterThan(nextLintBefore);
const filesBeforeCleanup = Math.max(
0,
...signals.filter((signal) => signal.ch === 'files').map((signal) => signal.seq),
);
const cleanup = await fetch(`http://127.0.0.1:${server.port}/api/lint/frontmatter-schema`, {
method: 'POST',
headers: { 'content-type': 'application/json' },
body: JSON.stringify({ file: schemaFile, delete: true }),
});
expect(cleanup.status).toBe(200);
await pollUntil(
() => signals.some((signal) => signal.ch === 'files' && signal.seq > filesBeforeCleanup),
5_000,
20,
'the schema-removal files signal before provider teardown',
);
} finally {
rmSync(markdownlintFile, { force: true });
rmSync(schemaPath, { force: true });
destroy();
}
});
test('empty disk-created markdown file triggers ch:files and appears in documents', async () => {
const { provider, signals, destroy } = connectSystemDoc(server.port);
try {
await waitForSync(provider);
await wait(100);
const docName = `cc1-empty-${crypto.randomUUID()}`;
const filesBefore = Math.max(0, ...signals.map((signal) => signal.seq));
writeFileSync(join(server.contentDir, `${docName}.md`), '', 'utf-8');
await pollUntil(
() => signals.some((signal) => signal.seq > filesBefore),
5000,
50,
'a files signal caused after the empty-file write',
);
expect(signals.some((signal) => signal.ch === 'files' && signal.seq > filesBefore)).toBe(
true,
);
await expect(
pollUntil(
async () => {
const docsRes = await fetch(`http://127.0.0.1:${server.port}/api/documents`);
const docsBody: { documents?: Array<{ docName: string }> } = await docsRes.json();
return docsBody.documents?.some((doc) => doc.docName === docName) === true;
},
5000,
50,
'the empty file to appear in documents',
),
).resolves.toBeUndefined();
} finally {
destroy();
}
});
test('10 spaced creates produce 10 signals with monotonic seq', async () => {
const { provider, signals, destroy } = connectSystemDoc(server.port);
try {
await waitForSync(provider);
await wait(300);
const baseline = signals.length;
for (let i = 0; i < 10; i++) {
const fileName = `cc1-mono-${i}-${crypto.randomUUID()}.md`;
writeFileSync(join(server.contentDir, fileName), `# file ${i}\n`, 'utf-8');
const expected = baseline + i + 1;
try {
await pollUntil(() => signals.length >= expected, 5000, 20);
} catch {
throw new Error(
`create ${i}: ch:files signal ${expected - baseline} never arrived ` +
`(have ${signals.length - baseline} test signals) — watcher event lost?`,
);
}
expect(signals.length).toBe(expected);
}
await wait(300);
expect(signals.length).toBe(baseline + 10);
const testSignals = signals.slice(baseline);
for (let i = 1; i < testSignals.length; i++) {
expect(testSignals[i].seq).toBeGreaterThan(testSignals[i - 1].seq);
}
} finally {
destroy();
}
});
test('burst of rapid creates debounces to ~1 signal', async () => {
const { provider, signals, destroy } = connectSystemDoc(server.port);
try {
await waitForSync(provider);
await wait(300);
const baseline = signals.length;
for (let i = 0; i < 50; i++) {
const fileName = `cc1-burst-${i}-${crypto.randomUUID()}.md`;
writeFileSync(join(server.contentDir, fileName), `# burst ${i}\n`, 'utf-8');
}
await wait(500);
const burstSignals = signals.length - baseline;
expect(burstSignals).toBeLessThanOrEqual(5);
expect(burstSignals).toBeGreaterThanOrEqual(1);
} finally {
destroy();
}
});
test('file update does not trigger ch:files signal', async () => {
const { provider, signals, destroy } = connectSystemDoc(server.port);
try {
await waitForSync(provider);
const fileName = `cc1-update-test-${crypto.randomUUID()}.md`;
const filePath = join(server.contentDir, fileName);
writeFileSync(filePath, '# original\n', 'utf-8');
await wait(500);
const createCount = signals.length;
expect(createCount).toBeGreaterThanOrEqual(1);
writeFileSync(filePath, '# updated content\n', 'utf-8');
await wait(500);
expect(signals.length).toBe(createCount);
} finally {
destroy();
}
});
test('skip surface: no __system__ state in any subsystem', async () => {
expect(existsSync(join(server.contentDir, '__system__.md'))).toBe(false);
const docsRes = await fetch(`http://127.0.0.1:${server.port}/api/documents`);
const body = (await docsRes.json()) as { documents: Array<{ docName: string }> };
const systemDocs = body.documents.filter((d) => d.docName === '__system__');
expect(systemDocs).toHaveLength(0);
});
test('POST /api/create-page rejects __system__ docName', async () => {
const res = await fetch(`http://127.0.0.1:${server.port}/api/create-page`, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ path: '__system__.md' }),
});
expect(res.status).toBe(400);
const body = (await res.json()) as Record<string, unknown>;
expect(body.type).toBe('urn:ok:error:reserved-doc-name');
expect(String(body.title)).toContain('reserved');
});
test('forged BroadcastStateless on __system__ does not relay to other peers', async () => {
const { provider: subscriber, signals, destroy } = connectSystemDoc(server.port);
try {
await waitForSync(subscriber);
await wait(50);
const baselineCount = signals.length;
const enc = encoding.createEncoder();
encoding.writeVarString(enc, SYSTEM_DOC_NAME);
encoding.writeVarUint(enc, 6);
encoding.writeVarString(
enc,
JSON.stringify({ v: 1, ch: 'files', seq: 999 } satisfies CC1DerivedViewPayload),
);
const forgedFrame = encoding.toUint8Array(enc);
const attackerWs = new WebSocket(`ws://127.0.0.1:${server.port}/collab/${SYSTEM_DOC_NAME}`);
await new Promise<void>((resolve, reject) => {
attackerWs.onopen = () => resolve();
attackerWs.onerror = (e) => reject(new Error(`ws error: ${String(e)}`));
});
attackerWs.send(forgedFrame);
await wait(200);
expect(signals.length).toBe(baselineCount);
attackerWs.close();
} finally {
destroy();
}
});
test('signal payload shape conforms to CC1 contract v1', async () => {
const { provider, signals, destroy } = connectSystemDoc(server.port);
try {
await waitForSync(provider);
await wait(100);
const fileName = `cc1-shape-${crypto.randomUUID()}.md`;
writeFileSync(join(server.contentDir, fileName), '# shape test\n', 'utf-8');
await wait(500);
expect(signals.length).toBeGreaterThanOrEqual(1);
const payload = signals[0];
expect(Object.keys(payload).sort()).toEqual(['ch', 'seq', 'v']);
expect(payload.v).toBe(1);
expect(typeof payload.ch).toBe('string');
expect(typeof payload.seq).toBe('number');
} finally {
destroy();
}
});
test('file delete triggers ch:files signal', async () => {
const { provider, signals, destroy } = connectSystemDoc(server.port);
try {
await waitForSync(provider);
const fileName = `cc1-delete-test-${crypto.randomUUID()}.md`;
const filePath = join(server.contentDir, fileName);
writeFileSync(filePath, '# to be deleted\n', 'utf-8');
await wait(500);
const createCount = signals.length;
expect(createCount).toBeGreaterThanOrEqual(1);
unlinkSync(filePath);
await wait(500);
expect(signals.length).toBeGreaterThan(createCount);
const deleteSignal = signals[signals.length - 1];
expect(deleteSignal.v).toBe(1);
expect(deleteSignal.ch).toBe('files');
expect(deleteSignal.seq).toBeGreaterThan(0);
} finally {
destroy();
}
});
test('file rename triggers ch:files signal', async () => {
const { provider, signals, destroy } = connectSystemDoc(server.port);
try {
await waitForSync(provider);
const oldName = `cc1-rename-old-${crypto.randomUUID()}.md`;
const newName = `cc1-rename-new-${crypto.randomUUID()}.md`;
const oldPath = join(server.contentDir, oldName);
const newPath = join(server.contentDir, newName);
writeFileSync(oldPath, '# to be renamed\n', 'utf-8');
await wait(500);
const createCount = signals.length;
expect(createCount).toBeGreaterThanOrEqual(1);
renameSync(oldPath, newPath);
await wait(600);
expect(signals.length).toBeGreaterThan(createCount);
const lastSignal = signals[signals.length - 1];
expect(lastSignal.v).toBe(1);
expect(lastSignal.ch).toBe('files');
} finally {
destroy();
}
});
test('reconcile with __system__ docName returns noop', () => {
const result = reconcile({
docName: SYSTEM_DOC_NAME,
base: '',
ours: 'any content',
theirs: 'different content',
});
expect(result.kind).toBe('noop');
});
test('BacklinkIndex.updateDocument(__system__, ...) is a no-op', () => {
const idx = new BacklinkIndex({
projectDir: server.contentDir,
contentDir: server.contentDir,
});
idx.updateDocument(SYSTEM_DOC_NAME, [{ target: 'some-page', snippet: null }]);
idx.updateDocumentFromMarkdown(SYSTEM_DOC_NAME, '# Has [[some-page]] link');
expect(idx.getForwardLinks(SYSTEM_DOC_NAME)).toEqual([]);
const backlinks = idx.getBacklinks('some-page');
expect(backlinks.find((b) => b.source === SYSTEM_DOC_NAME)).toBeUndefined();
expect(() => idx.deleteDocument(SYSTEM_DOC_NAME)).not.toThrow();
});
test('AgentSessionManager.getSession(__system__) throws', async () => {
await expect(server.instance.sessionManager.getSession(SYSTEM_DOC_NAME)).rejects.toThrow(
/reserved/i,
);
});
test('applyExternalChange(__system__, content) does not throw and does not mutate', () => {
const systemDoc = server.instance.hocuspocus.documents.get(SYSTEM_DOC_NAME);
const beforeXmlLen = systemDoc?.getXmlFragment('default').length ?? 0;
const beforeTextLen = systemDoc?.getText('source').length ?? 0;
expect(() =>
applyExternalChange(
server.instance.durabilityState,
server.instance.hocuspocus,
SYSTEM_DOC_NAME,
'# should be ignored',
),
).not.toThrow();
const afterXmlLen = systemDoc?.getXmlFragment('default').length ?? 0;
const afterTextLen = systemDoc?.getText('source').length ?? 0;
expect(afterXmlLen).toBe(beforeXmlLen);
expect(afterTextLen).toBe(beforeTextLen);
});
test('disk-to-signal latency p95 under budget', async () => {
const doc = new Y.Doc();
const arrivals: Array<{ seq: number; at: number }> = [];
const provider = new HocuspocusProvider({
url: `ws://127.0.0.1:${server.port}/collab`,
name: SYSTEM_DOC_NAME,
document: doc,
connect: true,
onStateless: ({ payload }) => {
try {
const parsed = JSON.parse(payload) as CC1DerivedViewPayload;
arrivals.push({ seq: parsed.seq, at: performance.now() });
} catch {}
},
});
try {
await waitForSync(provider);
await wait(300);
const arrivalBaseline = arrivals.length;
const sendTimes: number[] = [];
const N = 20;
for (let i = 0; i < N; i++) {
const fileName = `cc1-latency-${i}-${crypto.randomUUID()}.md`;
const sendAt = performance.now();
writeFileSync(join(server.contentDir, fileName), `# ${i}\n`, 'utf-8');
sendTimes.push(sendAt);
await pollUntil(() => arrivals.length >= arrivalBaseline + i + 1, 5000, 20);
}
const testArrivals = arrivals.slice(arrivalBaseline);
const paired = Math.min(sendTimes.length, testArrivals.length);
const latencies: number[] = [];
for (let i = 0; i < paired; i++) {
latencies.push(testArrivals[i].at - sendTimes[i]);
}
if (latencies.length === 0) {
throw new Error('no latency samples captured');
}
latencies.sort((a, b) => a - b);
const p95Idx = Math.max(0, Math.floor(latencies.length * 0.95) - 1);
const p95 = latencies[p95Idx];
expect(p95).toBeLessThan(2000);
} finally {
provider.destroy();
doc.destroy();
}
});
});