@skitterbyte/skitterspec 1.0.0 → 2.0.0

package/src/sync/normalize.js

@@ -1,249 +0,0 @@
-'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

@@ -1,84 +0,0 @@
-'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

@@ -1,106 +0,0 @@
-'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

@@ -1,86 +0,0 @@
-'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,
-}