@skitterbyte/skitterspec-linear 10.2.0 → 10.4.0

package/assets/core/linear.config.md

@@ -189,6 +189,59 @@ instead:
 
 ```bash
 export LINEAR_API_KEY=lin_api_…      # from Linear → Settings → Security & access
+
+Or store it once, for every repo on the machine, instead of exporting it in each:
+
+```
+skitterspec spec-sync credentials set        # prompts; input is hidden
+skitterspec spec-sync credentials status     # readiness only, never the value
+skitterspec spec-sync credentials unset      # remove this team's key
+```
+
+That writes `$XDG_CONFIG_HOME/skitterspec/credentials.json` (else
+`~/.config/…`) at mode `600`, keyed by team id. Resolution order is **environment
+variable first, then the store**, so CI is unaffected. A store readable by other
+users is refused with the `chmod` to run rather than used.
+
+`set` reads the key from a hidden prompt, or from a pipe with `--stdin`. There is
+deliberately **no `--key <value>` flag**: a secret in the command line is visible
+in shell history and to `ps`. For the same reason, run `set` yourself — never
+paste a key into an assistant conversation, where it would enter the transcript.
+`status` exists so an assistant can confirm readiness without ever seeing the
+key.
+
+### Delegating to a password manager
+
+Rather than storing the key at all, record a **command** that prints it. A
+command is not a secret, so unlike `--key` it is safe as an argument:
+
+```
+# 1Password CLI
+skitterspec spec-sync credentials set --command 'op read op://Private/linear/token'
+
+# pass
+skitterspec spec-sync credentials set --command 'pass show linear/api-key'
+
+# macOS Keychain (add once: security add-generic-password -s skitterspec -a linear -w)
+skitterspec spec-sync credentials set --command 'security find-generic-password -w -s skitterspec -a linear'
+```
+
+The command runs on each resolution; its stdout, trimmed, is the key. A non-zero
+exit or empty output means "no key", which simply falls back to MCP — with the
+reason shown by `credentials status`, so a broken command is never silently
+inert. It has 60 seconds to complete, enough for a biometric or master-password
+prompt. Recording a command replaces any stored key for that team, so the
+command actually runs.
+
+A command with a key written into it (`--command 'echo lin_api_…'`) is
+**refused**: commands are displayed by `status` and stored in clear, so that is
+strictly worse than storing the key. Use `credentials set` for a key.
+
+> **`keyCommand` is honoured only from the user-level store — never from
+> `specs/.core/linear.config.json`.** That file is committed and travels with the
+> repo, so a command named there would run on the machine of anyone who cloned it
+> and ran `spec-sync`. If one is found there it is ignored, and `credentials
+> status` says so.
 ```
 
 ```json

package/assets/skills/spec-linear-setup/SKILL.md

@@ -166,7 +166,27 @@ Confirm the file written and what it says, then name the next step:
 - `/spec-status` — read-only drift report, the safe way to prove the link works.
 - `/spec-push` — send a spec up.
 
+Then **check the API key, but never ask for it.** Run:
+
+```
+skitterspec spec-sync credentials status
+```
+
+It reports whether a key is set and where from, and never prints the value. If
+it says `key: not set`, tell the user to run this **themselves, in their own
+terminal**:
+
+```
+skitterspec spec-sync credentials set
+```
+
+**Do not ask the user to paste an API key into this conversation, and do not
+offer to store one for them.** A key pasted into a chat enters the transcript,
+is sent to the model, and may be logged — moving where a key is stored is
+pointless if it travels through the conversation to get there. Your job is to
+confirm the setup is ready and name the command; the value is theirs alone. The
+key is optional: without one, pushes go over MCP.
+
 Mention what setup did **not** configure, so the defaults aren't mistaken for
-decisions: phase mapping (`mapping.phases` — sub-issue per phase by default),
-field ownership, and the API key (`LINEAR_API_KEY`, which makes pushes take the
-fast path and never lives in the config). Point at `linear.config.md` for those.
+decisions: phase mapping (`mapping.phases` — sub-issue per phase by default) and
+field ownership. Point at `linear.config.md` for those.

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

@@ -0,0 +1,177 @@
+---
+name: spec-sync
+description: Run the repo-wide spec-sync operations against Linear — what's linked, the workspace's states and projects, read-back verification, manual stamping, and bulk `apply --all <bucket>`. Run it bare for the repo-wide overview. Wraps the `spec-sync` CLI, which is a local devDependency and never on PATH, so this skill always states the full invocation. Defers to /spec-push and /spec-status for per-spec work. Opt-in — needs specs/.core/linear.config.json. Use when the user says "/spec-sync", "run spec-sync", "what's linked to Linear", "which states does the workspace have", or "mirror the whole backlog".
+---
+
+# /spec-sync — the repo-wide Linear sync operations
+
+`/spec-push` and `/spec-status` cover **one spec**. This skill covers everything
+**repo-wide**, and is the answer to a bare "run spec-sync" — which is not itself
+a command.
+
+**Opt-in**: only runs when `specs/.core/linear.config.json` exists. If absent,
+tell the user how to enable Linear sync and stop.
+
+## The invocation — always state it
+
+`spec-sync` is a subcommand of a binary that is a **local devDependency**, so it
+is never on `PATH`. Typing `spec-sync` gives `command not found`, which reads as
+a broken install rather than a wrong invocation. Always run it — and always show
+the user you ran it — in full:
+
+```
+pnpm exec skitterspec-linear spec-sync <subcommand> [args]
+```
+
+In a project that installs the Linear superset the binary is
+`skitterspec-linear` (it also answers to `skitterspec`). Never print a bare
+`spec-sync …` as if the user could type it.
+
+## 1. Route the ask
+
+| The user asks | Run |
+|---------------|-----|
+| bare `/spec-sync`, "what's linked?", "how much is mirrored?" | `linked` |
+| "what states / projects does the workspace have?" | `states`, `projects` |
+| "did the mirror survive the push?" | `verify <spec> --stored <file>` |
+| "link this spec to KEY-1 by hand" | `stamp <spec> --issue KEY-1` |
+| "mirror the whole backlog / every complete spec" | `apply --all <bucket>` — **confirm first** |
+| "is the team key stale?", "did Linear get renamed?" | `doctor` |
+| push one spec, or "what would push?" | **defer** — see below |
+
+**With no argument, run `linked`.** It is the repo-wide overview, it is
+read-only, and it is what a bare "run spec-sync" means.
+
+**When the ask is genuinely ambiguous between a read and a write — ask.**
+"Sync the backlog" could mean `linked` (show me) or `apply --all backlog`
+(write dozens of issues). Never resolve that guess in favour of the write.
+
+## 2. Defer, don't duplicate
+
+Two front doors to one write path is worse than none:
+
+- **Push one spec** → `/spec-push`. It owns the transport choice, the
+  workspace-state gate, the plan, the apply, the stamping and the snapshot.
+- **Per-spec drift** ("is this spec in sync?", "what would push?") →
+  `/spec-status`.
+
+Say which skill you're handing to and stop; don't reimplement either.
+
+## 3. The read-only subcommands
+
+```
+pnpm exec skitterspec-linear spec-sync linked [--json]
+pnpm exec skitterspec-linear spec-sync states [--via api|mcp] [--json]
+pnpm exec skitterspec-linear spec-sync projects [--via api|mcp] [--json]
+```
+
+- **`linked`** is offline: which specs carry a `linear_identifier`, their bucket,
+  and an `N/M linked` total. Relay it, and when specs in `in-progress` have no
+  issue, say so — those are the ones a push would mint.
+- **`states` / `projects`** reach the workspace. `states` also reports the
+  **transport** (`api` when a key is set, else `mcp`), which is the honest way to
+  answer "how is this talking to Linear?".
+
+## 4. `verify` — check what the tracker actually stored
+
+```
+pnpm exec skitterspec-linear spec-sync verify <spec> --stored <file>
+```
+
+`--stored` is **what Linear currently holds**, read back over MCP:
+
+```json
+{ "issue": "…", "subIssues": { "01-engine": "…" } }
+```
+
+**It is not a `linear-base/*.base.json` snapshot.** That file holds content
+*hashes* keyed by identifier; comparing one against a description reports
+enormous losses on a perfectly intact mirror. The engine refuses a snapshot
+outright — if you see that refusal, you passed the wrong file, not found a bug.
+
+Warns, never fails. The repo is the source of truth; a mangled mirror is fixed
+by pushing again.
+
+## 5. `stamp` — the manual escape hatch
+
+```
+pnpm exec skitterspec-linear spec-sync stamp <spec> --issue KEY-1 [--url URL] [--sub <ref>=KEY-2 …]
+```
+
+Writes the ids into the spec's frontmatter without touching Linear. For adopting
+an issue created by hand, or repairing a stamp — not the normal path, which is
+`/spec-push`. A wrong id here makes the next push see an **unlinked** spec and
+mint a duplicate, so read the values back to the user before writing.
+
+## 6. `apply --all <bucket>` — bulk, and the one with real blast radius
+
+```
+pnpm exec skitterspec-linear spec-sync apply --all <bucket> [--via api|mcp] [--json]
+```
+
+**Confirm before running, and state creates and updates separately.** They are
+not the same risk:
+
+- an **update** refreshes a mirror that already exists;
+- a **create** mints new issues and sub-issues in someone's shared tracker.
+
+A repo adopting Linear reports "N to create" for every unlinked spec, so an
+unconsidered `--all` can mint dozens of sub-issues. Get the counts first — run
+`linked` to see what is unlinked, or `spec-sync push <spec>` per spec for exact
+numbers — then show the user something like:
+
+```
+apply --all backlog would:
+  create  12 issue(s) + 34 sub-issue(s)   ← new objects in Linear
+  update   3 issue(s) +  5 sub-issue(s)   ← refresh existing mirrors
+```
+
+Only run it on an explicit yes. It is resumable: every id is stamped the moment
+its object exists, so an interrupted run continues rather than duplicating.
+
+`--all` refuses over MCP by design — bulk goes through the API path.
+
+## 7. `doctor` — identifier drift after a team rename
+
+```
+pnpm exec skitterspec-linear spec-sync doctor [--json]
+```
+
+Renaming a Linear team changes every issue's identifier prefix and **nothing in
+the repo moves**: the stamps, the config `teamKey`, and the snapshot filenames
+and their sub-issue keys all keep the old prefix. `doctor` reports that. It is
+read-only and needs the **API transport** — it reads one issue per drifted ref,
+which over MCP would be a model round-trip each.
+
+It reports three things, deliberately separately:
+
+- **drift** — what `--write` would repair: stamps, snapshot filenames and keys,
+  the config key.
+- **mentions** — stale refs in spec *prose* (`(REU-61)` beside a task). Reported,
+  **never rewritten** — say so, so nobody reads a repair as total.
+- **missing** — refs that resolve to no issue under the new key. A different
+  problem; repair leaves them alone.
+
+A `missing` count that looks alarmingly high is worth a second look before you
+relay it as fact — the first hand-run of this check reported 146 of 198 refs as
+non-existent when every one was healthy and merely archived.
+
+**`--write` repairs it — confirm first, and state the counts.** It rewrites the
+config key, the frontmatter stamps, the snapshot filenames and the identifier
+keys inside them, all together. It refuses on a dirty git tree, because the
+repair is one large diff and has to be reviewable (and `git checkout -- .`-able)
+on its own — so commit or stash before offering it.
+
+It exits non-zero when it left anything behind: a ref that resolves to no issue
+is **not** rewritten, because repair fixes what is provably repairable rather
+than inventing a target. Relay that as an unfinished repair, not a success.
+
+After a repair, `spec-sync status` should still read `up to date` — the snapshot
+hashes are content-derived, so only their keys move. If it does not, say so
+rather than pushing over it.
+
+## 8. Report
+
+Relay the engine's output. Name the subcommand you ran, in full, so the user can
+re-run it themselves. For anything that wrote, say what changed in Linear and
+that the repo is unchanged — it is the source of truth either way.

package/bin/skitterspec-linear.js

@@ -4,8 +4,13 @@
 /**
  * The Linear-provider distribution's bin — a superset of the base CLI.
  *
- * `spec-sync …` is handled here (the provider engine seam); every other command
- * (`init`, `update`, `spec-env`, `--help`, …) delegates to the base CLI unchanged.
+ * The provider's own commands are routed from ONE table (`src/commands.js`),
+ * which also generates their `--help` section; every other command (`init`,
+ * `update`, `spec-env`, …) delegates to the base CLI unchanged.
+ *
+ * `--help` is the exception that has to be handled here rather than delegated:
+ * the base prints its own HELP const, which cannot know what a provider adds, so
+ * delegating made this distribution report that `spec-sync` did not exist.
  */
 
 // This package's bin/, src/ and assets/ are COMPOSED by scripts/build-dist.js and
@@ -27,24 +32,33 @@ if (!existsSync(join(__dirname, '..', 'src'))) {
   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')
+const { run, HELP } = require('../src/cli.js')
+const {
+  PROVIDER_COMMANDS,
+  providerHelpSection,
+} = require('../src/vendor/linear/commands.js')
 
 async function main(argv) {
   const [cmd, ...rest] = argv
-  if (cmd === 'spec-sync') {
-    // Propagate the exit code, like spec-sanitise below. Dropping it made
-    // `status --workspace-states` (a bad state name) and `stamp` (a refused
-    // write) both look successful to any caller checking $?, which is exactly
-    // what the /spec-push skill does before it applies a plan.
-    process.exitCode = await specSync(rest)
+
+  // Base help + what this distribution adds. Matched on the COMMAND SLOT only,
+  // never the whole argv: `spec-sanitise --help` must reach that command's own
+  // help, not be swallowed by the top-level one.
+  if (!cmd || cmd === '--help' || cmd === '-h') {
+    process.stdout.write(`${HELP}\n${providerHelpSection()}`)
     return
   }
-  if (cmd === 'spec-sanitise') {
-    process.exitCode = await specSanitise(rest)
+
+  const provider = PROVIDER_COMMANDS[cmd]
+  if (provider) {
+    // Propagate the exit code. Dropping it made `spec-sync status
+    // --workspace-states` (a bad state name) and `stamp` (a refused write) both
+    // look successful to any caller checking $?, which is exactly what the
+    // /spec-push skill does before it applies a plan.
+    process.exitCode = await provider.run(rest)
     return
   }
+
   await run(argv)
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skitterbyte/skitterspec-linear",
-  "version": "10.2.0",
+  "version": "10.4.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

@@ -48,6 +48,29 @@ const { renderRoutes, portsInUse, waitListening } = require('./env/proxy.js')
 
 const pkg = require('../package.json')
 
+// Commands this (tracker-free) base does NOT ship, and the distribution that
+// does. Without this the base says only "unknown command: spec-sync", which a
+// user correctly reads as "no such feature" — nothing anywhere named the
+// distribution that has it, so they were stranded. Naming Linear here is a
+// diagnostic string, not provider machinery: `init.js` already knows
+// `linear.config.json` and `linear-base/` by name in order to protect them.
+const PROVIDER_COMMANDS = {
+  'spec-sync': '@skitterbyte/skitterspec-linear',
+  'spec-sanitise': '@skitterbyte/skitterspec-linear',
+}
+
+function unknownCommand(cmd) {
+  const dist = PROVIDER_COMMANDS[cmd]
+  if (dist) {
+    return (
+      `unknown command: ${cmd} — this is the base distribution, which does not ` +
+      `ship it.\n  ${cmd} comes from ${dist} (a superset of this package): ` +
+      `install that instead.`
+    )
+  }
+  return `unknown command: ${cmd} (try --help)`
+}
+
 const HELP = `skitterspec — spec-driven-development for Claude Code
 
 Usage:
@@ -1384,8 +1407,8 @@ async function run(argv) {
       await cleanupReleaseTooling(dir, opts)
       break
     default:
-      throw new Error(`unknown command: ${cmd} (try --help)`)
+      throw new Error(unknownCommand(cmd))
   }
 }
 
-module.exports = { run, parse }
+module.exports = { run, parse, HELP, unknownCommand }

package/src/init.js

@@ -562,11 +562,21 @@ function printReport(dir, mode, { diff = false } = {}) {
   // 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'
-    : ''
+  const provider = setupSkill ? /^spec-(.+)-setup$/.exec(setupSkill)[1] : null
+  // …and the same derivation gives the provider's config filename, so this can
+  // report tracker sync the way it reports isolation above — from what is
+  // actually on disk. It used to say "opt-in: run /…-setup" even on a repo that
+  // had already configured it, telling you to set up what was already set up.
+  const trackerOn =
+    provider && fs.existsSync(path.join(dir, 'specs', '.core', `${provider}.config.json`))
+  const trackerNote = !setupSkill
+    ? ''
+    : trackerOn
+      ? `Tracker sync is ON: ${provider} — the repo stays the source of truth;` +
+        ' /spec-push mirrors a spec up and /spec-status reports drift.\n'
+      : `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' +

package/src/vendor/linear/api.js

@@ -29,27 +29,69 @@ const ENDPOINT = 'https://api.linear.app/graphql'
 const MAX_RETRIES = 5
 const MAX_BACKOFF_MS = 60_000
 
+const { storePath, readStore, resolveTeamKey } = require('./credentials.js')
+
 /**
- * Resolve the personal API key from the environment.
+ * Resolve the personal API key, environment first.
+ *
+ * Order — first hit wins:
+ *   1. `process.env[auth.keyEnv]`  (default LINEAR_API_KEY) — CI and every
+ *      existing setup, so this path is unchanged.
+ *   2. the user-level credentials store, keyed by `linear.teamId`.
  *
- * 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.
+ * Returns `{ ok: true, key, envVar, source }` where `source` is `'env'` or
+ * `'store'`, or `{ ok: false, envVar, error }` when nothing is set — a value the
+ * caller branches on rather than an exception, because "no key" is a normal
+ * state that means "use MCP", not a failure. A store that exists but is
+ * unreadable or world-readable is reported in `error`; it never silently
+ * degrades to "no key", or the leak would be invisible.
  *
  * 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) {
+function resolveApiKey(config, env = process.env, deps = {}) {
   const envVar = (config && config.auth && config.auth.keyEnv) || DEFAULT_KEY_ENV
-  const key = env[envVar]
-  if (typeof key !== 'string' || !key.trim()) {
+  const fromEnv = env[envVar]
+  if (typeof fromEnv === 'string' && fromEnv.trim()) {
+    return { ok: true, key: fromEnv.trim(), envVar, source: 'env' }
+  }
+
+  // The store is keyed by team, so with no teamId there is nothing to look up —
+  // skip the read entirely. That also keeps callers with no Linear config (and
+  // every unit test using the defaults) off the real filesystem.
+  const teamId = config && config.linear && config.linear.teamId
+  if (!teamId) {
     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 }
+
+  const file = (deps.storePath || storePath)(env)
+  const result = (deps.readStore || readStore)(file)
+  let commandReason = ''
+  if (result.ok) {
+    const found = (deps.resolveTeamKey || resolveTeamKey)(result.store, teamId, deps)
+    if (found.key) {
+      return { ok: true, key: found.key, envVar, source: found.source, command: found.command, path: file }
+    }
+    // A keyCommand that exists but did not produce a key is a real problem —
+    // surfacing it is the difference between "fix your command" and silence.
+    if (found.reason) commandReason = `\n  ${found.reason}`
+  }
+
+  // A store that is present but unusable is a distinct, reportable problem —
+  // don't let a permissions refusal read as "you never set a key".
+  const detail = (result.ok || result.code === 'absent' ? '' : `\n  ${result.reason}`) + commandReason
+  return {
+    ok: false,
+    envVar,
+    path: file,
+    error:
+      `no Linear API key — set ${envVar}, run \`skitterspec spec-sync credentials set\` ` +
+      `to store one in ${file}, or apply the plan over MCP with --via mcp${detail}`,
+  }
 }
 
 // Fields we read back on every write. `identifier` and `url` are what the skill
@@ -192,6 +234,18 @@ function makeApiAdapter({ apiKey, fetch: fetchImpl, endpoint, sleep, maxRetries
       if (data && data.team) return (data.team.projects && data.team.projects.nodes) || []
       return (data && data.projects && data.projects.nodes) || []
     },
+    // The team's CURRENT key, which is what `doctor` compares stamped
+    // identifiers against. Read from Linear rather than `config.linear.teamKey`
+    // on purpose: the config key is itself one of the things that goes stale
+    // when a team is renamed, so trusting it would make drift invisible. The
+    // teamId is stable across a rename; the key is not.
+    //
+    // API-only, like `listIssueStates` — see the operation-contract test: the
+    // API adapter may add ops, it may only never be missing one.
+    async readTeam(teamId) {
+      const data = await call(`query($id: String!) { team(id: $id) { id key name } }`, { id: teamId })
+      return (data && data.team) || null
+    },
     // 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) {