@skitterbyte/skitterspec 0.1.0 → 1.0.1

package/src/sync/mcp.js

@@ -0,0 +1,112 @@
+'use strict'
+
+/**
+ * The Linear MCP boundary — the one place that knows concrete Linear tool names.
+ *
+ * `discoverLinear(tools)` resolves the operations the sync needs (read/update a
+ * Project, list/create/update Milestones + Issues) against the *connected*
+ * server's advertised tool list at runtime, rather than hardcoding names that
+ * drift. If Linear isn't connected (empty / zero-match tool list) it returns a
+ * clean `{ ok:false, error }` so the caller can stop and do nothing destructive.
+ *
+ * `makeAdapter(callTool, resolved)` wraps a generic `callTool(name, args)` (the
+ * skill's MCP invoker) into the typed async operations push/pull consume. Tests
+ * inject a fake adapter directly (an in-memory Project), so the engine stays
+ * offline and deterministic; production wires `callTool` to the real MCP server.
+ */
+
+// Canonical operations, and the regexes that match a Linear MCP tool name to
+// each. Ordered patterns: first match wins. Verified against the connected
+// Linear MCP server during build (resolves the overview's Open questions).
+const MATCHERS = {
+  projectRead: [/get_?project\b/i, /read_?project/i, /project_?get/i],
+  projectUpdate: [/update_?project/i, /project_?update/i],
+  projectCreate: [/create_?project/i, /project_?create/i],
+  milestoneList: [/list_?.*milestone/i, /milestones?_?list/i, /get_?.*milestones?/i],
+  milestoneCreate: [/create_?.*milestone/i, /milestone_?create/i],
+  milestoneUpdate: [/update_?.*milestone/i, /milestone_?update/i],
+  issueList: [/list_?issues?/i, /issues?_?list/i, /get_?issues?/i],
+  issueCreate: [/create_?issue/i, /issue_?create/i],
+  issueUpdate: [/update_?issue/i, /issue_?update/i],
+}
+
+// The minimum the push/pull engine can't run without. Milestone/issue ops are
+// optional in Phase 2 (project description round-trips first).
+const REQUIRED = ['projectRead', 'projectUpdate']
+
+// Normalise a tools argument (array of strings or {name} objects) to names.
+function toolNames(tools) {
+  if (!Array.isArray(tools)) return []
+  return tools
+    .map((t) => (typeof t === 'string' ? t : t && typeof t === 'object' ? t.name : null))
+    .filter((n) => typeof n === 'string' && n)
+}
+
+/**
+ * Resolve Linear operations against the connected server's tool list.
+ * @returns {{ok:true, tools:Record<string,string>}} on success, or
+ *          {{ok:false, error:string, resolved?:object, missing?:string[]}}.
+ */
+function discoverLinear(tools) {
+  const names = toolNames(tools)
+  if (!names.length) {
+    return {
+      ok: false,
+      error: 'Linear not connected — connect the `linear` MCP server, then retry.',
+    }
+  }
+
+  const resolved = {}
+  for (const [op, patterns] of Object.entries(MATCHERS)) {
+    const hit = names.find((n) => patterns.some((p) => p.test(n)))
+    if (hit) resolved[op] = hit
+  }
+
+  const missing = REQUIRED.filter((op) => !resolved[op])
+  if (missing.length) {
+    return {
+      ok: false,
+      error:
+        `Linear MCP is connected but missing required tools: ${missing.join(', ')}. ` +
+        'Check the linear server exposes project read + update.',
+      resolved,
+      missing,
+    }
+  }
+
+  return { ok: true, tools: resolved }
+}
+
+/**
+ * Wrap a generic `callTool(name, args) → Promise<result>` into the typed ops the
+ * engine uses. `resolved` is `discoverLinear(...).tools`.
+ */
+function makeAdapter(callTool, resolved) {
+  const need = (op) => {
+    const name = resolved[op]
+    if (!name) throw new Error(`Linear MCP op not available: ${op}`)
+    return name
+  }
+  return {
+    async readProject(id) {
+      return callTool(need('projectRead'), { id })
+    },
+    async updateProject(id, updates) {
+      return callTool(need('projectUpdate'), { id, ...updates })
+    },
+    async createMilestone(projectId, milestone) {
+      return callTool(need('milestoneCreate'), { projectId, ...milestone })
+    },
+    async updateMilestone(id, updates) {
+      return callTool(need('milestoneUpdate'), { id, ...updates })
+    },
+  }
+}
+
+module.exports = {
+  discoverLinear,
+  makeAdapter,
+  toolNames,
+  MATCHERS,
+  REQUIRED,
+}

package/src/sync/normalize.js

@@ -0,0 +1,249 @@
+'use strict'
+
+/**
+ * Normalize a Linear Project projection and a local spec snapshot into the SAME
+ * field set, so the three-way compare (compare.js) can diff them field by field.
+ *
+ * Both `normalizeLocal(snapshotDir, config)` and `normalizeRemote(project, config)`
+ * return an object whose keys are exactly `config.sync.fieldOwnership`'s keys —
+ * identical field sets by construction. A field a given side can't supply is
+ * `null` (scalars) or `[]` (collections), never absent, so the sets stay equal.
+ *
+ * Pure: `normalizeLocal` reads files under `snapshotDir` but makes no other side
+ * effects and no Date.now()/Math.random(). `localOnlySections` are stripped from
+ * the local `description` so they're never pushed to Linear.
+ */
+
+const fs = require('node:fs')
+const path = require('node:path')
+
+// --- markdown / frontmatter parsing -----------------------------------------
+
+// Split `---\n…\n---` frontmatter off the top. Returns { data, body }.
+function parseFrontmatter(raw) {
+  const m = /^---\n([\s\S]*?)\n---\n?/.exec(raw)
+  if (!m) return { data: {}, body: raw }
+  const data = {}
+  for (const line of m[1].split('\n')) {
+    const kv = /^([A-Za-z0-9_-]+):\s*(.*)$/.exec(line)
+    if (!kv) continue
+    data[kv[1]] = parseScalar(kv[2].trim())
+  }
+  return { data, body: raw.slice(m[0].length) }
+}
+
+// Parse a frontmatter scalar: quoted string, JSON array, number, or bare string.
+function parseScalar(v) {
+  if (v === '') return null
+  const unq = /^["'](.*)["']$/.exec(v)
+  if (unq) return unq[1]
+  if (v.startsWith('[')) {
+    try {
+      return JSON.parse(v)
+    } catch {
+      return v
+        .replace(/^\[|\]$/g, '')
+        .split(',')
+        .map((s) => s.trim().replace(/^["']|["']$/g, ''))
+        .filter(Boolean)
+    }
+  }
+  if (/^-?\d+(\.\d+)?$/.test(v)) return Number(v)
+  return v
+}
+
+// Split a markdown body into { title, sections } where sections maps a `## `
+// heading text → its content (until the next `## `). The H1 `# ` is the title.
+function parseSections(body) {
+  const lines = body.split('\n')
+  let title = null
+  const sections = {}
+  let current = null
+  let buf = []
+  const flush = () => {
+    if (current !== null) sections[current] = buf.join('\n').trim()
+  }
+  for (const line of lines) {
+    const h1 = /^#\s+(.*)$/.exec(line)
+    const h2 = /^##\s+(.*)$/.exec(line)
+    if (h1 && title === null) {
+      title = h1[1].trim()
+      continue
+    }
+    if (h2) {
+      flush()
+      current = h2[1].trim()
+      buf = []
+      continue
+    }
+    if (current !== null) buf.push(line)
+  }
+  flush()
+  return { title, sections }
+}
+
+// Canonical milestone status from the phase-index emoji.
+const EMOJI_STATUS = { '⬜': 'not-started', '🔄': 'in-progress', '✅': 'done' }
+
+// Parse the "## Phases" index table into [{ name, status }] rows.
+function parsePhaseIndex(phasesSection) {
+  if (!phasesSection) return []
+  const rows = []
+  for (const line of phasesSection.split('\n')) {
+    // | 1 | Phase name | ✅ | [01-…](01-…) |
+    const cells = line.split('|').map((c) => c.trim())
+    if (cells.length < 5) continue
+    const n = cells[1]
+    if (!/^\d+$/.test(n)) continue // skip header + separator rows
+    const name = cells[2]
+    const emoji = (cells[3].match(/[⬜🔄✅]/u) || [])[0]
+    rows.push({ name, status: EMOJI_STATUS[emoji] || 'not-started' })
+  }
+  return rows
+}
+
+// Read the phase files (01-*.md, 02-*.md …) in execution order.
+function readPhaseFiles(snapshotDir) {
+  let entries
+  try {
+    entries = fs.readdirSync(snapshotDir)
+  } catch {
+    return []
+  }
+  return entries
+    .filter((f) => /^\d\d-.*\.md$/.test(f) && !f.startsWith('00-'))
+    .sort()
+    .map((file) => {
+      const raw = fs.readFileSync(path.join(snapshotDir, file), 'utf-8')
+      const goal = (/^\*\*Goal:\*\*\s*([\s\S]*?)(?:\n\n|$)/m.exec(raw) || [])[1] || ''
+      const tasks = (raw.match(/^-\s*\[[ x]\]\s*.*$/gm) || []).map((t) =>
+        t.replace(/^-\s*/, '').trim(),
+      )
+      return { phase: file.replace(/\.md$/, ''), goal: goal.trim(), tasks }
+    })
+}
+
+// --- ownership-driven field set ---------------------------------------------
+
+// Reduce an `extracted` map to exactly the configured field keys, defaulting a
+// missing field to `null` so local and remote always share an identical set.
+function toFieldSet(extracted, config) {
+  const out = {}
+  for (const field of Object.keys(config.sync.fieldOwnership)) {
+    out[field] = field in extracted ? extracted[field] : null
+  }
+  return out
+}
+
+// --- local snapshot ---------------------------------------------------------
+
+/**
+ * Read a spec snapshot (its 00-overview.md + phase files) into the raw pieces the
+ * extractors and callers need. Pure aside from reads under `snapshotDir`.
+ */
+function readSnapshot(snapshotDir, config) {
+  const overviewFile = (config && config.snapshot && config.snapshot.overviewFile) || '00-overview.md'
+  const raw = fs.readFileSync(path.join(snapshotDir, overviewFile), 'utf-8')
+  const { data, body } = parseFrontmatter(raw)
+  const { title, sections } = parseSections(body)
+  const phases = readPhaseFiles(snapshotDir)
+  return { frontmatter: data, title, sections, phases, body }
+}
+
+// Build the pushed description: the overview prose with local-only sections
+// removed. Keeps the title line for context.
+function buildDescription(title, sections, localOnlySections) {
+  const skip = new Set(localOnlySections || [])
+  const parts = []
+  if (title) parts.push(`# ${title}`)
+  for (const [heading, content] of Object.entries(sections)) {
+    if (skip.has(heading)) continue
+    parts.push(`## ${heading}\n\n${content}`.trim())
+  }
+  return parts.join('\n\n').trim() || null
+}
+
+/**
+ * Normalize a local spec snapshot into the configured field set.
+ */
+function normalizeLocal(snapshotDir, config) {
+  const { frontmatter, title, sections, phases } = readSnapshot(snapshotDir, config)
+  const extracted = {
+    description: buildDescription(title, sections, config.sync.localOnlySections),
+    milestones: parsePhaseIndex(sections.Phases),
+    phaseBodies: phases.map((p) => ({ phase: p.phase, goal: p.goal })),
+    acceptanceCriteria: sections['Acceptance criteria'] || null,
+    taskBreakdown: phases.map((p) => ({ phase: p.phase, tasks: p.tasks })),
+    workflowState: frontmatter.spec_status != null ? String(frontmatter.spec_status) : null,
+    priority: frontmatter.priority != null ? frontmatter.priority : null,
+    labels: Array.isArray(frontmatter.labels) ? frontmatter.labels : [],
+  }
+  return toFieldSet(extracted, config)
+}
+
+// --- remote projection ------------------------------------------------------
+
+// Map a Linear workflow-state name back to the local lifecycle bucket (the
+// vocabulary `spec_status` uses) via config.states, so local and remote
+// workflowState hash equal when semantically equal. Falls back to a lowercased
+// raw value when the state isn't one of the configured names.
+function bucketForState(state, config) {
+  if (state == null) return null
+  const states = (config && config.states) || {}
+  const want = String(state).toLowerCase().trim()
+  for (const [bucket, name] of Object.entries(states)) {
+    if (typeof name === 'string' && name.toLowerCase().trim() === want) return bucket
+  }
+  return want
+}
+
+// Canonicalise a Linear workflow-state name into the same vocabulary the local
+// milestone emojis use, so equal states hash equal.
+function canonicalRemoteStatus(state) {
+  const s = String(state || '').toLowerCase().trim()
+  if (!s) return 'not-started'
+  if (/(done|complete|completed|merged)/.test(s)) return 'done'
+  if (/(progress|started|doing|review)/.test(s)) return 'in-progress'
+  if (/(backlog|todo|planned|triage)/.test(s)) return 'not-started'
+  return s
+}
+
+/**
+ * Normalize a Linear Project projection (from the Phase 2 MCP adapter, or a
+ * fixture) into the same field set as `normalizeLocal`.
+ */
+function normalizeRemote(project, config) {
+  const p = project || {}
+  const milestones = Array.isArray(p.milestones) ? p.milestones : []
+  const extracted = {
+    description: p.description != null ? p.description : null,
+    milestones: milestones.map((m) => ({
+      name: m.name,
+      status: canonicalRemoteStatus(m.status != null ? m.status : m.state),
+    })),
+    phaseBodies: milestones.map((m) => ({
+      phase: m.name,
+      goal: (m.description != null ? m.description : '').trim(),
+    })),
+    acceptanceCriteria: p.acceptanceCriteria != null ? p.acceptanceCriteria : null,
+    taskBreakdown: milestones.map((m) => ({
+      phase: m.name,
+      tasks: Array.isArray(m.tasks) ? m.tasks : [],
+    })),
+    workflowState: p.state != null ? bucketForState(p.state, config) : null,
+    priority: p.priority != null ? p.priority : null,
+    labels: Array.isArray(p.labels) ? p.labels : [],
+  }
+  return toFieldSet(extracted, config)
+}
+
+module.exports = {
+  normalizeLocal,
+  normalizeRemote,
+  readSnapshot,
+  parseFrontmatter,
+  parseSections,
+  parsePhaseIndex,
+  canonicalRemoteStatus,
+  bucketForState,
+}

package/src/sync/pull.js

@@ -0,0 +1,84 @@
+'use strict'
+
+/**
+ * `pull` — Linear → repo, three-way aware.
+ *
+ * Applies remote-only fields to the local snapshot; a `both`-owned field where
+ * both sides moved off base is a real **conflict** and pull refuses (unless
+ * `--force`, which makes remote win after backing up the local side). On success
+ * it rewrites the base for the fields it actually reconciled and stamps
+ * `last_synced_at`. Body fields with no local frontmatter home yet are reported
+ * as `deferred` and their base is deliberately left pending (not falsely synced).
+ *
+ * Pure orchestration over an injected `adapter` (readProject) + injected
+ * `timestamp`; no clock, no MCP knowledge here (that's mcp.js). Tests drive it
+ * with a fake in-memory adapter.
+ */
+
+const { normalizeLocal, normalizeRemote } = require('./normalize.js')
+const { classify } = require('./compare.js')
+const { readBase, writeBase, backup } = require('./base.js')
+const { writeFrontmatter } = require('./write.js')
+const { frontmatterPatchFor } = require('./apply.js')
+
+async function pull({ dir, snapshotDir, identifier, projectId, adapter, config, force = false, timestamp }) {
+  const local = normalizeLocal(snapshotDir, config)
+  const remoteRaw = await adapter.readProject(projectId)
+  if (!remoteRaw) {
+    return { ok: false, error: `Linear project not found: ${projectId}` }
+  }
+  const remote = normalizeRemote(remoteRaw, config)
+  const base = readBase(dir, identifier, config)
+  const fields = classify(local, remote, base, config)
+
+  const conflicts = fields.filter((f) => f.status === 'conflict').map((f) => f.field)
+  if (conflicts.length && !force) {
+    return {
+      ok: false,
+      blocked: true,
+      reason: 'conflict',
+      conflicts,
+      message: `pull refused — ${conflicts.length} field(s) changed on both sides: ` +
+        `${conflicts.join(', ')}. Resolve locally or re-run with --force (remote wins).`,
+    }
+  }
+
+  // Everything remote wants to write down: remote-only fields, plus (under force)
+  // both-conflict fields where remote wins.
+  const pullFields = fields.filter((f) => f.pullable)
+  const fieldValues = {}
+  for (const f of pullFields) fieldValues[f.field] = remote[f.field]
+
+  const { patch, applied, deferred } = frontmatterPatchFor(fieldValues, config)
+
+  // --force overwrites local edits — back the local side up first.
+  let backupPath = null
+  if (force) {
+    backupPath = backup('local', dir, identifier, config, { timestamp, data: local })
+  }
+
+  // Apply frontmatter-mapped fields + stamp the sync.
+  if (applied.length || timestamp) {
+    writeFrontmatter(snapshotDir, config, { ...patch, last_synced_at: timestamp })
+  }
+
+  // Advance base only for reconciled fields; deferred (body) fields keep the
+  // local value as base so the remote edit stays pending, not marked synced.
+  const newBase = { ...local }
+  for (const field of applied) newBase[field] = remote[field]
+  newBase.__meta = { updatedAt: remoteRaw.updatedAt || null, syncedAt: timestamp }
+  const basePath = writeBase(dir, identifier, config, newBase)
+
+  return {
+    ok: true,
+    blocked: false,
+    applied,
+    deferred,
+    conflictsForced: force ? conflicts : [],
+    backupPath,
+    basePath,
+    pulled: pullFields.map((f) => f.field),
+  }
+}
+
+module.exports = { pull }

package/src/sync/push.js

@@ -0,0 +1,106 @@
+'use strict'
+
+/**
+ * `push` — repo → Linear, three-way aware and ownership-respecting.
+ *
+ * Never writes a `pull`-owned field or a `localOnlySection` (those aren't in the
+ * pushable set / the field set at all). Optimistic concurrency: if the remote has
+ * moved past the base — detected both by the classifier (any remote-only/conflict
+ * field) and by the recorded `updatedAt` — it aborts with "pull first" unless
+ * `--force`. It also **re-reads the remote immediately before writing** to catch a
+ * writer that raced in during the compare. `--force` makes local win after backing
+ * up the remote side. On success it rewrites the base and stamps `last_synced_at`.
+ *
+ * Pure orchestration over an injected `adapter` (readProject + updateProject) and
+ * injected `timestamp`. Tests drive it with a fake in-memory adapter.
+ */
+
+const { normalizeLocal, normalizeRemote } = require('./normalize.js')
+const { classify } = require('./compare.js')
+const { readBase, writeBase, backup } = require('./base.js')
+const { writeFrontmatter } = require('./write.js')
+
+async function push({ dir, snapshotDir, identifier, projectId, adapter, config, force = false, timestamp }) {
+  const local = normalizeLocal(snapshotDir, config)
+  const remoteRaw = await adapter.readProject(projectId)
+  if (!remoteRaw) {
+    return { ok: false, error: `Linear project not found: ${projectId}` }
+  }
+  const remote = normalizeRemote(remoteRaw, config)
+  const base = readBase(dir, identifier, config)
+  const baseStamp = base && base.__meta ? base.__meta.updatedAt : null
+  const fields = classify(local, remote, base, config)
+
+  // Remote moved past base if the classifier sees remote-side divergence OR the
+  // recorded updatedAt no longer matches (a change we can't even see as a field).
+  const remoteDivergedFields = fields
+    .filter((f) => f.raw === 'remote-only' || f.raw === 'conflict')
+    .map((f) => f.field)
+  const stampMoved = baseStamp != null && remoteRaw.updatedAt !== baseStamp
+  const moved = remoteDivergedFields.length > 0 || stampMoved
+
+  if (moved && !force) {
+    return {
+      ok: false,
+      blocked: true,
+      reason: 'remote-moved',
+      movedFields: remoteDivergedFields,
+      message:
+        'push refused — Linear moved since the last sync' +
+        (remoteDivergedFields.length ? ` (${remoteDivergedFields.join(', ')})` : '') +
+        '. Pull first, or re-run with --force (local wins).',
+    }
+  }
+
+  const pushFields = fields.filter((f) => f.pushable)
+  if (!pushFields.length && !force) {
+    return { ok: true, blocked: false, written: [], skipped: [], note: 'nothing to push' }
+  }
+
+  // Optimistic concurrency: re-read immediately before writing to catch a racer.
+  const remoteRaw2 = await adapter.readProject(projectId)
+  if (remoteRaw2 && remoteRaw2.updatedAt !== remoteRaw.updatedAt && !force) {
+    return {
+      ok: false,
+      blocked: true,
+      reason: 'concurrent-write',
+      message: 'push refused — Linear changed during the push. Pull first, or --force.',
+    }
+  }
+
+  // --force clobbers the remote side — back it up first.
+  let backupPath = null
+  if (force) {
+    backupPath = backup('remote', dir, identifier, config, { timestamp, data: remoteRaw2 || remoteRaw })
+  }
+
+  const updates = {}
+  for (const f of pushFields) updates[f.field] = local[f.field]
+  const updated = (await adapter.updateProject(projectId, updates)) || remoteRaw2 || remoteRaw
+  const updatedRemote = normalizeRemote(updated, config)
+
+  // Reconciled base: local is the source of truth for the fields we pushed (and
+  // for unchanged/local-only fields); pull-owned fields keep Linear's value so
+  // they don't read as pending next time.
+  const newBase = { ...local }
+  for (const [field, own] of Object.entries(config.sync.fieldOwnership)) {
+    if (own === 'pull') newBase[field] = updatedRemote[field]
+  }
+  newBase.__meta = { updatedAt: updated.updatedAt || null, syncedAt: timestamp }
+  const basePath = writeBase(dir, identifier, config, newBase)
+
+  if (timestamp) writeFrontmatter(snapshotDir, config, { last_synced_at: timestamp })
+
+  return {
+    ok: true,
+    blocked: false,
+    written: pushFields.map((f) => f.field),
+    skipped: fields
+      .filter((f) => !f.pushable && f.status !== 'unchanged')
+      .map((f) => f.field),
+    backupPath,
+    basePath,
+  }
+}
+
+module.exports = { push }

package/src/sync/write.js

@@ -0,0 +1,86 @@
+'use strict'
+
+/**
+ * Local snapshot writes for pull (Linear → repo).
+ *
+ * Phase 2 applies **frontmatter-mapped** pulled fields — the `pull`-owned data
+ * Linear genuinely owns (`workflowState` → `spec_status`, `priority`, `labels`)
+ * plus sync bookkeeping (`last_synced_at`, ids) — by surgically editing the YAML
+ * frontmatter of `00-overview.md` and leaving the markdown body byte-for-byte
+ * untouched. Existing keys are updated in place (order preserved); new keys are
+ * appended; a file with no frontmatter gets one prepended.
+ *
+ * Body/`both`-owned fields (`description`, `milestones`, …) are NOT written back
+ * here — that denormalizer is a tracked follow-up (see the spec). Callers advance
+ * the base only for fields they actually applied, so an un-applied remote edit
+ * stays pending rather than being silently marked synced.
+ */
+
+const fs = require('node:fs')
+const path = require('node:path')
+
+// Serialize a JS value as a YAML-ish frontmatter scalar. null/undefined → the
+// key is dropped (caller shouldn't pass those).
+function serialize(value) {
+  if (Array.isArray(value)) return JSON.stringify(value)
+  if (typeof value === 'number' || typeof value === 'boolean') return String(value)
+  return JSON.stringify(String(value)) // quoted string
+}
+
+// Split `---\n…\n---\n` frontmatter off the top. Returns { fmLines, body, had }.
+function splitFrontmatter(raw) {
+  const m = /^---\n([\s\S]*?)\n---\n?/.exec(raw)
+  if (!m) return { fmLines: [], body: raw, had: false }
+  return { fmLines: m[1].split('\n'), body: raw.slice(m[0].length), had: true }
+}
+
+// Apply a key→value patch onto frontmatter lines, preserving order.
+function patchFrontmatterLines(lines, patch) {
+  const keys = new Set(Object.keys(patch))
+  const out = []
+  const seen = new Set()
+  for (const line of lines) {
+    const kv = /^([A-Za-z0-9_-]+):\s*(.*)$/.exec(line)
+    if (kv && keys.has(kv[1])) {
+      out.push(`${kv[1]}: ${serialize(patch[kv[1]])}`)
+      seen.add(kv[1])
+    } else {
+      out.push(line)
+    }
+  }
+  // Append any new keys not already present.
+  for (const key of Object.keys(patch)) {
+    if (!seen.has(key)) out.push(`${key}: ${serialize(patch[key])}`)
+  }
+  return out
+}
+
+/**
+ * Update `00-overview.md` frontmatter under `snapshotDir` with `patch`
+ * (key → value; nullish values are skipped). Returns the list of keys written.
+ */
+function writeFrontmatter(snapshotDir, config, patch) {
+  const overviewFile = (config && config.snapshot && config.snapshot.overviewFile) || '00-overview.md'
+  const file = path.join(snapshotDir, overviewFile)
+  const raw = fs.readFileSync(file, 'utf-8')
+
+  const clean = {}
+  for (const [k, v] of Object.entries(patch)) {
+    if (v !== null && v !== undefined) clean[k] = v
+  }
+  if (!Object.keys(clean).length) return []
+
+  const { fmLines, body, had } = splitFrontmatter(raw)
+  const patched = patchFrontmatterLines(fmLines, clean)
+  const frontmatter = `---\n${patched.join('\n')}\n---\n`
+  const next = had ? frontmatter + body : frontmatter + '\n' + raw
+
+  fs.writeFileSync(file, next, 'utf-8')
+  return Object.keys(clean)
+}
+
+module.exports = {
+  writeFrontmatter,
+  splitFrontmatter,
+  serialize,
+}