@skitterbyte/skitterspec-linear 1.0.0

package/src/vendor/sync-core/src/base.js

@@ -0,0 +1,83 @@
+'use strict'
+
+/**
+ * The committed base sidecar + the backup-before-force reflog.
+ *
+ * The base is the last-synced snapshot per spec, stored at
+ * `{sync.baseDir}/{identifier}.base.json` and committed so each worktree carries
+ * its own base and the three-way divergence check stays accurate. After any
+ * successful pull/push/force the engine rewrites it (`writeBase`).
+ *
+ * `backup(side, …)` lands the about-to-be-clobbered side under `{sync.backupDir}`
+ * BEFORE a `--force` overwrites it — force never destroys without first writing a
+ * copy. The filename carries a caller-supplied timestamp (the engine takes no
+ * Date.now(), for reproducible tests) and is made collision-safe with a counter.
+ */
+
+const fs = require('node:fs')
+const path = require('node:path')
+
+function baseFile(dir, identifier, config) {
+  return path.join(dir, config.sync.baseDir, `${identifier}.base.json`)
+}
+
+/**
+ * Read a spec's committed base. Returns the parsed object, or `null` when no base
+ * exists yet (never synced) — the compare treats null as "no prior state".
+ */
+function readBase(dir, identifier, config) {
+  const file = baseFile(dir, identifier, config)
+  let raw
+  try {
+    raw = fs.readFileSync(file, 'utf-8')
+  } catch (error) {
+    if (error.code === 'ENOENT') return null
+    throw error
+  }
+  try {
+    return JSON.parse(raw)
+  } catch (error) {
+    throw new Error(`Invalid base ${path.relative(dir, file)}: ${error.message}`)
+  }
+}
+
+/**
+ * Rewrite a spec's committed base with the freshly-synced field set. Creates
+ * `{sync.baseDir}` if needed. Returns the absolute path written.
+ */
+function writeBase(dir, identifier, config, data) {
+  const file = baseFile(dir, identifier, config)
+  fs.mkdirSync(path.dirname(file), { recursive: true })
+  fs.writeFileSync(file, JSON.stringify(data, null, 2) + '\n', 'utf-8')
+  return file
+}
+
+/**
+ * Back up the about-to-be-clobbered `side` ('local' | 'remote') into
+ * `{sync.backupDir}` before a --force. `timestamp` is caller-supplied (the engine
+ * never reads the clock); the name is made collision-safe with a `-N` counter.
+ * Returns the absolute path written, or null when `data` is nullish (nothing to
+ * back up — e.g. forcing a pull with no prior remote).
+ */
+function backup(side, dir, identifier, config, { timestamp, data }) {
+  if (data == null) return null
+  const backupRoot = path.join(dir, config.sync.backupDir)
+  fs.mkdirSync(backupRoot, { recursive: true })
+
+  const stem = `${identifier}.${side}.${timestamp}`
+  let file = path.join(backupRoot, `${stem}.json`)
+  let n = 1
+  while (fs.existsSync(file)) {
+    file = path.join(backupRoot, `${stem}-${n}.json`)
+    n += 1
+  }
+  fs.writeFileSync(file, JSON.stringify(data, null, 2) + '\n', 'utf-8')
+  return file
+}
+
+module.exports = {
+  readBase,
+  writeBase,
+  backup,
+  baseFile,
+}

package/src/vendor/sync-core/src/compare.js

@@ -0,0 +1,99 @@
+'use strict'
+
+/**
+ * The three-way compare at the heart of the hybrid sync.
+ *
+ * `classify(local, remote, base, config)` compares each configured field across
+ * the local snapshot, the remote (remote) projection, and the committed base
+ * (the last-synced state). Per field it returns a raw three-way `status`
+ * (unchanged / local-only / remote-only / conflict), then collapses it through
+ * the field's ownership (`both|pull|push`) into effective `pushable` / `pullable`
+ * flags. Ownership is what makes most "both sides differ" cases *not* a real
+ * conflict:
+ *   - a `pull` field never pushes (remote wins) → conflict collapses to remote-only
+ *   - a `push` field never pulls (repo wins)    → conflict collapses to local-only
+ *   - only a `both` field where both sides moved off base is a true `conflict`.
+ *
+ * Pure and deterministic: field identity is a stable content hash (sorted-key
+ * JSON → SHA-1), so `null`, `undefined`, and a missing base all compare equal,
+ * and object key order never causes a false diff. No Date.now()/Math.random().
+ */
+
+const { createHash } = require('node:crypto')
+
+// Deterministic JSON: object keys sorted recursively; array order preserved
+// (order is meaningful for milestones/tasks). undefined normalises to null.
+function stableStringify(value) {
+  if (value === undefined || value === null) return 'null'
+  if (Array.isArray(value)) {
+    return '[' + value.map(stableStringify).join(',') + ']'
+  }
+  if (typeof value === 'object') {
+    const keys = Object.keys(value).sort()
+    return '{' + keys.map((k) => JSON.stringify(k) + ':' + stableStringify(value[k])).join(',') + '}'
+  }
+  return JSON.stringify(value)
+}
+
+// Stable content hash of a single field value.
+function hashField(value) {
+  return createHash('sha1').update(stableStringify(value)).digest('hex')
+}
+
+// Raw three-way status from the three hashes.
+function rawStatus(localH, remoteH, baseH) {
+  const localChanged = localH !== baseH
+  const remoteChanged = remoteH !== baseH
+  if (!localChanged && !remoteChanged) return 'unchanged'
+  if (localChanged && !remoteChanged) return 'local-only'
+  if (!localChanged && remoteChanged) return 'remote-only'
+  // both moved off base — but they may have converged on the same value.
+  if (localH === remoteH) return 'unchanged'
+  return 'conflict'
+}
+
+// Collapse the raw status through ownership into an effective status + flags.
+function collapse(raw, ownership) {
+  const canPush = ownership === 'both' || ownership === 'push'
+  const canPull = ownership === 'both' || ownership === 'pull'
+
+  if (raw === 'unchanged') return { status: 'unchanged', pushable: false, pullable: false }
+  if (raw === 'local-only') return { status: 'local-only', pushable: canPush, pullable: false }
+  if (raw === 'remote-only') return { status: 'remote-only', pushable: false, pullable: canPull }
+
+  // conflict: both sides diverged off base.
+  if (ownership === 'push') return { status: 'local-only', pushable: true, pullable: false }
+  if (ownership === 'pull') return { status: 'remote-only', pushable: false, pullable: true }
+  return { status: 'conflict', pushable: true, pullable: true }
+}
+
+/**
+ * Classify every field in `config.sync.fieldOwnership`.
+ *
+ * @param {object} local  normalized local snapshot (normalizeLocal output)
+ * @param {object} remote normalized remote projection (normalizeRemote output)
+ * @param {object|null} base the committed base (same shape) or null (never synced)
+ * @returns {Array<{field, ownership, raw, status, pushable, pullable}>}
+ *   one entry per configured field, in config order.
+ */
+function classify(local, remote, base, config) {
+  const ownership = config.sync.fieldOwnership
+  const baseObj = base || {}
+  return Object.keys(ownership).map((field) => {
+    const own = ownership[field]
+    const localH = hashField(local ? local[field] : null)
+    const remoteH = hashField(remote ? remote[field] : null)
+    const baseH = hashField(field in baseObj ? baseObj[field] : null)
+    const raw = rawStatus(localH, remoteH, baseH)
+    const { status, pushable, pullable } = collapse(raw, own)
+    return { field, ownership: own, raw, status, pushable, pullable }
+  })
+}
+
+module.exports = {
+  classify,
+  hashField,
+  stableStringify,
+  rawStatus,
+  collapse,
+}

package/src/vendor/sync-core/src/normalize.js

@@ -0,0 +1,249 @@
+'use strict'
+
+/**
+ * Normalize a remote 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 remote.
+ */
+
+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 remote 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 remote 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 remote 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/vendor/sync-core/src/pull.js

@@ -0,0 +1,84 @@
+'use strict'
+
+/**
+ * `pull` — remote → 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: `remote 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/vendor/sync-core/src/push.js

@@ -0,0 +1,106 @@
+'use strict'
+
+/**
+ * `push` — repo → remote, 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: `remote 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 — remote 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 — remote 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 remote'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 }