@skitterbyte/skitterspec-linear 10.2.0 → 10.4.0

package/src/vendor/linear/cli-sync.js

@@ -46,6 +46,15 @@ const {
 
 const { loadLinearConfig, mergeConfig, defaults: configDefaults, CONFIG_FILE, LIFECYCLE_BUCKETS } = require('./config.js')
 const { resolveApiKey, makeApiAdapter, stateIdFor, fetchWorkspaceStates } = require('./api.js')
+const { scanDrift, isClean, fileCount, dirtyPaths, repairDrift } = require('./doctor.js')
+const {
+  storePath,
+  storeMode,
+  fingerprint,
+  writeKey,
+  writeKeyCommand,
+  removeKey,
+} = require('./credentials.js')
 
 // Resolve a spec argument to its snapshot dir. Accepts a spec name/folder found
 // under specs/** (preferred) or a literal path to a snapshot directory.
@@ -158,8 +167,15 @@ function warnToErr(snapshotDir, config, err) {
   if (lines.length) err.write(lines.join('\n') + '\n')
 }
 
+// Resolve a spec argument to its folder, or null with a message on stdout.
+// EVERY failure path here must print and EVERY caller must return a non-zero
+// code: /spec-push checks $? before it applies a plan, so a resolve failure that
+// exits 0 reads as "nothing to do" rather than "I could not find the spec".
 function resolveOrExit(specArg, dir, out) {
-  if (!specArg) return null
+  if (!specArg) {
+    out.write('spec-sync: no spec given\n')
+    return null
+  }
   const snapshotDir = resolveSnapshotDir(specArg, dir)
   if (!snapshotDir) {
     out.write(`spec-sync: spec not found: ${specArg}\n`)
@@ -171,7 +187,7 @@ function resolveOrExit(specArg, dir, out) {
 // `spec-sync normalize <spec>` — print the local projection as JSON.
 function specSyncNormalize(dir, config, specArg, out, err) {
   const snapshotDir = resolveOrExit(specArg, dir, out)
-  if (!snapshotDir) return
+  if (!snapshotDir) return 1
   // stdout is the projection and nothing else — callers pipe it into jq.
   warnToErr(snapshotDir, config, err)
   out.write(JSON.stringify(projectionOf(snapshotDir, config), null, 2) + '\n')
@@ -404,7 +420,7 @@ function specSyncStamp(dir, config, specArg, flags, out) {
 // files. The skill calls this AFTER applying the plan and stamping new ids.
 function specSyncRecord(dir, config, specArg, out) {
   const snapshotDir = resolveOrExit(specArg, dir, out)
-  if (!snapshotDir) return
+  if (!snapshotDir) return 1
   const identifier = specIdentifier(snapshotDir, config)
   const file = recordPush({ dir, snapshotDir, identifier, config })
   out.write(`spec-sync record: snapshot written → ${path.relative(dir, file)}\n`)
@@ -417,7 +433,7 @@ function specSyncRecord(dir, config, specArg, out) {
 // configured state names and fails loudly on a typo Linear would silently no-op.
 function specSyncStatus(dir, config, specArg, flags, out) {
   const snapshotDir = resolveOrExit(specArg, dir, out)
-  if (!snapshotDir) return
+  if (!snapshotDir) return 1
   const identifier = specIdentifier(snapshotDir, config)
   const lines = [`spec-sync status: ${identifier}`, ...warningLines(snapshotDir, config)]
 
@@ -487,6 +503,26 @@ function specSyncVerify(dir, config, specArg, flags, out) {
     )
     return 1
   }
+  // A `.base.json` is the LAST-PUSHED SNAPSHOT, not a read-back: it stores
+  // content HASHES keyed by identifier, never description text. Passed as
+  // `--stored` it parses fine and compares a description against a hash, so the
+  // report is confidently, entirely wrong — a real field run read "5045
+  // character(s) lost" off an intact mirror. Refused here rather than only
+  // documented, because a guard is enforceable and prose is not.
+  const snapshotRoot = path.resolve(dir, config.sync.baseDir)
+  const isSnapshot =
+    flags.stored.endsWith('.base.json') || !path.relative(snapshotRoot, flags.stored).startsWith('..')
+  if (isSnapshot) {
+    out.write(
+      `spec-sync verify: ${path.relative(dir, flags.stored)} is a last-pushed snapshot, not a read-back.\n` +
+        '  It holds content hashes keyed by identifier — comparing one against a\n' +
+        '  description reports enormous bogus losses on a perfectly intact mirror.\n' +
+        '  --stored wants what the tracker CURRENTLY holds:\n' +
+        '    {"issue": "…", "subIssues": {"<ref>": "…"}}\n' +
+        '  /spec-push reads that back over MCP and writes it for this command.\n',
+    )
+    return 1
+  }
   let stored
   try {
     stored = JSON.parse(fs.readFileSync(flags.stored, 'utf-8'))
@@ -543,6 +579,160 @@ function verifyLines(snapshotDir, config, stored, identifier) {
   return lines
 }
 
+/**
+ * `spec-sync doctor [--json]` — identifier drift against the team's CURRENT key.
+ *
+ * A Linear team rename leaves every stamped identifier, the config `teamKey` and
+ * every snapshot filename on the old prefix, and nothing noticed. This reports
+ * it. Read-only: exit 0 whether or not it finds drift; non-zero only when it
+ * could not look (no key, MCP, unreadable team).
+ *
+ * Two things it deliberately does NOT do:
+ *
+ * 1. It does not trust `config.linear.teamKey` for the current key — that value
+ *    is itself one of the things that goes stale, so trusting it would make the
+ *    drift invisible. `teamId` survives a rename; the key does not.
+ * 2. It does not resolve refs with a bulk `team.issues` query. That connection
+ *    excludes archived issues AND caps at 250 per page, so the naive version
+ *    reports most of a healthy repo as missing — measured on a real workspace:
+ *    328 issues, 149 archived, and the unpaginated default returns 179. Reading
+ *    each ref individually has no list to page and no archived flag to forget;
+ *    `issue(id:)` resolves an archived issue by identifier (also verified).
+ */
+async function specSyncDoctor(dir, config, flags, out) {
+  const key = resolveApiKey(config, flags.env || process.env)
+  const transport = flags.via || (config.apply && config.apply.transport) || (key.ok ? 'api' : 'mcp')
+
+  // One read PER DRIFTED REF is the whole design; over MCP that is a model
+  // round-trip each, which is impractical at the scale this exists for (198 refs
+  // in the run that motivated it). Refused rather than quietly slow — the same
+  // call `apply --all` makes.
+  if (transport === 'mcp') {
+    out.write(
+      [
+        'spec-sync doctor: needs the api transport (nothing was read)',
+        `  ${key.ok ? '--via mcp was requested' : key.error}`,
+        '  it reads one issue per drifted ref, which MCP would route through the model.',
+      ].join('\n') + '\n',
+    )
+    return 1
+  }
+
+  const teamId = (config.linear && config.linear.teamId) || ''
+  if (!teamId) {
+    out.write('spec-sync doctor: no linear.teamId in specs/.core/linear.config.json — nothing to compare against.\n')
+    return 1
+  }
+
+  const adapter = flags.adapter || makeApiAdapter({ apiKey: key.key, fetch: flags.fetch })
+  let team
+  try {
+    team = await adapter.readTeam(teamId)
+  } catch (error) {
+    out.write(`spec-sync doctor: could not read the team: ${error.message}\n`)
+    return 1
+  }
+  if (!team || !team.key) {
+    out.write(`spec-sync doctor: Linear returned no team for ${teamId}\n`)
+    return 1
+  }
+
+  const drift = scanDrift(dir, config, team.key)
+
+  // Only the DISTINCT drifted identifiers are checked, so 221 stamps of 198
+  // identifiers cost 198 reads.
+  const missing = []
+  for (const ref of drift.refs) {
+    let got
+    try {
+      got = await adapter.readIssue(ref.to)
+    } catch (error) {
+      out.write(`spec-sync doctor: could not read ${ref.to}: ${error.message}\n`)
+      return 1
+    }
+    if (!got) missing.push(ref)
+  }
+
+  if (flags.json) {
+    out.write(JSON.stringify({ team: { id: team.id, key: team.key, name: team.name }, ...drift, missing }, null, 2) + '\n')
+    return 0
+  }
+
+  const was = [...new Set(drift.refs.map((r) => r.from.split('-')[0]))]
+  const lines = [`spec-sync doctor: team ${team.key}${was.length ? ` (stamps still on ${was.join(', ')})` : ''}`]
+  if (isClean(drift)) {
+    lines.push('  drift:   none — every stamped identifier is on the current team key')
+    out.write(lines.join('\n') + '\n')
+    return 0
+  }
+
+  const driftLines = []
+  const stamped = drift.stamps.length + drift.urls.length
+  if (stamped) driftLines.push(`${stamped} stamp(s) across ${fileCount(drift)} file(s), ${drift.refs.length} distinct ref(s)`)
+  if (drift.snapshots.length || drift.snapshotKeys.length) {
+    const parts = []
+    if (drift.snapshots.length) parts.push(`${drift.snapshots.length} filename(s)`)
+    if (drift.snapshotKeys.length) parts.push(`${drift.snapshotKeys.length} sub-issue key(s)`)
+    driftLines.push(`snapshots: ${parts.join(' + ')} under ${config.sync.baseDir}`)
+  }
+  if (drift.config) driftLines.push(`config linear.teamKey = "${drift.config.from}"`)
+  lines.push(`  drift:   ${driftLines[0]}`)
+  for (const l of driftLines.slice(1)) lines.push(`           ${l}`)
+
+  // Reported SEPARATELY from drift: a ref that resolves is repairable, one that
+  // does not is a different problem and must not be silently rewritten.
+  // Prose mentions are NOT repaired, so they are reported outside the drift
+  // block — a report that folded them in would imply --write fixes them.
+  if (drift.mentions.length) {
+    lines.push(
+      `  mentions: ${drift.mentions.length} stale ref(s) in spec prose — reported, NOT repaired by --write`,
+    )
+  }
+  lines.push(`  missing: ${missing.length} ref(s) that resolve to no issue under ${team.key}`)
+  for (const m of missing.slice(0, 10)) lines.push(`           ${m.from} → ${m.to} does not exist`)
+  if (missing.length > 10) lines.push(`           … and ${missing.length - 10} more`)
+
+  if (!flags.write) {
+    lines.push('  run with --write to repair (requires a clean git tree)')
+    out.write(lines.join('\n') + '\n')
+    return 0
+  }
+
+  // A repair rewrites hundreds of stamps across dozens of files. That is only
+  // safe to hand someone if it arrives as ONE reviewable diff they can throw
+  // away with `git checkout -- .` — which a dirty tree destroys. Same guard
+  // `spec-env integrate` uses, and for the same reason.
+  const dirty = dirtyPaths(dir)
+  if (dirty === null) {
+    lines.push('  --write refused: not a git repository, so the rewrite would not be reviewable')
+    out.write(lines.join('\n') + '\n')
+    return 1
+  }
+  if (dirty.length) {
+    lines.push(`  --write refused: ${dirty.length} uncommitted change(s) — commit or stash first`)
+    for (const d of dirty.slice(0, 10)) lines.push(`           ${d}`)
+    if (dirty.length > 10) lines.push(`           … and ${dirty.length - 10} more`)
+    lines.push('           the repair is one large diff; it must be reviewable on its own')
+    out.write(lines.join('\n') + '\n')
+    return 1
+  }
+
+  const skip = new Set(missing.map((m) => m.from))
+  const changed = repairDrift(dir, config, drift, { skip })
+  lines.push('  repaired:')
+  lines.push(`           ${changed.files.length} spec file(s)`)
+  lines.push(`           ${changed.snapshots.length} snapshot file(s) moved`)
+  if (changed.config) lines.push('           config linear.teamKey')
+  if (changed.skipped) {
+    lines.push(`           ${changed.skipped} ref(s) LEFT ALONE — they resolve to no issue under ${team.key}`)
+  }
+  lines.push('  review the diff, then commit it')
+  out.write(lines.join('\n') + '\n')
+  // Non-zero when anything was left behind, so a caller cannot read a partial
+  // repair as a complete one.
+  return changed.skipped ? 1 : 0
+}
+
 /**
  * `spec-sync states [--json]` — which transport this repo will use, and on the
  * API path the workspace's issue state NAMES.
@@ -739,13 +929,22 @@ async function applyOneSpec({ dir, config, snapshotDir, plan, adapter, teamId, p
   }
 
   // 3. Sub-issue updates — already linked, nothing to stamp.
+  //
+  // Keyed by REF, never by id: step 4 matches the read-back against the
+  // projection, which keys phases by ref. Keying an update by its id made every
+  // updated sub-issue report as a stale ref on every push. A plan written before
+  // updates carried a ref still resolves — by id, off the projection.
+  const refById = new Map()
+  for (const s of projectionOf(snapshotDir, config).subIssues || []) {
+    if (s.id != null) refById.set(String(s.id), s.ref)
+  }
   for (const sub of (plan.subIssues && plan.subIssues.update) || []) {
     await adapter.updateIssue(sub.id, withoutNull({
       title: sub.name,
       description: sub.goal,
       stateId: stateId(sub.state),
     }))
-    result.subIssues[sub.ref || sub.id] = sub.id
+    result.subIssues[sub.ref || refById.get(String(sub.id)) || sub.id] = sub.id
     lines.push(`  sub-issue updated: ${sub.id}`)
   }
 
@@ -1166,6 +1365,217 @@ function withoutNull(obj) {
   return out
 }
 
+// --- credentials -------------------------------------------------------------
+
+/**
+ * `spec-sync credentials <status|set|unset>` — manage the user-level API key.
+ *
+ * The split here is deliberate and is the whole point of the feature:
+ *
+ *   `status`  is SAFE FOR A SKILL TO RUN. It reports readiness and never the
+ *             value — path, mode, team, and a masked fingerprint.
+ *   `set`     is for a HUMAN, run outside the model. It reads the key from a TTY
+ *             with echo off (or `--stdin`), never from argv.
+ *
+ * A key typed into a chat enters the transcript, is sent to the model and may be
+ * logged; moving where a key is STORED is worthless if it travels through the
+ * conversation to get there. So nothing in this file ever prints a key, and
+ * `--key <value>` is refused rather than supported.
+ */
+async function specSyncCredentials(dir, config, action, flags, out) {
+  const env = flags.env || process.env
+  const file = storePath(env)
+  const teamId = (config.linear && config.linear.teamId) || ''
+  const teamKey = (config.linear && config.linear.teamKey) || ''
+  const label = teamKey ? `${teamId} (${teamKey})` : teamId
+
+  if (!teamId) {
+    out.write(
+      'spec-sync credentials: no linear.teamId in specs/.core/linear.config.json.\n' +
+        '  The store is keyed by team — run `spec-sync init-config` first.\n',
+    )
+    return 1
+  }
+
+  if (action === 'status' || !action) return credentialsStatus(dir, config, file, label, flags, out)
+  if (action === 'set') return credentialsSet(file, teamId, label, flags, out)
+  if (action === 'unset') return credentialsUnset(file, teamId, label, out)
+
+  out.write('Usage: skitterspec spec-sync credentials <status|set|unset> [--stdin] [--json]\n')
+  return 1
+}
+
+// Readiness only — the command a skill runs. Never prints the key.
+function credentialsStatus(dir, config, file, label, flags, out) {
+  const resolved = resolveApiKey(config, flags.env || process.env)
+  const mode = storeMode(file)
+  const present = resolved.ok
+  const payload = {
+    store: file,
+    mode,
+    team: label,
+    key: present ? { present: true, source: resolved.source, fingerprint: fingerprint(resolved.key) } : { present: false },
+  }
+  if (flags.json) {
+    out.write(JSON.stringify(payload, null, 2) + '\n')
+    return present ? 0 : 1
+  }
+
+  const lines = ['spec-sync credentials:']
+  const strayed = repoConfigKeyCommand(dir)
+  if (strayed) {
+    lines.push(
+      '  note:   a keyCommand in specs/.core/linear.config.json is IGNORED.',
+      '          That file is committed, so a command there would run on the',
+      '          machine of anyone who cloned the repo. Record it here instead:',
+      '            skitterspec spec-sync credentials set --command <cmd>',
+    )
+  }
+  lines.push(`  store:  ${file}${mode ? ` (${mode})` : ' (not created yet)'}`)
+  lines.push(`  team:   ${label}`)
+  if (present) {
+    const where =
+      resolved.source === 'env'
+        ? `environment (${resolved.envVar})`
+        : resolved.source === 'command'
+          ? 'keyCommand'
+          : 'store'
+    lines.push(`  key:    set — ${fingerprint(resolved.key)} from the ${where}`)
+    if (resolved.command) lines.push(`  runs:   ${resolved.command}`)
+  } else {
+    lines.push('  key:    not set')
+    // `resolveApiKey` appends a reason when the store or its keyCommand is
+    // broken rather than merely absent. Dropping it here would report a failing
+    // command as "you never set a key" and send the user to set it again.
+    for (const detail of resolved.error.split('\n').slice(1)) {
+      if (detail.trim()) lines.push(`  problem:${detail.replace(/^ +/, ' ')}`)
+    }
+    lines.push('')
+    lines.push('  Run this yourself, in your own terminal — not through an assistant:')
+    lines.push('    skitterspec spec-sync credentials set')
+  }
+  out.write(lines.join('\n') + '\n')
+  return present ? 0 : 1
+}
+
+// The human-facing setter. TTY prompt with echo off, or `--stdin` for a pipe.
+async function credentialsSet(file, teamId, label, flags, out) {
+  if (flags.keyArgGiven) {
+    out.write(
+      'spec-sync credentials: --key is not supported, on purpose.\n' +
+        '  A secret in the command line is visible in shell history and to `ps`.\n' +
+        '  Run `credentials set` with no arguments and paste at the prompt (input\n' +
+        '  is hidden), or pipe it: `… | credentials set --stdin`.\n',
+    )
+    return 1
+  }
+
+  // A command is not a secret — it names WHERE the key lives, so unlike --key it
+  // is safe on the command line and nothing is prompted for.
+  if (flags.command) {
+    const r = writeKeyCommand(file, teamId, flags.command)
+    if (!r.ok) {
+      out.write(`spec-sync credentials: ${r.reason}\n`)
+      return 1
+    }
+    out.write(
+      `spec-sync credentials: ${label} will resolve its key by running:\n` +
+        `  ${flags.command}\n` +
+        `  recorded in ${r.path} (600)\n`,
+    )
+    return 0
+  }
+
+  let key
+  if (flags.stdin) {
+    key = (await readAllStdin(flags.input || process.stdin)).trim()
+    if (!key) {
+      out.write('spec-sync credentials: nothing on stdin — no key stored.\n')
+      return 1
+    }
+  } else {
+    const input = flags.input || process.stdin
+    if (!input.isTTY) {
+      out.write(
+        'spec-sync credentials: not a terminal — cannot prompt for a key.\n' +
+          '  Run it in your own terminal, or pipe the key with --stdin.\n',
+      )
+      return 1
+    }
+    key = (await promptHidden(`Linear personal API key for ${label} (hidden): `, input, out)).trim()
+    if (!key) {
+      out.write('spec-sync credentials: empty input — no key stored.\n')
+      return 1
+    }
+  }
+
+  const r = writeKey(file, teamId, key)
+  if (!r.ok) {
+    out.write(`spec-sync credentials: ${r.reason}\n`)
+    return 1
+  }
+  out.write(`spec-sync credentials: key stored for ${label} in ${r.path} (600)\n`)
+  return 0
+}
+
+function credentialsUnset(file, teamId, label, out) {
+  const r = removeKey(file, teamId)
+  if (!r.ok) {
+    out.write(`spec-sync credentials: ${r.reason}\n`)
+    return 1
+  }
+  out.write(
+    r.removed
+      ? `spec-sync credentials: removed the key for ${label} from ${r.path}\n`
+      : `spec-sync credentials: no key stored for ${label} — nothing to remove\n`,
+  )
+  return 0
+}
+
+// Is a keyCommand set in the REPO's committed config? It is never honoured — the
+// loader drops unknown keys — but silently ignoring it would leave someone
+// wondering why their command never runs, so `status` calls it out.
+function repoConfigKeyCommand(dir) {
+  try {
+    const raw = fs.readFileSync(path.join(dir, CONFIG_FILE), 'utf-8')
+    const parsed = JSON.parse(raw)
+    const auth = parsed && parsed.auth
+    return auth && typeof auth.keyCommand === 'string' && auth.keyCommand.trim()
+      ? auth.keyCommand.trim()
+      : null
+  } catch {
+    return null
+  }
+}
+
+// Read stdin to completion (for `--stdin`).
+function readAllStdin(input) {
+  return new Promise((resolve, reject) => {
+    let data = ''
+    input.setEncoding('utf-8')
+    input.on('data', (chunk) => (data += chunk))
+    input.on('end', () => resolve(data))
+    input.on('error', reject)
+  })
+}
+
+// Prompt on a TTY with the input hidden. `_writeToOutput` is readline's own echo
+// hook — silencing it is what keeps the key off the screen (and out of a
+// screen-shared terminal or a recorded session).
+function promptHidden(question, input, out) {
+  const readline = require('node:readline')
+  return new Promise((resolve) => {
+    const rl = readline.createInterface({ input, output: process.stdout, terminal: true })
+    out.write(question)
+    rl.question('', (answer) => {
+      out.write('\n')
+      rl.close()
+      resolve(answer)
+    })
+    rl._writeToOutput = () => {}
+  })
+}
+
 async function specSync(rest, io = {}) {
   const out = io.out || process.stdout
   const err = io.err || process.stderr
@@ -1173,7 +1583,7 @@ async function specSync(rest, io = {}) {
   let dir = io.cwd || process.cwd()
   const positional = []
   const flags = { json: false, remote: null, workspaceStates: null, skipStateCheck: false, issue: null, url: null, subs: [], stored: null, plan: null, via: null, project: null, all: null,
-    force: false, teamId: '', teamKey: '', projectId: '', intakeLabel: '', bugLabels: [], hotfixLabels: [], stateNames: {}, statesFile: null }
+    force: false, write: false, teamId: '', teamKey: '', projectId: '', intakeLabel: '', bugLabels: [], hotfixLabels: [], stateNames: {}, statesFile: null }
   for (let i = 0; i < args.length; i++) {
     if (args[i] === '--dir') dir = path.resolve(args[++i])
     else if (args[i] === '--json') flags.json = true
@@ -1189,6 +1599,17 @@ async function specSync(rest, io = {}) {
     else if (args[i] === '--url') flags.url = args[++i]
     else if (args[i] === '--sub') flags.subs.push(args[++i])
     else if (args[i] === '--force') flags.force = true
+    else if (args[i] === '--write') flags.write = true
+    else if (args[i] === '--stdin') flags.stdin = true
+    else if (args[i] === '--command') flags.command = String(args[++i] || '').trim()
+    else if (args[i] === '--key') {
+      // Consumed and DELIBERATELY DISCARDED. A secret in argv is visible in
+      // shell history and to `ps`, so this is refused rather than supported —
+      // but it must still be swallowed here, or the value would fall through to
+      // `positional` and end up printed back in a usage message.
+      i++
+      flags.keyArgGiven = true
+    }
     else if (args[i] === '--team-id') flags.teamId = String(args[++i] || '').trim()
     else if (args[i] === '--team-key') flags.teamKey = String(args[++i] || '').trim()
     else if (args[i] === '--project-id') flags.projectId = String(args[++i] || '').trim()
@@ -1227,21 +1648,21 @@ async function specSync(rest, io = {}) {
 
   switch (sub) {
     case 'normalize':
-      specSyncNormalize(dir, config, positional[0], out, err)
-      return 0
+      return specSyncNormalize(dir, config, positional[0], out, err) || 0
     case 'push':
       return specSyncPush(dir, config, positional[0], flags, out, err) || 0
     case 'stamp':
       return specSyncStamp(dir, config, positional[0], flags, out)
     case 'record':
-      specSyncRecord(dir, config, positional[0], out)
-      return 0
+      return specSyncRecord(dir, config, positional[0], out) || 0
     case 'status':
       return specSyncStatus(dir, config, positional[0], flags, out) || 0
     case 'projects':
       return (await specSyncProjects(dir, config, flags, out)) || 0
     case 'states':
       return (await specSyncStates(dir, config, flags, out)) || 0
+    case 'doctor':
+      return (await specSyncDoctor(dir, config, flags, out)) || 0
     case 'apply':
       return (await specSyncApply(dir, config, positional[0], flags, out)) || 0
     case 'verify':
@@ -1249,8 +1670,11 @@ async function specSync(rest, io = {}) {
     case 'linked':
       specSyncLinked(dir, config, flags, out)
       return 0
+    case 'credentials':
+      return await specSyncCredentials(dir, config, positional[0], flags, out)
     default:
       out.write('Usage: skitterspec spec-sync <normalize|record|status> <spec> [--json] [--remote file] [--workspace-states file]\n' +
+        '       skitterspec spec-sync credentials <status|set|unset> [--stdin] [--json]\n' +
         '       skitterspec spec-sync push <spec> --workspace-states <file> [--json] [--skip-state-check]\n' +
         '       skitterspec spec-sync stamp <spec> --issue KEY-1 [--url URL] [--sub <ref>=KEY-2 …]\n' +
         '       skitterspec spec-sync states [--via api|mcp] [--json]\n' +
@@ -1259,6 +1683,7 @@ async function specSync(rest, io = {}) {
         '       skitterspec spec-sync apply --all <bucket> [--via api|mcp] [--json]\n' +
         '       skitterspec spec-sync verify <spec> --stored <file>\n' +
         '       skitterspec spec-sync linked [--json]\n' +
+        '       skitterspec spec-sync doctor [--write] [--json]\n' +
         '       skitterspec spec-sync init-config --team-id <id> [--team-key K] [--project-id id]\n' +
         '                    [--intake-label L] [--bug-labels a,b] [--hotfix-labels a,b]\n' +
         '                    [--state <bucket>=<name> …] [--states <file>] [--force] [--json]\n')

package/src/vendor/linear/commands.js

@@ -0,0 +1,54 @@
+'use strict'
+
+/**
+ * The commands this provider distribution adds on top of the base CLI.
+ *
+ * ONE table drives both routing and `--help`. That pairing is the point: the bug
+ * this fixes was `spec-sync` being routed by the bin while the base's `HELP`
+ * const knew nothing about it, so the one distribution that ships the command
+ * told users it did not exist. Anything added here is routed and documented in
+ * the same edit — the two cannot drift, and a test asserts it.
+ *
+ * `run(rest)` returns an exit code (the bin propagates it); `summary` is the
+ * one-line description `--help` prints.
+ */
+
+const { specSync } = require('./cli-sync.js')
+const { specSanitise } = require('./cli-sanitise.js')
+
+const DIST = '@skitterbyte/skitterspec-linear'
+
+const PROVIDER_COMMANDS = {
+  'spec-sync': {
+    run: specSync,
+    usage: 'skitterspec spec-sync <cmd>',
+    summary:
+      'One-way sync to Linear (repo -> tracker; opt-in, needs\n' +
+      'specs/.core/linear.config.json). Run it with no args to\n' +
+      'list its subcommands.',
+  },
+  'spec-sanitise': {
+    run: specSanitise,
+    usage: 'skitterspec spec-sanitise',
+    summary:
+      'Rewrite spec markdown so no emphasis or link straddles a\n' +
+      'line break. Dry-run; --write to apply.',
+  },
+}
+
+// The `--help` section for these commands, in the base HELP's column layout:
+// two-space indent, description starting at column 30, continuations aligned.
+const COL = 30
+
+function providerHelpSection() {
+  const lines = [`Provider commands (${DIST}):`]
+  for (const name of Object.keys(PROVIDER_COMMANDS)) {
+    const { usage, summary } = PROVIDER_COMMANDS[name]
+    const [first, ...rest] = summary.split('\n')
+    lines.push(`  ${usage.padEnd(COL - 2)}${first}`)
+    for (const line of rest) lines.push(`${' '.repeat(COL)}${line}`)
+  }
+  return lines.join('\n') + '\n'
+}
+
+module.exports = { PROVIDER_COMMANDS, providerHelpSection, DIST }