Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
import { execFile } from 'node:child_process';
import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
import { mkdtemp, rm } from 'node:fs/promises';
import { tmpdir } from 'node:os';
import { dirname, resolve } from 'node:path';
import { setTimeout as wait } from 'node:timers/promises';
import { promisify } from 'node:util';
import {
DocumentListSuccessSchema,
DocumentReadSuccessSchema,
OK_DIR,
SyncConflictsSuccessSchema,
} from '@inkeep/open-knowledge-core';
import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest';
import * as Y from 'yjs';
import { bootServer } from '../../../test-support/boot-server.test-helper.ts';
import { configureTestGitRepository } from '../../../test-support/configure-git-fixture.test-helper.ts';
import { ConfigSchema } from './config/schema.ts';
import * as headWatcher from './head-watcher.ts';
import type { ServerInstance } from './server-factory.ts';
const execFileAsync = promisify(execFile);
const TEST_CONFIG = ConfigSchema.parse({});
const DOC_NAME = 'notes/topic';
const DOC_FILE = 'notes/topic.md';
const SCRATCH_DOC = 'notes/scratch';
const SCRATCH_FILE = 'notes/scratch.md';
const COLLISION_FILE = 'notes/pull-collision.md';
const CONTROL_MARKER = 'stored while the batch was down';
const DEFERRED_MARKER = 'drained by the resolve';
function seedOkScaffold(projectDir: string): void {
const okDir = resolve(projectDir, OK_DIR);
mkdirSync(okDir, { recursive: true });
writeFileSync(resolve(okDir, 'config.yml'), '', 'utf-8');
writeFileSync(resolve(okDir, '.gitignore'), 'local/\n', 'utf-8');
}
function seedConflictsJson(projectDir: string, file: string): void {
const localDir = resolve(projectDir, OK_DIR, 'local');
mkdirSync(localDir, { recursive: true });
writeFileSync(
resolve(localDir, 'conflicts.json'),
JSON.stringify(
{
version: 1,
branch: 'main',
conflicts: [{ kind: 'merge-native', file, detectedAt: '2026-05-19T00:00:00.000Z' }],
},
null,
2,
),
'utf-8',
);
}
async function seedRealMergeConflict(projectDir: string, filePath: string): Promise<void> {
const opts = { cwd: projectDir };
await execFileAsync('git', ['config', 'maintenance.auto', 'false'], opts);
await execFileAsync('git', ['config', 'user.email', '[email protected]'], opts);
await execFileAsync('git', ['config', 'user.name', 'Test'], opts);
mkdirSync(resolve(projectDir, 'notes'), { recursive: true });
writeFileSync(resolve(projectDir, filePath), 'line1\nline2\nline3\n', 'utf-8');
await execFileAsync('git', ['add', '-A'], opts);
await execFileAsync('git', ['commit', '-m', 'base'], opts);
await execFileAsync('git', ['checkout', '-b', 'theirs-branch'], opts);
writeFileSync(resolve(projectDir, filePath), 'line1\nUPSTREAM\nline3\n', 'utf-8');
await execFileAsync('git', ['commit', '-am', 'theirs'], opts);
await execFileAsync('git', ['checkout', 'main'], opts);
writeFileSync(resolve(projectDir, filePath), 'line1\nLOCAL\nline3\n', 'utf-8');
await execFileAsync('git', ['commit', '-am', 'ours'], opts);
await execFileAsync('git', ['merge', 'theirs-branch'], opts).catch(() => {});
if (!existsSync(resolve(projectDir, '.git', 'MERGE_HEAD'))) {
throw new Error('seedRealMergeConflict: no MERGE_HEAD — the merge did not conflict');
}
}
async function isIndexed(port: number, docName: string): Promise<boolean> {
const res = await fetch(`http://127.0.0.1:${port}/api/documents`);
expect(res.ok).toBe(true);
const data = DocumentListSuccessSchema.parse(await res.json());
return data.documents.some((d) => d.docName === docName);
}
async function listConflictFiles(port: number): Promise<string[]> {
const res = await fetch(`http://127.0.0.1:${port}/api/sync/conflicts`);
expect(res.ok).toBe(true);
const data = SyncConflictsSuccessSchema.parse(await res.json());
return data.conflicts.map((c) => c.file);
}
interface ProbeAnswer {
status: number;
outcome: unknown;
}
async function writeDocProbe(
port: number,
docName: string,
markdown: string,
): Promise<ProbeAnswer> {
const res = await fetch(`http://127.0.0.1:${port}/api/agent-write-md`, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ docName, markdown, position: 'replace', agentId: 'probe' }),
});
const body = (await res.json()) as { outcome?: unknown };
return { status: res.status, outcome: body.outcome };
}
async function writeProbe(port: number, markdown: string): Promise<ProbeAnswer> {
return writeDocProbe(port, DOC_NAME, markdown);
}
function expectAdmitted(answer: ProbeAnswer): void {
expect(answer).toEqual(
answer.status === 503
? { status: 503, outcome: 'projection-held' }
: { status: 200, outcome: 'applied' },
);
}
function expectRefusedByConflict(answer: ProbeAnswer): void {
expect(answer).toEqual({ status: 409, outcome: 'refused' });
}
async function resolveConflictOverHttp(
port: number,
file: string,
strategy: string,
): Promise<number> {
const res = await fetch(`http://127.0.0.1:${port}/api/sync/resolve-conflict`, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ file, strategy }),
});
return res.status;
}
async function pollUntil(
condition: () => boolean | Promise<boolean>,
timeoutMs: number,
what: string,
): Promise<void> {
const start = Date.now();
while (Date.now() - start < timeoutMs) {
if (await condition()) return;
await wait(200);
}
throw new Error(`timed out after ${timeoutMs}ms waiting for ${what}`);
}
function awaitWithin<T>(
promise: Promise<T>,
timeoutMs: number,
what: string,
signal: AbortSignal,
): Promise<T> {
const stopped = Promise.withResolvers<never>();
const timer = setTimeout(
() => stopped.reject(new Error(`timed out after ${timeoutMs}ms waiting for ${what}`)),
timeoutMs,
);
const abandon = () => stopped.reject(signal.reason);
if (signal.aborted) abandon();
else signal.addEventListener('abort', abandon, { once: true });
return Promise.race([promise, stopped.promise]).finally(() => {
clearTimeout(timer);
signal.removeEventListener('abort', abandon);
});
}
let tmpDir: string;
let pendingTeardown: Promise<void> = Promise.resolve();
beforeEach(async () => {
tmpDir = await mkdtemp(resolve(tmpdir(), 'ok-conflict-authority-'));
});
afterEach(async () => {
await pendingTeardown;
await rm(tmpDir, { recursive: true, force: true });
});
async function bootWithHeldConflictedDoc(options?: {
extraFiles?: Record<string, string>;
load?: boolean;
}): Promise<{
port: number;
serverInstance: ServerInstance;
destroy: () => Promise<void>;
release: () => Promise<void>;
readSource: () => Promise<string>;
}> {
const contentDir = tmpDir;
await execFileAsync('git', ['init', '--initial-branch=main', contentDir]);
configureTestGitRepository(contentDir);
seedOkScaffold(contentDir);
for (const [file, body] of Object.entries(options?.extraFiles ?? {})) {
const abs = resolve(contentDir, file);
mkdirSync(dirname(abs), { recursive: true });
writeFileSync(abs, body, 'utf-8');
}
await seedRealMergeConflict(contentDir, DOC_FILE);
seedConflictsJson(contentDir, DOC_FILE);
const booted = await bootServer({
config: TEST_CONFIG,
contentDir,
port: 0,
quiet: true,
gitEnabled: false,
idleShutdownMs: null,
});
const dc =
options?.load === false
? null
: await booted.serverInstance.hocuspocus.openDirectConnection(DOC_NAME);
await pollUntil(
() => isIndexed(booted.port, DOC_NAME),
30_000,
'the initial file-watcher scan to index the conflicted doc',
);
return {
port: booted.port,
serverInstance: booted.serverInstance,
destroy: async () => {
await booted.destroy();
},
release: async () => {
await dc?.disconnect();
},
readSource: async () => {
const res = await fetch(
`http://127.0.0.1:${booted.port}/api/document?docName=${encodeURIComponent(DOC_NAME)}`,
);
expect(res.ok).toBe(true);
return DocumentReadSuccessSchema.parse(await res.json()).content;
},
};
}
async function checkoutOurs(port: number, replacement: string): Promise<void> {
if (replacement === 'separated delete/create') {
await rm(resolve(tmpDir, DOC_FILE));
await pollUntil(
async () => !(await isIndexed(port, DOC_NAME)),
30_000,
'the server to observe the removal before recreation',
);
}
await execFileAsync('git', ['checkout', '--ours', '--', DOC_FILE], { cwd: tmpDir });
}
describe('PRD-8318: a merge-native conflict resolved with raw git unfreezes the loaded doc', () => {
test.each(['checkout', 'separated delete/create'])(
'ordering A — the disk event drains before HEAD moves, and the write is admitted (%s)',
async (replacement) => {
const held = await bootWithHeldConflictedDoc();
try {
await pollUntil(
async () => (await listConflictFiles(held.port)).includes(DOC_FILE),
20_000,
'the seeded merge-native entry to be listed',
);
expectRefusedByConflict(await writeProbe(held.port, '# blocked\n'));
const opts = { cwd: tmpDir };
await checkoutOurs(held.port, replacement);
await execFileAsync('git', ['add', '--', DOC_FILE], opts);
await pollUntil(
async () => {
const source = await held.readSource();
return source.includes('LOCAL') && !source.includes('<<<<<<<');
},
30_000,
'the server to process the disk update for the resolved file',
);
await execFileAsync('git', ['commit', '--no-edit'], opts);
await pollUntil(
async () => (await listConflictFiles(held.port)).length === 0,
60_000,
'the conflict ledger to empty after the external resolve',
);
expectAdmitted(await writeProbe(held.port, '# probe\n'));
expect(await held.readSource()).toContain('# probe');
} finally {
await held.release();
await held.destroy();
}
},
180_000,
);
test('ordering B — resolved bytes on disk alone do not prune; completing the merge does', async () => {
const held = await bootWithHeldConflictedDoc();
try {
await pollUntil(
async () => (await listConflictFiles(held.port)).includes(DOC_FILE),
20_000,
'the seeded merge-native entry to be listed',
);
expectRefusedByConflict(await writeProbe(held.port, '# blocked\n'));
writeFileSync(resolve(tmpDir, DOC_FILE), 'line1\nLOCAL\nline3\n', 'utf-8');
await pollUntil(
async () => {
const source = await held.readSource();
return source.includes('LOCAL') && !source.includes('<<<<<<<');
},
30_000,
'the server to process the disk update for the hand-resolved file',
);
const opts = { cwd: tmpDir };
const stillUnmerged = await execFileAsync(
'git',
['diff', '--name-only', '--diff-filter=U'],
opts,
);
expect(stillUnmerged.stdout).toContain(DOC_FILE);
expect(await listConflictFiles(held.port)).toContain(DOC_FILE);
expectRefusedByConflict(await writeProbe(held.port, '# still blocked\n'));
await execFileAsync('git', ['add', '--', DOC_FILE], opts);
await execFileAsync('git', ['commit', '--no-edit'], opts);
await pollUntil(
async () => (await listConflictFiles(held.port)).length === 0,
60_000,
'the conflict ledger to empty once the merge was completed',
);
expect(existsSync(resolve(tmpDir, '.git', 'MERGE_HEAD'))).toBe(false);
expectAdmitted(await writeProbe(held.port, '# probe\n'));
expect(await held.readSource()).toContain('# probe');
} finally {
await held.release();
await held.destroy();
}
}, 180_000);
test.each(['checkout', 'separated delete/create'])(
'a mid-merge `git add` with no commit heals through the disk-update path (%s)',
async (replacement) => {
const held = await bootWithHeldConflictedDoc();
try {
await pollUntil(
async () => (await listConflictFiles(held.port)).includes(DOC_FILE),
20_000,
'the seeded merge-native entry to be listed',
);
const opts = { cwd: tmpDir };
await checkoutOurs(held.port, replacement);
await execFileAsync('git', ['add', '--', DOC_FILE], opts);
await pollUntil(
async () => {
const source = await held.readSource();
return source.includes('LOCAL') && !source.includes('<<<<<<<');
},
30_000,
'the server to process the disk update for the staged file',
);
await pollUntil(
async () => (await listConflictFiles(held.port)).length === 0,
60_000,
'the conflict ledger to empty from the disk-update prune',
);
expect(existsSync(resolve(tmpDir, '.git', 'MERGE_HEAD'))).toBe(true);
expectAdmitted(await writeProbe(held.port, '# probe\n'));
expect(await held.readSource()).toContain('# probe');
} finally {
await held.release();
await held.destroy();
}
},
180_000,
);
test.each(['checkout', 'separated delete/create'])(
'a staged merge-native entry prunes for a document that was never loaded (%s)',
async (replacement) => {
const held = await bootWithHeldConflictedDoc({ load: false });
try {
await pollUntil(
async () => (await listConflictFiles(held.port)).includes(DOC_FILE),
20_000,
'the seeded merge-native entry to be listed',
);
expect(held.serverInstance.hocuspocus.documents.has(DOC_NAME)).toBe(false);
const opts = { cwd: tmpDir };
await checkoutOurs(held.port, replacement);
await execFileAsync('git', ['add', '--', DOC_FILE], opts);
await pollUntil(
async () => (await listConflictFiles(held.port)).length === 0,
60_000,
'the disk-update prune to drop the entry for the unloaded doc',
);
expect(held.serverInstance.hocuspocus.documents.has(DOC_NAME)).toBe(false);
expect(existsSync(resolve(tmpDir, '.git', 'MERGE_HEAD'))).toBe(true);
} finally {
await held.release();
await held.destroy();
}
},
180_000,
);
test('staging a recreated unloaded document prunes from the persistent index notification', async ({
onTestFinished,
signal,
}) => {
const notification = Promise.withResolvers<(path: string) => void>();
const batchEnded = Promise.withResolvers<void>();
const startHeadWatcher = headWatcher.startHeadWatcher;
const subscription = vi
.spyOn(headWatcher, 'startHeadWatcher')
.mockImplementation((projectRoot, begin, end, options) =>
startHeadWatcher(
projectRoot,
begin,
async (info) => {
try {
await end(info);
} finally {
batchEnded.resolve();
}
},
{
...options,
subscribeForTest: async (_gitDir, dispatch) => {
notification.resolve(dispatch);
return async () => {};
},
},
),
);
onTestFinished(() => subscription.mockRestore());
const held = await bootWithHeldConflictedDoc({ load: false });
const tornDown = Promise.withResolvers<void>();
pendingTeardown = tornDown.promise;
try {
const dispatch = await awaitWithin(
notification.promise,
30_000,
'the head watcher to subscribe',
signal,
);
expect(await listConflictFiles(held.port)).toContain(DOC_FILE);
expect(held.serverInstance.hocuspocus.documents.has(DOC_NAME)).toBe(false);
await checkoutOurs(held.port, 'separated delete/create');
await pollUntil(
() => isIndexed(held.port, DOC_NAME),
30_000,
'the server to index the recreated file before staging',
);
expect(await listConflictFiles(held.port)).toContain(DOC_FILE);
await execFileAsync('git', ['add', '--', DOC_FILE], { cwd: tmpDir });
dispatch(resolve(tmpDir, '.git', 'index'));
await awaitWithin(
batchEnded.promise,
30_000,
'the batch started by the index notification to end',
signal,
);
expect(await listConflictFiles(held.port)).toEqual([]);
expect(held.serverInstance.hocuspocus.documents.has(DOC_NAME)).toBe(false);
expect(existsSync(resolve(tmpDir, '.git', 'MERGE_HEAD'))).toBe(true);
} finally {
try {
await held.release();
await held.destroy();
} finally {
tornDown.resolve();
}
}
}, 180_000);
test('a resolve over HTTP drains the stores the batch deferred, with no manual flush', async () => {
const held = await bootWithHeldConflictedDoc({
extraFiles: { [SCRATCH_FILE]: 'scratch base\n', [COLLISION_FILE]: 'overlay\n' },
});
const readScratch = () => readFileSync(resolve(tmpDir, SCRATCH_FILE), 'utf-8');
try {
await pollUntil(
() => isIndexed(held.port, SCRATCH_DOC),
30_000,
'the initial file-watcher scan to index the scratch doc',
);
expectAdmitted(await writeDocProbe(held.port, SCRATCH_DOC, `# ${CONTROL_MARKER}\n`));
await pollUntil(
() => readScratch().includes(CONTROL_MARKER),
30_000,
'an undeferred store to reach disk',
);
held.serverInstance.conflicts.raise({
kind: 'working-tree',
file: COLLISION_FILE,
theirsSha: '0'.repeat(40),
});
held.serverInstance.durabilityState.setBatchInProgress(true);
const scratch = await held.serverInstance.hocuspocus.openDirectConnection(SCRATCH_DOC);
try {
await scratch.transact((doc) => {
const paragraph = new Y.XmlElement('paragraph');
paragraph.insert(0, [new Y.XmlText(DEFERRED_MARKER)]);
doc.getXmlFragment('default').push([paragraph]);
});
const debounceId = `onStoreDocument-${SCRATCH_DOC}`;
await pollUntil(
() => held.serverInstance.hocuspocus.debouncer.isDebounced(debounceId),
15_000,
'the edit to schedule a store',
);
await held.serverInstance.hocuspocus.debouncer.executeNow(debounceId);
} finally {
await scratch.disconnect();
}
expect(readScratch()).toContain(CONTROL_MARKER);
expect(readScratch()).not.toContain(DEFERRED_MARKER);
expect(await listConflictFiles(held.port)).toContain(COLLISION_FILE);
expect(await resolveConflictOverHttp(held.port, COLLISION_FILE, 'mine')).toBe(200);
await pollUntil(
() => readScratch().includes(DEFERRED_MARKER),
30_000,
'the resolve route to drain the deferred store to disk',
);
} finally {
await held.release();
await held.destroy();
}
}, 180_000);
});