@skitterbyte/skitterspec-linear 10.1.0 → 10.2.0

package/bin/skitterspec-linear.js

@@ -8,6 +8,25 @@
  * (`init`, `update`, `spec-env`, `--help`, …) delegates to the base CLI unchanged.
  */
 
+// This package's bin/, src/ and assets/ are COMPOSED by scripts/build-dist.js and
+// gitignored, not committed — so a checkout linked before a build (or after a
+// `git clean`) has a working binary with nothing behind it. Say that, instead of
+// letting `require` raise MODULE_NOT_FOUND on an internal path the caller has no
+// way to interpret.
+//
+// Inline rather than shared: a helper would have to live in src/, which is
+// exactly what may be missing. In the workspace packages src/ always exists, so
+// this is inert there.
+const { existsSync } = require('node:fs')
+const { join } = require('node:path')
+if (!existsSync(join(__dirname, '..', 'src'))) {
+  console.error(
+    'skitterspec-linear: no build output — this package\'s bin/src/assets are composed, not committed.\n' +
+      '  run "npm run build" in the skitterspec repo, then try again.',
+  )
+  process.exit(1)
+}
+
 const { run } = require('../src/cli.js')
 const { specSync } = require('../src/vendor/linear/cli-sync.js')
 const { specSanitise } = require('../src/vendor/linear/cli-sanitise.js')

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skitterbyte/skitterspec-linear",
-  "version": "10.1.0",
+  "version": "10.2.0",
   "description": "Spec-driven development for Claude Code, with one-way Linear sync — a superset of @skitterbyte/skitterspec: the base filesystem workflow plus /spec-status · /spec-push and the spec-sync CLI. The repo is canonical; Linear is a generated mirror. Install this OR the base, not both.",
   "keywords": [
     "claude",

package/src/cli.js

@@ -190,7 +190,7 @@ function specEnvUp(dir, config, specArg) {
     process.stdout.write('Usage: skitterspec spec-env up <spec>\n')
     return
   }
-  const spec = resolveSpec(specArg, dir, config)
+  const spec = resolveSpecWithWorktree(dir, config, specArg)
 
   // Live-safe: if this spec is already live on the primary checkout (its branch was
   // branch-switched in by `live take`), a `git worktree add` would fail — the branch
@@ -357,7 +357,7 @@ function specEnvDown(dir, config, specArg, flags) {
     process.stdout.write('Usage: skitterspec spec-env down <spec> [--keep-volumes] [--force]\n')
     return
   }
-  const spec = resolveSpec(specArg, dir, config)
+  const spec = resolveSpecWithWorktree(dir, config, specArg)
 
   // A worktree-only spec never held a slot but its worktree still needs removing,
   // so "nothing to do" means neither a slot nor a worktree exists.
@@ -459,6 +459,31 @@ function liveWorktreePaths(dir) {
   return paths
 }
 
+// Resolve a spec argument the ONE way every spec-env subcommand resolves it:
+// against the primary checkout first, then the spec's own worktree, then every
+// other checkout git knows about. An in-progress spec is git-mv'd into
+// specs/in-progress/ **on its own branch**, so it exists only in its worktree —
+// a primary-checkout-only lookup fails for exactly the specs these commands
+// serve. The first fallback is the worktree path the config derives for this
+// spec (cheap, no git); the rest come from `git worktree list`, so a worktree
+// provisioned under an older `worktree.root` still resolves. Identity and
+// coordinate tokens always expand against `dir` (the primary checkout), so the
+// answer is identical whether the command was run from main or a worktree.
+function resolveSpecWithWorktree(dir, config, specArg) {
+  const { slug } = splitPrefix(path.basename(specArg))
+  const { repo, repoSlug } = repoInfo(dir)
+  const wtTokens = { repo, repoSlug, slug }
+  const worktreeGuess = path.resolve(
+    dir,
+    expandTokens(config.worktree.root, wtTokens),
+    expandTokens(config.worktree.folderPattern, wtTokens),
+  )
+  const searchDirs = [...new Set([worktreeGuess, ...liveWorktreePaths(dir)])].filter(
+    (p) => p !== dir,
+  )
+  return resolveSpec(specArg, dir, config, { searchDirs })
+}
+
 // Every spec folder name found under specs/* across the given checkout roots.
 // An in-progress spec lives on its *worktree branch*, not the primary checkout,
 // so we must scan the worktrees too — otherwise a live spec's DB looks orphaned.
@@ -771,7 +796,7 @@ function specEnvResolve(dir, config, specArg) {
     process.stdout.write('Usage: skitterspec spec-env resolve <spec>\n')
     return
   }
-  const r = resolveSpec(specArg, dir, config)
+  const r = resolveSpecWithWorktree(dir, config, specArg)
   process.stdout.write(
     `spec:       ${r.folder} (${r.bucket})\n` +
       `type/slug:  ${r.type} / ${r.slug}\n` +
@@ -792,7 +817,7 @@ async function specEnvDev(dir, config, positional) {
     process.stdout.write('Usage: skitterspec spec-env dev <up|down> <spec>\n')
     return
   }
-  const spec = resolveSpec(specArg, dir, config)
+  const spec = resolveSpecWithWorktree(dir, config, specArg)
   if (!config.dev.length) {
     process.stdout.write(
       'spec-env dev: no dev processes configured — set "dev": [...] in env.config.json.\n',
@@ -888,7 +913,7 @@ async function specEnvConnect(dir, config, specArg) {
     return
   }
 
-  const spec = resolveSpec(target, dir, config)
+  const spec = resolveSpecWithWorktree(dir, config, target)
   const registry = readRegistry(dir, config)
   if (!Object.prototype.hasOwnProperty.call(registry.slots, spec.folder)) {
     process.stdout.write(
@@ -984,20 +1009,6 @@ async function specEnvLive(dir, config, positional) {
   }
 }
 
-// Resolve a spec, offering its worktree as a fallback search dir — a spec authored
-// on its own branch may not exist in the primary checkout's specs/**.
-function resolveSpecWithWorktree(dir, config, specArg) {
-  const { slug } = splitPrefix(path.basename(specArg))
-  const { repo, repoSlug } = repoInfo(dir)
-  const wtTokens = { repo, repoSlug, slug }
-  const worktreeGuess = path.resolve(
-    dir,
-    expandTokens(config.worktree.root, wtTokens),
-    expandTokens(config.worktree.folderPattern, wtTokens),
-  )
-  return resolveSpec(specArg, dir, config, { searchDirs: [worktreeGuess] })
-}
-
 // Take the running instance: rebase the spec's branch onto base, free it from its
 // worktree, and check it out in the primary checkout so the dev server reloads it.
 async function specEnvLiveTake(dir, config, specArg) {

package/src/env/resolve.js

@@ -217,9 +217,14 @@ function assertPrimaryOnMain(config, git) {
  * (the primary checkout), so a worktree-only spec resolves to the right base.
  */
 function resolveSpec(specArg, dir, config, opts = {}) {
-  const found = findSpecFolder(specArg, dir, opts.searchDirs || [])
+  const searchDirs = opts.searchDirs || []
+  const found = findSpecFolder(specArg, dir, searchDirs)
   if (!found) {
-    throw new Error(`spec not found under specs/**: ${specArg}`)
+    // Name the roots we looked under: the usual cause is a spec that only exists
+    // on its own branch, and the message should say where we didn't find it.
+    throw new Error(
+      `spec not found under specs/**: ${specArg} (searched: ${[dir, ...searchDirs].join(', ')})`,
+    )
   }
 
   const { type, slug } = splitPrefix(found.folder)

package/src/env/teardown.js

@@ -33,7 +33,10 @@ function planDown(spec, config, flags, ctx) {
   // A hotfix lands by tag + cherry-pick, so its branch is never an ancestor of
   // base — but once its head is captured by a tag (the deploy tag from
   // `hotfix land`), the commits are recoverable and the branch is safe to drop.
-  // Treat "reachable from a tag" as landed, alongside merged.
+  // Treat "reachable from a tag" as landed, alongside merged. Read twice below:
+  // it decides whether the unpushed guard blocks, and whether the branch delete
+  // can use `-D` — the same question ("are these commits recoverable?"), so the
+  // two must never answer it differently.
   const landed = Boolean(worktreeState.merged || worktreeState.reachableFromTag)
 
   // --- guards (overridable with --force) ---
@@ -88,15 +91,26 @@ function planDown(spec, config, flags, ctx) {
   )
 
   // --- delete the branch ---
-  // Runs after the worktree remove frees the branch. Normally `-d` (safe: refuses
-  // an unmerged branch, never -D). A tag-landed hotfix branch is intentionally NOT
-  // an ancestor of base, so `-d` would refuse it — but its commits are captured by
-  // the deploy tag, so `-D` is safe *only* in that case. Everything else stays `-d`;
-  // on a forced teardown of a genuinely unmerged branch it fails loudly and the
-  // skill relays it rather than -D-ing.
+  // Runs after the worktree remove frees the branch. `-D` exactly when we have
+  // PROVEN the commits survive the delete, `-d` otherwise.
+  //
+  // `-d` looks like the safe default and mostly is, but its refusal answers a
+  // different question from ours: it also declines a branch that is ahead of its
+  // upstream ref, reporting `not yet merged to refs/remotes/origin/<branch>,
+  // even though it is merged to HEAD`. That fires on the ordinary spec flow —
+  // `/spec-go` pushes the branch when it provisions, and the phase commits after
+  // it are landed locally rather than pushed — so teardown meets a branch whose
+  // every commit is on `main` and `-d` refuses it. `merged` (HEAD is an ancestor
+  // of base) already establishes what we actually care about, and establishes it
+  // more strongly than `-d` checks.
+  //
+  // `reachableFromTag` is the same argument for a hotfix: never an ancestor of
+  // base, but its head is captured by the deploy tag.
+  //
+  // Everything else keeps `-d`, so a forced teardown of a genuinely unlanded
+  // branch fails loudly and the skill relays it rather than -D-ing.
   if (spec.branch) {
-    const tagLanded = Boolean(worktreeState.reachableFromTag && !worktreeState.merged)
-    commands.push(`git branch ${tagLanded ? '-D' : '-d'} ${spec.branch}`)
+    commands.push(`git branch ${landed ? '-D' : '-d'} ${spec.branch}`)
   }
 
   return { blocked: false, reason: null, commands, backupCommand, backupPath, volumesDropped }

package/src/init.js

@@ -558,12 +558,22 @@ function printReport(dir, mode, { diff = false } = {}) {
       ' at /spec-go (Docker is a per-spec escalation — set > **Stack:** in the spec).\n'
     : 'Per-spec isolation is opt-in: re-run with --isolation (or copy' +
       ' specs/.core/env.config.json.example → env.config.json) to enable it.\n'
+  // A provider superset ships its own `spec-<provider>-setup` skill; the base
+  // ships none. Discovering it from what was actually installed keeps this file
+  // tracker-free — it never has to know which tracker (if any) is in the box.
+  const setupSkill = SKILLS.find((s) => /^spec-.+-setup$/.test(s))
+  const trackerNote = setupSkill
+    ? `Tracker sync is opt-in: run /${setupSkill} to configure it` +
+      ' (it discovers your workspace and writes the config), or see' +
+      ' specs/.core/SETUP.md.\n'
+    : ''
   process.stdout.write(
     '\nDone. Skills resolve as /spec, /spec-go, /spec-complete, /spec-cancel,' +
       ' /spec-bug, /spec-review, /spec-init, /spec-connect.\n' +
       'Next: tailor .claude/rules/spec-planning.md + the CLAUDE.md section to this' +
       " project's stack, then run /spec.\n" +
-      isolationNote,
+      isolationNote +
+      trackerNote,
   )
 }
 

package/src/vendor/linear/api.js

@@ -0,0 +1,246 @@
+'use strict'
+
+/**
+ * The Linear GraphQL boundary — the one place that knows concrete Linear API
+ * shapes, exactly as `mcp.js` is the one place that knows concrete tool names.
+ *
+ * Both fulfil the SAME typed operation contract (`makeAdapter`'s return), so
+ * `spec-sync apply` is written once against an adapter and never learns which
+ * transport it got. That is the whole point: the MCP path stays supported, and
+ * the API path exists because routing every issue description through the model
+ * as generated tokens makes push throughput a function of decode speed rather
+ * than of Linear's API.
+ *
+ * Auth: a personal API key goes in `Authorization` **raw, with no `Bearer`
+ * prefix** — verified against Linear's own docs (https://linear.app/developers/graphql),
+ * which is the opposite of the OAuth access-token convention. Sending
+ * `Bearer lin_api_…` fails authentication.
+ *
+ * `fetch` is injected so tests exercise every operation offline and
+ * deterministically; production passes the global.
+ */
+
+const { DEFAULT_KEY_ENV } = require('./config.js')
+
+const ENDPOINT = 'https://api.linear.app/graphql'
+
+// Rate-limit handling. Enough retries to ride out a burst without turning a
+// genuinely stuck run into an unbounded one.
+const MAX_RETRIES = 5
+const MAX_BACKOFF_MS = 60_000
+
+/**
+ * Resolve the personal API key from the environment.
+ *
+ * Returns `{ ok: true, key, envVar }`, or `{ ok: false, envVar, error }` when
+ * unset — a value the caller branches on rather than an exception, because "no
+ * key" is a normal state that means "use MCP", not a failure.
+ *
+ * The key is never part of the returned error, and callers must keep it out of
+ * logs, plans, snapshots and stamped frontmatter.
+ */
+function resolveApiKey(config, env = process.env) {
+  const envVar = (config && config.auth && config.auth.keyEnv) || DEFAULT_KEY_ENV
+  const key = env[envVar]
+  if (typeof key !== 'string' || !key.trim()) {
+    return {
+      ok: false,
+      envVar,
+      error: `no Linear API key — set ${envVar}, or apply the plan over MCP with --via mcp`,
+    }
+  }
+  return { ok: true, key: key.trim(), envVar }
+}
+
+// Fields we read back on every write. `identifier` and `url` are what the skill
+// stamps into the spec; `description` is what `spec-sync verify` compares.
+const ISSUE_FIELDS = 'id identifier url title description state { id name }'
+
+/**
+ * A GraphQL caller bound to one key. Throws a clear Error on transport failure,
+ * on an HTTP error, and on a GraphQL `errors` payload — an `apply` that half
+ * succeeds must be loud, never silent.
+ */
+function makeClient({ apiKey, fetch: fetchImpl, endpoint = ENDPOINT, sleep, maxRetries = MAX_RETRIES }) {
+  const doFetch = fetchImpl || globalThis.fetch
+  if (typeof doFetch !== 'function') {
+    throw new Error('no fetch available — Node 18+ is required for the API transport')
+  }
+  // Injected so the retry path is testable without real delays.
+  const wait = sleep || ((ms) => new Promise((r) => setTimeout(r, ms)))
+
+  return async function call(query, variables) {
+    for (let attempt = 0; ; attempt++) {
+      let res
+      try {
+        res = await doFetch(endpoint, {
+          method: 'POST',
+          headers: {
+            'Content-Type': 'application/json',
+            // Raw, no `Bearer` — see the module comment.
+            Authorization: apiKey,
+          },
+          body: JSON.stringify({ query, variables }),
+        })
+      } catch (cause) {
+        throw new Error(`Linear API unreachable: ${cause && cause.message ? cause.message : cause}`)
+      }
+      if (res.status === 401 || res.status === 403) {
+        throw new Error(
+          `Linear rejected the API key (HTTP ${res.status}) — check the value of your key environment variable`,
+        )
+      }
+      // Rate limited. A bulk backfill is exactly the workload that hits this, and
+      // failing the run would strand a half-mirrored bucket — so wait and retry
+      // rather than surfacing it. Linear says how long to wait; honour that over
+      // guessing, and fall back to exponential backoff when it doesn't.
+      if (res.status === 429 && attempt < maxRetries) {
+        await wait(retryDelay(res, attempt))
+        continue
+      }
+      if (res.status === 429) {
+        throw new Error(`Linear rate-limited this request and did not recover after ${maxRetries} retries`)
+      }
+      if (!res.ok) throw new Error(`Linear API returned HTTP ${res.status}`)
+      const body = await res.json()
+      if (body && Array.isArray(body.errors) && body.errors.length) {
+        throw new Error(`Linear API error: ${body.errors.map((e) => e.message).join('; ')}`)
+      }
+      return body && body.data
+    }
+  }
+}
+
+// How long to wait before retrying a 429: the server's `Retry-After` (seconds)
+// when it sends one, else exponential backoff from 1s.
+function retryDelay(res, attempt) {
+  const header = res.headers && typeof res.headers.get === 'function' ? res.headers.get('retry-after') : null
+  const seconds = header != null ? Number(header) : NaN
+  if (Number.isFinite(seconds) && seconds >= 0) return Math.min(seconds * 1000, MAX_BACKOFF_MS)
+  return Math.min(1000 * 2 ** attempt, MAX_BACKOFF_MS)
+}
+
+/**
+ * Wrap a GraphQL client into the typed ops the engine uses — the same set
+ * `mcp.js`'s `makeAdapter` returns, so the two are interchangeable.
+ */
+function makeApiAdapter({ apiKey, fetch: fetchImpl, endpoint, sleep, maxRetries } = {}) {
+  const call = makeClient({ apiKey, fetch: fetchImpl, endpoint, sleep, maxRetries })
+
+  // Issue mutations return the created/updated issue under a payload wrapper.
+  const unwrap = (data, field) => (data && data[field] && data[field].issue) || null
+
+  return {
+    async readIssue(id) {
+      const data = await call(`query($id: String!) { issue(id: $id) { ${ISSUE_FIELDS} } }`, { id })
+      return (data && data.issue) || null
+    },
+    async createIssue(issue) {
+      const data = await call(
+        `mutation($input: IssueCreateInput!) { issueCreate(input: $input) { success issue { ${ISSUE_FIELDS} } } }`,
+        { input: issue },
+      )
+      return unwrap(data, 'issueCreate')
+    },
+    async updateIssue(id, updates) {
+      const data = await call(
+        `mutation($id: String!, $input: IssueUpdateInput!) { issueUpdate(id: $id, input: $input) { success issue { ${ISSUE_FIELDS} } } }`,
+        { id, input: updates },
+      )
+      return unwrap(data, 'issueUpdate')
+    },
+    // A phase sub-issue is an ordinary issue carrying `parentId`. Same mutation,
+    // so there is no separate sub-issue surface to keep in step.
+    async createSubIssue(parentId, subIssue) {
+      return this.createIssue({ ...subIssue, parentId })
+    },
+    async updateSubIssue(id, updates) {
+      return this.updateIssue(id, updates)
+    },
+    async listSubIssues(parentId) {
+      const data = await call(
+        `query($id: String!) { issue(id: $id) { children { nodes { ${ISSUE_FIELDS} } } } }`,
+        { id: parentId },
+      )
+      return (data && data.issue && data.issue.children && data.issue.children.nodes) || []
+    },
+    // The intake inbox. A free-text term uses Linear's `searchIssues` query; a
+    // label/team filter alone uses `issues`. Two queries rather than one because
+    // Linear exposes text search as its own root field, not an `IssueFilter` key.
+    async searchIssues({ label, query, teamId } = {}) {
+      const filter = {}
+      if (label) filter.labels = { name: { eq: label } }
+      if (teamId) filter.team = { id: { eq: teamId } }
+      if (query) {
+        const data = await call(
+          `query($term: String!, $filter: IssueFilter) {
+             searchIssues(term: $term, filter: $filter) { nodes { ${ISSUE_FIELDS} } } }`,
+          { term: query, filter },
+        )
+        return (data && data.searchIssues && data.searchIssues.nodes) || []
+      }
+      const data = await call(
+        `query($filter: IssueFilter) { issues(filter: $filter) { nodes { ${ISSUE_FIELDS} } } }`,
+        { filter },
+      )
+      return (data && data.issues && data.issues.nodes) || []
+    },
+    async listProjects(teamId) {
+      const data = teamId
+        ? await call(`query($id: String!) { team(id: $id) { projects { nodes { id name } } } }`, { id: teamId })
+        : await call('query { projects { nodes { id name } } }')
+      if (data && data.team) return (data.team.projects && data.team.projects.nodes) || []
+      return (data && data.projects && data.projects.nodes) || []
+    },
+    // The workspace's issue workflow states, in the shape `--workspace-states`
+    // already accepts, so the existing state check is reused rather than forked.
+    async listIssueStates(teamId) {
+      const data = teamId
+        ? await call(`query($id: String!) { team(id: $id) { states { nodes { id name type } } } }`, { id: teamId })
+        : await call('query { workflowStates { nodes { id name type } } }')
+      if (data && data.team) return (data.team.states && data.team.states.nodes) || []
+      return (data && data.workflowStates && data.workflowStates.nodes) || []
+    },
+  }
+}
+
+/**
+ * The workspace's state NAMES, for `validateStates` — the same array
+ * `--workspace-states` carries on the MCP path. On the API path nobody has to
+ * fetch it by hand.
+ */
+async function fetchWorkspaceStates(adapter, teamId) {
+  const states = await adapter.listIssueStates(teamId)
+  return states.map((s) => s && s.name).filter((n) => typeof n === 'string' && n)
+}
+
+/**
+ * Map a local lifecycle bucket to a Linear state ID.
+ *
+ * MCP accepted a state NAME; the GraphQL API needs an id, so this is the one
+ * extra hop the API transport adds. Resolved against the states actually fetched
+ * from the workspace, so a `config.states` value the workspace lacks fails here
+ * with the same vocabulary the state check already uses.
+ */
+function stateIdFor(bucket, config, states) {
+  const name = config && config.states && config.states[bucket]
+  if (!name) return null
+  const hit = states.find((s) => s && s.name === name)
+  if (!hit) {
+    throw new Error(
+      `no Linear state named ${JSON.stringify(name)} for bucket ${JSON.stringify(bucket)} — ` +
+        `workspace has: ${states.map((s) => s.name).join(', ')}`,
+    )
+  }
+  return hit.id
+}
+
+module.exports = {
+  ENDPOINT,
+  MAX_RETRIES,
+  resolveApiKey,
+  makeClient,
+  makeApiAdapter,
+  fetchWorkspaceStates,
+  stateIdFor,
+}