@skitterbyte/skitterspec-linear 3.4.0 → 5.0.0

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

@@ -32,13 +32,17 @@ async function push({ dir, snapshotDir, identifier, projectId, adapter, config,
 
   // Remote moved past base only if a *co-authored* (`both`) field diverged on the
   // remote side — that's the case the repo can't safely overwrite without a pull.
-  // A `pull`-owned change (status/priority/labels) is Linear's to own and must
-  // NOT block a content push, and a bare `updatedAt` bump (which any Linear edit
-  // produces) is too coarse to gate on — the pre-write re-read below still catches
-  // a racer that lands during the push itself.
+  // For a keyed field the equivalent is a same-item conflict (independent edits to
+  // different items don't collide, so they don't block). A `pull`-owned change
+  // (status/priority/labels) is Linear's to own and must NOT block a content push,
+  // and a bare `updatedAt` bump is too coarse to gate on — the pre-write re-read
+  // below still catches a racer that lands during the push itself.
   const remoteDivergedFields = fields
-    .filter((f) => f.ownership === 'both' && (f.raw === 'remote-only' || f.raw === 'conflict'))
+    .filter((f) => !f.keyed && f.ownership === 'both' && (f.raw === 'remote-only' || f.raw === 'conflict'))
     .map((f) => f.field)
+  for (const f of fields) {
+    if (f.keyed) for (const it of f.items) if (it.status === 'conflict') remoteDivergedFields.push(`${f.field}#${it.id}`)
+  }
   const moved = remoteDivergedFields.length > 0
 
   if (moved && !force) {
@@ -54,8 +58,37 @@ async function push({ dir, snapshotDir, identifier, projectId, adapter, config,
     }
   }
 
-  const pushFields = fields.filter((f) => f.pushable)
-  if (!pushFields.length && !force) {
+  // Scalar push goes through the project adapter here. Keyed body fields
+  // (milestones) can't be written by the offline engine — the provider skill does
+  // the MCP create/update and stamps new ids — so the engine emits a *plan* the
+  // skill applies. The base still advances to local (below): a created milestone's
+  // id:null item is skipped by the keyed compare until the skill stamps it, then
+  // it converges on the next sync, so no special base handling is needed.
+  const pushFields = fields.filter((f) => f.pushable && !f.keyed)
+  // A per-field create/update plan for each keyed collection. The item content
+  // (minus its id) is exactly what the skill sends to the Linear save tool.
+  const keyedPush = {}
+  for (const f of fields) {
+    if (!f.keyed) continue
+    const strip = (obj) => {
+      const { [f.idKey]: _omit, ...rest } = obj
+      return rest
+    }
+    const plan = { create: [], update: [] }
+    // Edits to already-linked items (matched by id) → update.
+    for (const it of f.items) {
+      if (!it.pushable || !it.local) continue
+      if (it.status !== 'added') plan.update.push({ id: it.id, ...strip(it.local) })
+    }
+    // Unlinked local items (no id yet) are new content to create; the keyed
+    // compare skips them (nothing to key on), so collect them straight from local.
+    const localItems = Array.isArray(local[f.field]) ? local[f.field] : []
+    for (const li of localItems) if (li && li[f.idKey] == null) plan.create.push(strip(li))
+    if (plan.create.length || plan.update.length) keyedPush[f.field] = plan
+  }
+  const hasKeyedPush = Object.keys(keyedPush).length > 0
+
+  if (!pushFields.length && !hasKeyedPush && !force) {
     return { ok: true, blocked: false, written: [], skipped: [], note: 'nothing to push' }
   }
 
@@ -78,7 +111,9 @@ async function push({ dir, snapshotDir, identifier, projectId, adapter, config,
 
   const updates = {}
   for (const f of pushFields) updates[f.field] = local[f.field]
-  const updated = (await adapter.updateProject(projectId, updates)) || remoteRaw2 || remoteRaw
+  const updated = Object.keys(updates).length
+    ? (await adapter.updateProject(projectId, updates)) || remoteRaw2 || remoteRaw
+    : remoteRaw2 || remoteRaw
   const updatedRemote = normalizeRemote(updated, config)
 
   // Reconciled base: local is the source of truth for the fields we pushed (and
@@ -97,8 +132,12 @@ async function push({ dir, snapshotDir, identifier, projectId, adapter, config,
     ok: true,
     blocked: false,
     written: pushFields.map((f) => f.field),
+    // The skill applies these Linear writes (create → stamp the new id back into
+    // the phase file / task line; update → save by id). Omitted when empty.
+    ...(keyedPush.milestones ? { milestonesPush: keyedPush.milestones } : {}),
+    ...(keyedPush.tasks ? { issuesPush: keyedPush.tasks } : {}),
     skipped: fields
-      .filter((f) => !f.pushable && f.status !== 'unchanged')
+      .filter((f) => !f.pushable && !f.keyed && f.status !== 'unchanged')
       .map((f) => f.field),
     backupPath,
     basePath,

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

@@ -79,8 +79,255 @@ function writeFrontmatter(snapshotDir, config, patch) {
   return Object.keys(clean)
 }
 
+// --- phase-file denormalizer (keyed milestone pull) ------------------------
+//
+// Writes pulled milestone edits back into the *body* — the phase files — which
+// the frontmatter writer above never touches. An edit updates the matching phase
+// file (by its linear_milestone_id) in place, leaving everything else
+// byte-untouched; a Linear-only milestone becomes a new phase file. Removals are
+// never applied here (report-only, Decision 7).
+
+// Phase files in a snapshot dir (01-*.md …), execution order.
+function listPhaseFiles(snapshotDir) {
+  try {
+    return fs
+      .readdirSync(snapshotDir)
+      .filter((f) => /^\d\d-.*\.md$/.test(f) && !f.startsWith('00-'))
+      .sort()
+  } catch {
+    return []
+  }
+}
+
+// The linear_milestone_id recorded in a phase file's frontmatter, or null.
+function phaseMilestoneId(raw) {
+  const { fmLines } = splitFrontmatter(raw)
+  for (const line of fmLines) {
+    const m = /^linear_milestone_id:\s*(.*)$/.exec(line)
+    if (m) return m[1].trim().replace(/^["']|["']$/g, '') || null
+  }
+  return null
+}
+
+// Find the phase file linked to a milestone id, or null.
+function findPhaseFileByMilestoneId(snapshotDir, id) {
+  const want = String(id)
+  for (const file of listPhaseFiles(snapshotDir)) {
+    const raw = fs.readFileSync(path.join(snapshotDir, file), 'utf-8')
+    if (phaseMilestoneId(raw) === want) return file
+  }
+  return null
+}
+
+// Find the phase file whose h1 title matches `name` (used to link a freshly
+// created milestone back to the phase it came from, before it has an id).
+function findPhaseFileByTitle(snapshotDir, name) {
+  const want = String(name).trim()
+  for (const file of listPhaseFiles(snapshotDir)) {
+    const raw = fs.readFileSync(path.join(snapshotDir, file), 'utf-8')
+    const h1 = /^#\s+(.*)$/m.exec(splitFrontmatter(raw).body)
+    if (!h1) continue
+    const title = h1[1]
+      .replace(/\s*[⬜🔄✅]\s*$/u, '')
+      .replace(/^Phase\s+\d+\s*[—–-]\s*/i, '')
+      .trim()
+    if (title === want) return file
+  }
+  return null
+}
+
+// Update a phase file's title (h1, preserving the "Phase N — " prefix + status
+// emoji) and its `**Goal:**` line, leaving everything else untouched.
+function writeMilestoneFields(snapshotDir, file, { name, goal }) {
+  const p = path.join(snapshotDir, file)
+  let raw = fs.readFileSync(p, 'utf-8')
+  if (name != null) {
+    raw = raw.replace(/^(#[ \t]+)(.*)$/m, (_full, hash, rest) => {
+      const pm = /^(Phase\s+\d+\s*[—–-]\s*)(.*?)(\s*[⬜🔄✅])?\s*$/.exec(rest)
+      return pm ? `${hash}${pm[1]}${name}${pm[3] || ''}` : `${hash}${name}`
+    })
+  }
+  if (goal != null && /^\*\*Goal:\*\*/m.test(raw)) {
+    raw = raw.replace(/^(\*\*Goal:\*\*[ \t]*).*$/m, `$1${goal}`)
+  }
+  fs.writeFileSync(p, raw, 'utf-8')
+}
+
+// Add/update linear_milestone_id in a phase file's frontmatter (in place).
+function stampMilestoneId(snapshotDir, file, id) {
+  const p = path.join(snapshotDir, file)
+  const raw = fs.readFileSync(p, 'utf-8')
+  const { fmLines, body, had } = splitFrontmatter(raw)
+  const patched = patchFrontmatterLines(fmLines, { linear_milestone_id: String(id) })
+  const fm = `---\n${patched.join('\n')}\n---\n`
+  fs.writeFileSync(p, had ? fm + body : fm + '\n' + raw, 'utf-8')
+}
+
+const slugify = (name) =>
+  String(name || 'phase')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 40) || 'phase'
+
+// Next phase number (max existing + 1).
+function nextPhaseNumber(snapshotDir) {
+  const nums = listPhaseFiles(snapshotDir)
+    .map((f) => parseInt(f.slice(0, 2), 10))
+    .filter(Number.isFinite)
+  return nums.length ? Math.max(...nums) + 1 : 1
+}
+
+// Create a new phase file for a Linear-only milestone. Returns the filename.
+function createPhaseFileForMilestone(snapshotDir, { id, name, goal }) {
+  const n = nextPhaseNumber(snapshotDir)
+  const file = `${String(n).padStart(2, '0')}-${slugify(name)}.md`
+  const content =
+    `---\nlinear_milestone_id: ${JSON.stringify(String(id))}\n---\n\n` +
+    `# Phase ${n} — ${name || 'Untitled'} ⬜\n\n` +
+    `> Spec: [00-overview.md](00-overview.md) · **Status:** Not started\n\n` +
+    `**Goal:** ${goal || ''}\n\n## Tasks\n\n- [ ] (pulled from Linear — flesh out)\n`
+  fs.writeFileSync(path.join(snapshotDir, file), content, 'utf-8')
+  return file
+}
+
+/**
+ * Apply a pull's keyed milestone item outcomes to the phase files.
+ * @param items classifyItems output for the milestones field.
+ * @returns { applied:string[], created:Array<{id,file}>, reported:string[] }
+ */
+function applyMilestonesPull(snapshotDir, items) {
+  const applied = []
+  const created = []
+  const reported = []
+  for (const it of items || []) {
+    if (it.report) {
+      reported.push(it.id)
+      continue
+    }
+    if (!it.pullable || !it.remote) continue
+    if (it.status === 'added') {
+      const file = createPhaseFileForMilestone(snapshotDir, it.remote)
+      created.push({ id: it.id, file })
+    } else if (it.status === 'edited' || it.status === 'conflict') {
+      const file = findPhaseFileByMilestoneId(snapshotDir, it.id)
+      if (file) {
+        writeMilestoneFields(snapshotDir, file, it.remote)
+        applied.push(it.id)
+      }
+    }
+  }
+  return { applied, created, reported }
+}
+
+// --- task-line denormalizer (keyed issue pull) -----------------------------
+//
+// Tasks live as checkbox lines inside phase files. A pulled issue edit rewrites
+// the matching line (by its inline id) in place; a Linear-only issue appends a
+// new task line; a created issue's id is stamped inline. Removals report-only.
+
+const TASK_RE = /^(\s*)-\s*\[([ xX])\]\s*(.*)$/
+const INLINE_ID_RE = /\s*\(([A-Za-z][A-Za-z0-9]*-\d+)\)\s*$/
+
+// Render a task line from an item.
+function taskLine(indent, { id, text, done }) {
+  return `${indent}- [${done ? 'x' : ' '}] ${text}${id ? ` (${id})` : ''}`
+}
+
+// Update the task line carrying inline id `id` (text + checkbox), in place.
+function updateTaskLine(snapshotDir, id, { text, done }) {
+  const want = String(id)
+  for (const file of listPhaseFiles(snapshotDir)) {
+    const p = path.join(snapshotDir, file)
+    const lines = fs.readFileSync(p, 'utf-8').split('\n')
+    for (let i = 0; i < lines.length; i++) {
+      const m = TASK_RE.exec(lines[i])
+      if (!m) continue
+      const idm = INLINE_ID_RE.exec(m[3])
+      if (idm && idm[1] === want) {
+        lines[i] = taskLine(m[1], { id: want, text, done })
+        fs.writeFileSync(p, lines.join('\n'), 'utf-8')
+        return true
+      }
+    }
+  }
+  return false
+}
+
+// Append a task line for a Linear-only issue after the last existing task line
+// (falls back to end of the last phase file). Returns the file it landed in.
+function addTaskLine(snapshotDir, item) {
+  const files = listPhaseFiles(snapshotDir)
+  const file = files[files.length - 1]
+  if (!file) return null
+  const p = path.join(snapshotDir, file)
+  const lines = fs.readFileSync(p, 'utf-8').split('\n')
+  let lastTask = -1
+  for (let i = 0; i < lines.length; i++) if (TASK_RE.test(lines[i])) lastTask = i
+  const line = taskLine('', item)
+  if (lastTask >= 0) lines.splice(lastTask + 1, 0, line)
+  else lines.push(line)
+  fs.writeFileSync(p, lines.join('\n'), 'utf-8')
+  return file
+}
+
+// Stamp an inline id onto the (idless) task line whose text matches — used after
+// the skill creates an issue for a new local task.
+function stampIssueId(snapshotDir, text, id) {
+  const want = String(text).trim()
+  for (const file of listPhaseFiles(snapshotDir)) {
+    const p = path.join(snapshotDir, file)
+    const lines = fs.readFileSync(p, 'utf-8').split('\n')
+    for (let i = 0; i < lines.length; i++) {
+      const m = TASK_RE.exec(lines[i])
+      if (!m || INLINE_ID_RE.test(m[3])) continue
+      if (m[3].trim() === want) {
+        lines[i] = `${m[1]}- [${m[2].toLowerCase() === 'x' ? 'x' : ' '}] ${want} (${id})`
+        fs.writeFileSync(p, lines.join('\n'), 'utf-8')
+        return file
+      }
+    }
+  }
+  return null
+}
+
+/**
+ * Apply a pull's keyed task item outcomes to the phase files' task lines.
+ * @returns { applied:string[], created:Array<{id,file}>, reported:string[] }
+ */
+function applyTasksPull(snapshotDir, items) {
+  const applied = []
+  const created = []
+  const reported = []
+  for (const it of items || []) {
+    if (it.report) {
+      reported.push(it.id)
+      continue
+    }
+    if (!it.pullable || !it.remote) continue
+    if (it.status === 'added') {
+      const file = addTaskLine(snapshotDir, it.remote)
+      if (file) created.push({ id: it.id, file })
+    } else if (it.status === 'edited' || it.status === 'conflict') {
+      if (updateTaskLine(snapshotDir, it.id, it.remote)) applied.push(it.id)
+    }
+  }
+  return { applied, created, reported }
+}
+
 module.exports = {
   writeFrontmatter,
   splitFrontmatter,
   serialize,
+  listPhaseFiles,
+  findPhaseFileByMilestoneId,
+  findPhaseFileByTitle,
+  writeMilestoneFields,
+  stampMilestoneId,
+  createPhaseFileForMilestone,
+  applyMilestonesPull,
+  updateTaskLine,
+  addTaskLine,
+  stampIssueId,
+  applyTasksPull,
 }