Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

fix(open-knowledge): merge frontmatter instead of doubling on write (PRD-6997) (#1964)

tim-inkeep89f4275a4649
diff --git a/.changeset/prd-6997-frontmatter-doubling.md b/.changeset/prd-6997-frontmatter-doubling.md
new file mode 100644
index 000000000..40ef3a5c2
--- /dev/null
+++ b/.changeset/prd-6997-frontmatter-doubling.md
@@ -0,0 +1,5 @@
+---
+"@inkeep/open-knowledge": patch
+---
+
+Fix `write` doubling frontmatter when `content` already has a `---` block and a `frontmatter` param is also supplied. The two are now merged into a single block (the `frontmatter` param wins per key, embedded-only keys survive) instead of stacking a second block on disk. A malformed embedded block is rejected with a clear error rather than silently doubled.
diff --git a/packages/server/src/content/frontmatter-merge.test.ts b/packages/server/src/content/frontmatter-merge.test.ts
index b53fd78e6..d2636bbdd 100644
--- a/packages/server/src/content/frontmatter-merge.test.ts
+++ b/packages/server/src/content/frontmatter-merge.test.ts
@@ -1,5 +1,5 @@
import { describe, expect, test } from 'bun:test';
-import { dropEmpties, mergePatch } from './frontmatter-merge.ts';
+import { mergePatch } from './frontmatter-merge.ts';
describe('mergePatch — write path (scalars + arrays REPLACE; empties drop)', () => {
test('scalars in patch replace existing', () => {
@@ -48,31 +48,3 @@ describe('mergePatch — write path (scalars + arrays REPLACE; empties drop)', (
expect(merged).toEqual({ status: 'review', owners: ['alice'] });
});
});
-
-describe('dropEmpties — submit-time normalization', () => {
- test('drops null / undefined / empty string / empty array', () => {
- const cleaned = dropEmpties({
- keep: 'value',
- a: null,
- b: undefined,
- c: '',
- d: [],
- e: 0,
- f: false,
- g: ['x'],
- });
- expect(cleaned).toEqual({ keep: 'value', e: 0, f: false, g: ['x'] });
- });
-
- test('preserves nested objects (treated as scalars)', () => {
- const cleaned = dropEmpties({ meta: { a: 1 }, empty: '' });
- expect(cleaned).toEqual({ meta: { a: 1 } });
- });
-
- test('returns a fresh object (does not mutate)', () => {
- const input = { a: 'x', b: '' };
- const cleaned = dropEmpties(input);
- expect(input).toEqual({ a: 'x', b: '' });
- expect(cleaned).not.toBe(input);
- });
-});
diff --git a/packages/server/src/content/frontmatter-merge.ts b/packages/server/src/content/frontmatter-merge.ts
index 643cd84fd..0ae5d03b7 100644
--- a/packages/server/src/content/frontmatter-merge.ts
+++ b/packages/server/src/content/frontmatter-merge.ts
@@ -18,17 +18,6 @@ export function mergePatch(
return result;
}
-export function dropEmpties(input: FrontmatterRecord): FrontmatterRecord {
- const result: FrontmatterRecord = {};
- for (const [key, value] of Object.entries(input)) {
- if (value === undefined || value === null) continue;
- if (typeof value === 'string' && value === '') continue;
- if (Array.isArray(value) && value.length === 0) continue;
- result[key] = value;
- }
- return result;
-}
-
function isEmpty(value: unknown): boolean {
return isFrontmatterValueEmpty(value as FrontmatterValue | null);
}
diff --git a/packages/server/src/mcp/tools/write.test.ts b/packages/server/src/mcp/tools/write.test.ts
new file mode 100644
index 000000000..12e55a0cc
--- /dev/null
+++ b/packages/server/src/mcp/tools/write.test.ts
@@ -0,0 +1,93 @@
+import { describe, expect, it } from 'bun:test';
+import { stripFrontmatter } from '@inkeep/open-knowledge-core';
+import { composeWithFrontmatter } 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'); // param wins
+ expect(frontmatter).toContain('author: HeeGun'); // embedded-only key survives
+ expect(frontmatter).not.toContain('Embedded'); // overwritten title gone
+ });
+
+ 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.');
+ });
+});
diff --git a/packages/server/src/mcp/tools/write.ts b/packages/server/src/mcp/tools/write.ts
index 370f2d10d..5d2bb32a4 100644
--- a/packages/server/src/mcp/tools/write.ts
+++ b/packages/server/src/mcp/tools/write.ts
@@ -1,15 +1,19 @@
import { existsSync, readFileSync } from 'node:fs';
import { resolve as resolvePath } from 'node:path';
import {
+ type FrontmatterMap,
type FrontmatterPatch,
normalizeBridge,
+ parseFrontmatterYaml,
renderInventoryFooter,
+ serializeFrontmatterMap,
stripFrontmatter,
+ unwrapFrontmatterFences,
+ withFences,
} from '@inkeep/open-knowledge-core';
-import { stringify as stringifyYaml } from 'yaml';
import { z } from 'zod';
import { resolveContentDir, resolveLockDir } from '../../config/paths.ts';
-import { dropEmpties } from '../../content/frontmatter-merge.ts';
+import { mergePatch } from '../../content/frontmatter-merge.ts';
import { parentFolderOf } from '../../content/nested-folder-rules.ts';
import { applySubstitution, todayIsoUtc } from '../../content/substitution.ts';
import { resolveTemplatesAvailable } from '../../content/templates-resolver.ts';
@@ -132,10 +136,28 @@ function extensionIgnoredNote(
return `Note: "${docName}" already exists as \`${docName}${existingExt}\`, so the requested \`${requestedExt}\` extension was not applied — the write went to \`${docName}${existingExt}\`. Changing a doc's on-disk extension in place isn't available via the MCP today.`;
}
-function composeWithFrontmatter(frontmatter: FrontmatterPatch, body: string): string {
- const cleaned = dropEmpties(frontmatter as Record<string, unknown>);
- if (Object.keys(cleaned).length === 0) return body;
- return `---\n${stringifyYaml(cleaned)}---\n${body}`;
+export function composeWithFrontmatter(
+ frontmatter: FrontmatterPatch,
+ body: string,
+): { ok: true; markdown: string } | { ok: false; error: string } {
+ const { frontmatter: embeddedFenced, body: cleanBody } = stripFrontmatter(body);
+
+ let base: FrontmatterMap = {};
+ if (embeddedFenced !== '') {
+ const parsed = parseFrontmatterYaml(unwrapFrontmatterFences(embeddedFenced));
+ if (parsed.map === null) {
+ return {
+ ok: false,
+ error: `EMBEDDED_FRONTMATTER_MALFORMED — \`content\` opens with a \`---\` block whose YAML failed to parse (${parsed.parseError}), so it can't be merged with the \`frontmatter\` param. Fix the embedded YAML, or supply the frontmatter only via the \`frontmatter\` param (not also inline in \`content\`).`,
+ };
+ }
+ base = parsed.map;
+ }
+
+ const merged = mergePatch(base, frontmatter as Record<string, unknown>) as FrontmatterMap;
+ const yamlBody = serializeFrontmatterMap(merged);
+ if (yamlBody === '') return { ok: true, markdown: cleanBody };
+ return { ok: true, markdown: withFences(yamlBody) + cleanBody };
}
async function writeOneDoc(
@@ -219,10 +241,12 @@ async function writeOneDoc(
});
effectivePosition = 'replace';
} else if (hasFrontmatter) {
- effectiveMarkdown = composeWithFrontmatter(
+ const composed = composeWithFrontmatter(
spec.frontmatter as FrontmatterPatch,
effectiveMarkdown,
);
+ if (!composed.ok) return { docName, ok: false, error: composed.error };
+ effectiveMarkdown = composed.markdown;
effectivePosition = 'replace';
}