@skitterbyte/skitterspec-linear 10.3.0 → 10.5.0

package/src/vendor/linear/credentials.js

@@ -0,0 +1,299 @@
+'use strict'
+
+/**
+ * The user-level credentials store — where a Linear API key lives when it is
+ * not in the environment.
+ *
+ * The repo's `specs/.core/linear.config.json` is COMMITTED and deliberately
+ * holds only the NAME of an env var, never a key. That is what makes it safe to
+ * share, so a key can never go there. This store is the alternative: one file
+ * per machine, outside every repo, at
+ * `$XDG_CONFIG_HOME/skitterspec/credentials.json` (else `~/.config/…`), keyed by
+ * Linear team id so one file serves every checkout.
+ *
+ * Reads never throw. `resolveApiKey` already treats "no key" as a NORMAL state
+ * meaning "fall back to MCP" rather than an error, so every failure here returns
+ * a structured reason the caller can report or ignore — a missing store is not a
+ * problem, it is the default.
+ *
+ * Nothing in this module ever returns a key inside an error, and callers must
+ * keep it out of logs, plans, snapshots and stamped frontmatter.
+ */
+
+const { spawnSync } = require('node:child_process')
+const fs = require('node:fs')
+const os = require('node:os')
+const path = require('node:path')
+
+const DIR_NAME = 'skitterspec'
+const FILE_NAME = 'credentials.json'
+
+// Modes wider than owner-only. Checked ssh-style: a store other users can read
+// is refused rather than read, because silently using it would hide the leak,
+// and silently chmod'ing someone's file is not ours to do.
+const GROUP_OR_WORLD = 0o077
+
+/**
+ * Absolute path of the store. Honours `$XDG_CONFIG_HOME`, else `~/.config`.
+ * `env` and `homedir` are injected so tests never touch a real home directory.
+ */
+function storePath(env = process.env, homedir = os.homedir) {
+  const xdg = env.XDG_CONFIG_HOME && env.XDG_CONFIG_HOME.trim()
+  const base = xdg || path.join(homedir(), '.config')
+  return path.join(base, DIR_NAME, FILE_NAME)
+}
+
+/**
+ * Read the store.
+ *
+ * @returns {object} `{ ok: true, store, path }` — parsed and owner-only;
+ *   `{ ok: false, reason, code, path }` otherwise. `code` is one of:
+ *   `absent` (no file — the normal default, not a problem), `permissions`
+ *   (group/world readable), `unreadable`, `malformed`.
+ */
+function readStore(file, { stat = fs.statSync, read = fs.readFileSync } = {}) {
+  let info
+  try {
+    info = stat(file)
+  } catch (err) {
+    if (err.code === 'ENOENT') {
+      return { ok: false, code: 'absent', path: file, reason: `no credentials store at ${file}` }
+    }
+    return { ok: false, code: 'unreadable', path: file, reason: `cannot read ${file}: ${err.message}` }
+  }
+
+  if (info.mode & GROUP_OR_WORLD) {
+    const mode = (info.mode & 0o777).toString(8)
+    return {
+      ok: false,
+      code: 'permissions',
+      path: file,
+      reason:
+        `credentials store ${file} is mode ${mode} — readable by other users.\n` +
+        `  Run: chmod 600 ${file}`,
+    }
+  }
+
+  let raw
+  try {
+    raw = read(file, 'utf-8')
+  } catch (err) {
+    return { ok: false, code: 'unreadable', path: file, reason: `cannot read ${file}: ${err.message}` }
+  }
+
+  let store
+  try {
+    store = JSON.parse(raw)
+  } catch (err) {
+    return { ok: false, code: 'malformed', path: file, reason: `invalid JSON in ${file}: ${err.message}` }
+  }
+  if (!store || typeof store !== 'object' || Array.isArray(store)) {
+    return { ok: false, code: 'malformed', path: file, reason: `invalid credentials store in ${file}` }
+  }
+  return { ok: true, store, path: file }
+}
+
+/**
+ * The key recorded for one team, or null. Never throws, and never reports the
+ * value it did or didn't find.
+ */
+function keyForTeam(store, teamId) {
+  if (!teamId) return null
+  const teams = store && store.teams
+  const entry = teams && typeof teams === 'object' ? teams[teamId] : null
+  if (!entry || typeof entry !== 'object') return null
+  const key = entry.key
+  return typeof key === 'string' && key.trim() ? key.trim() : null
+}
+
+// Last 4 characters, for reporting that a key exists without revealing it.
+function fingerprint(key) {
+  if (typeof key !== 'string' || !key) return null
+  return `…${key.slice(-4)}`
+}
+
+
+/**
+ * Record a key for one team, creating the store at `0600` and its directory at
+ * `0700`. Other teams' entries are preserved.
+ *
+ * Refuses rather than writing when the existing store is unreadable or
+ * over-permissive — the same guard as reading, because silently rewriting a
+ * world-readable file would leave the leak in place.
+ *
+ * Returns `{ ok: true, path, created }` or `{ ok: false, reason }`. The key is
+ * never echoed back in either.
+ */
+function writeKey(file, teamId, key, deps = {}) {
+  const mkdir = deps.mkdir || fs.mkdirSync
+  const write = deps.write || fs.writeFileSync
+  const chmod = deps.chmod || fs.chmodSync
+  const exists = deps.exists || fs.existsSync
+
+  if (!teamId) return { ok: false, reason: 'no team id — nothing to key the entry by' }
+  if (typeof key !== 'string' || !key.trim()) return { ok: false, reason: 'empty key — nothing stored' }
+
+  const created = !exists(file)
+  let store = { version: 1, teams: {} }
+  if (!created) {
+    const current = readStore(file, deps)
+    if (!current.ok) return { ok: false, reason: current.reason, code: current.code }
+    store = current.store
+    if (!store.teams || typeof store.teams !== 'object') store.teams = {}
+    if (!store.version) store.version = 1
+  }
+
+  store.teams[teamId] = { ...(store.teams[teamId] || {}), key: key.trim() }
+
+  mkdir(path.dirname(file), { recursive: true, mode: 0o700 })
+  write(file, JSON.stringify(store, null, 2) + '\n', { mode: 0o600 })
+  // `mode` on writeFileSync only applies when the file is CREATED, so an
+  // existing file keeps its mode — narrow it explicitly.
+  chmod(file, 0o600)
+  return { ok: true, path: file, created }
+}
+
+/**
+ * Remove one team's entry, leaving every other team intact. A store or entry
+ * that isn't there is a clean no-op, not an error.
+ */
+function removeKey(file, teamId, deps = {}) {
+  const write = deps.write || fs.writeFileSync
+  const current = readStore(file, deps)
+  if (!current.ok) {
+    if (current.code === 'absent') return { ok: true, path: file, removed: false }
+    return { ok: false, reason: current.reason, code: current.code }
+  }
+  const teams = current.store.teams
+  if (!teams || !teams[teamId]) return { ok: true, path: file, removed: false }
+  delete teams[teamId]
+  write(file, JSON.stringify(current.store, null, 2) + '\n', { mode: 0o600 })
+  return { ok: true, path: file, removed: true }
+}
+
+/**
+ * Resolve one team's key from the store: a stored `key` first, else running its
+ * `keyCommand` and taking stdout.
+ *
+ * `keyCommand` is honoured ONLY from this user-level store — never from the
+ * repo's committed `linear.config.json`. That file travels with the repo, so a
+ * command named there would let a cloned repo run arbitrary code on the machine
+ * of anyone who ran `spec-sync`. The repo config keeps naming only an env var.
+ *
+ * A command that fails, times out or prints nothing resolves to no key, which is
+ * the ordinary "fall back to MCP" state — but its stderr is carried back so a
+ * broken command is diagnosable rather than mysteriously inert. Its **stdout is
+ * never** put in an error: that is the key.
+ *
+ * @returns {object} `{ key, source }` with source `'store'` | `'command'`, or
+ *   `{ key: null, source: null, reason }`.
+ */
+function resolveTeamKey(store, teamId, deps = {}) {
+  const direct = keyForTeam(store, teamId)
+  if (direct) return { key: direct, source: 'store' }
+
+  const entry = store && store.teams && typeof store.teams === 'object' ? store.teams[teamId] : null
+  const command = entry && typeof entry.keyCommand === 'string' ? entry.keyCommand.trim() : ''
+  if (!command) return { key: null, source: null }
+
+  const run = deps.run || defaultRunCommand
+  const result = run(command, deps.timeoutMs || COMMAND_TIMEOUT_MS)
+  if (!result.ok) {
+    return { key: null, source: null, command, reason: `keyCommand failed: ${result.error}` }
+  }
+  const key = (result.stdout || '').trim()
+  if (!key) {
+    return { key: null, source: null, command, reason: 'keyCommand produced no output' }
+  }
+  return { key, source: 'command', command }
+}
+
+// 60s: a password manager may prompt for biometric or a master password, and a
+// hang here would look like the CLI itself wedging.
+const COMMAND_TIMEOUT_MS = 60_000
+
+// Linear personal API keys are `lin_api_` + a long token.
+const LITERAL_KEY_RE = /lin_api_[A-Za-z0-9]{8,}/
+
+function defaultRunCommand(command, timeout) {
+  const r = spawnSync('sh', ['-c', command], { encoding: 'utf-8', timeout })
+  if (r.error) return { ok: false, error: r.error.message }
+  if (r.status !== 0) {
+    // stderr only — stdout is the secret, and must not reach an error message.
+    const detail = (r.stderr || '').trim().split('\n')[0] || `exit ${r.status}`
+    return { ok: false, error: detail }
+  }
+  return { ok: true, stdout: r.stdout }
+}
+
+/**
+ * Record a command for one team instead of a key. Unlike a key, a command is not
+ * a secret, so this one IS safe to pass as an argument.
+ */
+function writeKeyCommand(file, teamId, command, deps = {}) {
+  const mkdir = deps.mkdir || fs.mkdirSync
+  const write = deps.write || fs.writeFileSync
+  const chmod = deps.chmod || fs.chmodSync
+  const exists = deps.exists || fs.existsSync
+
+  if (!teamId) return { ok: false, reason: 'no team id — nothing to key the entry by' }
+  if (typeof command !== 'string' || !command.trim()) {
+    return { ok: false, reason: 'empty command — nothing stored' }
+  }
+  // Refusing `--key` makes `--command "echo lin_api_…"` the obvious workaround,
+  // and it is worse: a command is NOT treated as a secret — `status` prints it
+  // back, and it sits in the store in clear. Catch the shortcut at the door.
+  if (LITERAL_KEY_RE.test(command)) {
+    return {
+      ok: false,
+      reason:
+        'that command has a Linear key written into it.\n' +
+        '  A command is displayed by `credentials status` and is not treated as a\n' +
+        '  secret — embedding a key there exposes it. To store a key, run\n' +
+        '  `credentials set` with no arguments and paste at the hidden prompt.',
+    }
+  }
+
+  const created = !exists(file)
+  let store = { version: 1, teams: {} }
+  if (!created) {
+    const current = readStore(file, deps)
+    if (!current.ok) return { ok: false, reason: current.reason, code: current.code }
+    store = current.store
+    if (!store.teams || typeof store.teams !== 'object') store.teams = {}
+    if (!store.version) store.version = 1
+  }
+
+  // A command REPLACES a stored key for that team — keeping both would mean the
+  // key silently wins and the command never runs.
+  store.teams[teamId] = { keyCommand: command.trim() }
+
+  mkdir(path.dirname(file), { recursive: true, mode: 0o700 })
+  write(file, JSON.stringify(store, null, 2) + '\n', { mode: 0o600 })
+  chmod(file, 0o600)
+  return { ok: true, path: file, created }
+}
+
+/** The store's permission bits as an octal string, or null when absent. */
+function storeMode(file, deps = {}) {
+  const stat = deps.stat || fs.statSync
+  try {
+    return (stat(file).mode & 0o777).toString(8)
+  } catch {
+    return null
+  }
+}
+
+module.exports = {
+  storePath,
+  readStore,
+  keyForTeam,
+  fingerprint,
+  writeKey,
+  writeKeyCommand,
+  resolveTeamKey,
+  removeKey,
+  storeMode,
+  DIR_NAME,
+  FILE_NAME,
+}

package/src/vendor/linear/doctor.js

@@ -0,0 +1,179 @@
+'use strict'
+
+/**
+ * `spec-sync doctor` — one readiness report across every layer of a setup.
+ *
+ * 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 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 STATES = ['ok', 'missing', 'broken', 'skipped']
+
+// 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 }
+}
+
+/**
+ * @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 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 }
+}
+
+function scaffoldCheck(s = {}) {
+  if (!s.specsDir) {
+    return row('scaffold', 'scaffold', 'missing', 'no specs/ folder', 'skitterspec init')
+  }
+  // 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.
+  //
+  // `.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',
+    )
+  }
+  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`)
+}
+
+// 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')
+  }
+  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')
+}
+
+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}`)
+}
+
+// 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'}`)
+}
+
+function remoteCheck(s = {}) {
+  if (!s.checked) {
+    return row('remote', 'remote', 'skipped', 'pass --check-remote to verify against Linear')
+  }
+  // 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')
+  }
+  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')
+  }
+  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 row('remote', 'remote', 'ok', `team ${s.teamKey} resolves, key accepted`)
+}
+
+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/compare.js

@@ -71,7 +71,9 @@ function snapshotOf(projection) {
 /**
  * Diff the local projection against the last-pushed snapshot.
  * @returns {{ issue?: object, subIssues: {create,update} }}
- *   create items carry a `ref` (local handle) and no id; update items carry `id`.
+ *   create items carry a `ref` (local handle) and no id; update items carry both
+ *   — the `ref` because the read-back check matches sub-issues to phases BY ref,
+ *   and an update with only an id makes every one of them look unmatched.
  *   `plan.issue` (when present) is the spec issue's description + state; the push
  *   skill applies `config.linear.projectId` grouping on top of it.
  */
@@ -85,7 +87,7 @@ function planChanges(projection, snapshot) {
     if (s.id == null) {
       subIssues.create.push({ ref: s.ref, name: s.name, goal: s.goal, state: s.state })
     } else if (snapS[String(s.id)] !== subIssueHash(s)) {
-      subIssues.update.push({ id: s.id, name: s.name, goal: s.goal, state: s.state })
+      subIssues.update.push({ ref: s.ref, id: s.id, name: s.name, goal: s.goal, state: s.state })
     }
   }
 

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',