Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
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.mdnew file mode 100644index 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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.tsindex 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';}