astro-dev-edit 0.11.0

package/src/patcher/dotenv.ts

@@ -0,0 +1,121 @@
+/**
+ * `.env` document patching — pure string-in/string-out, like the frontmatter
+ * patcher, and deliberately NOT a registry `Patcher`: that interface is
+ * loc-based (classify/apply against a source annotation), while this targets a
+ * named variable. The caller owns all filesystem access.
+ *
+ * This exists because the Unsplash access key must not live in
+ * `.astro-dev-edit.json`. That file sits in the directory Vite serves; a `.env`
+ * file is one Vite already refuses to serve, and one every project's ignore
+ * rules already expect to hold a secret.
+ *
+ * **Values are validated, not escaped.** dotenv gives `"`, `'`, `` ` ``, `#`
+ * and whitespace their own meanings, and Vite runs dotenv-expand over what it
+ * parses, so `$` interpolates. A value needing any of that would not read back
+ * as it was written — and quoting it would be this module guessing at intent.
+ * Anything outside {@link ENV_VALUE_RE} is refused instead.
+ *
+ * Everything is done by line slicing, never by re-serializing the document:
+ * comments, blank lines, ordering and the quoting style of untouched lines
+ * survive exactly. Line *endings* are the one normalization — the document's
+ * dominant ending is applied throughout, so a mixed-ending file comes out
+ * consistent rather than gaining a third style.
+ */
+
+/**
+ * What a value may contain. Wide enough for every access-key format in play
+ * (Unsplash's are URL-safe base64) and narrow enough that no dotenv
+ * metacharacter can reach the file.
+ */
+export const ENV_VALUE_RE = /^[A-Za-z0-9_-]+$/;
+
+/** Conventional shell variable naming. Ours is a constant; assert anyway. */
+const ENV_NAME_RE = /^[A-Z][A-Z0-9_]*$/;
+
+/** Shown to the user when a save is refused, so it says what to do. */
+const VALUE_REFUSAL =
+  'An access key may contain only letters, digits, hyphens and underscores. ' +
+  'Check for a stray space or quotation mark in what you pasted.';
+
+export type EnvPatchAction = 'created' | 'updated' | 'appended' | 'removed' | 'unchanged';
+
+export type EnvPatchResult =
+  | { ok: true; text: string; action: EnvPatchAction }
+  | { ok: false; reason: string };
+
+/** An uncommented `NAME=` assignment, allowing indentation and a `export `
+ *  prefix (dotenv accepts both). A `#` before it makes the line a comment. */
+function assignmentRe(name: string): RegExp {
+  return new RegExp(`^(\\s*)(export\\s+)?${name}\\s*=`);
+}
+
+/** A commented-out assignment — not a value, but a hint about where the user
+ *  expects the variable to live. */
+function commentedRe(name: string): RegExp {
+  return new RegExp(`^\\s*#\\s*(export\\s+)?${name}\\s*=`);
+}
+
+/**
+ * Upsert `NAME=value` into a `.env` document, or remove it when `value` is
+ * empty. Returns the new text, or a refusal the caller turns into a 422.
+ *
+ * Where the line lands, in order: an existing assignment is replaced **in
+ * place**; failing that, immediately after a commented-out one; failing that,
+ * appended. Earlier duplicate assignments are deleted rather than left behind —
+ * dotenv is last-wins, so a stale copy of a rotated key would otherwise sit on
+ * disk reading as inert while still being a secret.
+ */
+export function upsertEnvVar(source: string, name: string, value: string): EnvPatchResult {
+  if (!ENV_NAME_RE.test(name)) return { ok: false, reason: `not a valid environment variable name: ${name}` };
+  const next = value.trim();
+  if (next && !ENV_VALUE_RE.test(next)) return { ok: false, reason: VALUE_REFUSAL };
+
+  // Match the document's own line ending rather than imposing one.
+  const eol = /\r\n/.test(source) ? '\r\n' : '\n';
+  const assignment = assignmentRe(name);
+  const commented = commentedRe(name);
+
+  // Split on either ending so a \r never rides along on the line content and
+  // double up when the parts are rejoined with `eol`.
+  const lines = source === '' ? [] : source.split(/\r?\n/);
+  // A trailing newline yields a final empty element; drop it and re-add at the
+  // end, so "append" cannot produce a blank line in the middle.
+  const trailingNewline = lines.length > 0 && lines[lines.length - 1] === '';
+  if (trailingNewline) lines.pop();
+
+  const hits: number[] = [];
+  let commentedAt = -1;
+  lines.forEach((line, i) => {
+    if (assignment.test(line)) hits.push(i);
+    else if (commentedAt === -1 && commented.test(line)) commentedAt = i;
+  });
+
+  if (!next) {
+    if (hits.length === 0) return { ok: true, text: source, action: 'unchanged' };
+    const kept = lines.filter((_, i) => !hits.includes(i));
+    return { ok: true, text: kept.length === 0 ? '' : kept.join(eol) + eol, action: 'removed' };
+  }
+
+  let action: EnvPatchAction;
+  if (hits.length > 0) {
+    // Rewrite the last (the one dotenv would use) and drop the earlier ones.
+    const last = hits[hits.length - 1];
+    const [, indent = '', exported = ''] = assignment.exec(lines[last]) ?? [];
+    // Any trailing `# comment` described the old value, so it goes with it.
+    lines[last] = `${indent}${exported}${name}=${next}`;
+    for (const i of hits.slice(0, -1).reverse()) lines.splice(i, 1);
+    action = 'updated';
+  } else if (commentedAt !== -1) {
+    lines.splice(commentedAt + 1, 0, `${name}=${next}`);
+    action = 'appended';
+  } else if (lines.length === 0) {
+    lines.push('# Written by astro-dev-edit. Keep this file out of version control.');
+    lines.push(`${name}=${next}`);
+    action = 'created';
+  } else {
+    lines.push(`${name}=${next}`);
+    action = 'appended';
+  }
+
+  return { ok: true, text: lines.join(eol) + eol, action };
+}

package/src/patcher/expression-trace.ts

@@ -0,0 +1,326 @@
+import type { AstNode } from './astro.ts';
+
+/**
+ * Tracing `{expression}` text back to the string constant it renders, so the
+ * words can be edited where they are read.
+ *
+ * Two shapes are understood, and only these two:
+ *
+ *   {title}     ← const title = 'Hello'
+ *   {b.title}   ← const benefits = [{ title: 'Hello' }, …]  via  benefits.map((b) => …)
+ *
+ * **No JS parser is involved, and none is needed.** `@astrojs/compiler` already
+ * splits a template expression into its text parts, so the expression source
+ * (`b.title`) and the loop head (`benefits.map((b) => (`) arrive as plain
+ * strings. What remains is finding one string literal inside the frontmatter,
+ * which is done by scanning rather than parsing — deliberately, since a real
+ * parser would mean a runtime dependency (`typescript` is absent from ordinary
+ * Astro projects) for a job whose failure mode must be *refusal* anyway.
+ *
+ * Everything here therefore fails closed: any shape not matched exactly returns
+ * null, and the caller keeps today's "edit this in the source" refusal.
+ *
+ * ## Which item, when a loop renders many
+ *
+ * Every card in a `.map()` shares one source loc, so the loc cannot say which
+ * item was clicked. The rendered string does: the client sends the text it
+ * showed and the item whose value equals it is the one patched. Two items with
+ * the same text refuse rather than guess. A DOM sibling index was considered
+ * and rejected — a `.filter()`, `.sort()` or `.slice()` in the chain would
+ * silently mis-target, and a silently wrong write is the one failure this
+ * project must not have.
+ */
+
+const IDENT = '[A-Za-z_$][\\w$]*';
+const BARE_IDENT = new RegExp(`^${IDENT}$`);
+const MEMBER = new RegExp(`^(${IDENT})\\.(${IDENT})$`);
+
+/**
+ * The head of a `.map()` call, up to the arrow: `items.map((it) => (`, or
+ * `items.map(it =>`, with an optional index parameter. Anything else — a
+ * `.filter().map()` chain, a nested member (`data.items.map`), a `function`
+ * callback — does not match, and the expression stays refused.
+ */
+const MAP_HEAD = new RegExp(
+  `^\\s*(${IDENT})\\s*\\.\\s*map\\s*\\(\\s*(?:\\(\\s*(${IDENT})\\s*(?:,[^)]*)?\\)|(${IDENT}))\\s*=>`,
+);
+
+export interface ExpressionTrace {
+  /** Frontmatter key holding the string: `title`. */
+  property: string;
+  /** The array const the item lives in, when the text came from a `.map()`
+   *  loop. Absent for a plain `{title}` const. */
+  array?: string;
+  /** How to name the target in the editor: `title` or `benefits[].title`. */
+  label: string;
+}
+
+/** An expression node's source text, when it is one plain run of text.
+ *  A nested element or a second text part means it isn't a simple value. */
+function expressionText(node: AstNode): string | null {
+  const children = node.children ?? [];
+  if (children.length !== 1 || children[0].type !== 'text') return null;
+  return (children[0].value ?? '').trim();
+}
+
+/** The leading text of an expression — for a `.map()` call, its head. */
+function headText(node: AstNode): string {
+  const first = (node.children ?? [])[0];
+  return first?.type === 'text' ? (first.value ?? '') : '';
+}
+
+/**
+ * What the element's `{expression}` renders, when it can be traced. `parentOf`
+ * must reach every ancestor of `el`, so a member access can be bound through
+ * the loop that introduced it.
+ */
+export function traceExpression(
+  el: AstNode,
+  parentOf: Map<AstNode, AstNode>,
+): ExpressionTrace | null {
+  const children = el.children ?? [];
+  if (children.length !== 1 || children[0].type !== 'expression') return null;
+
+  const expr = expressionText(children[0]);
+  if (!expr) return null;
+
+  if (BARE_IDENT.test(expr)) return { property: expr, label: expr };
+
+  const member = MEMBER.exec(expr);
+  if (!member) return null;
+  const [, param, property] = member;
+
+  // Bind the parameter through the nearest enclosing expression, which for a
+  // mapped element is the `.map()` call itself.
+  for (let node = parentOf.get(el); node; node = parentOf.get(node)) {
+    if (node.type !== 'expression') continue;
+    const map = MAP_HEAD.exec(headText(node));
+    if (!map) return null; // an enclosing expression we don't understand
+    const array = map[1];
+    const bound = map[2] ?? map[3];
+    if (bound !== param) return null; // shadowed, or bound somewhere else
+    return { property, array, label: `${array}[].${property}` };
+  }
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// Locating the string in the frontmatter
+// ---------------------------------------------------------------------------
+
+/** A string literal's span within the frontmatter, and its decoded value. */
+export interface LiteralSpan {
+  /** Index of the opening quote, relative to the frontmatter text. */
+  from: number;
+  /** Index just past the closing quote. */
+  to: number;
+  quote: string;
+  value: string;
+}
+
+const ESCAPES: Record<string, string> = {
+  n: '\n', t: '\t', r: '\r', '\\': '\\', "'": "'", '"': '"', '`': '`',
+};
+
+/**
+ * Read the string literal starting at `i` (which must be its opening quote).
+ * Returns null for an unterminated literal, or a template literal carrying an
+ * `${…}` interpolation — that is code, not copy. Escapes outside the common
+ * set are left encoded, so they simply fail to match and refuse.
+ */
+export function readLiteral(text: string, i: number): LiteralSpan | null {
+  const quote = text[i];
+  if (quote !== '"' && quote !== "'" && quote !== '`') return null;
+  let value = '';
+  for (let j = i + 1; j < text.length; j++) {
+    const ch = text[j];
+    if (ch === '\\') {
+      const next = text[j + 1];
+      if (next === undefined) return null;
+      value += ESCAPES[next] ?? `\\${next}`;
+      j++;
+      continue;
+    }
+    if (ch === quote) return { from: i, to: j + 1, quote, value };
+    if (quote === '`' && ch === '$' && text[j + 1] === '{') return null;
+    if (quote !== '`' && ch === '\n') return null; // unterminated
+    value += ch;
+  }
+  return null;
+}
+
+/** Step over a string literal or a comment, so scanners never mistake their
+ *  contents for structure. Returns the index just past it, or -1. */
+function skipOpaque(text: string, i: number): number {
+  const ch = text[i];
+  if (ch === '"' || ch === "'" || ch === '`') {
+    const lit = readLiteral(text, i);
+    if (lit) return lit.to;
+    // An interpolated template still has to be stepped over; find its end
+    // naively so the surrounding scan can continue or bail.
+    for (let j = i + 1; j < text.length; j++) {
+      if (text[j] === '\\') j++;
+      else if (text[j] === ch) return j + 1;
+    }
+    return -1;
+  }
+  if (ch === '/' && text[i + 1] === '/') {
+    const nl = text.indexOf('\n', i);
+    return nl < 0 ? text.length : nl;
+  }
+  if (ch === '/' && text[i + 1] === '*') {
+    const end = text.indexOf('*/', i + 2);
+    return end < 0 ? -1 : end + 2;
+  }
+  return -1;
+}
+
+const DECL = (name: string) => new RegExp(`(?:^|[\\s;])(?:const|let|var)\\s+${name}\\s*(?::[^=\\n]*)?=\\s*`, 'm');
+
+/** Index just past `const <name> = `, or -1. */
+function declarationEnd(frontmatter: string, name: string): number {
+  const m = DECL(name).exec(frontmatter);
+  return m ? m.index + m[0].length : -1;
+}
+
+/**
+ * The span of the array literal a const is initialised with — from its `[` to
+ * the matching `]`, stepping over strings and comments so a bracket inside one
+ * cannot close it early.
+ */
+export function arraySpan(frontmatter: string, name: string): { from: number; to: number } | null {
+  const start = declarationEnd(frontmatter, name);
+  if (start < 0 || frontmatter[start] !== '[') return null;
+  let depth = 0;
+  for (let i = start; i < frontmatter.length; i++) {
+    const past = skipOpaque(frontmatter, i);
+    if (past >= 0) {
+      i = past - 1;
+      continue;
+    }
+    const ch = frontmatter[i];
+    if (ch === '[' || ch === '{' || ch === '(') depth++;
+    else if (ch === ']' || ch === '}' || ch === ')') {
+      depth--;
+      if (depth === 0) return { from: start, to: i + 1 };
+      if (depth < 0) return null;
+    }
+  }
+  return null;
+}
+
+/** Every `<property>: "…"` string literal within `[from, to)`. */
+export function propertyLiterals(
+  frontmatter: string,
+  property: string,
+  from: number,
+  to: number,
+): LiteralSpan[] {
+  const re = new RegExp(`(?:^|[{,\\s])${property}\\s*:\\s*`, 'g');
+  const scope = frontmatter.slice(from, to);
+  const out: LiteralSpan[] = [];
+  let m: RegExpExecArray | null;
+  while ((m = re.exec(scope)) !== null) {
+    const at = from + m.index + m[0].length;
+    const lit = readLiteral(frontmatter, at);
+    if (lit) out.push(lit);
+    // Overlapping keys can't occur, but keep the scan moving regardless.
+    re.lastIndex = m.index + m[0].length;
+  }
+  return out;
+}
+
+/**
+ * Whether the frontmatter holds anything a trace could patch — the const
+ * exists and, for a loop, at least one item carries the property as a string.
+ * Classification uses this so the page never offers an edit that the write
+ * path would have to refuse for structural reasons. It deliberately does *not*
+ * value-match: which item was clicked is only known once the text is sent.
+ */
+export function hasCandidates(frontmatter: string, trace: ExpressionTrace): boolean {
+  if (!trace.array) {
+    const at = declarationEnd(frontmatter, trace.property);
+    return at >= 0 && readLiteral(frontmatter, at) !== null;
+  }
+  const span = arraySpan(frontmatter, trace.array);
+  return span !== null && propertyLiterals(frontmatter, trace.property, span.from, span.to).length > 0;
+}
+
+export type Located =
+  | { ok: true; span: LiteralSpan }
+  | { ok: false; code: 'untraceable' | 'mismatch' | 'ambiguous'; error: string };
+
+/**
+ * Find the one string literal the traced expression rendered, matching on the
+ * text the client saw. Whitespace-trimmed on both sides, so re-indentation in
+ * the source doesn't break the match — items that differ only in whitespace
+ * therefore read as duplicates and refuse.
+ */
+export function locateValue(
+  frontmatter: string,
+  trace: ExpressionTrace,
+  original: string,
+): Located {
+  const wanted = original.trim();
+
+  if (!trace.array) {
+    const at = declarationEnd(frontmatter, trace.property);
+    if (at < 0) {
+      return {
+        ok: false,
+        code: 'untraceable',
+        error: `“${trace.property}” isn’t declared in this file’s frontmatter (it may be imported), so it must be edited in the source.`,
+      };
+    }
+    const lit = readLiteral(frontmatter, at);
+    if (!lit) {
+      return {
+        ok: false,
+        code: 'untraceable',
+        error: `“${trace.property}” isn’t a plain string in the frontmatter, so it must be edited in the source.`,
+      };
+    }
+    if (lit.value.trim() !== wanted) {
+      return {
+        ok: false,
+        code: 'mismatch',
+        error: 'The source no longer matches the text on the page (it may have been edited elsewhere). Reload and try again.',
+      };
+    }
+    return { ok: true, span: lit };
+  }
+
+  const span = arraySpan(frontmatter, trace.array);
+  if (!span) {
+    return {
+      ok: false,
+      code: 'untraceable',
+      error: `“${trace.array}” isn’t an array declared in this file’s frontmatter (it may be imported), so it must be edited in the source.`,
+    };
+  }
+
+  const hits = propertyLiterals(frontmatter, trace.property, span.from, span.to).filter(
+    (l) => l.value.trim() === wanted,
+  );
+  if (hits.length === 1) return { ok: true, span: hits[0] };
+  if (hits.length === 0) {
+    return {
+      ok: false,
+      code: 'mismatch',
+      error: `No “${trace.property}” in ${trace.array} still reads that way — the file may have been edited elsewhere. Reload and try again.`,
+    };
+  }
+  return {
+    ok: false,
+    code: 'ambiguous',
+    error: `Two entries in ${trace.array} have exactly this text, so the right one can’t be identified. Edit it in the source instead.`,
+  };
+}
+
+/** Re-encode a replacement for the quote style the literal already uses. */
+export function encodeLiteral(value: string, quote: string): string {
+  let out = value.replace(/\\/g, '\\\\').split(quote).join(`\\${quote}`);
+  if (quote !== '`') out = out.replace(/\r?\n/g, '\\n');
+  else out = out.replace(/\$\{/g, '\\${');
+  return out;
+}

package/src/patcher/frontmatter.ts

@@ -0,0 +1,249 @@
+import { Document, isMap, isNode, isPair, isScalar, parseDocument } from 'yaml';
+
+/**
+ * Frontmatter entry parsing and patching for the CMS entry panel — pure
+ * string-in/string-out, like the .astro patcher. Deliberately NOT a registry
+ * `Patcher`: that interface is loc-based (classify/apply against a source
+ * annotation), while entry edits target named frontmatter keys and the body.
+ * The middleware still owns all filesystem access.
+ *
+ * The YAML block is patched via the `yaml` Document API so that comments, key
+ * order, and the quoting style of untouched keys survive a save byte-for-byte.
+ * Only the keys the client actually changed are re-emitted.
+ */
+
+export interface ParsedEntry {
+  hasFrontmatter: boolean;
+  /** Raw text between the fences ('' when none). \n-normalized. */
+  frontmatterText: string;
+  /** Parsed frontmatter mapping; {} when absent or not a mapping. */
+  data: Record<string, unknown>;
+  /** Set when the YAML block failed to parse — frontmatter edits must refuse. */
+  yamlError?: string;
+  /** Markdown body with the post-fence blank-line run stripped. \n-normalized. */
+  body: string;
+  /** Newline run that separated the closing fence from the body. */
+  bodyGap: string;
+  /** Dominant EOL of the original file, restored on write. */
+  eol: '\n' | '\r\n';
+  /** Leading byte-order mark, restored on write. */
+  bom: string;
+}
+
+export interface EntryChanges {
+  /** Only changed keys. `null` deletes the key. */
+  frontmatter?: Record<string, unknown>;
+  /** Full replacement body (\n-normalized). */
+  body?: string;
+}
+
+export type EntryPatchResult =
+  | { ok: true; newSource: string }
+  | { ok: false; error: string };
+
+const CLOSE_FENCE = /^(---|\.\.\.)[ \t]*$/;
+
+export function parseEntry(source: string): ParsedEntry {
+  const bom = source.startsWith('\uFEFF') ? '\uFEFF' : '';
+  const eol: '\n' | '\r\n' = source.includes('\r\n') ? '\r\n' : '\n';
+  const text = source.slice(bom.length).replace(/\r\n/g, '\n');
+
+  const empty: Omit<ParsedEntry, 'body' | 'bodyGap'> = {
+    hasFrontmatter: false,
+    frontmatterText: '',
+    data: {},
+    eol,
+    bom,
+  };
+
+  const lines = text.split('\n');
+  if (lines[0]?.trimEnd() !== '---') {
+    const { body, bodyGap } = splitGap(text);
+    return { ...empty, body, bodyGap };
+  }
+
+  const closeIdx = lines.findIndex((l, i) => i > 0 && CLOSE_FENCE.test(l));
+  if (closeIdx === -1) {
+    // Unterminated fence — treat the whole file as body so nothing is lost.
+    const { body, bodyGap } = splitGap(text);
+    return { ...empty, body, bodyGap };
+  }
+
+  const frontmatterText = lines.slice(1, closeIdx).join('\n') + (closeIdx > 1 ? '\n' : '');
+  const rawBody = lines.slice(closeIdx + 1).join('\n');
+  const { body, bodyGap } = splitGap(rawBody);
+
+  let data: Record<string, unknown> = {};
+  let yamlError: string | undefined;
+  try {
+    const doc = parseDocument(frontmatterText);
+    if (doc.errors.length > 0) {
+      yamlError = doc.errors[0].message;
+    } else {
+      const js = doc.toJS() as unknown;
+      if (js && typeof js === 'object' && !Array.isArray(js)) {
+        data = js as Record<string, unknown>;
+      }
+    }
+  } catch (err) {
+    yamlError = err instanceof Error ? err.message : String(err);
+  }
+
+  return { hasFrontmatter: true, frontmatterText, data, yamlError, body, bodyGap, eol, bom };
+}
+
+/** Split a leading newline run off the body so the textarea starts at content. */
+function splitGap(raw: string): { body: string; bodyGap: string } {
+  const m = raw.match(/^\n+/);
+  return m ? { body: raw.slice(m[0].length), bodyGap: m[0] } : { body: raw, bodyGap: '' };
+}
+
+/** Byte span of one top-level `key: value` pair, from the key's first
+ *  character to the end of its value — excluding any trailing inline comment
+ *  and the line break after it. */
+interface PairSpan {
+  start: number;
+  end: number;
+}
+
+/**
+ * Index a mapping's top-level pairs by key name. A key that is not a plain
+ * string, that appears twice, or whose value carries no source range maps to
+ * `null`: without a single unambiguous span there is nothing to copy back.
+ */
+function pairSpans(doc: Document): Map<string, PairSpan | null> {
+  const spans = new Map<string, PairSpan | null>();
+  if (!isMap(doc.contents)) return spans;
+  for (const item of doc.contents.items) {
+    if (!isPair(item)) continue;
+    const key = item.key;
+    if (!isScalar(key) || typeof key.value !== 'string') continue;
+    if (spans.has(key.value)) {
+      spans.set(key.value, null); // duplicate key
+      continue;
+    }
+    const start = key.range?.[0];
+    const end = isNode(item.value) ? item.value.range?.[1] : undefined;
+    spans.set(
+      key.value,
+      start !== undefined && end !== undefined && end > start ? { start, end } : null,
+    );
+  }
+  return spans;
+}
+
+/**
+ * Copy every untouched pair's original bytes back over the re-emitted ones.
+ *
+ * Re-serializing the document normalizes keys nobody asked about: long plain
+ * scalars get re-folded (which `lineWidth: 0` answers), flow collections gain
+ * padding inside their brackets (`[a, b]` becomes `[ a, b ]`), a four-space
+ * block indent becomes two. Each is a separate stringify option, and chasing
+ * them one at a time only ever fixes the instance in front of you — so the
+ * bytes are restored wholesale instead, which is what this module's contract
+ * has always promised. Keys the caller changed, added or deleted keep the
+ * serializer's output, since for those there is no original to preserve.
+ */
+function restoreUntouchedPairs(
+  before: string,
+  beforeSpans: Map<string, PairSpan | null>,
+  after: string,
+  changed: Set<string>,
+): string {
+  const afterDoc = parseDocument(after);
+  if (afterDoc.errors.length > 0) return after;
+
+  const edits: { start: number; end: number; text: string }[] = [];
+  for (const [name, afterSpan] of pairSpans(afterDoc)) {
+    if (afterSpan === null || changed.has(name)) continue;
+    const beforeSpan = beforeSpans.get(name);
+    if (!beforeSpan) continue;
+    const original = before.slice(beforeSpan.start, beforeSpan.end);
+    const emitted = after.slice(afterSpan.start, afterSpan.end);
+    if (original === emitted) continue;
+    // A pair's span ends at its last character for a plain scalar, but at the
+    // newline closing its final line for a block collection. Keep whichever
+    // terminator the emitted text had so the bytes after the span still line up.
+    const body = original.replace(/\n$/, '');
+    edits.push({
+      start: afterSpan.start,
+      end: afterSpan.end,
+      text: emitted.endsWith('\n') ? `${body}\n` : body,
+    });
+  }
+
+  // Back to front, so an earlier edit cannot shift a later one's offsets.
+  edits.sort((a, b) => b.start - a.start);
+  let out = after;
+  for (const edit of edits) out = out.slice(0, edit.start) + edit.text + out.slice(edit.end);
+  return out;
+}
+
+/**
+ * Apply field/body changes to an entry source. Untouched frontmatter keys,
+ * comments, and ordering survive; a body-only change leaves the frontmatter
+ * block byte-identical (and vice versa).
+ */
+export function applyEntryChanges(source: string, changes: EntryChanges): EntryPatchResult {
+  const parsed = parseEntry(source);
+  const fmChanges = changes.frontmatter ?? {};
+  const fmKeys = Object.keys(fmChanges);
+
+  if (fmKeys.length === 0 && changes.body === undefined) {
+    return { ok: false, error: 'no changes to apply' };
+  }
+
+  let frontmatterText = parsed.frontmatterText;
+  let hasFrontmatter = parsed.hasFrontmatter;
+
+  if (fmKeys.length > 0) {
+    if (parsed.yamlError) {
+      return { ok: false, error: `frontmatter YAML is invalid: ${parsed.yamlError}` };
+    }
+    const hadMapping = parsed.hasFrontmatter && frontmatterText.trim() !== '';
+    const doc = hadMapping ? parseDocument(frontmatterText) : new Document({});
+    // Spans are read before the edits, while every node still carries the
+    // range it parsed from.
+    const beforeSpans = hadMapping ? pairSpans(doc) : new Map<string, PairSpan | null>();
+    for (const [key, value] of Object.entries(fmChanges)) {
+      if (value === null) doc.delete(key);
+      else doc.set(key, value);
+    }
+    // lineWidth 0 disables wrapping: without it, untouched long plain scalars
+    // get re-folded across lines just by round-tripping through toString().
+    frontmatterText = doc.toString({ lineWidth: 0 });
+    if (hadMapping) {
+      frontmatterText = restoreUntouchedPairs(
+        parsed.frontmatterText,
+        beforeSpans,
+        frontmatterText,
+        new Set(fmKeys),
+      );
+    }
+    if (frontmatterText === '{}\n') frontmatterText = ''; // emptied mapping
+    hasFrontmatter = true;
+  }
+
+  const body = changes.body !== undefined ? changes.body.replace(/\r\n/g, '\n') : parsed.body;
+  // A file with frontmatter conventionally separates fence and body with a
+  // blank line; keep whatever the file had, defaulting to one for new fences.
+  const gap = parsed.hasFrontmatter ? parsed.bodyGap : (hasFrontmatter ? '\n' : parsed.bodyGap);
+
+  let text = hasFrontmatter
+    ? `---\n${frontmatterText}---\n${gap}${body}`
+    : `${gap}${body}`;
+  if (text !== '' && !text.endsWith('\n')) text += '\n';
+
+  if (parsed.eol === '\r\n') text = text.replace(/\n/g, '\r\n');
+  return { ok: true, newSource: parsed.bom + text };
+}
+
+/** Build a brand-new entry file from scratch (for /entry/create). */
+export function serializeEntry(frontmatter: Record<string, unknown>, body: string): string {
+  const doc = new Document(frontmatter);
+  const fm = doc.toString({ lineWidth: 0 });
+  const normalizedBody = body.replace(/\r\n/g, '\n');
+  let text = `---\n${fm}---\n\n${normalizedBody}`;
+  if (!text.endsWith('\n')) text += '\n';
+  return text;
+}