@skitterbyte/skitterspec-linear 7.0.1 → 8.0.0

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

@@ -1,147 +1,53 @@
 'use strict'
 
 /**
- * `push` — repo → remote, three-way aware and ownership-respecting.
+ * `push` — repo → Linear, one-way. The repo is the source of truth; Linear is a
+ * generated mirror. We never read remote content: `push` builds the local
+ * projection, diffs it against the committed **last-pushed snapshot**, and
+ * returns a **create/update plan** the provider skill applies over MCP.
  *
- * 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`.
+ * The skill: applies the plan → stamps each newly-created id back into the phase
+ * frontmatter / task line → calls `recordPush`, which re-reads the (now
+ * id-stamped) projection and writes the snapshot. That closes the loop: the next
+ * `push` sees an unchanged snapshot and produces an empty plan.
  *
- * Pure orchestration over an injected `adapter` (readProject + updateProject) and
- * injected `timestamp`. Tests drive it with a fake in-memory adapter.
+ * Pure aside from reading the snapshot; no adapter, no remote read, no
+ * Date.now(). `recordPush` writes the snapshot sidecar.
  */
 
-const { normalizeLocal, normalizeRemote } = require('./normalize.js')
-const { classify } = require('./compare.js')
-const { readBase, writeBase, backup } = require('./base.js')
-const { writeFrontmatter } = require('./write.js')
+const { normalizeLocal } = require('./normalize.js')
+const { planChanges, snapshotOf, isEmptyPlan } = require('./compare.js')
+const { readBase, writeBase } = require('./base.js')
 
-async function push({ dir, snapshotDir, identifier, projectId, adapter, config, force = false, timestamp }) {
+// Build the one-way projection from a local snapshot: the project prose + status,
+// and the milestone/issue items. `status` is the local lifecycle bucket; the
+// skill maps it to the Linear project-state NAME via config.states at apply time.
+function projectionOf(snapshotDir, config) {
   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)
-
-  // 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.
-  // 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.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) {
-    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).',
-    }
-  }
-
-  // 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' }
-  }
-
-  // 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 = 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
-  // 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]
+  return {
+    description: local.description ?? null,
+    status: local.workflowState ?? null,
+    priority: local.priority ?? null,
+    labels: Array.isArray(local.labels) ? local.labels : [],
+    milestones: Array.isArray(local.milestones) ? local.milestones : [],
+    issues: Array.isArray(local.tasks) ? local.tasks : [],
   }
-  newBase.__meta = { updatedAt: updated.updatedAt || null, syncedAt: timestamp }
-  const basePath = writeBase(dir, identifier, config, newBase)
+}
 
-  if (timestamp) writeFrontmatter(snapshotDir, config, { last_synced_at: timestamp })
+function push({ dir, snapshotDir, identifier, config }) {
+  const projection = projectionOf(snapshotDir, config)
+  const snapshot = readBase(dir, identifier, config)
+  const plan = planChanges(projection, snapshot)
+  return { ok: true, empty: isEmptyPlan(plan), plan, projection }
+}
 
-  return {
-    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.keyed && f.status !== 'unchanged')
-      .map((f) => f.field),
-    backupPath,
-    basePath,
-  }
+/**
+ * Record the last-pushed snapshot from the CURRENT files — call after the skill
+ * has applied the plan and stamped new ids. Returns the snapshot path.
+ */
+function recordPush({ dir, snapshotDir, identifier, config }) {
+  const projection = projectionOf(snapshotDir, config)
+  return writeBase(dir, identifier, config, snapshotOf(projection))
 }
 
-module.exports = { push }
+module.exports = { push, recordPush, projectionOf }

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

@@ -0,0 +1,143 @@
+'use strict'
+
+/**
+ * One-time sanitiser: rewrite spec markdown so no inline emphasis or link span
+ * straddles a hard line break, and repair any Linear-mangled `****` artifacts
+ * already committed. This brings hand-wrapped spec files "inline" so they round-
+ * trip through Linear cleanly (Linear mangles a straddling `**`/`*`/link on save).
+ *
+ * Deliberately minimal-diff: only a block that actually contains a straddle or a
+ * mangle is reflowed — every other paragraph, table, code fence, and heading is
+ * left byte-for-byte untouched. A reflowed block is re-wrapped emphasis-aware to
+ * the file's own inferred width, so spans stay whole. Idempotent: a second run is
+ * a no-op.
+ *
+ * Pure string→string (`sanitizeSpecMarkdown`); the CLI wraps it with fs walking.
+ */
+
+const { wrapEmphasisAware, collapseHyphenAware, inferWidth, DEFAULT_WIDTH } = require('./task-block.js')
+const { joinEmphasisAcrossBreaks } = require('./normalize.js')
+
+// A run of non-blank lines contains an emphasis straddle / mangle iff joining
+// spans across breaks changes it.
+function hasStraddle(text) {
+  return joinEmphasisAcrossBreaks(text) !== text
+}
+
+// Turn a multi-line region into its clean single logical line: repair mangles and
+// join straddles first (needs the newlines), then collapse whitespace — hyphen-
+// aware, so a compound wrapped at the hyphen isn't spaced out.
+function cleanLogicalLine(text) {
+  return collapseHyphenAware(joinEmphasisAcrossBreaks(text))
+}
+
+// A bullet line: indent, marker (`- `, `* `, `+ `, `1. `, optionally a `[ ]`/`[x]`
+// checkbox), then the text.
+const BULLET_RE = /^(\s*)((?:[-*+]|\d+\.)\s+(?:\[[ xX]\]\s+)?)(.*)$/
+// Structural blocks we never reflow.
+const PASSTHROUGH_RE = /^\s*(#{1,6}\s|>|\||[-*_]{3,}\s*$|<)/
+// A GFM table separator row (only pipes/colons/dashes/spaces, with a pipe AND a
+// dash). Detecting a table by this — not by any stray `|` — so a pipe inside an
+// inline `code|span` doesn't make us treat a whole list as an untouchable table.
+const TABLE_SEP_RE = /^[\s|:-]*\|[\s|:-]*-[\s|:-]*$|^[\s|:-]*-[\s|:-]*\|[\s|:-]*$/
+
+// Split a block (consecutive non-blank lines) into items when it's a list; each
+// item is its bullet line plus more-indented continuation lines.
+function splitListItems(block) {
+  const items = []
+  let cur = null
+  for (const line of block) {
+    if (BULLET_RE.test(line)) {
+      cur = [line]
+      items.push(cur)
+    } else if (cur) {
+      cur.push(line) // continuation of the current bullet
+    } else {
+      return null // leading non-bullet line — not a clean list block
+    }
+  }
+  return items
+}
+
+// Reflow one bullet item (raw lines) to width, emphasis-aware. Returns the item's
+// lines unchanged when it carries no straddle.
+function sanitizeItem(itemLines, width) {
+  const raw = itemLines.join('\n')
+  if (!hasStraddle(raw)) return { lines: itemLines, fixed: false }
+  const m = BULLET_RE.exec(itemLines[0])
+  const indent = m[1]
+  const marker = m[2]
+  const firstPrefix = indent + marker
+  const hang = ' '.repeat(firstPrefix.length)
+  // Body = the item's text (first line after the marker + continuations).
+  const bodyRaw = [m[3], ...itemLines.slice(1)].join('\n')
+  const body = cleanLogicalLine(bodyRaw)
+  return { lines: wrapEmphasisAware(body, { firstPrefix, hang, width }), fixed: true }
+}
+
+// Reflow a plain prose paragraph (raw lines) to width, preserving its leading
+// indent. Unchanged when it carries no straddle.
+function sanitizeProse(block, width) {
+  const raw = block.join('\n')
+  if (!hasStraddle(raw)) return { lines: block, fixed: false }
+  const indent = (/^(\s*)/.exec(block[0]) || ['', ''])[1]
+  const body = cleanLogicalLine(raw)
+  return { lines: wrapEmphasisAware(body, { firstPrefix: indent, hang: indent, width }), fixed: true }
+}
+
+/**
+ * Sanitise one markdown document.
+ * @returns {{ text:string, changed:boolean, fixes:number }} fixes = blocks/items reflowed.
+ */
+function sanitizeSpecMarkdown(text, { width } = {}) {
+  const src = String(text)
+  const lines = src.split('\n')
+  const w = width || inferWidth(lines) || DEFAULT_WIDTH
+  const out = []
+  let i = 0
+  let fixes = 0
+  while (i < lines.length) {
+    const line = lines[i]
+    // Fenced code — copy verbatim through the closing fence.
+    if (/^[ \t]*```/.test(line)) {
+      out.push(line)
+      i++
+      while (i < lines.length && !/^[ \t]*```/.test(lines[i])) out.push(lines[i++])
+      if (i < lines.length) out.push(lines[i++])
+      continue
+    }
+    if (!line.trim()) {
+      out.push(line)
+      i++
+      continue
+    }
+    // Gather a block of consecutive non-blank, non-fence lines.
+    let j = i
+    while (j < lines.length && lines[j].trim() && !/^[ \t]*```/.test(lines[j])) j++
+    const block = lines.slice(i, j)
+    i = j
+
+    // Never reflow structural blocks (headings, tables, quotes, rules, HTML).
+    if (PASSTHROUGH_RE.test(block[0]) || block.some((l) => TABLE_SEP_RE.test(l))) {
+      out.push(...block)
+      continue
+    }
+
+    const items = BULLET_RE.test(block[0]) ? splitListItems(block) : null
+    if (items) {
+      for (const it of items) {
+        const r = sanitizeItem(it, w)
+        out.push(...r.lines)
+        if (r.fixed) fixes++
+      }
+    } else {
+      const r = sanitizeProse(block, w)
+      out.push(...r.lines)
+      if (r.fixed) fixes++
+    }
+  }
+  const result = out.join('\n')
+  return { text: result, changed: result !== src, fixes }
+}
+
+module.exports = { sanitizeSpecMarkdown, hasStraddle }

package/src/vendor/sync-core/src/task-block.js

@@ -26,6 +26,51 @@ function collapse(text) {
   return String(text).replace(/\s+/g, ' ').trim()
 }
 
+// Like `collapse`, but a word wrapped at a hyphen (`state-entry-with-`⏎
+// `assignment`) rejoins TIGHT — one compound — instead of gaining a space. Every
+// other break collapses to a single space. Use this wherever hand-wrapped prose
+// is flattened to one logical line, so a hard wrap at a hyphen isn't data loss.
+function collapseHyphenAware(text) {
+  return String(text)
+    .replace(/(\w-)[ \t]*\n[ \t]*(?=\w)/g, '$1')
+    .replace(/\s+/g, ' ')
+    .trim()
+}
+
+// Mark every character of `body` that lies inside an inline emphasis or link
+// span — `**bold**`, `*italic*`, `[text](url)` — so wrapping can avoid breaking
+// one across a line (Linear mangles a straddling `**`/`*`/link on save). Code
+// spans are exempt (Linear only rejoins them, harmlessly) but their contents are
+// neutralised first so a `*` inside code can't spoof an italic marker.
+function spanMask(body) {
+  const mask = new Array(body.length).fill(false)
+  // Neutralise code-span contents to same-length filler (indices stay aligned).
+  const chars = body.split('')
+  let m
+  const codeRe = /`[^`]*`/g
+  while ((m = codeRe.exec(body)) !== null) {
+    for (let i = m.index; i < m.index + m[0].length; i++) chars[i] = 'x'
+  }
+  let masked = chars.join('')
+  const cover = (re) => {
+    re.lastIndex = 0
+    let mm
+    while ((mm = re.exec(masked)) !== null) {
+      for (let i = mm.index; i < mm.index + mm[0].length; i++) mask[i] = true
+      if (mm[0].length === 0) re.lastIndex++
+    }
+  }
+  cover(/\*\*.+?\*\*/g) // bold
+  cover(/\[[^\]]*\]\([^)]*\)/g) // link
+  // Neutralise the bold/link spans already found, so their asterisks aren't
+  // reused when scanning for single-`*` italics.
+  const m2 = masked.split('')
+  for (let i = 0; i < mask.length; i++) if (mask[i]) m2[i] = 'x'
+  masked = m2.join('')
+  cover(/\*[^*]+?\*/g) // italic
+  return mask
+}
+
 /**
  * Find every task bullet in `lines` as a logical block.
  * @returns {Array<{start:number, end:number, indent:string, mark:string, text:string}>}
@@ -50,7 +95,7 @@ function findTaskBlocks(lines) {
       end: j,
       indent: m[1],
       mark: m[2].toLowerCase() === 'x' ? 'x' : ' ',
-      text: collapse(parts.join(' ')),
+      text: collapseHyphenAware(parts.join('\n')),
     })
     i = j - 1
   }
@@ -62,16 +107,34 @@ function findTaskBlocks(lines) {
  * style: `- [x] ` opener, continuations aligned under the text.
  * @returns {string[]}
  */
-function renderTaskBlock({ indent = '', done, text, id }, width = DEFAULT_WIDTH) {
-  const opener = `${indent}- [${done ? 'x' : ' '}] `
-  const hang = ' '.repeat(opener.length)
-  const body = collapse(text) + (id ? ` (${id})` : '')
+// Wrap `body` (a single logical line) into file lines, emphasis-aware: a break is
+// only taken at a word gap that lies OUTSIDE every `**`/`*`/link span, so an
+// emphasis run never straddles a line (Linear mangles one that does). The first
+// line is prefixed with `firstPrefix`, continuations with `hang`. An over-width
+// single span overflows rather than being split.
+function wrapEmphasisAware(body, { firstPrefix = '', hang = '', width = DEFAULT_WIDTH } = {}) {
+  const mask = spanMask(body)
+  const words = body.split(' ')
+  // The index in `body` of the space that precedes each word.
+  const spaceBefore = []
+  let pos = 0
+  for (let k = 0; k < words.length; k++) {
+    if (k > 0) {
+      spaceBefore[k] = pos
+      pos += 1
+    }
+    pos += words[k].length
+  }
 
   const out = []
-  let line = opener
+  let line = firstPrefix
   let first = true
-  for (const word of body.split(' ')) {
-    if (!first && line.length + 1 + word.length > width) {
+  for (let k = 0; k < words.length; k++) {
+    const word = words[k]
+    // Break only at a safe gap; a gap inside a span overflows instead of
+    // splitting it (so an over-width single span stays whole on one line).
+    const canBreak = k > 0 && !mask[spaceBefore[k]]
+    if (!first && canBreak && line.length + 1 + word.length > width) {
       out.push(line)
       line = hang + word
     } else {
@@ -83,13 +146,43 @@ function renderTaskBlock({ indent = '', done, text, id }, width = DEFAULT_WIDTH)
   return out
 }
 
+function renderTaskBlock({ indent = '', done, text, id }, width = DEFAULT_WIDTH) {
+  const opener = `${indent}- [${done ? 'x' : ' '}] `
+  const hang = ' '.repeat(opener.length)
+  const body = collapse(text) + (id ? ` (${id})` : '')
+  return wrapEmphasisAware(body, { firstPrefix: opener, hang, width })
+}
+
 // Infer the wrap width a file already uses, so a rewrite doesn't reflow it to a
-// different column. Falls back to the default when there's nothing to learn from.
+// different column. Only *prose* lines count — a single wide table row or a long
+// line of fenced code would otherwise pull the whole file's prose to a wider
+// column than the author wrapped at. Falls back to the default when there's
+// nothing prose-like to learn from.
 function inferWidth(lines, fallback = DEFAULT_WIDTH) {
-  const widths = lines.filter((l) => l.trim()).map((l) => l.length)
+  let inFence = false
+  const widths = []
+  for (const l of lines) {
+    if (/^[ \t]*```/.test(l)) {
+      inFence = !inFence
+      continue
+    }
+    if (inFence) continue
+    if (!l.trim()) continue
+    if (l.includes('|')) continue // table row
+    widths.push(l.length)
+  }
   if (!widths.length) return fallback
   const max = Math.max(...widths)
   return max > 40 && max <= 120 ? Math.max(max, 60) : fallback
 }
 
-module.exports = { findTaskBlocks, renderTaskBlock, collapse, inferWidth, DEFAULT_WIDTH }
+module.exports = {
+  findTaskBlocks,
+  renderTaskBlock,
+  wrapEmphasisAware,
+  spanMask,
+  collapse,
+  collapseHyphenAware,
+  inferWidth,
+  DEFAULT_WIDTH,
+}