Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

fix(open-knowledge): FM region destroyed by Path B merge after fence-breaking source edit (#1783)

Nick Gomez87f2c4555cce
diff --git a/.changeset/fm-fence-trailing-whitespace.md b/.changeset/fm-fence-trailing-whitespace.md
new file mode 100644
index 000000000..e94dadde2
--- /dev/null
+++ b/.changeset/fm-fence-trailing-whitespace.md
@@ -0,0 +1,7 @@
+---
+"@inkeep/open-knowledge": patch
+---
+
+Fixed: a trailing space or tab typed at the end of a frontmatter fence line in source mode no longer destroys the document's frontmatter on the next visual edit. Frontmatter fence recognition now tolerates trailing spaces/tabs on the `---` lines (matching CommonMark / remark-frontmatter behavior), so documents whose fences carry trailing whitespace are recognized consistently across the editor bridge, the property panel, templates, search heading extraction, outline navigation, skill bundle metadata, the CLI, and source-mode syntax styling. Leading whitespace before a fence still disqualifies it, as before.
+
+For maintainers — mechanism: `FRONTMATTER_RE` rejected fence lines with trailing whitespace while the bridge tolerance layer (`normalizeBridge` step 7b, the per-line trailing-whitespace strip) declared exactly those bytes equivalent, violating partition invariance: an in-tolerance W2 keystroke (`---` → `--- `) silently changed FM-region recognition, so Observer A Path B's recompose (`prependFrontmatter(readCurrentFm(), serialize(fragment))`) fabricated an FM deletion that the three-way merge then applied and settled. The recognition predicate is widened to `/^---[ \t]*\r?\n([\s\S]*?\r?\n)?---[ \t]*(\r?\n|$)/` at its definition boundary in core, with every sibling recognition site (server template/heading/enrichment/page-identity/templates-listing/skill-metadata parsers, CLI parser, CodeMirror decoration scoping and outline navigation) either rewired through the core functions or sharing the line-scoped form of the same contract.
diff --git a/packages/app/src/editor/SourceEditor.dom.test.tsx b/packages/app/src/editor/SourceEditor.dom.test.tsx
index f29c7a56d..f6194d0bd 100644
--- a/packages/app/src/editor/SourceEditor.dom.test.tsx
+++ b/packages/app/src/editor/SourceEditor.dom.test.tsx
@@ -7,6 +7,7 @@ import { act, cleanup, render, waitFor } from '@testing-library/react';
import { Awareness } from 'y-protocols/awareness';
import * as Y from 'yjs';
import { OpenInAgentMenuRequestProvider } from '@/components/handoff/OpenInAgentMenuRequestContext';
+import { OUTLINE_NAV_EVENT, type OutlineNavDetail } from '@/components/OutlinePanel';
import { ConfigContext, type ConfigContextValue } from '@/lib/config-context';
import { evictCmEditor } from './editor-cache';
import { SourceEditor } from './SourceEditor';
@@ -41,10 +42,13 @@ function makeConfigValue(wordWrap: boolean): ConfigContextValue {
};
}
-function makeProvider(docName: string): { provider: HocuspocusProvider; ytext: Y.Text } {
+function makeProvider(
+ docName: string,
+ content = '# heading\n\nbody',
+): { provider: HocuspocusProvider; ytext: Y.Text } {
const document = new Y.Doc();
const ytext = document.getText('source');
- ytext.insert(0, '# heading\n\nbody');
+ ytext.insert(0, content);
const awareness = new Awareness(document);
const provider = {
document,
@@ -239,3 +243,107 @@ describe('SourceEditor word-wrap preference wiring', () => {
expect(openRequests).toEqual([]);
});
});
+
+describe('SourceEditor outline navigation', () => {
+ beforeEach(() => {
+ globalThis.fetch = mock(async (input: RequestInfo | URL) => {
+ const url = String(input);
+ if (url === '/api/pages') return Response.json({ pages: [] });
+ if (url === '/api/documents') return Response.json({ documents: [] });
+ if (url === '/api/tags') return Response.json({ tags: [] });
+ return Response.json({}, { status: 404 });
+ }) as unknown as typeof fetch;
+ });
+
+ afterEach(() => {
+ cleanup();
+ for (const docName of mountedDocNames) {
+ evictCmEditor(docName);
+ }
+ mountedDocNames.clear();
+ globalThis.fetch = originalFetch;
+ });
+
+ async function dispatchOutlineNav(index: number, slug: string): Promise<void> {
+ const detail: OutlineNavDetail = { index, slug, mode: 'source' };
+ await act(async () => {
+ window.dispatchEvent(new CustomEvent(OUTLINE_NAV_EVENT, { detail }));
+ });
+ }
+
+ test('skips a frontmatter region whose opening fence carries a trailing space', async () => {
+ const content = [
+ '--- ',
+ 'title: Fence hazard',
+ '# yaml comment, not a heading',
+ '---',
+ '',
+ '# Real Heading',
+ '',
+ 'body',
+ ].join('\n');
+ const { provider, ytext } = makeProvider('source-outline-nav-fm-ws', content);
+ const { container } = render(<Harness provider={provider} ytext={ytext} wordWrap={true} />);
+
+ const cmContent = await findCmContent(container);
+ const view = EditorView.findFromDOM(cmContent);
+ expect(view).toBeTruthy();
+ if (!view) return;
+
+ await dispatchOutlineNav(0, 'real-heading');
+
+ const headingLine = view.state.doc.line(6);
+ expect(headingLine.text).toBe('# Real Heading');
+ expect(view.state.selection.main.head).toBe(headingLine.from);
+ });
+
+ test('skips a frontmatter region whose closing fence carries a trailing tab', async () => {
+ const content = [
+ '---',
+ 'title: Fence hazard',
+ '# yaml comment, not a heading',
+ '---\t',
+ '',
+ '# Real Heading',
+ ].join('\n');
+ const { provider, ytext } = makeProvider('source-outline-nav-fm-close-ws', content);
+ const { container } = render(<Harness provider={provider} ytext={ytext} wordWrap={true} />);
+
+ const cmContent = await findCmContent(container);
+ const view = EditorView.findFromDOM(cmContent);
+ expect(view).toBeTruthy();
+ if (!view) return;
+
+ await dispatchOutlineNav(0, 'real-heading');
+
+ const headingLine = view.state.doc.line(6);
+ expect(headingLine.text).toBe('# Real Heading');
+ expect(view.state.selection.main.head).toBe(headingLine.from);
+ });
+
+ test('bare fences: jumps to the Nth heading after the FM region (regression control)', async () => {
+ const content = [
+ '---',
+ 'title: Fence hazard',
+ '# yaml comment, not a heading',
+ '---',
+ '',
+ '# First',
+ '',
+ '## Second',
+ ].join('\n');
+ const { provider, ytext } = makeProvider('source-outline-nav-fm-bare', content);
+ const { container } = render(<Harness provider={provider} ytext={ytext} wordWrap={true} />);
+
+ const cmContent = await findCmContent(container);
+ const view = EditorView.findFromDOM(cmContent);
+ expect(view).toBeTruthy();
+ if (!view) return;
+
+ await dispatchOutlineNav(1, 'second');
+
+ const headingLine = view.state.doc.line(8);
+ expect(headingLine.text).toBe('## Second');
+ expect(view.state.selection.main.head).toBe(headingLine.from);
+ });
+});
diff --git a/packages/app/src/editor/SourceEditor.tsx b/packages/app/src/editor/SourceEditor.tsx
index fe7bdad88..0801301bf 100644
--- a/packages/app/src/editor/SourceEditor.tsx
+++ b/packages/app/src/editor/SourceEditor.tsx
@@ -33,6 +33,7 @@ import {
consumePendingSourceNavigation,
} from './source-editor-navigation';
import { createSourcePolishExtension } from './source-polish';
+import { FM_FENCE_LINE_RE } from './source-polish/view-plugin';
import { attachTypingBurstDetector } from './typing-burst-detector';
const TOOLBAR_OVERLAP_PX = 56;
@@ -48,9 +49,9 @@ interface SourceEditorProps {
function applyOutlineNavigation(view: EditorView, detail: OutlineNavDetail): void {
const doc = view.state.doc;
let startLine = 1;
- if (doc.lines >= 1 && doc.line(1).text === '---') {
+ if (doc.lines >= 1 && FM_FENCE_LINE_RE.test(doc.line(1).text)) {
for (let i = 2; i <= doc.lines; i++) {
- if (doc.line(i).text === '---') {
+ if (FM_FENCE_LINE_RE.test(doc.line(i).text)) {
startLine = i + 1;
break;
}
diff --git a/packages/app/src/editor/source-polish/view-plugin.test.ts b/packages/app/src/editor/source-polish/view-plugin.test.ts
index 964ee4b7c..4e4a019d7 100644
--- a/packages/app/src/editor/source-polish/view-plugin.test.ts
+++ b/packages/app/src/editor/source-polish/view-plugin.test.ts
@@ -221,6 +221,29 @@ describe('source-polish view-plugin — buildDecorationsForRanges', () => {
expect(classesAtLine(decos, bodyListStart).join(' ')).toContain('cm-list-item');
});
+ test('FM region with a trailing space on the opening fence still skips decorations', () => {
+ const doc = '--- \ntags:\n - characters\n - air-nomads\n---\n# Body\n';
+ const decos = collect(doc);
+ const lineOne = doc.indexOf(' - characters');
+ const lineTwo = doc.indexOf(' - air-nomads');
+ expect(classesAtLine(decos, lineOne).join(' ')).not.toContain('cm-list-item');
+ expect(classesAtLine(decos, lineTwo).join(' ')).not.toContain('cm-list-item');
+ });
+
+ test('FM region with a trailing space on the closing fence still skips decorations', () => {
+ const doc = '---\ntags:\n - characters\n--- \n# Body\n';
+ const decos = collect(doc);
+ const yamlListLine = doc.indexOf(' - characters');
+ expect(classesAtLine(decos, yamlListLine).join(' ')).not.toContain('cm-list-item');
+ });
+
+ test('a leading space before the opening fence means no FM region — list styling applies', () => {
+ const doc = ' ---\ntags:\n - characters\n---\n# Body\n';
+ const decos = collect(doc);
+ const listLine = doc.indexOf(' - characters');
+ expect(classesAtLine(decos, listLine).join(' ')).toContain('cm-list-item');
+ });
+
test('doc with no FM block: list items render with .cm-list-item as before', () => {
const doc = '- alpha\n- beta\n';
const decos = collect(doc);
diff --git a/packages/app/src/editor/source-polish/view-plugin.ts b/packages/app/src/editor/source-polish/view-plugin.ts
index 445e2a421..cccdab7e9 100644
--- a/packages/app/src/editor/source-polish/view-plugin.ts
+++ b/packages/app/src/editor/source-polish/view-plugin.ts
@@ -31,13 +31,17 @@ function countLeadingIndent(text: string): number {
return indent;
}
+import { FM_FENCE_LINE_RE } from '@inkeep/open-knowledge-core';
+
+export { FM_FENCE_LINE_RE };
+
function frontmatterRange(state: EditorState): { from: number; to: number } | null {
if (state.doc.lines < 2) return null;
const firstLine = state.doc.line(1);
- if (firstLine.text !== '---') return null;
+ if (!FM_FENCE_LINE_RE.test(firstLine.text)) return null;
for (let i = 2; i <= state.doc.lines; i++) {
const line = state.doc.line(i);
- if (line.text === '---') {
+ if (FM_FENCE_LINE_RE.test(line.text)) {
return { from: firstLine.from, to: line.to };
}
}
diff --git a/packages/cli/src/utils/frontmatter.test.ts b/packages/cli/src/utils/frontmatter.test.ts
index 363d51ddf..7222d1478 100644
--- a/packages/cli/src/utils/frontmatter.test.ts
+++ b/packages/cli/src/utils/frontmatter.test.ts
@@ -71,6 +71,20 @@ describe('parseFrontmatter', () => {
expect(parseFrontmatter(content, StrictSchema)).toBeNull();
});
+ test('parses frontmatter whose opening fence carries a trailing space', () => {
+ const content = '--- \ntitle: Hello\ndescription: World\n---\n\nBody text.';
+ expect(parseFrontmatter(content)).toEqual({ title: 'Hello', description: 'World' });
+ });
+
+ test('parses frontmatter whose closing fence carries a trailing tab', () => {
+ const content = '---\ntitle: Hello\n---\t\n\nBody text.';
+ expect(parseFrontmatter(content)).toEqual({ title: 'Hello' });
+ });
+
+ test('rejects leading whitespace before the opening fence', () => {
+ expect(parseFrontmatter(' ---\ntitle: Not FM\n---\n\nBody.')).toBeNull();
+ });
+
test('Zod schema applies defaults for missing fields', () => {
const WithDefaults = z.object({
title: z.string(),
diff --git a/packages/cli/src/utils/frontmatter.ts b/packages/cli/src/utils/frontmatter.ts
index 3430cbbfa..34bf89e10 100644
--- a/packages/cli/src/utils/frontmatter.ts
+++ b/packages/cli/src/utils/frontmatter.ts
@@ -1,19 +1,18 @@
+import { stripFrontmatter, unwrapFrontmatterFences } from '@inkeep/open-knowledge-core';
import { parse as parseYaml, stringify as stringifyYaml } from 'yaml';
import type { output, ZodType } from 'zod';
import { isObject } from './is-object.ts';
type Resolve<T> = { [K in keyof T]: T[K] } & {};
-const FRONTMATTER_RE = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/;
-
export function parseFrontmatter<S extends ZodType = ZodType<Record<string, unknown>>>(
content: string,
schema?: S,
): Resolve<output<S>> | null {
- const match = content.match(FRONTMATTER_RE);
- if (!match) return null;
+ const { frontmatter } = stripFrontmatter(content);
+ if (frontmatter === '') return null;
try {
- const parsed = parseYaml(match[1]);
+ const parsed = parseYaml(unwrapFrontmatterFences(frontmatter));
if (isObject(parsed)) {
if (schema) {
const result = schema.safeParse(parsed);
diff --git a/packages/core/src/bridge/bind-frontmatter-doc.test.ts b/packages/core/src/bridge/bind-frontmatter-doc.test.ts
index cf84cab12..65a220e4d 100644
--- a/packages/core/src/bridge/bind-frontmatter-doc.test.ts
+++ b/packages/core/src/bridge/bind-frontmatter-doc.test.ts
@@ -1350,3 +1350,32 @@ describe('bindFrontmatterDoc — multi-client convergence', () => {
bindingB.dispose();
});
});
+
+describe('bindFrontmatterDoc — fence trailing whitespace (fm-delimiter hazard)', () => {
+ test('current() recognizes an FM region whose fences carry trailing whitespace', () => {
+ const provider = makeProvider('--- \ntitle: Hazard\n--- \n\nBody\n');
+ const binding = bindFrontmatterDoc(provider);
+
+ const snapshot = binding.current();
+
+ expect(snapshot.parseError).toBeUndefined();
+ expect(snapshot.map).toEqual({ title: 'Hazard' });
+ expect(snapshot.keys).toEqual(['title']);
+ binding.dispose();
+ });
+
+ test('an edit at byte >= 5 that completes a trailing-whitespace fence re-parses and notifies', () => {
+ const seed = '--- \ntitle: Hazard\n';
+ const provider = makeProvider(seed);
+ const binding = bindFrontmatterDoc(provider);
+ const snapshots: FrontmatterSnapshot[] = [];
+ binding.subscribe((s) => snapshots.push(s));
+
+ provider.document.getText('source').insert(seed.length, '---\n');
+
+ expect(snapshots.length).toBeGreaterThan(0);
+ expect(snapshots.at(-1)?.map).toEqual({ title: 'Hazard' });
+ expect(binding.current().map).toEqual({ title: 'Hazard' });
+ binding.dispose();
+ });
+});
diff --git a/packages/core/src/bridge/bind-frontmatter-doc.ts b/packages/core/src/bridge/bind-frontmatter-doc.ts
index ac20bc4a1..c014b1413 100644
--- a/packages/core/src/bridge/bind-frontmatter-doc.ts
+++ b/packages/core/src/bridge/bind-frontmatter-doc.ts
@@ -231,7 +231,7 @@ function snapshotFromRaw(raw: string): FrontmatterSnapshot {
}
function detectOpenFencePrefix(raw: string): boolean {
- return /^---\r?\n/.test(raw);
+ return raw.startsWith('---');
}
export function bindFrontmatterDoc(provider: FrontmatterDocProvider): FrontmatterBinding {
diff --git a/packages/core/src/bridge/fm-partition-invariance.test.ts b/packages/core/src/bridge/fm-partition-invariance.test.ts
new file mode 100644
index 000000000..258946b29
--- /dev/null
+++ b/packages/core/src/bridge/fm-partition-invariance.test.ts
@@ -0,0 +1,54 @@
+import { describe, expect, test } from 'bun:test';
+import { FM_FENCE_LINE_RE, FRONTMATTER_RE, stripFrontmatter } from '../extensions/frontmatter.ts';
+import { normalizeBridge } from './normalize.ts';
+
+const CLEAN = '---\ntitle: x\n---\n\nbody\n';
+
+const FENCE_WHITESPACE_VARIANTS: Array<[string, string]> = [
+ ['trailing space on the opening fence', '--- \ntitle: x\n---\n\nbody\n'],
+ ['trailing space on the closing fence', '---\ntitle: x\n--- \n\nbody\n'],
+ ['trailing tab on the opening fence', '---\t\ntitle: x\n---\n\nbody\n'],
+ ['trailing tab on the closing fence', '---\ntitle: x\n---\t\n\nbody\n'],
+];
+
+describe('FM partition invariance under bridge tolerance', () => {
+ test('precondition: the clean fixture has a recognized FM region', () => {
+ expect(stripFrontmatter(CLEAN).frontmatter).toBe('---\ntitle: x\n---\n');
+ });
+
+ for (const [name, mutated] of FENCE_WHITESPACE_VARIANTS) {
+ test(`${name}: an in-tolerance edit must not break FM recognition`, () => {
+ const inTolerance = normalizeBridge(mutated) === normalizeBridge(CLEAN);
+ const recognized = stripFrontmatter(mutated).frontmatter !== '';
+
+ expect({ inTolerance, recognized }).not.toEqual({
+ inTolerance: true,
+ recognized: false,
+ });
+ });
+ }
+
+ test('control: leading space before the opening fence is beyond tolerance', () => {
+ const leading = ' ---\ntitle: x\n---\n\nbody\n';
+ expect(normalizeBridge(leading)).not.toBe(normalizeBridge(CLEAN));
+ });
+});
+
+describe('FM fence-line predicate agreement (FM_FENCE_LINE_RE vs FRONTMATTER_RE)', () => {
+ const FENCE_LINES = ['---', '--- ', '---\t', '--- \t '];
+ const NON_FENCE_LINES = [' ---', '----', '--- x', '---x', '-- -', ''];
+
+ for (const line of FENCE_LINES) {
+ test(`fence line ${JSON.stringify(line)}: both predicates recognize`, () => {
+ expect(FM_FENCE_LINE_RE.test(line)).toBe(true);
+ expect(FRONTMATTER_RE.test(`${line}\ntitle: x\n---\n`)).toBe(true);
+ });
+ }
+
+ for (const line of NON_FENCE_LINES) {
+ test(`non-fence line ${JSON.stringify(line)}: both predicates reject`, () => {
+ expect(FM_FENCE_LINE_RE.test(line)).toBe(false);
+ expect(FRONTMATTER_RE.test(`${line}\ntitle: x\n---\n`)).toBe(false);
+ });
+ }
+});
diff --git a/packages/core/src/extensions/frontmatter.test.ts b/packages/core/src/extensions/frontmatter.test.ts
index 4b89e4945..820c7b41d 100644
--- a/packages/core/src/extensions/frontmatter.test.ts
+++ b/packages/core/src/extensions/frontmatter.test.ts
@@ -119,6 +119,66 @@ describe('unwrapFrontmatterFences', () => {
});
});
+describe('fence trailing whitespace — recognition contract', () => {
+ const recognized: Array<{ label: string; input: string; fm: string }> = [
+ {
+ label: 'space after the opening fence',
+ input: '--- \ntitle: X\n---\n# Body',
+ fm: '--- \ntitle: X\n---\n',
+ },
+ {
+ label: 'tab after the opening fence',
+ input: '---\t\ntitle: X\n---\n# Body',
+ fm: '---\t\ntitle: X\n---\n',
+ },
+ {
+ label: 'space after the closing fence',
+ input: '---\ntitle: X\n--- \n# Body',
+ fm: '---\ntitle: X\n--- \n',
+ },
+ {
+ label: 'tab after the closing fence',
+ input: '---\ntitle: X\n---\t\n# Body',
+ fm: '---\ntitle: X\n---\t\n',
+ },
+ ];
+
+ for (const { label, input, fm } of recognized) {
+ test(`stripFrontmatter recognizes ${label} and preserves the raw bytes`, () => {
+ const { frontmatter, body } = stripFrontmatter(input);
+ expect(frontmatter).toBe(fm);
+ expect(body).toBe('# Body');
+ });
+ }
+
+ test('leading whitespace before the opening fence stays unrecognized', () => {
+ const input = ' ---\ntitle: X\n---\n# Body';
+ const { frontmatter, body } = stripFrontmatter(input);
+ expect(frontmatter).toBe('');
+ expect(body).toBe(input);
+ });
+
+ test('unwrapFrontmatterFences unwraps fences carrying trailing whitespace', () => {
+ expect(unwrapFrontmatterFences('--- \ntitle: X\n---\n')).toBe('title: X');
+ expect(unwrapFrontmatterFences('---\ntitle: X\n--- \n')).toBe('title: X');
+ expect(unwrapFrontmatterFences('---\t\ntitle: X\n---\t')).toBe('title: X');
+ });
+
+ test('strip then prepend stays identity with trailing-whitespace fences', () => {
+ const original = '--- \ntitle: Keep\n--- \n# Content\n';
+ const { frontmatter, body } = stripFrontmatter(original);
+ expect(prependFrontmatter(frontmatter, body)).toBe(original);
+ expect(frontmatter).not.toBe('');
+ });
+
+ test('closing-fence detection stops at the first ---[ \\t]* line inside the region', () => {
+ const input = '---\ntitle: X\n--- \nrest: y\n---\n# Body';
+ const { frontmatter, body } = stripFrontmatter(input);
+ expect(frontmatter).toBe('---\ntitle: X\n--- \n');
+ expect(body).toBe('rest: y\n---\n# Body');
+ });
+});
+
describe('round-trip', () => {
test('strip then prepend is identity', () => {
const original = '---\ntitle: Test\ndate: 2026-01-01\n---\n# Content\n\nParagraph here.\n';
diff --git a/packages/core/src/extensions/frontmatter.ts b/packages/core/src/extensions/frontmatter.ts
index c8fb30cd2..c0d4f67dc 100644
--- a/packages/core/src/extensions/frontmatter.ts
+++ b/packages/core/src/extensions/frontmatter.ts
@@ -1,4 +1,6 @@
-export const FRONTMATTER_RE = /^---\r?\n([\s\S]*?\r?\n)?---(\r?\n|$)/;
+export const FRONTMATTER_RE = /^---[ \t]*\r?\n([\s\S]*?\r?\n)?---[ \t]*(\r?\n|$)/;
+
+export const FM_FENCE_LINE_RE = /^---[ \t]*$/;
export function stripFrontmatter(markdown: string): { frontmatter: string; body: string } {
const match = markdown.match(FRONTMATTER_RE);
diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts
index c55155a7b..c4a6eead9 100644
--- a/packages/core/src/index.ts
+++ b/packages/core/src/index.ts
@@ -256,6 +256,7 @@ export {
nextFootnoteIdentifier,
} from './extensions/footnote-reference.ts';
export {
+ FM_FENCE_LINE_RE,
FRONTMATTER_RE,
prependFrontmatter,
stripFrontmatter,
diff --git a/packages/server/src/api-extension.ts b/packages/server/src/api-extension.ts
index ec0dba032..46bb10773 100644
--- a/packages/server/src/api-extension.ts
+++ b/packages/server/src/api-extension.ts
@@ -170,6 +170,7 @@ import {
TrashCleanupSuccessSchema,
UploadAssetSuccessSchema,
UploadRequestSchema,
+ unwrapFrontmatterFences,
type WorkspaceSearchCorpus,
type WorkspaceSearchDocument,
type WorkspaceSearchIntent,
@@ -1591,13 +1592,7 @@ interface WorkspaceSearchCacheEntry {
const workspaceSearchCaches = new Map<string, WorkspaceSearchCacheEntry>();
export function extractHeadings(content: string): HeadingEntry[] {
- let body = content;
- if (content.startsWith('---\n') || content.startsWith('---\r\n')) {
- const closingIdx = content.indexOf('\n---', 3);
- if (closingIdx !== -1) {
- body = content.slice(closingIdx + 4);
- }
- }
+ const { body } = stripFrontmatter(content);
const headings: HeadingEntry[] = [];
const slugCounts = new Map<string, number>();
@@ -9414,21 +9409,18 @@ export function createApiExtension(options: ApiExtensionOptions): Extension {
});
}
- const FRONTMATTER_RE = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/;
const parseTemplateFile = (
raw: string,
): { frontmatter: Record<string, unknown>; body: string } => {
- const match = raw.match(FRONTMATTER_RE);
+ const { frontmatter: fenced, body } = stripFrontmatter(raw);
let frontmatter: Record<string, unknown> = {};
- let body = raw;
- if (match) {
+ if (fenced !== '') {
try {
- const parsed = parseYaml(match[1] ?? '');
+ const parsed = parseYaml(unwrapFrontmatterFences(fenced));
if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
frontmatter = parsed as Record<string, unknown>;
}
} catch {}
- body = raw.slice(match[0].length);
}
return { frontmatter, body };
};
diff --git a/packages/server/src/api-pages.test.ts b/packages/server/src/api-pages.test.ts
index 71a27a3d4..f7beb4944 100644
--- a/packages/server/src/api-pages.test.ts
+++ b/packages/server/src/api-pages.test.ts
@@ -133,6 +133,51 @@ describe('extractHeadings', () => {
const content = ['# Real', '```js', '# inside', '## still inside'].join('\n');
expect(extractHeadings(content)).toEqual([{ level: 1, text: 'Real', slug: 'real' }]);
});
+
+ test('strips frontmatter whose opening fence carries a trailing space', () => {
+ const content = [
+ '--- ',
+ 'title: Fence hazard',
+ '# yaml comment, not a heading',
+ '---',
+ '',
+ '# Real Heading',
+ ].join('\n');
+
+ expect(extractHeadings(content)).toEqual([
+ { level: 1, text: 'Real Heading', slug: 'real-heading' },
+ ]);
+ });
+
+ test('strips frontmatter whose opening fence carries a trailing tab', () => {
+ const content = [
+ '---\t',
+ 'title: Fence hazard',
+ '# yaml comment, not a heading',
+ '---',
+ '',
+ '# Real Heading',
+ ].join('\n');
+
+ expect(extractHeadings(content)).toEqual([
+ { level: 1, text: 'Real Heading', slug: 'real-heading' },
+ ]);
+ });
+
+ test('strips frontmatter whose closing fence carries trailing whitespace', () => {
+ const content = [
+ '---',
+ 'title: Fence hazard',
+ '# yaml comment, not a heading',
+ '--- ',
+ '',
+ '# Real Heading',
+ ].join('\n');
+
+ expect(extractHeadings(content)).toEqual([
+ { level: 1, text: 'Real Heading', slug: 'real-heading' },
+ ]);
+ });
});
function makeReq(method: string): IncomingMessage {
diff --git a/packages/server/src/api-template-get.test.ts b/packages/server/src/api-template-get.test.ts
new file mode 100644
index 000000000..abf21ed4e
--- /dev/null
+++ b/packages/server/src/api-template-get.test.ts
@@ -0,0 +1,123 @@
+import { describe, expect, test } from 'bun:test';
+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 { createApiExtension } from './api-extension.ts';
+
+function makeReq(url: string): IncomingMessage {
+ const readable = Readable.from(Buffer.from('')) as unknown as IncomingMessage;
+ readable.method = 'GET';
+ readable.url = url;
+ readable.headers = { host: 'localhost' };
+ return readable;
+}
+
+interface CapturedResponse {
+ status: number;
+ body: string;
+}
+
+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 };
+}
+
+async function getTemplate(contentDir: string, name: string): Promise<CapturedResponse> {
+ const ext = createApiExtension({
+ hocuspocus: {} as unknown as Parameters<typeof createApiExtension>[0]['hocuspocus'],
+ sessionManager: {} as unknown as Parameters<typeof createApiExtension>[0]['sessionManager'],
+ contentDir,
+ serverInstanceId: 'test-instance',
+ getFileIndex: () => new Map(),
+ });
+ const req = makeReq(`/api/template?name=${name}`);
+ const { res, captured } = makeRes();
+ await (
+ ext as {
+ onRequest: (ctx: { request: IncomingMessage; response: ServerResponse }) => Promise<void>;
+ }
+ ).onRequest({ request: req, response: res });
+ return captured;
+}
+
+interface TemplateGetBody {
+ template?: { frontmatter?: Record<string, unknown>; body?: string };
+}
+
+describe('GET /api/template — fence trailing whitespace (fm-delimiter hazard)', () => {
+ test('parses template frontmatter whose opening fence carries a trailing space', async () => {
+ const dir = mkdtempSync(join(tmpdir(), 'ok-template-get-'));
+ try {
+ mkdirSync(join(dir, '.ok/templates'), { recursive: true });
+ writeFileSync(
+ join(dir, '.ok/templates/trip-log.md'),
+ '--- \ntitle: Trip Log\ndescription: Catch log\n---\n\n# {{date}}\n',
+ 'utf-8',
+ );
+
+ const result = await getTemplate(dir, 'trip-log');
+
+ expect(result.status).toBe(200);
+ const body = JSON.parse(result.body) as TemplateGetBody;
+ expect(body.template?.frontmatter).toEqual({
+ title: 'Trip Log',
+ description: 'Catch log',
+ });
+ expect(body.template?.body).not.toContain('title: Trip Log');
+ } finally {
+ rmSync(dir, { recursive: true, force: true });
+ }
+ });
+
+ test('parses template frontmatter whose closing fence carries a trailing tab', async () => {
+ const dir = mkdtempSync(join(tmpdir(), 'ok-template-get-'));
+ try {
+ mkdirSync(join(dir, '.ok/templates'), { recursive: true });
+ writeFileSync(
+ join(dir, '.ok/templates/standup.md'),
+ '---\ntitle: Standup\n---\t\n\n# Notes\n',
+ 'utf-8',
+ );
+
+ const result = await getTemplate(dir, 'standup');
+
+ expect(result.status).toBe(200);
+ const body = JSON.parse(result.body) as TemplateGetBody;
+ expect(body.template?.frontmatter).toEqual({ title: 'Standup' });
+ expect(body.template?.body).not.toContain('title: Standup');
+ } finally {
+ rmSync(dir, { recursive: true, force: true });
+ }
+ });
+
+ test('a leading space before the opening fence still means no frontmatter', async () => {
+ const dir = mkdtempSync(join(tmpdir(), 'ok-template-get-'));
+ try {
+ mkdirSync(join(dir, '.ok/templates'), { recursive: true });
+ writeFileSync(
+ join(dir, '.ok/templates/indented.md'),
+ ' ---\ntitle: Not FM\n---\n\n# Notes\n',
+ 'utf-8',
+ );
+
+ const result = await getTemplate(dir, 'indented');
+
+ expect(result.status).toBe(200);
+ const body = JSON.parse(result.body) as TemplateGetBody;
+ expect(body.template?.frontmatter).toEqual({});
+ expect(body.template?.body).toContain('title: Not FM');
+ } finally {
+ rmSync(dir, { recursive: true, force: true });
+ }
+ });
+});
diff --git a/packages/server/src/build-skill-zip.test.ts b/packages/server/src/build-skill-zip.test.ts
index 9b1e19cad..329dc1f2f 100644
--- a/packages/server/src/build-skill-zip.test.ts
+++ b/packages/server/src/build-skill-zip.test.ts
@@ -4,7 +4,7 @@ import { tmpdir } from 'node:os';
import { dirname, join, posix, win32 } from 'node:path';
import { __testing, resolveBundledSkillDir } from './build-skill-zip.ts';
-const { computeWrapperFolderName, toPosixZipPath } = __testing;
+const { computeWrapperFolderName, extractMetadataVersion, toPosixZipPath } = __testing;
/** Build the `Contents/Resources/cli/dist/assets/skills/<which>` subpath that
* a co-installed OK Desktop ships, rooted at an arbitrary `appsRoot`. */
@@ -22,6 +22,24 @@ function desktopSkillDir(appsRoot: string, which: 'discovery' | 'project'): stri
);
}
+describe('extractMetadataVersion', () => {
+ const FM_BODY = 'name: open-knowledge\nmetadata:\n version: "1.2.3"\n';
+
+ test('reads metadata.version from a bare-fence SKILL.md', () => {
+ expect(extractMetadataVersion(`---\n${FM_BODY}---\n\n# Skill\n`)).toBe('1.2.3');
+ });
+
+ test('tolerates trailing whitespace on the fence lines (core fence contract)', () => {
+ expect(extractMetadataVersion(`--- \n${FM_BODY}--- \n\n# Skill\n`)).toBe('1.2.3');
+ expect(extractMetadataVersion(`---\t\n${FM_BODY}---\n\n# Skill\n`)).toBe('1.2.3');
+ });
+
+ test('returns undefined when frontmatter or metadata.version is absent', () => {
+ expect(extractMetadataVersion('# No frontmatter\n')).toBeUndefined();
+ expect(extractMetadataVersion('---\nname: open-knowledge\n---\n')).toBeUndefined();
+ });
+});
+
describe('computeWrapperFolderName', () => {
test('POSIX: returns last segment', () => {
expect(computeWrapperFolderName('/usr/local/lib/skills/open-knowledge', posix.basename)).toBe(
diff --git a/packages/server/src/build-skill-zip.ts b/packages/server/src/build-skill-zip.ts
index 9a0679fdf..94ba4da5d 100644
--- a/packages/server/src/build-skill-zip.ts
+++ b/packages/server/src/build-skill-zip.ts
@@ -4,6 +4,7 @@ import { readdir, readFile } from 'node:fs/promises';
import { homedir } from 'node:os';
import { basename, join, relative, sep } from 'node:path';
import { fileURLToPath } from 'node:url';
+import { stripFrontmatter, unwrapFrontmatterFences } from '@inkeep/open-knowledge-core';
import yazl from 'yazl';
/** Maximum uncompressed + compressed size. Catches accidental binary bloat.
@@ -132,9 +133,9 @@ async function sha256OfFile(path: string): Promise<string> {
}
function extractMetadataVersion(markdown: string): string | undefined {
- const frontmatterEnd = markdown.indexOf('\n---', 4);
- if (!markdown.startsWith('---\n') || frontmatterEnd < 0) return undefined;
- const frontmatter = markdown.slice(4, frontmatterEnd);
+ const { frontmatter: fenced } = stripFrontmatter(markdown);
+ if (fenced === '') return undefined;
+ const frontmatter = unwrapFrontmatterFences(fenced);
const metaStart = frontmatter.search(/^metadata:/m);
if (metaStart < 0) return undefined;
diff --git a/packages/server/src/content/enrichment.test.ts b/packages/server/src/content/enrichment.test.ts
index 26a82308a..2cdd00c05 100644
--- a/packages/server/src/content/enrichment.test.ts
+++ b/packages/server/src/content/enrichment.test.ts
@@ -64,6 +64,25 @@ describe('enrichPath — slim (multi-path) shape', () => {
expect(meta.tags).toEqual([]);
});
+ test('frontmatter under trailing-whitespace fences still enriches title/description/tags', async () => {
+ const project = await bootstrapProject();
+ const contentDir = resolve(project, 'content');
+ mkdirSync(contentDir, { recursive: true });
+ writeFileSync(
+ resolve(contentDir, 'open-space.md'),
+ '--- \ntitle: Auth\ndescription: OAuth\ntags:\n - auth\n---\n\nBody\n',
+ );
+ writeFileSync(resolve(contentDir, 'close-tab.md'), '---\ntitle: Sessions\n---\t\n\nBody\n');
+
+ const openSpace = await enrichPath('content/open-space.md', { projectDir: project });
+ expect(openSpace.title).toBe('Auth');
+ expect(openSpace.description).toBe('OAuth');
+ expect(openSpace.tags).toEqual(['auth']);
+
+ const closeTab = await enrichPath('content/close-tab.md', { projectDir: project });
+ expect(closeTab.title).toBe('Sessions');
+ });
+
test('missing file still returns a slim shape with tags=[]', async () => {
const project = await bootstrapProject();
const meta = await enrichPath('does-not-exist.md', { projectDir: project });
diff --git a/packages/server/src/content/enrichment.ts b/packages/server/src/content/enrichment.ts
index b5aea882d..4b2781160 100644
--- a/packages/server/src/content/enrichment.ts
+++ b/packages/server/src/content/enrichment.ts
@@ -1,7 +1,7 @@
import type { Dirent } from 'node:fs';
import { readdir, readFile, stat } from 'node:fs/promises';
import { basename, relative, resolve } from 'node:path';
-import { OK_DIR } from '@inkeep/open-knowledge-core';
+import { OK_DIR, stripFrontmatter, unwrapFrontmatterFences } from '@inkeep/open-knowledge-core';
import { parse as parseYaml } from 'yaml';
import { resolveWithinRoot } from '../mcp/tools/path-safety.ts';
import { httpGet } from '../mcp/tools/shared.ts';
@@ -10,12 +10,11 @@ import { type GitCommit, type ProjectHistorySource, readProjectGitLog } from './
import { type HistorySource, readShadowLog, type ShadowCommit } from './shadow-log.ts';
import { resolveTemplatesAvailable, type TemplateEntry } from './templates-resolver.ts';
-const FRONTMATTER_RE = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/;
function parseFrontmatterRaw(content: string): Record<string, unknown> | null {
- const match = content.match(FRONTMATTER_RE);
- if (!match) return null;
+ const { frontmatter } = stripFrontmatter(content);
+ if (frontmatter === '') return null;
try {
- const parsed = parseYaml(match[1]);
+ const parsed = parseYaml(unwrapFrontmatterFences(frontmatter));
if (parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed)) {
return parsed as Record<string, unknown>;
}
diff --git a/packages/server/src/content/templates-resolver.test.ts b/packages/server/src/content/templates-resolver.test.ts
index afaec133f..ba7cf6646 100644
--- a/packages/server/src/content/templates-resolver.test.ts
+++ b/packages/server/src/content/templates-resolver.test.ts
@@ -134,6 +134,41 @@ describe('resolveTemplatesAvailable', () => {
expect(tpls[0]?.scope).toBe('local');
});
+ test('frontmatter whose opening fence carries a trailing space still surfaces metadata', () => {
+ writeTemplate(
+ 'meetings',
+ 'prep-notes',
+ '--- \ntitle: Meeting Prep\ndescription: Use before a meeting.\n---\nbody\n',
+ );
+
+ const tpls = resolveTemplatesAvailable(projectDir, 'meetings');
+ expect(tpls).toHaveLength(1);
+ expect(tpls[0]?.title).toBe('Meeting Prep');
+ expect(tpls[0]?.description).toBe('Use before a meeting.');
+ });
+
+ test('frontmatter whose closing fence carries a trailing tab still surfaces metadata', () => {
+ writeTemplate(
+ 'meetings',
+ 'prep-notes',
+ '---\ntitle: Meeting Prep\ndescription: Use before a meeting.\n---\t\nbody\n',
+ );
+
+ const tpls = resolveTemplatesAvailable(projectDir, 'meetings');
+ expect(tpls).toHaveLength(1);
+ expect(tpls[0]?.title).toBe('Meeting Prep');
+ expect(tpls[0]?.description).toBe('Use before a meeting.');
+ });
+
+ test('an indented opening fence is not frontmatter (matches core recognition)', () => {
+ writeTemplate('meetings', 'prep-notes', ' ---\ntitle: Nope\n---\nbody\n');
+
+ const tpls = resolveTemplatesAvailable(projectDir, 'meetings');
+ expect(tpls).toHaveLength(1);
+ expect(tpls[0]?.title).toBeUndefined();
+ expect(tpls[0]?.description).toBeUndefined();
+ });
+
test('non-md files in templates/ are ignored', () => {
writeTemplate('meetings', 'good', withFm('Good', 'OK'));
const dir = join(projectDir, 'meetings', '.ok', 'templates');
diff --git a/packages/server/src/content/templates-resolver.ts b/packages/server/src/content/templates-resolver.ts
index e58b52a4f..72b58539b 100644
--- a/packages/server/src/content/templates-resolver.ts
+++ b/packages/server/src/content/templates-resolver.ts
@@ -1,5 +1,6 @@
import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
import { join, posix } from 'node:path';
+import { stripFrontmatter, unwrapFrontmatterFences } from '@inkeep/open-knowledge-core';
import { parse as parseYaml } from 'yaml';
type TemplateScope = 'local' | 'inherited';
@@ -226,6 +227,7 @@ function readTemplateMeta(absPath: string): TemplateMeta {
function extractFrontmatterYaml(content: string): string | null {
const normalized = content.replace(/^/, '');
- const match = /^[ \t]*---\r?\n([\s\S]*?)\r?\n[ \t]*---(\r?\n|$)/.exec(normalized);
- return match ? (match[1] ?? null) : null;
+ const { frontmatter } = stripFrontmatter(normalized);
+ if (frontmatter === '') return null;
+ return unwrapFrontmatterFences(frontmatter);
}
diff --git a/packages/server/src/mcp/tools/edit.ts b/packages/server/src/mcp/tools/edit.ts
index ae06c7220..be37b2b78 100644
--- a/packages/server/src/mcp/tools/edit.ts
+++ b/packages/server/src/mcp/tools/edit.ts
@@ -3,6 +3,7 @@ import {
type FrontmatterPatch,
renderInventoryFooter,
stripFrontmatter,
+ unwrapFrontmatterFences,
} from '@inkeep/open-knowledge-core';
import { parse as parseYaml } from 'yaml';
import { z } from 'zod';
@@ -287,10 +288,7 @@ function templateFilePath(
}
function parseTemplateFrontmatter(raw: string): TemplateFrontmatter {
- const inner = raw
- .replace(/^---\r?\n/, '')
- .replace(/\r?\n?---\r?\n?$/, '')
- .trim();
+ const inner = unwrapFrontmatterFences(raw).trim();
if (inner === '') return { title: '' };
const parsed: unknown = parseYaml(inner);
if (parsed == null || typeof parsed !== 'object' || Array.isArray(parsed)) return { title: '' };
diff --git a/packages/server/src/mcp/tools/verb-tools.test.ts b/packages/server/src/mcp/tools/verb-tools.test.ts
index 1c6988285..59b0d35f4 100644
--- a/packages/server/src/mcp/tools/verb-tools.test.ts
+++ b/packages/server/src/mcp/tools/verb-tools.test.ts
@@ -1,5 +1,13 @@
import { describe, expect, test } from 'bun:test';
-import { existsSync, mkdtempSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import {
+ existsSync,
+ mkdirSync,
+ mkdtempSync,
+ readdirSync,
+ readFileSync,
+ statSync,
+ writeFileSync,
+} from 'node:fs';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { fileURLToPath } from 'node:url';
@@ -141,6 +149,57 @@ describe('write/edit/delete({ template }) — server-routed for attribution (PRD
});
});
+describe('edit({ template }) — fence trailing whitespace (fm-delimiter hazard)', () => {
+ test('a body edit preserves frontmatter stored under trailing-whitespace fences', async () => {
+ const cwd = newProject();
+ mkdirSync(join(cwd, 'fishing-log', '.ok', 'templates'), { recursive: true });
+ writeFileSync(
+ join(cwd, 'fishing-log', '.ok', 'templates', 'trip-log.md'),
+ '--- \ntitle: Trip Log\ndescription: Catch log\n---\n\n# Log\n\nFish: none\n',
+ );
+
+ let putPayload: Record<string, unknown> | undefined;
+ const stub = Bun.serve({
+ port: 0,
+ async fetch(req) {
+ if (req.method === 'PUT' && new URL(req.url).pathname === '/api/template') {
+ putPayload = (await req.json()) as Record<string, unknown>;
+ return Response.json({ path: 'fishing-log/.ok/templates/trip-log.md' });
+ }
+ return Response.json({ error: 'unexpected request' }, { status: 404 });
+ },
+ });
+ try {
+ let handler: Handler | undefined;
+ const server = {
+ registerTool(_name: string, _cfg: unknown, h: Handler) {
+ handler = h;
+ },
+ } as unknown as ServerInstance;
+ registerEdit(server, {
+ serverUrl: `http://127.0.0.1:${stub.port}`,
+ config: BASE_CONFIG,
+ resolveCwd: async () => cwd,
+ } as unknown as Parameters<typeof registerEdit>[1]);
+ if (!handler) throw new Error('tool did not register');
+
+ const r = await handler({
+ template: { path: 'fishing-log/trip-log', find: 'none', replace: 'two bass' },
+ });
+
+ expect(r.isError).toBeUndefined();
+ const fm = putPayload?.frontmatter as Record<string, unknown> | undefined;
+ expect(fm?.title).toBe('Trip Log');
+ expect(fm?.description).toBe('Catch log');
+ const body = putPayload?.body as string | undefined;
+ expect(body).toContain('two bass');
+ expect(body).not.toContain('title: Trip Log');
+ } finally {
+ stub.stop(true);
+ }
+ });
+});
+
describe('D13 migration meta-test — no retired tool name survives in the skill surface', () => {
const RETIRED = [
'write_document',
diff --git a/packages/server/src/page-identity.test.ts b/packages/server/src/page-identity.test.ts
index 9073504a6..1c76a7271 100644
--- a/packages/server/src/page-identity.test.ts
+++ b/packages/server/src/page-identity.test.ts
@@ -53,6 +53,37 @@ describe('extractPageIdentity', () => {
});
});
+describe('extractPageIdentity — fence trailing whitespace (fm-delimiter hazard)', () => {
+ test('title and aliases survive trailing spaces on both fence lines', () => {
+ const content = [
+ '--- ',
+ 'title: Project Alpha',
+ 'aliases:',
+ ' - Alpha Project',
+ '--- ',
+ '',
+ '# Different Heading',
+ '',
+ 'Body.',
+ ].join('\n');
+
+ const identity = extractPageIdentity(content, 'project-alpha');
+ expect(identity.title).toBe('Project Alpha');
+ expect(identity.aliases).toEqual(['Alpha Project']);
+ expect(identity.matchLabels).toEqual(['Project Alpha', 'Alpha Project']);
+ });
+
+ test('extractPageTitle reads the frontmatter title under a trailing-tab closing fence', () => {
+ const content = '---\ntitle: Tab Fence\n---\t\n\nBody.';
+ expect(extractPageTitle(content, 'fallback-name')).toBe('Tab Fence');
+ });
+
+ test('a leading space before the opening fence still disqualifies the block', () => {
+ const content = ' ---\ntitle: Not FM\n---\n\n# Heading\n';
+ expect(extractPageTitle(content, 'fallback-name')).toBe('Heading');
+ });
+});
+
describe('extractPageAliases', () => {
test('supports inline alias arrays and exact deduplication', () => {
const content = ['---', 'aliases: ["Alpha", "Project, A", "Alpha"]', '---', '', 'Body.'].join(
diff --git a/packages/server/src/page-identity.ts b/packages/server/src/page-identity.ts
index c2add6bfd..b57f8f27a 100644
--- a/packages/server/src/page-identity.ts
+++ b/packages/server/src/page-identity.ts
@@ -1,4 +1,8 @@
-import { stripFrontmatter, toWikiLinkSlug } from '@inkeep/open-knowledge-core';
+import {
+ stripFrontmatter,
+ toWikiLinkSlug,
+ unwrapFrontmatterFences,
+} from '@inkeep/open-knowledge-core';
export interface PageIdentity {
docName: string;
@@ -10,8 +14,7 @@ export interface PageIdentity {
function splitFrontmatterLines(frontmatter: string): string[] {
if (!frontmatter) return [];
- const withoutDelimiters = frontmatter.replace(/^---\r?\n/, '').replace(/\r?\n---(?:\r?\n)?$/, '');
- return withoutDelimiters.split(/\r?\n/);
+ return unwrapFrontmatterFences(frontmatter).split(/\r?\n/);
}
function normalizeFrontmatterScalar(value: string): string {
diff --git a/packages/server/src/server-observers.fm-fence-hazard.test.ts b/packages/server/src/server-observers.fm-fence-hazard.test.ts
new file mode 100644
index 000000000..88adc8c1c
--- /dev/null
+++ b/packages/server/src/server-observers.fm-fence-hazard.test.ts
@@ -0,0 +1,235 @@
+/**
+ * FM-fence trailing-whitespace hazard — user-outcome contract.
+ *
+ * A source-mode (W2) keystroke that appends trailing whitespace to a
+ * frontmatter fence line is within normalizeBridge tolerance, so Observer B
+ * early-exits without refreshing witnesses. The partition-invariance
+ * contract (see packages/core/src/bridge/fm-partition-invariance.test.ts)
+ * requires that such an edit must not change FM-region recognition; when it
+ * does, Observer A's next Path B merge composes its user input without the
+ * FM region and destroys it.
+ *
+ * These tests pin the user-visible outcome on the real observer pipeline
+ * (real setupServerObservers + composeAndWriteRawBody on a raw Y.Doc):
+ * after the fence keystroke plus a subsequent WYSIWYG edit,
+ * (a) the FM region's bytes are still present in Y.Text,
+ * (b) the user's keystroke is not reverted (Y.Text-is-truth),
+ * (c) the WYSIWYG edit is applied, and
+ * (d) the FM region is not re-derived into the WYSIWYG body.
+ */
+import { describe, expect, test } from 'bun:test';
+import {
+ MarkdownManager,
+ prependFrontmatter,
+ sharedExtensions,
+ stripFrontmatter,
+} from '@inkeep/open-knowledge-core';
+import { getSchema } from '@tiptap/core';
+import { yXmlFragmentToProseMirrorRootNode } from '@tiptap/y-tiptap';
+import * as Y from 'yjs';
+import { composeAndWriteRawBody } from './bridge-intake.ts';
+import { __resetBridgeWatchdogForTests } from './bridge-watchdog.ts';
+import { FILE_WATCHER_ORIGIN } from './external-change.ts';
+import { resetMetrics } from './metrics.ts';
+import { setupServerObservers } from './server-observers.ts';
+
+const mdManager = new MarkdownManager({ extensions: sharedExtensions });
+const schema = getSchema(sharedExtensions);
+
+const USER_TYPING_ORIGIN = {
+ source: 'connection' as const,
+ context: { origin: 'user-typing' },
+};
+
+const RAW = '---\ntitle: Fence hazard\n---\n\nFirst paragraph body.\n\nSecond paragraph stays.\n';
+
+function canonicalOf(raw: string): string {
+ const { frontmatter, body } = stripFrontmatter(raw);
+ return prependFrontmatter(frontmatter, mdManager.serialize(mdManager.parseWithFallback(body)));
+}
+
+function seedThenAttach(raw: string, docName: string) {
+ const doc = new Y.Doc();
+ const xmlFragment = doc.getXmlFragment('default');
+ const ytext = doc.getText('source');
+ doc.transact(() => {
+ composeAndWriteRawBody(doc, raw, 'file-watcher');
+ }, FILE_WATCHER_ORIGIN);
+ const cleanup = setupServerObservers({ doc, xmlFragment, ytext, mdManager, schema, docName });
+ return { doc, xmlFragment, ytext, cleanup };
+}
+
+function serializeFragmentBody(xmlFragment: Y.XmlFragment): string {
+ return mdManager.serialize(yXmlFragmentToProseMirrorRootNode(xmlFragment, schema).toJSON());
+}
+
+function findTextNodeContaining(
+ node: Y.XmlFragment | Y.XmlElement,
+ needle: string,
+): Y.XmlText | null {
+ for (let i = 0; i < node.length; i++) {
+ const child = node.get(i);
+ if (child instanceof Y.XmlText && child.toString().includes(needle)) return child;
+ if (child instanceof Y.XmlElement) {
+ const found = findTextNodeContaining(child, needle);
+ if (found) return found;
+ }
+ }
+ return null;
+}
+
+function typeIntoParagraph(doc: Y.Doc, xmlFragment: Y.XmlFragment, needle: string): void {
+ doc.transact(() => {
+ const textNode = findTextNodeContaining(xmlFragment, needle);
+ if (!textNode) throw new Error(`no fragment text node containing ${JSON.stringify(needle)}`);
+ textNode.insert(0, 'Z');
+ }, USER_TYPING_ORIGIN);
+}
+
+function captureBridgeEvents(eventName: string, fn: () => void): Record<string, unknown>[] {
+ const originalWarn = console.warn;
+ const warnings: string[] = [];
+ console.warn = (...args: unknown[]) => {
+ warnings.push(args.map(String).join(' '));
+ };
+ try {
+ fn();
+ } finally {
+ console.warn = originalWarn;
+ }
+ return warnings
+ .map((w) => {
+ try {
+ return JSON.parse(w);
+ } catch {
+ return null;
+ }
+ })
+ .filter((e): e is Record<string, unknown> => e !== null)
+ .filter((e) => e.event === eventName);
+}
+
+interface FenceVariant {
+ name: string;
+ slug: string;
+ ws: string;
+ fence: 'open' | 'close';
+ insertAt: (s: string) => number;
+}
+
+const endOfOpeningFence = (s: string): number => s.indexOf('\n');
+const endOfClosingFence = (s: string): number => s.indexOf('\n---\n') + '\n---'.length;
+
+const FENCE_VARIANTS: FenceVariant[] = [
+ {
+ name: 'trailing space on the opening fence',
+ slug: 'open-space',
+ ws: ' ',
+ fence: 'open',
+ insertAt: endOfOpeningFence,
+ },
+ {
+ name: 'trailing space on the closing fence',
+ slug: 'close-space',
+ ws: ' ',
+ fence: 'close',
+ insertAt: endOfClosingFence,
+ },
+ {
+ name: 'trailing tab on the opening fence',
+ slug: 'open-tab',
+ ws: '\t',
+ fence: 'open',
+ insertAt: endOfOpeningFence,
+ },
+ {
+ name: 'trailing tab on the closing fence',
+ slug: 'close-tab',
+ ws: '\t',
+ fence: 'close',
+ insertAt: endOfClosingFence,
+ },
+];
+
+describe('FM-fence trailing whitespace + adjacent WYSIWYG edit', () => {
+ test('precondition: the fixture is round-trip byte-stable', () => {
+ expect(canonicalOf(RAW)).toBe(RAW);
+ });
+
+ for (const variant of FENCE_VARIANTS) {
+ test(`${variant.name}: FM survives, keystroke kept, edit applied`, () => {
+ __resetBridgeWatchdogForTests();
+ resetMetrics();
+ const { doc, xmlFragment, ytext, cleanup } = seedThenAttach(
+ RAW,
+ `fm-fence-adjacent-${variant.slug}`,
+ );
+ expect(ytext.toString()).toBe(RAW);
+
+ doc.transact(() => {
+ ytext.insert(variant.insertAt(ytext.toString()), variant.ws);
+ }, USER_TYPING_ORIGIN);
+ expect(ytext.toString()).toContain(`---${variant.ws}\n`);
+
+ typeIntoParagraph(doc, xmlFragment, 'First paragraph');
+
+ const finalText = ytext.toString();
+ expect(finalText).toContain('title: Fence hazard');
+ if (variant.fence === 'open') {
+ expect(finalText).toContain(`---${variant.ws}\n`);
+ } else {
+ const closeFence = finalText
+ .split('\n')
+ .slice(1)
+ .find((line) => /^---[ \t]*$/.test(line));
+ expect(closeFence).toMatch(/^---[ \t]+$/);
+ expect(closeFence).toContain(variant.ws);
+ }
+ expect(finalText).toContain('ZFirst paragraph body.');
+ expect(finalText).toContain('Second paragraph stays.');
+ expect(serializeFragmentBody(xmlFragment)).not.toContain('title: Fence hazard');
+
+ cleanup();
+ });
+ }
+});
+
+describe('FM-fence trailing whitespace + distal WYSIWYG edit', () => {
+ for (const variant of FENCE_VARIANTS) {
+ test(`${variant.name}: doc settles coherently, FM keeps partitioning as FM`, () => {
+ __resetBridgeWatchdogForTests();
+ resetMetrics();
+ const { doc, xmlFragment, ytext, cleanup } = seedThenAttach(
+ RAW,
+ `fm-fence-distal-${variant.slug}`,
+ );
+
+ doc.transact(() => {
+ ytext.insert(variant.insertAt(ytext.toString()), variant.ws);
+ }, USER_TYPING_ORIGIN);
+
+ const splitBrainEvents = captureBridgeEvents('bridge-split-brain-rederive', () => {
+ typeIntoParagraph(doc, xmlFragment, 'Second paragraph');
+ });
+ expect(splitBrainEvents).toHaveLength(0);
+
+ const finalText = ytext.toString();
+ expect(finalText).toContain('title: Fence hazard');
+ if (variant.fence === 'open') {
+ expect(finalText).toContain(`---${variant.ws}\n`);
+ } else {
+ const closeFence = finalText
+ .split('\n')
+ .slice(1)
+ .find((line) => /^---[ \t]*$/.test(line));
+ expect(closeFence).toMatch(/^---[ \t]+$/);
+ expect(closeFence).toContain(variant.ws);
+ }
+ expect(finalText).toContain('ZSecond paragraph stays.');
+ expect(finalText).toContain('First paragraph body.');
+ expect(serializeFragmentBody(xmlFragment)).not.toContain('title: Fence hazard');
+
+ cleanup();
+ });
+ }
+});