@skitterbyte/skitterspec-linear 10.4.0 → 10.5.0

package/src/vendor/linear/doctor.js

@@ -1,341 +1,179 @@
 'use strict'
 
 /**
- * Identifier drift — the offline half of `spec-sync doctor`.
+ * `spec-sync doctor` — one readiness report across every layer of a setup.
  *
- * When a Linear team is renamed (`REU` → `ERQ`), nothing in the repo moves: every
- * stamped `linear_identifier` / `linear_issue_id` / `linear_url`, the config's
- * `teamKey`, and every `linear-base/<ID>.base.json` filename keeps the old
- * prefix. Nothing detected it and nothing repaired it; the first occurrence was
- * fixed by hand across 221 refs in 54 files.
+ * Setting skitterspec up spans four layers — the `specs/` scaffold and skills,
+ * per-spec isolation, the tracker config, and the API key — and each was checked
+ * by a different command, or by none. `init` reports the scaffold and isolation;
+ * `credentials status` reports the key; the tracker config had no readiness check
+ * at all, only commands that write it. So "is this project set up?" had no single
+ * answer, and a skill needing to know its own prerequisites had nothing to call.
  *
- * This module only SCANS — it reads the repo and reports what disagrees with a
- * team key it is handed. It performs no network calls and writes nothing, so the
- * detection logic is testable without an adapter. Deciding what the current key
- * IS (a Linear read) and repairing (phase 3) live in `cli-sync.js`.
+ * This module is the PURE half. It takes the project's state as an argument —
+ * gathered by the caller — and returns rows. No `fs`, no network, no output, so
+ * every branch is exercised from a literal rather than a scaffolded temp project.
+ *
+ * Two distinctions carry the design:
+ *
+ * 1. **`missing` is not `broken`.** `missing` is an opt-in not taken, which is
+ *    fine; `broken` is configured-but-wrong, which is not. `ok` is false only for
+ *    `broken`, so declining isolation or a tracker never reads as a failure. The
+ *    existing commands blur exactly this.
+ * 2. **Every non-`ok` row names the command that fixes it**, so the output is
+ *    actionable without reading docs — the shape `credentials status` already
+ *    uses.
+ *
+ * It never prints a secret: the key row carries a masked fingerprint and its
+ * source, never the value. This is the command a skill runs, so that has to hold
+ * by construction rather than by convention.
  */
 
-const fs = require('node:fs')
-const path = require('node:path')
-const { execFileSync } = require('node:child_process')
-
-const { BUCKETS } = require('../../env/resolve.js')
-const { parseFrontmatter } = require('../sync-core')
-
-// A Linear issue identifier: an uppercase team key, a dash, a number. The key is
-// captured so drift is a prefix comparison rather than a guess.
-const IDENTIFIER_RE = /^([A-Z][A-Z0-9]*)-(\d+)$/
-// The same, embedded in a URL path (`…/issue/REU-151/slug`).
-const URL_IDENTIFIER_RE = /\b([A-Z][A-Z0-9]*)-(\d+)\b/g
+const STATES = ['ok', 'missing', 'broken', 'skipped']
 
-const STAMP_FIELDS = ['linear_identifier', 'linear_issue_id']
-
-// Every `.md` under each spec folder — overview and phase files alike, plus the
-// legacy bare `<name>.md` shape. Anything stamped lives in one of these.
-function specMarkdownFiles(dir) {
-  const files = []
-  for (const bucket of BUCKETS) {
-    const root = path.join(dir, 'specs', bucket)
-    let entries
-    try {
-      entries = fs.readdirSync(root, { withFileTypes: true })
-    } catch {
-      continue
-    }
-    for (const entry of entries) {
-      const p = path.join(root, entry.name)
-      if (entry.isDirectory()) {
-        for (const f of fs.readdirSync(p)) if (f.endsWith('.md')) files.push(path.join(p, f))
-      } else if (entry.isFile() && entry.name.endsWith('.md')) {
-        files.push(p)
-      }
-    }
-  }
-  return files.sort()
-}
-
-// Retarget one identifier onto `currentKey`, preserving the number. Returns null
-// when it is already current or is not an identifier at all.
-function retarget(value, currentKey) {
-  const m = IDENTIFIER_RE.exec(String(value).trim())
-  if (!m || m[1] === currentKey) return null
-  return `${currentKey}-${m[2]}`
+// A row is a check. `fix` is the exact command to run, or null when there is
+// nothing to fix.
+const row = (id, label, state, detail, fix = null) => {
+  if (!STATES.includes(state)) throw new Error(`doctor: unknown check state "${state}" for ${id}`)
+  return { id, label, state, detail, fix }
 }
 
 /**
- * Scan the repo for identifiers that disagree with `currentKey`.
- *
- * @returns {{
- *   stamps: Array<{file, field, from, to}>,
- *   urls: Array<{file, from, to}>,
- *   snapshots: Array<{from, to}>,
- *   snapshotKeys: Array<{file, from, to}>,
- *   mentions: Array<{file, from, to}>,   // prose refs — reported, never repaired
- *   config: {from, to}|null,
- *   refs: Array<{from, to}>,
- * }} `refs` is the DISTINCT set of drifted identifiers — what the caller checks
- *    against Linear, so 221 stamps of 198 identifiers cost 198 reads, not 221.
+ * @param {object} state gathered by the caller:
+ *   {
+ *     scaffold:  { specsDir: bool, buckets: string[], skills: number },
+ *     isolation: { present: bool, parsed: bool, error?: string },
+ *     tracker:   { present: bool, parsed: bool, teamId?: string, teamKey?: string, error?: string },
+ *     key:       { ok: bool, source?: string, fingerprint?: string, error?: string },
+ *     remote:    { checked: bool, ok?: bool, teamKey?: string, error?: string },
+ *   }
+ * @returns {{ok: boolean, checks: Array}}
  */
-function scanDrift(dir, config, currentKey) {
-  const stamps = []
-  const urls = []
-  const seen = new Map()
-  const note = (from, to) => seen.set(from, to)
-
-  for (const file of specMarkdownFiles(dir)) {
-    let raw
-    try {
-      raw = fs.readFileSync(file, 'utf-8')
-    } catch {
-      continue
-    }
-    const { data } = parseFrontmatter(raw)
-    for (const field of STAMP_FIELDS) {
-      if (!data[field]) continue
-      const to = retarget(data[field], currentKey)
-      if (!to) continue
-      stamps.push({ file: path.relative(dir, file), field, from: String(data[field]).trim(), to })
-      note(String(data[field]).trim(), to)
-    }
-    if (data.linear_url) {
-      const url = String(data.linear_url)
-      let changed = url
-      for (const m of url.matchAll(URL_IDENTIFIER_RE)) {
-        const to = retarget(m[0], currentKey)
-        if (!to) continue
-        changed = changed.split(m[0]).join(to)
-        note(m[0], to)
-      }
-      if (changed !== url) urls.push({ file: path.relative(dir, file), from: url, to: changed })
-    }
-  }
+function runChecks(state = {}) {
+  const checks = [
+    scaffoldCheck(state.scaffold),
+    isolationCheck(state.isolation),
+    trackerCheck(state.tracker),
+    keyCheck(state.key, state.tracker),
+    remoteCheck(state.remote),
+  ]
+  // `missing` is a declined opt-in, so it must not fail the run. Only a
+  // configured-but-wrong layer does.
+  return { ok: !checks.some((c) => c.state === 'broken'), checks }
+}
 
-  const snapshots = []
-  const snapshotKeys = []
-  const baseDir = path.resolve(dir, config.sync.baseDir)
-  let snapshotNames = []
-  try {
-    snapshotNames = fs.readdirSync(baseDir).filter((f) => f.endsWith('.base.json'))
-  } catch {
-    /* no snapshots yet — nothing to retarget */
+function scaffoldCheck(s = {}) {
+  if (!s.specsDir) {
+    return row('scaffold', 'scaffold', 'missing', 'no specs/ folder', 'skitterspec init')
   }
-  for (const name of snapshotNames.sort()) {
-    const to = retarget(name.slice(0, -'.base.json'.length), currentKey)
-    if (to) {
-      snapshots.push({ from: name, to: `${to}.base.json` })
-      note(name.slice(0, -'.base.json'.length), to)
-    }
-    // A snapshot's `subIssues` map is KEYED BY IDENTIFIER, so a rename strands
-    // every key inside the file as well as the filename. Missing these made the
-    // first scan report 59 refs where the repo really carries ~198: the bulk of
-    // a linked repo's identifiers live in here, not in frontmatter. The hashes
-    // are content-derived and stay valid — only their keys move.
-    let body
-    try {
-      body = JSON.parse(fs.readFileSync(path.join(baseDir, name), 'utf-8'))
-    } catch {
-      continue
-    }
-    for (const ident of Object.keys((body && body.subIssues) || {})) {
-      const keyTo = retarget(ident, currentKey)
-      if (!keyTo) continue
-      snapshotKeys.push({ file: path.join(config.sync.baseDir, name), from: ident, to: keyTo })
-      note(ident, keyTo)
-    }
-  }
-
-  // Prose MENTIONS of a stale identifier — `(REU-61)` beside a task, "the REU-196
-  // spec claimed …". These are human-written references, not functional stamps,
-  // and repair deliberately leaves them alone: rewriting narrative text is a
-  // different risk class, and an identifier-shaped token in prose need not be a
-  // Linear ref at all. They are counted anyway so the report cannot imply a
-  // `--write` left the repo fully retargeted when ~145 mentions still say REU.
+  // A LIFECYCLE BUCKET IS NOT CHECKED, deliberately. git does not track empty
+  // directories, so `specs/in-progress/` disappears whenever no spec is in
+  // progress and returns the moment one starts — every lifecycle skill runs
+  // `mkdir -p` before it moves a spec. Checking for it reported a healthy repo
+  // as broken, and exited 1 under any skill branching on the code.
   //
-  // Only prefixes that actually appear in the repo's STAMPS are counted, so an
-  // unrelated `ABC-123` in prose is never mistaken for a drifted ref.
-  const staleKeys = new Set([...seen.keys()].map((k) => k.split('-')[0]))
-  const mentions = []
-  if (staleKeys.size) {
-    for (const file of specMarkdownFiles(dir)) {
-      let raw
-      try {
-        raw = fs.readFileSync(file, 'utf-8')
-      } catch {
-        continue
-      }
-      const { body } = parseFrontmatter(raw)
-      for (const m of String(body).matchAll(URL_IDENTIFIER_RE)) {
-        if (!staleKeys.has(m[1]) || m[1] === currentKey) continue
-        mentions.push({ file: path.relative(dir, file), from: m[0], to: `${currentKey}-${m[2]}` })
-      }
-    }
+  // `.core` is the signal that survives: `init` always writes the config
+  // templates and the manifest into it, so it is never an empty directory.
+  if (!s.core) {
+    return row(
+      'scaffold',
+      'scaffold',
+      'broken',
+      'specs/ exists but specs/.core/ is missing — a half-installed scaffold',
+      'skitterspec init --resync',
+    )
   }
-
-  const configured = (config.linear && config.linear.teamKey) || ''
-  const configDrift = configured && configured !== currentKey ? { from: configured, to: currentKey } : null
-
-  return {
-    stamps,
-    urls,
-    snapshots,
-    snapshotKeys,
-    mentions,
-    config: configDrift,
-    refs: [...seen.entries()].map(([from, to]) => ({ from, to })).sort((a, b) => a.from.localeCompare(b.from)),
+  if (!s.skills) {
+    return row('scaffold', 'scaffold', 'broken', 'specs/ exists but no skills are installed', 'skitterspec init --resync')
   }
+  return row('scaffold', 'scaffold', 'ok', `specs/ + ${s.skills} skills installed`)
 }
 
-// True when a scan found nothing to repair.
-function isClean(drift) {
-  return (
-    !drift.stamps.length &&
-    !drift.urls.length &&
-    !drift.snapshots.length &&
-    !drift.snapshotKeys.length &&
-    !drift.config
-  )
-}
-
-// How many distinct files a repair would touch.
-function fileCount(drift) {
-  return new Set([...drift.stamps.map((s) => s.file), ...drift.urls.map((u) => u.file)]).size
-}
-
-// --- repair ------------------------------------------------------------------
-
-// `git status --porcelain` over `dir`: [] when clean, the offending lines when
-// dirty, null when this is not a git repo at all.
-function dirtyPaths(dir) {
-  let out
-  try {
-    out = execFileSync('git', ['-C', dir, 'status', '--porcelain'], {
-      stdio: ['ignore', 'pipe', 'ignore'],
-    })
-      .toString()
-      .trim()
-  } catch {
-    return null
+// Isolation and tracker have NO false-positive mode, and no test is added for
+// one: each only says `broken` on positive evidence — a file that is present and
+// does not parse, or a config that parses and holds no teamId. Absence is
+// reported as `missing`, an opt-in not taken, which never fails the run.
+function isolationCheck(s = {}) {
+  if (!s.present) {
+    return row('isolation', 'isolation', 'missing', 'not enabled — every spec builds in place', 'skitterspec init --isolation')
   }
-  return out ? out.split('\n') : []
-}
-
-// Rewrite identifier tokens INSIDE a file's frontmatter block only.
-//
-// Scoped to the frontmatter on purpose: the same token appears in spec prose,
-// which repair deliberately leaves alone. A blind whole-file replace would
-// rewrite narrative text as a side effect of fixing a stamp.
-function rewriteFrontmatter(raw, replacements) {
-  const m = /^(---\n[\s\S]*?\n---)(\n[\s\S]*)?$/.exec(raw)
-  if (!m) return raw
-  let head = m[1]
-  for (const [from, to] of replacements) head = head.split(from).join(to)
-  return head + (m[2] || '')
+  if (!s.parsed) {
+    return row('isolation', 'isolation', 'broken', s.error || 'env.config.json does not parse', 'fix specs/.core/env.config.json')
+  }
+  return row('isolation', 'isolation', 'ok', 'env.config.json — worktree per spec')
 }
 
-// Move a file, preferring `git mv` so history survives. Falls back to a plain
-// rename when the file is untracked (git mv refuses those) or git is absent.
-function moveFile(dir, from, to) {
-  try {
-    execFileSync('git', ['-C', dir, 'mv', from, to], { stdio: ['ignore', 'ignore', 'ignore'] })
-    return 'git mv'
-  } catch {
-    fs.renameSync(path.join(dir, from), path.join(dir, to))
-    return 'rename'
+function trackerCheck(s = {}) {
+  if (!s.present) {
+    return row('tracker', 'tracker', 'missing', 'no linear.config.json — sync is opt-in', '/spec-linear-setup')
+  }
+  if (!s.parsed) {
+    return row('tracker', 'tracker', 'broken', s.error || 'linear.config.json does not parse', '/spec-linear-setup')
+  }
+  if (!s.teamId) {
+    // Configured but unusable: every Linear call needs the team id.
+    return row('tracker', 'tracker', 'broken', 'linear.config.json has no linear.teamId', '/spec-linear-setup')
   }
+  const team = s.teamKey ? `${s.teamId} (${s.teamKey})` : s.teamId
+  return row('tracker', 'tracker', 'ok', `linear.config.json — team ${team}`)
 }
 
-/**
- * Apply a scan's repairs. Everything moves together — config, stamps, snapshot
- * filenames and the identifier keys inside them — because a half-repaired repo
- * is harder to reason about than an un-repaired one.
- *
- * `skip` is the set of `from` identifiers that resolve to NO issue under the new
- * key. Those are left exactly as they are: repair fixes what is provably
- * repairable, and reports the rest rather than inventing a target.
- *
- * Prose mentions are never touched — see `scanDrift`.
- */
-function repairDrift(dir, config, drift, { skip = new Set() } = {}) {
-  const keep = (r) => !skip.has(r.from)
-  const changed = { files: [], snapshots: [], config: false, skipped: 0 }
-
-  // 1. Frontmatter stamps and urls, one pass per file.
-  const byFile = new Map()
-  for (const r of [...drift.stamps, ...drift.urls]) {
-    if (!keep(r)) {
-      changed.skipped++
-      continue
-    }
-    if (!byFile.has(r.file)) byFile.set(r.file, [])
-    byFile.get(r.file).push([r.from, r.to])
-  }
-  for (const [rel, replacements] of byFile) {
-    const abs = path.join(dir, rel)
-    const raw = fs.readFileSync(abs, 'utf-8')
-    const next = rewriteFrontmatter(raw, replacements)
-    if (next !== raw) {
-      fs.writeFileSync(abs, next, 'utf-8')
-      changed.files.push(rel)
-    }
+// BLIND SPOT: `s.ok` collapses three sources — the env var, the store, and a
+// `keyCommand` the store runs. An absent env var is not an absent key, and the
+// caller resolves all three before this sees it. `s.error` carries WHY when one
+// of them failed; passing it through is what keeps a broken keyCommand from
+// being reported as a key the user never set.
+function keyCheck(s = {}, tracker = {}) {
+  // Without a tracker there is nothing for a key to authenticate, so asking for
+  // one would be noise.
+  if (!tracker.present) return row('key', 'key', 'skipped', 'no tracker configured')
+  if (!s.ok) {
+    return row(
+      'key',
+      'key',
+      'missing',
+      s.error || `no key for ${tracker.teamKey || tracker.teamId || 'this team'}`,
+      'skitterspec spec-sync credentials set',
+    )
   }
+  // Masked fingerprint and source only — never the value.
+  return row('key', 'key', 'ok', `${s.fingerprint || 'set'} from ${s.source || 'unknown'}`)
+}
 
-  // 2. Snapshot sub-issue keys, rewritten BEFORE the filename moves so the path
-  //    being read is still the one the scan recorded.
-  const keysByFile = new Map()
-  for (const k of drift.snapshotKeys) {
-    if (!keep(k)) {
-      changed.skipped++
-      continue
-    }
-    if (!keysByFile.has(k.file)) keysByFile.set(k.file, [])
-    keysByFile.get(k.file).push(k)
+function remoteCheck(s = {}) {
+  if (!s.checked) {
+    return row('remote', 'remote', 'skipped', 'pass --check-remote to verify against Linear')
   }
-  for (const [rel, keys] of keysByFile) {
-    const abs = path.join(dir, rel)
-    const body = JSON.parse(fs.readFileSync(abs, 'utf-8'))
-    const subIssues = {}
-    // The hashes are CONTENT-derived, so they survive a rename untouched — only
-    // the keys move. Rebuilt rather than mutated so key order stays stable.
-    for (const [ident, hash] of Object.entries(body.subIssues || {})) {
-      const hit = keys.find((k) => k.from === ident)
-      subIssues[hit ? hit.to : ident] = hash
-    }
-    fs.writeFileSync(abs, JSON.stringify({ ...body, subIssues }, null, 2) + '\n', 'utf-8')
+  // Asked for, but the check did not run — either there was nothing to ask WITH
+  // (no key, no team id; the row that owns that already reported it), or the
+  // request never got an answer (unreachable, rate-limited). Neither says this
+  // project is misconfigured, and `broken` here exits 1 for every skill
+  // branching on the code. The caller decides which failures land here.
+  if (s.skipped) {
+    return row('remote', 'remote', 'skipped', s.reason || 'nothing to check against')
   }
-
-  // 3. Snapshot filenames.
-  const baseRel = config.sync.baseDir
-  for (const snap of drift.snapshots) {
-    const ident = snap.from.slice(0, -'.base.json'.length)
-    if (skip.has(ident)) {
-      changed.skipped++
-      continue
-    }
-    const how = moveFile(dir, path.join(baseRel, snap.from), path.join(baseRel, snap.to))
-    changed.snapshots.push({ ...snap, how })
+  if (!s.ok) {
+    // Well-formed config is not working config: the id may not resolve, or the
+    // key may be revoked. Either way this is configured-but-wrong.
+    //
+    // `reason` is composed by the caller from a CLASSIFIED failure, never from a
+    // raw API message — an error body can echo the request back, and this is the
+    // command a skill prints.
+    return row('remote', 'remote', 'broken', s.reason || 'Linear did not accept the request', s.fix || 'skitterspec spec-sync credentials set')
   }
-
-  // 4. The config key, last: it is the thing that makes the next scan read
-  //    clean, so it should not flip before the files it describes have moved.
-  if (drift.config) {
-    const file = path.join(dir, 'specs', '.core', 'linear.config.json')
-    const raw = fs.readFileSync(file, 'utf-8')
-    // Textual, not parse-and-restringify: the config is hand-edited and carries
-    // comments and ordering a JSON round-trip would silently discard.
-    fs.writeFileSync(file, raw.replace(/("teamKey"\s*:\s*")([^"]*)(")/, `$1${drift.config.to}$3`), 'utf-8')
-    changed.config = true
+  if (s.teamKey && s.recordedKey && s.teamKey !== s.recordedKey) {
+    // The team resolved and the key worked — but it is not the team this repo
+    // thinks it files into. That is a rename, and every stamped identifier in
+    // the repo is now stale.
+    return row(
+      'remote',
+      'remote',
+      'broken',
+      `team resolves as ${s.teamKey}, but the config records ${s.recordedKey} — the team was renamed`,
+      'skitterspec spec-sync retarget',
+    )
   }
-
-  return changed
+  return row('remote', 'remote', 'ok', `team ${s.teamKey} resolves, key accepted`)
 }
 
-module.exports = {
-  scanDrift,
-  isClean,
-  fileCount,
-  retarget,
-  specMarkdownFiles,
-  dirtyPaths,
-  repairDrift,
-  rewriteFrontmatter,
-}
+module.exports = { runChecks, STATES }

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

@@ -22,6 +22,7 @@ const { sanitizeSpecMarkdown } = require('./src/sanitise.js')
 const { detectLegacyMirror } = require('./src/legacy.js')
 const { compareStored } = require('./src/verify.js')
 const { flattenNestedTables } = require('./src/tables.js')
+const { planRetarget, applyRetarget, deriveRecordedKey, isEmptyRetarget, dirtyPaths } = require('./src/retarget.js')
 
 module.exports = {
   normalizeLocal,
@@ -51,4 +52,9 @@ module.exports = {
   detectLegacyMirror,
   compareStored,
   flattenNestedTables,
+  planRetarget,
+  applyRetarget,
+  deriveRecordedKey,
+  isEmptyRetarget,
+  dirtyPaths,
 }

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

@@ -237,7 +237,12 @@ function parsePhaseIndex(phasesSection) {
     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' })
+    // `stated` separates "the row says not-started" from "the row said nothing
+    // we recognise". A cell holding the word `Done`, an em dash, or a legacy
+    // spec's freeform text expresses no status in this vocabulary, and reading
+    // its absence as `not-started` let lintPhases quote the overview as saying
+    // something it never said.
+    rows.push({ name, status: EMOJI_STATUS[emoji] || 'not-started', stated: Boolean(emoji) })
   }
   return rows
 }
@@ -419,6 +424,10 @@ function readPhaseFiles(snapshotDir) {
  */
 function lintPhases(snapshotDir, config) {
   const phases = readPhaseFiles(snapshotDir)
+  // BLIND SPOT: `readPhaseFiles` only sees `NN-*.md`, so a legacy bare
+  // `<name>.md` spec yields no phases at all. Silence is the right answer —
+  // there is no phase file to carry an emoji — but it is silence from having
+  // looked nowhere, not from having looked and found everything in order.
   if (!phases.length) return []
 
   // The overview may be absent (a legacy bare `<name>.md` spec) — that is not
@@ -459,8 +468,14 @@ function lintPhases(snapshotDir, config) {
 
     // Match the index row by phase title, falling back to position — a renamed
     // phase shouldn't silently drop the check.
+    //
+    // BLIND SPOT: the index is only evidence where it used the emoji vocabulary.
+    // A row whose Status cell holds prose (or nothing) parses as `not-started`,
+    // which is a default, not a statement — cross-checking against it accused a
+    // healthy spec of a disagreement with a value nobody wrote. `stated` is the
+    // positive signal: compare only against a status the row actually expressed.
     const row = indexRows.find((r) => r.name === phase.name) || indexRows[i]
-    if (row && row.status !== heading) {
+    if (row && row.stated && row.status !== heading) {
       warnings.push({
         file: phase.file,
         code: 'status-disagreement',