runlist 0.0.0 → 0.94.1

package/src/flags.mjs

@@ -0,0 +1,318 @@
+import { createHash } from 'node:crypto';
+import { appendFileSync, closeSync, existsSync, fsyncSync, mkdirSync, openSync, readFileSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { withPathLocks } from './atomic-mutation.mjs';
+import { stateDir } from './naming.mjs';
+import { die, hostSessionSource, nowIso, toRepoPath } from './util.mjs';
+import { bold, dim, green, red, yellow } from './color.mjs';
+
+// Flags: what anyone found that the person should know when they come back —
+// a plan contradicting another, a decision open in one place and ruled in
+// another, a citation that no longer says what it claims. A session, a person
+// or a check adds one; no model is needed. A later pass may build context onto
+// an open flag, but the flag stands on what its author wrote.
+//
+// Storage is an append-only event log (`add`, `accept`, `reject`, `resolve`),
+// one JSON object per line, so nothing is overwritten and the triage record
+// survives as written. The current state of a flag is derived from its events.
+// Default path `.runlist/flags.jsonl`; `export const flags = { file }` moves it.
+
+export const SEVERITIES = ['problem', 'warn', 'info'];
+const TRIAGE = new Set(['accept', 'reject', 'resolve']);
+const QUOTE_MAX = 200;
+
+export function flagsFile(config) {
+  const configured = config.raw?.flags?.file;
+  return configured ? path.resolve(config.repoRoot, configured) : path.join(stateDir(config.repoRoot), 'flags.jsonl');
+}
+
+export function readFlagEvents(file) {
+  if (!existsSync(file)) return [];
+  const events = [];
+  for (const line of readFileSync(file, 'utf8').split('\n')) {
+    if (!line.trim()) continue;
+    try { events.push(JSON.parse(line)); } catch { /* a torn line is skipped, never fatal */ }
+  }
+  return events;
+}
+
+export function deriveFlags(events) {
+  const flags = new Map();
+  for (const e of events) {
+    if (e.event === 'add' && e.id && !flags.has(e.id)) {
+      flags.set(e.id, { ...e, state: 'open', triage: null, history: [] });
+      continue;
+    }
+    const flag = flags.get(e.id);
+    if (!flag || !TRIAGE.has(e.event)) continue;
+    flag.history.push({ event: e.event, at: e.at, by: e.by, note: e.note ?? null });
+    if (e.event === 'accept') flag.triage = 'accepted';
+    if (e.event === 'reject') { flag.triage = 'rejected'; flag.state = 'closed'; }
+    if (e.event === 'resolve') flag.state = 'resolved';
+  }
+  return [...flags.values()];
+}
+
+function nextId(flags) {
+  let max = 0;
+  for (const f of flags) max = Math.max(max, Number(String(f.id).replace(/^F/, '')) || 0);
+  return `F${max + 1}`;
+}
+
+// `--by check:<name>`, `--by model:<name>`, `--by person:<name>`; otherwise the
+// session the environment names, or the person at the keyboard.
+export function resolveAuthor(byArg, env = process.env) {
+  if (byArg) {
+    const m = byArg.match(/^(session|person|check|model):(.+)$/);
+    if (!m) die('--by is <kind>:<name>, where kind is session, person, check or model.');
+    return { kind: m[1], name: m[2].trim() };
+  }
+  const source = hostSessionSource(env);
+  if (source?.scope === 'session') return { kind: 'session', name: source.host, session: source.id };
+  return { kind: 'person', name: os.userInfo().username };
+}
+
+export function normalizeText(text) {
+  return text.replace(/\s+/g, ' ').trim().toLowerCase();
+}
+
+// `docs/plans/x.md:12` → file and line; the file must exist in the repo and
+// the line must be inside it. The line's text is kept, so a later read can say
+// whether the place still says what was flagged.
+export function resolvePlace(place, config) {
+  const m = place.match(/^(.*?)(?::(\d+))?$/);
+  const rel = m[1];
+  const line = m[2] ? Number(m[2]) : null;
+  const abs = path.resolve(config.repoRoot, rel);
+  if (!existsSync(abs)) die(`No such file: ${rel}`);
+  const repoPath = toRepoPath(abs, config.repoRoot);
+  if (repoPath.startsWith('..')) die(`${rel} is outside the repository.`);
+  let quote = null;
+  if (line !== null) {
+    const lines = readFileSync(abs, 'utf8').split('\n');
+    if (line < 1 || line > lines.length) die(`${repoPath} has ${lines.length} lines; there is no line ${line}.`);
+    quote = lines[line - 1].trim().slice(0, QUOTE_MAX);
+  }
+  return { file: repoPath, line, quote };
+}
+
+// Where the flagged text is now: unchanged, moved to another line, or gone.
+export function locateFlag(flag, config) {
+  if (flag.line == null) return { status: existsSync(path.resolve(config.repoRoot, flag.file)) ? 'here' : 'gone' };
+  let lines;
+  try { lines = readFileSync(path.resolve(config.repoRoot, flag.file), 'utf8').split('\n'); }
+  catch { return { status: 'gone' }; }
+  if ((lines[flag.line - 1] ?? '').trim().slice(0, QUOTE_MAX) === flag.quote) return { status: 'here', line: flag.line };
+  if (flag.quote) {
+    const at = lines.findIndex(l => l.trim().slice(0, QUOTE_MAX) === flag.quote);
+    if (at !== -1) return { status: 'moved', line: at + 1 };
+  }
+  return { status: 'changed' };
+}
+
+function withFlagsLock(config, fn) {
+  const file = flagsFile(config);
+  const dir = path.dirname(file);
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  return withPathLocks([file], { repoRoot: config.repoRoot }, () => fn(file));
+}
+
+function append(file, event) {
+  const existing=existsSync(file)?readFileSync(file,'utf8'):'';
+  const prefix=existing&&!existing.endsWith('\n')?'\n':'';
+  const fd=openSync(file,'a');try{appendFileSync(fd,`${prefix}${JSON.stringify(event)}\n`);fsyncSync(fd);}finally{closeSync(fd);}
+}
+
+export function addFlag(config, { place, text, severity = 'warn', by = null }) {
+  if (!text || !text.trim()) die('A flag says what is wrong: runlist flag add <file[:line]> "<what is wrong>"');
+  if (!SEVERITIES.includes(severity)) die(`--severity is one of ${SEVERITIES.join(', ')}.`);
+  const where = resolvePlace(place, config);
+  const author = typeof by === 'object' && by ? by : resolveAuthor(by);
+  return withFlagsLock(config, file => {
+    const flags = deriveFlags(readFlagEvents(file));
+    const key = normalizeText(text);
+    const same = flags.find(f => f.state === 'open' && f.file === where.file && f.line === where.line && normalizeText(f.text) === key);
+    if (same) return { flag: same, added: false };
+    const event = { event: 'add', id: nextId(flags), at: nowIso(), ...where, text: text.trim(), severity, by: author };
+    append(file, event);
+    return { flag: { ...event, state: 'open', triage: null, history: [] }, added: true };
+  });
+}
+
+export function flagRevision(flag) { return `sha256:${createHash('sha256').update(JSON.stringify(flag)).digest('hex')}`; }
+function flagError(code,message){const error=new Error(message);error.code=code;throw error;}
+export function triageFlag(config, { id, event, note = null, by = null, expectedRevision, operationId = null }) {
+  if(!TRIAGE.has(event))flagError('flag-invalid-action','Choose accept, reject or resolve.');
+  if(operationId&&!/^[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12}$/.test(operationId))flagError('flag-invalid-operation','A valid operation UUID is required.');
+  const author = typeof by === 'object' && by ? by : resolveAuthor(by);
+  const requestHash=createHash('sha256').update(JSON.stringify({id,event,note,author,expectedRevision})).digest('hex');
+  return withFlagsLock(config, file => {
+    const events=readFlagEvents(file),flags=deriveFlags(events),prior=operationId&&events.find(e=>e.operationId===operationId);
+    if(prior){if(prior.requestHash!==requestHash)flagError('flag-operation-reused','This operation ID belongs to another reviewed request.');return {...flags.find(f=>f.id===id),replayed:true};}
+    const flag = flags.find(f => f.id === id);
+    if (!flag) die(`No flag ${id}.`);
+    if(expectedRevision!==undefined&&expectedRevision!==flagRevision(flag))flagError('flag-revision-conflict','This flag changed. Reload it and review the current history before retrying.');
+    if (flag.state !== 'open') die(`${id} is already ${flag.state === 'closed' ? 'rejected' : flag.state}.`);
+    const entry={event,id,at:nowIso(),by:author,...(note?{note}:{}),...(operationId?{operationId,requestHash}:{})};
+    append(file,entry);
+    return {...deriveFlags([...events,entry]).find(f=>f.id===id),replayed:false};
+  });
+}
+
+export function openFlags(config) {
+  const rank = f => SEVERITIES.indexOf(f.severity);
+  return deriveFlags(readFlagEvents(flagsFile(config)))
+    .filter(f => f.state === 'open')
+    .sort((a, b) => rank(a) - rank(b) || String(b.at).localeCompare(String(a.at)));
+}
+
+// A check's flags follow what the check reports: each error it reports is
+// flagged once, and a flag it raised earlier that it no longer reports is
+// resolved only when the caller explicitly confirms complete scan coverage.
+// Without that confirmation a partial/failed scan may add observations, but
+// absence from its findings is not evidence that an earlier flag was fixed.
+// A finding is matched to its open flag on file and text, not line: a check
+// reports the same problem at a new line after an edit above it, and that is
+// still one flag.
+export function syncCheckFlags(config, checkName, findings, { complete = false, files = null } = {}) {
+  const by = { kind: 'check', name: checkName };
+  const keyOf = f => `${f.file}\0${normalizeText(f.text)}`;
+  const current = new Set(findings.map(keyOf));
+  const open = new Set(openFlags(config).filter(f => f.by?.kind === 'check' && f.by?.name === checkName).map(keyOf));
+  let added = 0;
+  let resolved = 0;
+  let additionsComplete = true;
+  for (const finding of findings) {
+    if (open.has(keyOf(finding))) continue;
+    if (!existsSync(path.resolve(config.repoRoot, finding.file))) { additionsComplete = false; continue; }
+    const place = finding.line ? `${finding.file}:${finding.line}` : finding.file;
+    const severity = SEVERITIES.includes(finding.severity) ? finding.severity : 'problem';
+    try {
+      if (addFlag(config, { place, text: finding.text, severity, by }).added) { added++; open.add(keyOf(finding)); }
+    } catch { additionsComplete = false; /* retry on the next complete scan */ }
+  }
+  if (!complete || !additionsComplete) return { added, resolved };
+  const covered = files === null ? null : new Set(files);
+  for (const flag of openFlags(config)) {
+    if (flag.by?.kind !== 'check' || flag.by?.name !== checkName) continue;
+    if (covered && !covered.has(flag.file)) continue;
+    if (current.has(`${flag.file}\0${normalizeText(flag.text)}`)) continue;
+    triageFlag(config, { id: flag.id, event: 'resolve', note: `no longer reported by ${checkName}`, by });
+    resolved++;
+  }
+  return { added, resolved };
+}
+
+function authorLabel(by) {
+  if (!by) return 'unknown';
+  return by.kind === 'session' ? `${by.name} session ${String(by.session ?? '').slice(0, 8)}` : `${by.kind} ${by.name}`;
+}
+
+function placeLabel(flag, config) {
+  const where = locateFlag(flag, config);
+  const base = flag.line != null ? `${flag.file}:${flag.line}` : flag.file;
+  if (where.status === 'moved') return `${base} ${dim(`(now line ${where.line})`)}`;
+  if (where.status === 'changed') return `${base} ${yellow('(text there has changed)')}`;
+  if (where.status === 'gone') return `${base} ${yellow('(file gone)')}`;
+  return base;
+}
+
+const severityLabel = s => (s === 'problem' ? red(s) : s === 'warn' ? yellow(s) : dim(s));
+
+// One line for the session-start banner, or null when nothing is open.
+export function flagsHudLine(config, { top = 3 } = {}) {
+  let open;
+  try { open = openFlags(config); } catch { return null; }
+  if (open.length === 0) return null;
+  const problems = open.filter(f => f.severity === 'problem').length;
+  const items = open.slice(0, top).map(f => `${f.id} ${f.line != null ? `${f.file}:${f.line}` : f.file} ${f.text.slice(0, 80)}`).join('; ');
+  return `[runlist] ${open.length} open flag${open.length === 1 ? '' : 's'}${problems ? `, ${problems} problem${problems === 1 ? '' : 's'}` : ''}, for awareness: ${items}. List: \`runlist flags\`.`;
+}
+
+export function runFlags(argv, config) {
+  const json = argv.includes('--json');
+  const all = argv.includes('--all');
+  const events = readFlagEvents(flagsFile(config));
+  const flags = deriveFlags(events)
+    .filter(f => all || f.state === 'open')
+    .sort((a, b) => SEVERITIES.indexOf(a.severity) - SEVERITIES.indexOf(b.severity) || String(b.at).localeCompare(String(a.at)));
+  if (json) {
+    process.stdout.write(`${JSON.stringify(flags.map(f => ({ ...f, location: locateFlag(f, config) })), null, 2)}\n`);
+    return;
+  }
+  if (flags.length === 0) {
+    process.stdout.write(dim(all ? 'No flags.\n' : 'No open flags.\n'));
+    return;
+  }
+  for (const f of flags) {
+    const state = f.state === 'open' ? (f.triage === 'accepted' ? green('accepted') : '') : dim(f.state === 'closed' ? 'rejected' : f.state);
+    process.stdout.write(`${bold(f.id)} ${severityLabel(f.severity)} ${placeLabel(f, config)} ${state}\n`);
+    process.stdout.write(`  ${f.text}\n`);
+    process.stdout.write(dim(`  ${authorLabel(f.by)}, ${f.at}`) + '\n');
+  }
+}
+
+export function runFlag(argv, config) {
+  const [sub, ...rest] = argv;
+  const positional = [];
+  let severity;
+  let by = null;
+  let note = null;
+  for (let i = 0; i < rest.length; i++) {
+    const a = rest[i];
+    if (a === '--severity' && rest[i + 1]) { severity = rest[++i]; continue; }
+    if (a === '--by' && rest[i + 1]) { by = rest[++i]; continue; }
+    if (a === '--note' && rest[i + 1]) { note = rest[++i]; continue; }
+    if (a === '--config') { i++; continue; }
+    if (a.startsWith('-')) continue;
+    positional.push(a);
+  }
+  const usage = 'Usage: runlist flag add <file[:line]> "<what is wrong>" [--severity problem|warn|info]\n'
+    + '       runlist flag accept|reject|resolve <id> [--note "..."]\n'
+    + '       runlist flag show <id>\n'
+    + '       runlist flag sync <check-name> [@findings.json | -]';
+
+  if (sub === 'add') {
+    const [place, ...words] = positional;
+    if (!place) die(usage);
+    const { flag, added } = addFlag(config, { place, text: words.join(' '), severity, by });
+    process.stdout.write(added ? `${green('Flagged')} ${flag.id} ${placeLabel(flag, config)}\n` : `${dim('Already open as')} ${flag.id}\n`);
+    return;
+  }
+  if (TRIAGE.has(sub)) {
+    const [id] = positional;
+    if (!id) die(usage);
+    triageFlag(config, { id, event: sub, note, by });
+    process.stdout.write(`${green({ accept: 'Accepted', reject: 'Rejected', resolve: 'Resolved' }[sub])} ${id}\n`);
+    return;
+  }
+  if (sub === 'sync') {
+    // A check outside runlist hands over everything it reports now, as a JSON
+    // array of { file, line?, text, severity? }; the list follows it.
+    const [name, source] = positional;
+    if (!name) die('Usage: runlist flag sync <check-name> [@findings.json | -]   (JSON array of { file, line?, text, severity? })');
+    let raw;
+    try { raw = source && source !== '-' ? readFileSync(source.replace(/^@/, ''), 'utf8') : readFileSync(0, 'utf8'); }
+    catch (err) { die(`Could not read the findings: ${err.message}`); }
+    let findings;
+    try { findings = JSON.parse(raw); } catch { die('The findings are not valid JSON.'); }
+    if (!Array.isArray(findings) || findings.some(f => typeof f?.file !== 'string' || typeof f?.text !== 'string')) {
+      die('The findings are a JSON array of { file, line?, text, severity? }.');
+    }
+    // `flag sync` supplies a complete snapshot for this named external check.
+    const { added, resolved } = syncCheckFlags(config, name, findings, { complete: true });
+    process.stdout.write(`flags from ${name}: ${added} added, ${resolved} resolved\n`);
+    return;
+  }
+  if (sub === 'show') {
+    const flag = deriveFlags(readFlagEvents(flagsFile(config))).find(f => f.id === positional[0]);
+    if (!flag) die(`No flag ${positional[0] ?? ''}.`);
+    process.stdout.write(`${bold(flag.id)} ${severityLabel(flag.severity)} ${placeLabel(flag, config)}\n  ${flag.text}\n`);
+    if (flag.quote) process.stdout.write(dim(`  flagged line: ${flag.quote}`) + '\n');
+    process.stdout.write(dim(`  raised by ${authorLabel(flag.by)}, ${flag.at}`) + '\n');
+    for (const h of flag.history) process.stdout.write(dim(`  ${h.event} by ${authorLabel(h.by)}, ${h.at}${h.note ? `: ${h.note}` : ''}`) + '\n');
+    return;
+  }
+  die(usage);
+}

package/src/frontmatter-fix.mjs

@@ -0,0 +1,195 @@
+import { readFileSync, writeFileSync } from 'node:fs';
+import { extractFrontmatter, parseSimpleFrontmatter } from './frontmatter.mjs';
+import { asString, toRepoPath, escapeRegex, warn } from './util.mjs';
+import { collectDocFiles } from './index.mjs';
+import { bold, green, dim } from './color.mjs';
+import { authorizeManagedSweep } from './managed-path.mjs';
+
+// Caps must stay in lockstep with the warnings emitted by validatePlanShape in
+// src/validate.mjs — that's where the user first sees these numbers. Targets
+// are deliberately under the cap so a fix-then-edit cycle doesn't reintroduce
+// the warning on the next few-word touch-up.
+const FIELDS = [
+  { name: 'current_state', cap: 1500, target: 1200, heading: '## Current State' },
+  { name: 'next_step',     cap: 800,  target: 600,  heading: '## Next Step' },
+];
+
+export function runFrontmatterFix(config, opts = {}) {
+  const { dryRun, out = process.stdout } = opts;
+  const allFiles = collectDocFiles(config);
+  authorizeManagedSweep(allFiles, config, { kind: 'Frontmatter fix source' });
+  const results = [];
+
+  for (const filePath of allFiles) {
+    const raw = readFileSync(filePath, 'utf8');
+    const { frontmatter: fm, body } = extractFrontmatter(raw);
+    if (!fm) continue;
+    const parsed = parseSimpleFrontmatter(fm);
+    const docType = asString(parsed.type);
+    // The warnings only fire for type: plan (validatePlanShape). Untyped docs
+    // skip the warning too, so skip them here as well — auto-injecting a
+    // `## Current State` into a non-plan doc would be surprising.
+    if (docType !== 'plan') continue;
+    const status = asString(parsed.status);
+    if (config.lifecycle.terminalStatuses.has(status)
+      || config.lifecycle.archiveStatuses.has(status)
+      || config.lifecycle.skipsWarnings(status, docType)) continue;
+
+    const ops = [];
+    for (const { name, cap, target, heading } of FIELDS) {
+      const value = asString(parsed[name]);
+      if (!value || value.length <= cap) continue;
+      const { head, tail } = splitAtBoundary(value, target);
+      if (!tail) continue;
+      ops.push({ field: name, heading, before: value.length, head, tail });
+    }
+    if (ops.length === 0) continue;
+
+    let newFm = fm;
+    let newBody = body;
+    for (const op of ops) {
+      newFm = replaceFrontmatterField(newFm, op.field, op.head);
+      newBody = insertOrAppendSection(newBody, op.heading, op.tail);
+    }
+
+    if (!dryRun) {
+      writeFileSync(filePath, `---\n${newFm}\n---\n${newBody}`, 'utf8');
+      try { config.hooks.onLint?.({ path: toRepoPath(filePath, config.repoRoot), fixes: ops.map(o => ({ field: o.field, type: 'frontmatter-fix' })) }); } catch (err) { warn(`Hook 'onLint' threw: ${err.message}`); }
+    }
+    results.push({ filePath, repoPath: toRepoPath(filePath, config.repoRoot), ops });
+  }
+
+  const prefix = dryRun ? dim('[dry-run] ') : '';
+  const banner = dryRun ? dim(' [preview — run without --dry-run to write]') : '';
+  out.write(bold('runlist doctor --frontmatter-fix') + banner + '\n\n');
+
+  if (results.length === 0) {
+    out.write(green('No over-cap fields found.') + '\n');
+    return { results };
+  }
+
+  out.write(`${results.length} file(s) with over-cap fields:\n\n`);
+  for (const r of results) {
+    out.write(`  ${r.repoPath}\n`);
+    for (const op of r.ops) {
+      const moved = op.before - op.head.length;
+      out.write(dim(`    ${prefix}${op.field}: ${op.before} → ${op.head.length} chars (moved ${moved} to \`${op.heading}\`)\n`));
+    }
+  }
+  out.write(`\n${prefix}${green(dryRun ? 'Would fix' : 'Fixed')}: ${results.length} file(s)\n`);
+  return { results };
+}
+
+// Splits at the last sentence-ending punctuation (`.!?` + space/newline/EOS)
+// within `target` chars. If no good sentence boundary lands in the back half of
+// the window, falls back to the last whitespace. If even that fails, a hard
+// cut at `target` — the result still parses; readability just suffers.
+export function splitAtBoundary(value, target) {
+  if (value.length <= target) return { head: value, tail: '' };
+
+  const windowStr = value.slice(0, target);
+  // Sentence boundary: greedy match capturing everything up to the last `.!?`
+  // followed by whitespace or end-of-string inside the window.
+  const sentenceRe = /^[\s\S]*[.!?](?=\s|$)/;
+  const sentenceMatch = windowStr.match(sentenceRe);
+  if (sentenceMatch && sentenceMatch[0].length >= Math.floor(target / 2)) {
+    const splitIdx = sentenceMatch[0].length;
+    return {
+      head: value.slice(0, splitIdx).trim(),
+      tail: value.slice(splitIdx).trim(),
+    };
+  }
+
+  const wsIdx = Math.max(windowStr.lastIndexOf(' '), windowStr.lastIndexOf('\n'));
+  if (wsIdx >= Math.floor(target / 2)) {
+    return {
+      head: value.slice(0, wsIdx).trim(),
+      tail: value.slice(wsIdx + 1).trim(),
+    };
+  }
+
+  return {
+    head: value.slice(0, target).trim(),
+    tail: value.slice(target).trim(),
+  };
+}
+
+// Replace a single frontmatter scalar with a folded block scalar (`key: >\n  …`).
+// Folded form is safe regardless of YAML-special chars in the value (colons,
+// quotes, leading dashes) and matches what `parseSimpleFrontmatter` already
+// reads. Consumes the existing key's continuation block if it was multi-line.
+export function replaceFrontmatterField(fm, key, newValue) {
+  const lines = fm.split('\n');
+  const out = [];
+  let i = 0;
+  let replaced = false;
+
+  while (i < lines.length) {
+    const line = lines[i];
+    const keyRe = new RegExp(`^${escapeRegex(key)}:(.*)$`);
+    const match = !replaced && line.match(keyRe);
+    if (match) {
+      const rest = match[1].trim();
+      const isBlock = /^[>|][-+]?\s*$/.test(rest);
+      i++;
+      if (isBlock || rest === '') {
+        // Consume only scalar continuation lines. Top-level comments and other
+        // YAML syntax belong to the frontmatter, not to this field.
+        while (i < lines.length && (lines[i].trim() === '' || /^[ \t]/.test(lines[i]))) i++;
+      }
+      const folded = foldBlockScalar(newValue);
+      out.push(`${key}: >`);
+      for (const fLine of folded) out.push(`  ${fLine}`);
+      replaced = true;
+      continue;
+    }
+    out.push(line);
+    i++;
+  }
+
+  if (!replaced) {
+    const folded = foldBlockScalar(newValue);
+    out.push(`${key}: >`);
+    for (const fLine of folded) out.push(`  ${fLine}`);
+  }
+
+  return out.join('\n');
+}
+
+// Collapse whitespace into a single line — folded block scalar joins on a
+// single space anyway, so writing one wide line keeps the diff tight and
+// round-trips identically.
+function foldBlockScalar(value) {
+  const single = value.replace(/\s+/g, ' ').trim();
+  return [single];
+}
+
+// Ensure a `## <heading>` section exists in the body and contains `content`.
+// If the section is present (case-insensitive heading match), append the new
+// content to its end. If absent, insert a new section just before the first
+// H2 (so it lands above other content sections) — or append at end if no H2
+// exists.
+export function insertOrAppendSection(body, heading, content) {
+  const headingPattern = new RegExp(`^${escapeRegex(heading)}\\s*$`, 'mi');
+  const existing = body.match(headingPattern);
+  if (existing && existing.index !== undefined) {
+    const startIdx = existing.index + existing[0].length;
+    const after = body.slice(startIdx);
+    const nextHeaderRel = after.search(/\n#{1,2}\s+/);
+    const sectionEnd = nextHeaderRel >= 0 ? startIdx + nextHeaderRel : body.length;
+    const before = body.slice(0, sectionEnd).replace(/\s+$/, '');
+    const rest = body.slice(sectionEnd);
+    return `${before}\n\n${content}\n${rest.startsWith('\n') ? rest : '\n' + rest}`;
+  }
+
+  const firstH2 = body.match(/^##\s+/m);
+  if (firstH2 && firstH2.index !== undefined) {
+    const insertIdx = firstH2.index;
+    const before = body.slice(0, insertIdx).replace(/\s+$/, '');
+    const rest = body.slice(insertIdx);
+    return `${before}\n\n${heading}\n\n${content}\n\n${rest}`;
+  }
+
+  const trimmed = body.replace(/\s+$/, '');
+  return `${trimmed}\n\n${heading}\n\n${content}\n`;
+}