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 { tmpdir } from 'node:os';
import { join } from 'node:path';
import { stripFrontmatter } from '@inkeep/open-knowledge-core';
import { afterAll, beforeAll, describe, expect, it } from 'vitest';
import {
CONCURRENT_OVERWRITE_REFUSED_DETAIL_WITH_POSITIONS,
CONCURRENT_OVERWRITE_REFUSED_TITLE,
CONCURRENT_OVERWRITE_REFUSED_TYPE,
CONCURRENT_OVERWRITE_RETRY_AFTER_SECONDS,
} from '../../concurrent-overwrite-refused-error.ts';
import { ConfigSchema } from '../../config/schema.ts';
import { splitPayloadFrontmatter } from '../../payload-frontmatter.ts';
import { type FetchTestServer, startFetchTestServer } from './fetch-test-server.test-helper.ts';
import type { ServerInstance } from './shared.ts';
import {
composeWithFrontmatter,
frontmatterIgnoredNote,
register as registerWrite,
} from './write.ts';
function frontmatterBlockCount(markdown: string): number {
let remaining = markdown;
let count = 0;
while (true) {
const { frontmatter, body } = stripFrontmatter(remaining);
if (frontmatter === '') break;
count += 1;
remaining = body;
}
return count;
}
describe('composeWithFrontmatter', () => {
it('composes a single block from a plain body + param (frontmatter-only path)', () => {
const result = composeWithFrontmatter({ title: 'Hello', tags: ['demo'] }, '# Hello\n\nBody.');
expect(result.ok).toBe(true);
if (!result.ok) return;
expect(frontmatterBlockCount(result.markdown)).toBe(1);
expect(result.markdown).toContain('title: Hello');
expect(result.markdown.endsWith('# Hello\n\nBody.')).toBe(true);
});
it('PRD-6997: does NOT stack a second block when content already has one', () => {
const content = '---\ntitle: Doubled FM\ntags: [demo]\n---\n\n# Doubled FM\n\nReal body line.';
const result = composeWithFrontmatter({ title: 'Doubled FM', tags: ['demo'] }, content);
expect(result.ok).toBe(true);
if (!result.ok) return;
expect(frontmatterBlockCount(result.markdown)).toBe(1);
expect(result.markdown).toContain('# Doubled FM');
expect(result.markdown).toContain('Real body line.');
});
it('merges embedded + param with the param winning on conflicting keys', () => {
const content = '---\ntitle: Embedded\nauthor: HeeGun\n---\n\nBody.';
const result = composeWithFrontmatter({ title: 'Param' }, content);
expect(result.ok).toBe(true);
if (!result.ok) return;
expect(frontmatterBlockCount(result.markdown)).toBe(1);
const { frontmatter } = stripFrontmatter(result.markdown);
expect(frontmatter).toContain('title: Param');
expect(frontmatter).toContain('author: HeeGun');
expect(frontmatter).not.toContain('Embedded');
});
it('rejects a malformed embedded block instead of doubling', () => {
const content = '---\ntitle: [unterminated\n---\n\nBody.';
const result = composeWithFrontmatter({ title: 'Param' }, content);
expect(result.ok).toBe(false);
if (result.ok) return;
expect(result.error).toContain('EMBEDDED_FRONTMATTER_MALFORMED');
});
it('drops the block entirely when the merged result is empty', () => {
const result = composeWithFrontmatter({ title: '' }, 'Just a body, no block.');
expect(result.ok).toBe(true);
if (!result.ok) return;
expect(frontmatterBlockCount(result.markdown)).toBe(0);
expect(result.markdown).toBe('Just a body, no block.');
});
it('a param empty value clears a conflicting embedded key', () => {
const content = '---\ntitle: Keep\nstatus: draft\n---\n\nBody.';
const result = composeWithFrontmatter({ status: '' }, content);
expect(result.ok).toBe(true);
if (!result.ok) return;
const { frontmatter } = stripFrontmatter(result.markdown);
expect(frontmatter).toContain('title: Keep');
expect(frontmatter).not.toContain('status');
});
it('a param null value clears a conflicting embedded key (RFC 7396 delete sentinel)', () => {
const content = '---\ntitle: Keep\nstatus: draft\n---\n\nBody.';
const result = composeWithFrontmatter({ status: null }, content);
expect(result.ok).toBe(true);
if (!result.ok) return;
const { frontmatter } = stripFrontmatter(result.markdown);
expect(frontmatter).toContain('title: Keep');
expect(frontmatter).not.toContain('status');
});
it('strips the embedded block entirely when the param clears its only key', () => {
const content = '---\nstatus: draft\n---\n\nBody.';
const result = composeWithFrontmatter({ status: null }, content);
expect(result.ok).toBe(true);
if (!result.ok) return;
expect(frontmatterBlockCount(result.markdown)).toBe(0);
expect(result.markdown).toBe('\nBody.');
});
});
describe('splitPayloadFrontmatter — the shared append/prepend partition rule', () => {
it('treats a `---`-fenced NON-mapping span as body, so no drop is announced', () => {
const payload = '---\n\n## Findings\n\n---\n\nTrailing note.\n';
const split = splitPayloadFrontmatter(payload);
expect(split.frontmatter).toBe('');
expect(split.body).toBe(payload);
});
it('still partitions a real YAML-mapping block off the payload', () => {
const split = splitPayloadFrontmatter('---\ntitle: Second\n---\n\nExtra.\n');
expect(split.frontmatter).toBe('---\ntitle: Second\n---\n');
expect(split.body).toBe('\nExtra.\n');
});
it('leaves a payload with no leading fence untouched', () => {
const split = splitPayloadFrontmatter('Just a paragraph.\n');
expect(split.frontmatter).toBe('');
expect(split.body).toBe('Just a paragraph.\n');
});
});
describe('frontmatterIgnoredNote — the two outcomes are distinguishable', () => {
const dropped = frontmatterIgnoredNote('append', '---\ntitle: Fine\n---\nbody\n');
const asBody = frontmatterIgnoredNote('append', '---\ntitle: Foo: Bar\n---\nbody\n');
it('says DROPPED for a well-formed mapping', () => {
expect(dropped).toContain('was ignored');
expect(dropped).not.toContain('written as BODY');
});
it('says WRITTEN AS BODY for a span that is not a mapping', () => {
expect(asBody).toContain('written as BODY');
expect(asBody).toContain('not a YAML mapping');
});
it('stays silent when the payload never opened with a fence pair', () => {
expect(frontmatterIgnoredNote('append', 'just a paragraph\n')).toBeNull();
expect(frontmatterIgnoredNote('append', '---\njust a break\n')).toBeNull();
});
it('stays silent on replace, which does not drop anything', () => {
expect(frontmatterIgnoredNote('replace', '---\ntitle: Fine\n---\nbody\n')).toBeNull();
});
});
describe('write({ skill }) with bundle files — the per-file report reaches both text channels', () => {
interface ToolResult {
content: Array<{ type: 'text'; text: string }>;
structuredContent?: Record<string, unknown>;
isError?: true;
}
type Handler = (args: Record<string, unknown>) => Promise<ToolResult>;
let testServer: FetchTestServer;
let cwd: string;
let handler: Handler;
beforeAll(async () => {
testServer = await startFetchTestServer({
hostname: '127.0.0.1',
fetch(request) {
const { pathname } = new URL(request.url);
if (pathname === '/api/skill') {
return Response.json({
ok: true,
path: '.agents/skills/trip-log/SKILL.md',
created: true,
});
}
return Response.json({ error: 'Bundle file rejected by the server.' }, { status: 500 });
},
});
cwd = mkdtempSync(join(tmpdir(), 'ok-write-skill-files-'));
mkdirSync(join(cwd, '.ok'), { recursive: true });
let captured: Handler | null = null;
const server = {
registerTool(_name: string, _cfg: unknown, toolHandler: Handler) {
captured = toolHandler;
},
} as unknown as ServerInstance;
registerWrite(server, {
serverUrl: `http://127.0.0.1:${testServer.port}`,
config: ConfigSchema.parse({}),
resolveCwd: async () => cwd,
});
if (captured === null) throw new Error('write tool did not register');
handler = captured;
});
afterAll(() => {
testServer.stop();
rmSync(cwd, { recursive: true, force: true });
});
it('mirrors a failed bundle file into structuredContent.text, not just content[0].text', async () => {
const result = await handler({
skill: {
name: 'trip-log',
description: 'Use when logging a fishing trip.',
files: [{ path: 'references/gear.md', content: '# Gear\n' }],
},
});
expect(result.isError).toBe(true);
expect(result.content[0]?.text).toContain('0/1 bundle file(s) written.');
expect(result.content[0]?.text).toContain('Failed references/gear.md');
expect(result.structuredContent?.text).toBe(result.content[0]?.text);
});
});
describe('write({ document }) relaying a concurrent-overwrite refusal', () => {
interface ToolResult {
content: Array<{ type: 'text'; text: string }>;
structuredContent?: Record<string, unknown>;
isError?: true;
}
type Handler = (args: Record<string, unknown>) => Promise<ToolResult>;
let testServer: FetchTestServer;
let cwd: string;
let handler: Handler;
beforeAll(async () => {
testServer = await startFetchTestServer({
hostname: '127.0.0.1',
fetch(request) {
const { pathname } = new URL(request.url);
if (pathname === '/api/agent-write-md') {
return Response.json(
{
type: CONCURRENT_OVERWRITE_REFUSED_TYPE,
title: CONCURRENT_OVERWRITE_REFUSED_TITLE,
status: 409,
instance: 'urn:uuid:11111111-2222-4333-8444-555555555555',
detail: CONCURRENT_OVERWRITE_REFUSED_DETAIL_WITH_POSITIONS,
file: 'notes/contended.md',
retryAfterSeconds: CONCURRENT_OVERWRITE_RETRY_AFTER_SECONDS,
},
{
status: 409,
headers: { 'Retry-After': String(CONCURRENT_OVERWRITE_RETRY_AFTER_SECONDS) },
},
);
}
return Response.json({ error: `unexpected route ${pathname}` }, { status: 500 });
},
});
cwd = mkdtempSync(join(tmpdir(), 'ok-write-concurrent-refusal-'));
mkdirSync(join(cwd, '.ok'), { recursive: true });
let captured: Handler | null = null;
const server = {
registerTool(_name: string, _cfg: unknown, toolHandler: Handler) {
captured = toolHandler;
},
} as unknown as ServerInstance;
registerWrite(server, {
serverUrl: `http://127.0.0.1:${testServer.port}`,
config: ConfigSchema.parse({}),
resolveCwd: async () => cwd,
});
if (captured === null) throw new Error('write tool did not register');
handler = captured;
});
afterAll(() => {
testServer.stop();
rmSync(cwd, { recursive: true, force: true });
});
it('carries the retry bound into the single-doc error text', async () => {
const result = await handler({
document: { path: 'notes/contended', content: '# From B\n', position: 'replace' },
});
expect(result.isError).toBe(true);
expect(result.content[0]?.text).toBe(
`Error: ${CONCURRENT_OVERWRITE_REFUSED_TITLE} (${CONCURRENT_OVERWRITE_REFUSED_DETAIL_WITH_POSITIONS}) Retry after ${CONCURRENT_OVERWRITE_RETRY_AFTER_SECONDS}s. Wait and retry, or use edit for a targeted change.`,
);
});
it('carries the retry bound into the batch per-entry error text', async () => {
const result = await handler({
documents: [{ path: 'notes/contended', content: '# From B\n', position: 'replace' }],
});
expect(result.isError).toBe(true);
expect(result.content[0]?.text).toContain(
`Retry after ${CONCURRENT_OVERWRITE_RETRY_AFTER_SECONDS}s.`,
);
expect(result.content[0]?.text).toContain('or use edit');
});
});
describe('write({ document }) appending or prepending to a path with no document', () => {
interface ToolResult {
content: Array<{ type: 'text'; text: string }>;
isError?: true;
}
type Handler = (args: Record<string, unknown>) => Promise<ToolResult>;
let testServer: FetchTestServer;
let cwd: string;
let handler: Handler;
beforeAll(async () => {
testServer = await startFetchTestServer({
hostname: '127.0.0.1',
fetch(request) {
const { pathname } = new URL(request.url);
if (pathname === '/api/agent-write-md') {
return Response.json({ timestamp: new Date().toISOString(), subscriberCount: 0 });
}
return Response.json({ error: `unexpected route ${pathname}` }, { status: 500 });
},
});
cwd = mkdtempSync(join(tmpdir(), 'ok-write-created-by-position-'));
mkdirSync(join(cwd, '.ok'), { recursive: true });
mkdirSync(join(cwd, 'notes'), { recursive: true });
writeFileSync(join(cwd, 'notes', 'existing.md'), '# Existing\n');
let captured: Handler | null = null;
const server = {
registerTool(_name: string, _cfg: unknown, toolHandler: Handler) {
captured = toolHandler;
},
} as unknown as ServerInstance;
registerWrite(server, {
serverUrl: `http://127.0.0.1:${testServer.port}`,
config: ConfigSchema.parse({}),
resolveCwd: async () => cwd,
});
if (captured === null) throw new Error('write tool did not register');
handler = captured;
});
afterAll(() => {
testServer.stop();
rmSync(cwd, { recursive: true, force: true });
});
it('says the append created a new document instead of reporting a plain success', async () => {
const result = await handler({
document: { path: 'system/ops', content: 'appended line\n', position: 'append' },
});
expect(result.isError).toBeUndefined();
const text = result.content[0]?.text ?? '';
expect(text.split('\n')[0]).toContain('Created new document "system/ops"');
expect(text).not.toContain('Written successfully');
});
it('keeps the plain success line when the appended-to document exists', async () => {
const result = await handler({
document: { path: 'notes/existing', content: 'more\n', position: 'append' },
});
expect(result.content[0]?.text.split('\n')[0]).toBe('Written successfully (append).');
});
it('names the created document in a batch entry', async () => {
const result = await handler({
documents: [
{ path: 'notes/existing', content: 'more\n', position: 'prepend' },
{ path: 'system/ops', content: 'prepended line\n', position: 'prepend' },
],
});
const text = result.content[0]?.text ?? '';
expect(text).toContain('Wrote notes/existing (prepend).');
expect(text).toContain('Created new document "system/ops"');
expect(text).not.toContain('Wrote system/ops');
});
});
describe('write — an asset upload whose request to the server fails', () => {
type AssetHandler = (args: Record<string, unknown>) => Promise<{
isError?: boolean;
content: Array<{ type: string; text?: string }>;
}>;
const asset = { path: 'assets/photo.bin', content: Buffer.from('bytes').toString('base64') };
let cwd: string;
beforeAll(() => {
cwd = mkdtempSync(join(tmpdir(), 'ok-write-asset-transport-'));
mkdirSync(join(cwd, '.ok'), { recursive: true });
});
afterAll(() => {
rmSync(cwd, { recursive: true, force: true });
});
function writeTool(deps: Omit<Parameters<typeof registerWrite>[1], 'config' | 'resolveCwd'>) {
let captured: AssetHandler | null = null;
const server = {
registerTool(_name: string, _cfg: unknown, toolHandler: AssetHandler) {
captured = toolHandler;
},
} as unknown as ServerInstance;
registerWrite(server, { ...deps, config: ConfigSchema.parse({}), resolveCwd: async () => cwd });
if (captured === null) throw new Error('write tool did not register');
return captured as AssetHandler;
}
it('says the server timed out, and may have applied it, when the upload runs out of time', async () => {
const upload = writeTool({
serverUrl: 'http://127.0.0.1:1',
localApi: async () => {
throw new DOMException('The operation was aborted due to timeout', 'TimeoutError');
},
});
const result = await upload({ asset });
expect(result.isError).toBe(true);
expect(result.content[0]?.text).toBe(
'Error: Server timed out: The operation was aborted due to timeout. The server may still have applied the request, so check before retrying.',
);
});
it('says the server is unreachable when the upload cannot connect', async () => {
const upload = writeTool({ serverUrl: 'http://127.0.0.1:1' });
const result = await upload({ asset });
expect(result.isError).toBe(true);
expect(result.content[0]?.text).toBe('Error: Server unreachable: fetch failed');
});
});
describe('write — the reply to an asset upload the server accepted', () => {
type AssetHandler = (args: Record<string, unknown>) => Promise<{
isError?: boolean;
content: Array<{ type: string; text?: string }>;
structuredContent?: { asset?: unknown };
}>;
const asset = { path: 'assets/photo.bin', content: Buffer.from('bytes').toString('base64') };
let cwd: string;
beforeAll(() => {
cwd = mkdtempSync(join(tmpdir(), 'ok-write-asset-reply-'));
mkdirSync(join(cwd, '.ok'), { recursive: true });
});
afterAll(() => {
rmSync(cwd, { recursive: true, force: true });
});
function uploadAnswering(bodyText: string): AssetHandler {
let captured: AssetHandler | null = null;
const server = {
registerTool(_name: string, _cfg: unknown, toolHandler: AssetHandler) {
captured = toolHandler;
},
} as unknown as ServerInstance;
registerWrite(server, {
serverUrl: 'http://127.0.0.1:1',
localApi: async () => ({ status: 200, bodyText }),
config: ConfigSchema.parse({}),
resolveCwd: async () => cwd,
});
if (captured === null) throw new Error('write tool did not register');
return captured as AssetHandler;
}
it('claims no location rather than the requested path when the response names none', async () => {
const result = await uploadAnswering('{"src":"photo.bin"}')({ asset });
expect(result.isError ?? false).toBe(false);
expect(result.structuredContent?.asset).toStrictEqual({ ok: true, src: 'photo.bin' });
expect(result.content[0]?.text).not.toContain(asset.path);
});
it('reports an error, not an upload, when the response breaks the upload contract', async () => {
const result = await uploadAnswering('{"src":"photo.bin","path":12345}')({ asset });
expect(result.isError).toBe(true);
expect(result.structuredContent?.asset).toBeUndefined();
expect(result.content[0]?.text).toMatch(
/^Error: Server returned 2xx response with malformed upload body: .*path/s,
);
});
});