Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
import { execFileSync } from 'node:child_process';
import { readFileSync } from 'node:fs';
import { join } from 'node:path';
import { AgentWriteBatchSuccessSchema } from '@inkeep/open-knowledge-core';
import { parseWriterId, resolveShadowDir } from '@inkeep/open-knowledge-core/shadow-repo-layout';
import { afterEach, describe, expect, test } from 'vitest';
import { createTestServer, getServerState, type TestServer } from './test-harness';
interface BatchResponseBody {
timestamp: string;
results: Array<{
status: 'written' | 'error';
docName: string;
summary?: { value: string; truncatedFrom?: number };
brokenLinks?: Array<{ href: string; resolvedTo: string | null; reason: string }>;
error?: { type: string; title: string; detail?: string };
}>;
written: number;
failed: number;
}
interface TimelineResponse {
entries: Array<{
sha: string;
type: string;
message: string;
contributors: Array<{ id: string; name?: string; docs?: string[] }>;
}>;
}
let server: TestServer | undefined;
afterEach(async () => {
await server?.cleanup();
server = undefined;
});
async function postBatch(
port: number,
body: Record<string, unknown>,
headers: Record<string, string> = {},
): Promise<Response> {
return fetch(`http://127.0.0.1:${port}/api/agent-write-batch`, {
method: 'POST',
headers: { 'Content-Type': 'application/json', ...headers },
body: JSON.stringify(body),
});
}
async function readConcurrentOverwriteRefusedCount(port: number): Promise<number> {
const res = await fetch(`http://127.0.0.1:${port}/api/metrics/reconciliation`);
const body = (await res.json()) as { concurrentOverwriteRefused?: number };
return body.concurrentOverwriteRefused ?? -1;
}
function listWipRefs(contentDir: string): string[] {
const shadowDir = resolveShadowDir(contentDir);
const raw = execFileSync('git', ['for-each-ref', '--format=%(refname)', 'refs/wip/'], {
env: { ...process.env, GIT_DIR: shadowDir },
encoding: 'utf-8',
});
return raw
.trim()
.split('\n')
.filter(Boolean)
.filter((refname) => {
const writerId = refname.split('/').slice(3).join('/');
if (!writerId) return false;
const { classification } = parseWriterId(writerId);
return classification === 'agent' || classification === 'principal';
});
}
function countCommits(contentDir: string, ref: string): number {
const shadowDir = resolveShadowDir(contentDir);
const raw = execFileSync('git', ['rev-list', '--count', ref], {
env: { ...process.env, GIT_DIR: shadowDir },
encoding: 'utf-8',
});
return Number(raw.trim());
}
describe('agent-write-batch', () => {
test('mixed create/update batch lands per entry, attributed, with one coalesced shadow commit', async () => {
server = await createTestServer({ gitEnabled: true, commitDebounceMs: 600_000 });
const agentId = 'batch-writer';
const res = await postBatch(server.port, {
agentId,
agentName: 'Batch Writer',
docs: [
{ docName: 'batch/alpha', markdown: '# Alpha\n', position: 'replace' },
{ docName: 'batch/beta', markdown: '# Beta\n', position: 'replace' },
{ docName: 'batch/alpha', markdown: 'Second paragraph.\n', position: 'append' },
],
});
expect(res.status).toBe(200);
const body = (await res.json()) as BatchResponseBody;
expect(AgentWriteBatchSuccessSchema.safeParse(body).success).toBe(true);
expect(body.written).toBe(3);
expect(body.failed).toBe(0);
expect(body.results.map((r) => r.status)).toEqual(['written', 'written', 'written']);
expect(body.results.map((r) => r.docName)).toEqual([
'batch/alpha',
'batch/beta',
'batch/alpha',
]);
const alpha = readFileSync(join(server.contentDir, 'batch/alpha.md'), 'utf-8');
expect(alpha).toContain('# Alpha');
expect(alpha).toContain('Second paragraph.');
expect(readFileSync(join(server.contentDir, 'batch/beta.md'), 'utf-8')).toContain('# Beta');
expect(listWipRefs(server.contentDir)).toEqual([]);
const hist = (await (
await fetch(`${server.baseUrl}/api/history?docName=${encodeURIComponent('batch/alpha')}`)
).json()) as TimelineResponse;
expect(hist.entries.length).toBeGreaterThanOrEqual(1);
const contributorIds = new Set(hist.entries.flatMap((e) => e.contributors.map((c) => c.id)));
expect([...contributorIds]).toEqual([`agent-${agentId}`]);
const batchContributor = hist.entries[0].contributors.find((c) => c.id === `agent-${agentId}`);
expect(batchContributor?.docs).toContain('batch/alpha');
expect(batchContributor?.docs).toContain('batch/beta');
const refs = listWipRefs(server.contentDir);
expect(refs.length).toBe(1);
expect(countCommits(server.contentDir, refs[0])).toBe(1);
}, 30_000);
test('system/config docs reject per entry; siblings land unaffected', async () => {
server = await createTestServer();
const res = await postBatch(server.port, {
agentId: 'batch-gate',
docs: [
{ docName: 'batch-gate/ok-doc', markdown: '# Fine\n', position: 'replace' },
{ docName: '__system__', markdown: '# Nope\n', position: 'replace' },
{ docName: '__config__/project', markdown: '# Nope\n', position: 'replace' },
{ docName: 'batch-gate/also-ok', markdown: '# Also fine\n', position: 'replace' },
],
});
expect(res.status).toBe(200);
const body = (await res.json()) as BatchResponseBody;
expect(body.written).toBe(2);
expect(body.failed).toBe(2);
expect(body.results[0].status).toBe('written');
expect(body.results[1].status).toBe('error');
expect(body.results[1].error?.type).toBe('urn:ok:error:reserved-doc-name');
expect(body.results[2].status).toBe('error');
expect(body.results[2].error?.type).toBe('urn:ok:error:reserved-doc-name');
expect(body.results[3].status).toBe('written');
expect(readFileSync(join(server.contentDir, 'batch-gate/ok-doc.md'), 'utf-8')).toContain(
'# Fine',
);
expect(readFileSync(join(server.contentDir, 'batch-gate/also-ok.md'), 'utf-8')).toContain(
'# Also fine',
);
}, 30_000);
test('a concurrent replace fails only its batch entry', async () => {
server = await createTestServer();
const first = await fetch(`${server.baseUrl}/api/agent-write-md`, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
docName: 'batch-race/contended',
markdown: '# First writer\n',
position: 'replace',
agentId: 'agent-a',
}),
});
expect(first.status).toBe(200);
const refusalsBefore = await readConcurrentOverwriteRefusedCount(server.port);
const response = await postBatch(server.port, {
agentId: 'agent-b',
docs: [
{
docName: 'batch-race/contended',
markdown: '# Second writer\n',
position: 'replace',
},
{ docName: 'batch-race/quiet', markdown: '# Quiet\n', position: 'replace' },
],
});
expect(response.status).toBe(200);
const body = (await response.json()) as BatchResponseBody;
expect(body.written).toBe(1);
expect(body.failed).toBe(1);
expect(body.results[0].error).toEqual({
type: 'urn:ok:error:concurrent-overwrite-refused',
title: 'Concurrent overwrite refused.',
detail:
'Another writer changed this document recently. Wait a few seconds and retry. A write with position append or prepend is not refused.',
retryAfterSeconds: 3,
});
expect(body.results[1].status).toBe('written');
expect(await readConcurrentOverwriteRefusedCount(server.port)).toBe(refusalsBefore + 1);
});
test('broken-link validation admits sibling batch docs and reports dead links', async () => {
server = await createTestServer();
const res = await postBatch(server.port, {
agentId: 'batch-links',
docs: [
{
docName: 'batch-links/a',
markdown: '# A\n\n[to b](./b.md)\n',
position: 'replace',
},
{ docName: 'batch-links/b', markdown: '# B\n', position: 'replace' },
{
docName: 'batch-links/c',
markdown: '# C\n\n[dead](./no-such-doc.md)\n',
position: 'replace',
},
],
});
expect(res.status).toBe(200);
const body = (await res.json()) as BatchResponseBody;
expect(body.results[0].status).toBe('written');
expect(body.results[0].brokenLinks).toEqual([]);
expect(body.results[1].brokenLinks).toEqual([]);
expect(body.results[2].status).toBe('written');
expect(body.results[2].brokenLinks?.length).toBe(1);
expect(body.results[2].brokenLinks?.[0].reason).toBe('no-such-doc');
}, 30_000);
test('per-entry summaries echo with the shared truncation shape', async () => {
server = await createTestServer();
const longSummary = 'x'.repeat(120);
const res = await postBatch(server.port, {
agentId: 'batch-summaries',
docs: [
{
docName: 'batch-summaries/one',
markdown: '# One\n',
position: 'replace',
summary: 'Wrote one',
},
{
docName: 'batch-summaries/two',
markdown: '# Two\n',
position: 'replace',
summary: longSummary,
},
{ docName: 'batch-summaries/three', markdown: '# Three\n', position: 'replace' },
],
});
expect(res.status).toBe(200);
const body = (await res.json()) as BatchResponseBody;
expect(body.results[0].summary?.value).toBe('Wrote one');
expect(body.results[1].summary?.value).toBe(`${'x'.repeat(79)}…`);
expect(body.results[1].summary?.truncatedFrom).toBe(120);
expect(body.results[2].summary).toBeUndefined();
}, 30_000);
test('undo after a batch write flows through the normal per-session path', async () => {
server = await createTestServer();
const agentId = 'batch-undo';
const docName = 'batch-undo/target';
const writeRes = await postBatch(server.port, {
agentId,
docs: [{ docName, markdown: '# Undo target\n', position: 'replace' }],
});
expect(writeRes.status).toBe(200);
expect(getServerState(server, docName)?.ytext.toString()).toContain('# Undo target');
const undoRes = await fetch(`${server.baseUrl}/api/agent-undo`, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ docName, connectionId: `agent-${agentId}`, scope: 'session' }),
});
expect(undoRes.status).toBe(200);
const undoBody = (await undoRes.json()) as { undone: boolean };
expect(undoBody.undone).toBe(true);
expect(getServerState(server, docName)?.ytext.toString()).not.toContain('# Undo target');
}, 30_000);
test('response echoes a well-formed incoming x-request-id', async () => {
server = await createTestServer();
const res = await postBatch(
server.port,
{
agentId: 'batch-reqid',
docs: [{ docName: 'batch-reqid/doc', markdown: '# Hi\n', position: 'replace' }],
},
{ 'x-request-id': 'batch-req-1' },
);
expect(res.status).toBe(200);
expect(res.headers.get('x-request-id')).toBe('batch-req-1');
}, 30_000);
});