@skitterbyte/skitterspec-linear 7.0.1 → 8.0.0

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

@@ -1,32 +1,25 @@
 'use strict'
 
 /**
- * Local snapshot writes for pull (remote → repo).
+ * Push-side writeback: after `push` creates milestones/issues in Linear, the
+ * skill stamps each returned id back into the repo so the next push updates
+ * rather than recreates. Everything here edits the repo in place:
  *
- * Phase 2 applies **frontmatter-mapped** pulled fields — the `pull`-owned data
- * remote 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.
+ *   - `stampMilestoneId(dir, file, id)` — add/update `linear_milestone_id` in a
+ *     phase file's frontmatter (locate the file with `findPhaseFileByTitle`).
+ *   - `stampIssueId(dir, text, id)` — append `(ID)` to the matching task line,
+ *     re-wrapped in the file's own style.
+ *   - `writeFrontmatter(dir, config, patch)` — patch `00-overview.md` frontmatter
+ *     (e.g. `last_synced_at`).
  *
- * 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.
+ * No remote read, no pull writeback — the repo is the source of truth.
  */
 
 const fs = require('node:fs')
 const path = require('node:path')
-const {
-  findTaskBlocks,
-  renderTaskBlock,
-  collapse,
-  inferWidth,
-} = require('./task-block.js')
+const { findTaskBlocks, renderTaskBlock, collapse, inferWidth } = require('./task-block.js')
 
-// Serialize a JS value as a YAML-ish frontmatter scalar. null/undefined → the
-// key is dropped (caller shouldn't pass those).
+// Serialize a JS value as a YAML-ish frontmatter scalar.
 function serialize(value) {
   if (Array.isArray(value)) return JSON.stringify(value)
   if (typeof value === 'number' || typeof value === 'boolean') return String(value)
@@ -54,7 +47,6 @@ function patchFrontmatterLines(lines, patch) {
       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])}`)
   }
@@ -85,14 +77,6 @@ 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 {
@@ -105,28 +89,8 @@ function listPhaseFiles(snapshotDir) {
   }
 }
 
-// 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).
+// Find the phase file whose h1 title matches `name` (used to stamp a freshly
+// created milestone's id back into the phase it came from).
 function findPhaseFileByTitle(snapshotDir, name) {
   const want = String(name).trim()
   for (const file of listPhaseFiles(snapshotDir)) {
@@ -142,23 +106,6 @@ function findPhaseFileByTitle(snapshotDir, name) {
   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)
@@ -169,111 +116,8 @@ function stampMilestoneId(snapshotDir, file, id) {
   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 (hand-wrapped) checkbox bullets inside phase files. A pulled
-// issue edit rewrites the matching bullet — whole block, re-wrapped — by its
-// inline id; a Linear-only issue appends a new bullet; a created issue's id is
-// stamped inline. Removals report-only. See task-block.js for the wrapping.
-
 const INLINE_ID_RE = /\s*\(([A-Za-z][A-Za-z0-9]*-\d+)\)\s*$/
 
-// Update the task carrying inline id `id` (text + checkbox), in place.
-//
-// Block-aware: a task bullet is hand-wrapped across several lines, so the whole
-// block is replaced and the new text re-wrapped in the file's own style. Editing
-// only the first line would strand its continuation lines as orphaned prose.
-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')
-    const width = inferWidth(lines)
-    for (const b of findTaskBlocks(lines)) {
-      const idm = INLINE_ID_RE.exec(b.text)
-      if (!idm || idm[1] !== want) continue
-      const rendered = renderTaskBlock({ indent: b.indent, done, text, id: want }, width)
-      lines.splice(b.start, b.end - b.start, ...rendered)
-      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')
-  const blocks = findTaskBlocks(lines)
-  const rendered = renderTaskBlock({ indent: '', ...item }, inferWidth(lines))
-  if (blocks.length) lines.splice(blocks[blocks.length - 1].end, 0, ...rendered)
-  else lines.push(...rendered)
-  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) {
@@ -285,10 +129,7 @@ function stampIssueId(snapshotDir, text, id) {
     for (const b of findTaskBlocks(lines)) {
       if (INLINE_ID_RE.test(b.text)) continue
       if (b.text !== want) continue
-      const rendered = renderTaskBlock(
-        { indent: b.indent, done: b.mark === 'x', text: want, id },
-        width,
-      )
+      const rendered = renderTaskBlock({ indent: b.indent, done: b.mark === 'x', text: want, id }, width)
       lines.splice(b.start, b.end - b.start, ...rendered)
       fs.writeFileSync(p, lines.join('\n'), 'utf-8')
       return file
@@ -297,43 +138,12 @@ function stampIssueId(snapshotDir, text, id) {
   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,
 }

package/assets/skills/spec-pull/SKILL.md

@@ -1,49 +0,0 @@
----
-name: spec-pull
-description: Pull a spec's linked Linear project into the local spec (Linear → repo), three-way aware. Applies remote-only fields; refuses to clobber local edits on a conflict unless --force (which backs up the local side first). Fetches Linear over MCP and runs `skitterspec spec-sync pull`. Opt-in — needs specs/.core/linear.config.json. Use when the user says "/spec-pull", "pull from Linear", "sync Linear changes down", or "update this spec from Linear".
----
-
-# /spec-pull — bring Linear changes into the spec
-
-Linear → repo. Applies fields Linear changed since the last sync (status,
-priority, labels, and co-authored fields), rewrites the committed base, and
-stamps `last_synced_at`. It **refuses** to overwrite a local edit that conflicts
-with a Linear edit unless you pass `--force`.
-
-**Opt-in**: only runs when `specs/.core/linear.config.json` exists. If absent,
-tell the user how to enable Linear sync and stop.
-
-## 1. Identify the target spec
-
-Use the argument, else the spec in context; ask if unclear.
-
-## 2. Fetch the Linear project
-
-- Read `linear_project_id` from `00-overview.md` frontmatter; if missing, the
-  spec isn't linked — stop and point at `/spec`.
-- Discover the Linear MCP project-read tool at runtime. If Linear isn't
-  connected, relay the fix and stop — **do nothing destructive**.
-- Call it (include milestones) and write the project JSON to a temp file. When
-  tasks are keyed, also list the project's issues and add them as an `issues`
-  array on that JSON (each `{ identifier, title, state }`) so the engine can
-  reconcile task lines.
-
-## 3. Run the engine
-
-```
-skitterspec spec-sync pull <spec> --remote <tempfile> [--force]
-```
-
-- **No conflict** — the engine applies remote-only fields to the local snapshot,
-  rewrites the base, and stamps the sync. Body fields with no local home yet are
-  reported as `deferred` (apply them by hand from Linear if needed).
-- **Conflict** (a co-authored field changed on both sides) — the engine
-  **refuses** and lists the fields. Relay that; do not force on the user's behalf.
-- **`--force`** — only when the user explicitly asks. Remote wins after the engine
-  backs up the local side under `sync.backupDir` (the reflog). Relay the backup
-  path.
-
-## 4. Report
-
-Relay the git-like summary (applied / deferred / conflicts / backup / base). If
-fields were applied, remind the user to review and commit the refreshed snapshot.

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

@@ -1,66 +0,0 @@
-'use strict'
-
-/**
- * Translate normalized field values into a local frontmatter patch (pull side).
- *
- * Only the `pull`-owned, frontmatter-backed fields have a local home in Phase 2:
- *   workflowState → spec_status (remote state name mapped back to the bucket),
- *   priority      → priority,
- *   labels        → labels.
- * Any other field handed in (a body field like `description`/`milestones`) has no
- * frontmatter mapping yet, so it's returned in `deferred` — the caller must NOT
- * advance its base, keeping the remote edit pending instead of falsely synced.
- */
-
-// field name → frontmatter key.
-const FRONTMATTER_FIELD = {
-  workflowState: 'spec_status',
-  priority: 'priority',
-  labels: 'labels',
-}
-
-// Invert config.states ({ bucket: "remote Name" }) → { "remote name": bucket }.
-function invertStates(config) {
-  const out = {}
-  const states = (config && config.states) || {}
-  for (const [bucket, name] of Object.entries(states)) {
-    if (typeof name === 'string') out[name.toLowerCase()] = bucket
-  }
-  return out
-}
-
-// Map a remote workflowState (a remote state name) back to a local bucket. Falls
-// back to the raw value when it isn't one of the configured states.
-function localWorkflowState(value, config) {
-  if (value == null) return null
-  const bucket = invertStates(config)[String(value).toLowerCase()]
-  return bucket || String(value)
-}
-
-/**
- * Build the frontmatter patch for a set of applied field values.
- * @param {object} fieldValues  { fieldName: value } to write locally
- * @returns {{ patch:object, applied:string[], deferred:string[] }}
- */
-function frontmatterPatchFor(fieldValues, config) {
-  const patch = {}
-  const applied = []
-  const deferred = []
-  for (const [field, value] of Object.entries(fieldValues)) {
-    const key = FRONTMATTER_FIELD[field]
-    if (!key) {
-      deferred.push(field)
-      continue
-    }
-    patch[key] = field === 'workflowState' ? localWorkflowState(value, config) : value
-    applied.push(field)
-  }
-  return { patch, applied, deferred }
-}
-
-module.exports = {
-  frontmatterPatchFor,
-  localWorkflowState,
-  invertStates,
-  FRONTMATTER_FIELD,
-}

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

@@ -1,115 +0,0 @@
-'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, applyMilestonesPull, applyTasksPull } = require('./write.js')
-const { frontmatterPatchFor } = require('./apply.js')
-
-// Collect the conflicting units across scalar (field-level) and keyed
-// (item-level) fields, as stable labels for the refusal message.
-function collectConflicts(fields) {
-  const out = []
-  for (const f of fields) {
-    if (f.keyed) {
-      for (const it of f.items) if (it.status === 'conflict') out.push(`${f.field}#${it.id}`)
-    } else if (f.status === 'conflict') {
-      out.push(f.field)
-    }
-  }
-  return out
-}
-
-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 = collectConflicts(fields)
-  if (conflicts.length && !force) {
-    return {
-      ok: false,
-      blocked: true,
-      reason: 'conflict',
-      conflicts,
-      message: `pull refused — ${conflicts.length} unit(s) changed on both sides: ` +
-        `${conflicts.join(', ')}. Resolve locally or re-run with --force (remote wins).`,
-    }
-  }
-
-  // --force overwrites local edits — back the local side up first.
-  let backupPath = null
-  if (force) {
-    backupPath = backup('local', dir, identifier, config, { timestamp, data: local })
-  }
-
-  // Keyed body fields (e.g. milestones) — apply per-item via the denormalizer,
-  // which writes/creates the matching phase files. Removals are report-only.
-  const keyedApplied = []
-  const keyedCreated = []
-  const keyedReported = []
-  for (const f of fields) {
-    if (!f.keyed) continue
-    const apply = f.field === 'tasks' ? applyTasksPull : applyMilestonesPull
-    const res = apply(snapshotDir, f.items)
-    if (res.applied.length || res.created.length) keyedApplied.push(f.field)
-    keyedCreated.push(...res.created)
-    keyedReported.push(...res.reported.map((id) => `${f.field}#${id}`))
-  }
-
-  // Scalar pull-owned fields → frontmatter (keyed fields handled above).
-  const scalarPull = fields.filter((f) => f.pullable && !f.keyed)
-  const fieldValues = {}
-  for (const f of scalarPull) fieldValues[f.field] = remote[f.field]
-  const { patch, applied, deferred } = frontmatterPatchFor(fieldValues, config)
-
-  if (applied.length || timestamp) {
-    writeFrontmatter(snapshotDir, config, { ...patch, last_synced_at: timestamp })
-  }
-
-  // Re-normalize local so the base reflects the phase-file writes we just made,
-  // then advance base: scalar-applied fields take the remote value; keyed fields
-  // take the (now-updated) local value so applied items read in-sync and any
-  // report-only removal stays pending.
-  const newLocal = normalizeLocal(snapshotDir, config)
-  const newBase = { ...newLocal }
-  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,
-    keyedApplied,
-    keyedCreated,
-    keyedReported,
-    conflictsForced: force ? conflicts : [],
-    backupPath,
-    basePath,
-    pulled: [...scalarPull.map((f) => f.field), ...keyedApplied],
-  }
-}
-
-module.exports = { pull }