@skitterbyte/skitterspec-linear 18.3.1 → 19.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,10 +1,10 @@
1
1
  ---
2
2
  name: spec-status
3
- description: Show a spec's one-way sync status against Linear — a read-only drift report naming what would push, and whether the tracker's workflow-state has drifted from the spec's. Changes nothing. Opt-in — needs specs/.core/linear.config.json. Use when the user says "/spec-status", "is this spec in sync with Linear", "what would push", or "show spec sync status".
3
+ description: Show a spec's one-way sync status against Linear — a read-only report naming what would push, and whether someone edited the issue's description since the last push. Changes nothing. Opt-in — needs specs/.core/linear.config.json. Use when the user says "/spec-status", "is this spec in sync with Linear", "what would push", or "show spec sync status".
4
4
  disable-model-invocation: true
5
5
  ---
6
6
 
7
- # /spec-status — one-way sync drift report
7
+ # /spec-status — one-way sync report
8
8
 
9
9
  > Stay silent while this runs — speak only to ask something you cannot answer
10
10
  > yourself, or to report a failure at the moment it happens. Read
@@ -15,13 +15,17 @@ Read-only. Reports two things and writes nothing:
15
15
 
16
16
  1. **Pending push** — has the spec changed since the last push (is there an issue
17
17
  description/state or any phase sub-issue to create or update)?
18
- 2. **State drift** — does Linear's issue workflow-state differ from the spec's
19
- status? (The repo wins on the next push; this is just a heads-up, e.g. a card
20
- moved in Linear.)
18
+ 2. **Description edited** — did someone edit the issue's description on Linear
19
+ since the last push? The next push replaces it, so this is worth reading
20
+ first.
21
+
22
+ **Status is not compared, deliberately.** Skitterspec tells Linear about its
23
+ own transitions and never reads a status back: a card someone moved by hand is
24
+ theirs to have moved, and push resends State only when the spec itself moves.
21
25
 
22
26
  The repo is the source of truth; Linear is a generated mirror, so there is no
23
- per-field "conflict" — only "what would the next push send" and "did the mirror
24
- drift".
27
+ per-field "conflict" — only "what would the next push send" and "did someone
28
+ write over the mirror's text".
25
29
 
26
30
  **Opt-in**: only runs when `specs/.core/linear.config.json` exists. If absent,
27
31
  tell the user how to enable Linear sync and stop.
@@ -30,18 +34,16 @@ tell the user how to enable Linear sync and stop.
30
34
 
31
35
  Use the argument, else the spec in context; ask if unclear.
32
36
 
33
- ## 2. Fetch the Linear issue (optional, for drift)
37
+ ## 2. Fetch the Linear issue (optional, for the description check)
34
38
 
35
39
  If the spec has a `linear_identifier`, discover the Linear MCP read tool
36
- (`get_issue`) and write the issue JSON to a temp file. If Linear isn't connected,
37
- skip the drift lines (still report pending-push).
40
+ (`get_issue`) and write the issue JSON to a temp file. If Linear isn't
41
+ connected, skip the description check (still report pending-push).
38
42
 
39
- **Write the whole issue, including its `description`.** The engine reports two
40
- independent kinds of drift off that one file: the workflow-state someone moved,
41
- and the **description someone edited**. Write only the state fields and the
42
- second check has nothing to look at — and it says nothing rather than guessing,
43
- so the loss is silent. Keep `url` too: it is what the description line points
44
- the reader at.
43
+ **Write the whole issue, including its `description`.** That is the field the
44
+ check reads; without it the check has nothing to look at — and it says nothing
45
+ rather than guessing, so the loss is silent. Keep `url` too: it is what the
46
+ description line points the reader at.
45
47
 
46
48
  **The description itself never enters the conversation.** The engine hashes it
47
49
  and compares hashes; what it prints is *that* the text changed, plus where to
@@ -58,8 +60,9 @@ skitterspec spec-sync status <spec> [--remote <issuefile>] [--workspace-states <
58
60
  ```
59
61
 
60
62
  - Reports `push: pending — N to create, M to update` or `up to date`.
61
- - With `--remote`, adds a `drift:` line comparing Linear's issue workflow-state
62
- to the spec's status.
63
+ - With `--remote`, adds a `drift:` line when the issue's description was
64
+ edited on Linear since the last push, and nothing otherwise. It never
65
+ reports the issue's state.
63
66
  - With `--workspace-states`, fails loudly if a configured state name isn't in the
64
67
  workspace (Linear would silently no-op it).
65
68
 
@@ -92,18 +95,19 @@ the shape; this section carries only what is specific here.
92
95
  **Verdicts**
93
96
 
94
97
  - `✅` — in sync; nothing would push.
95
- - `⚠️` — drift: N objects would push, Linear's workflow state was moved by hand,
96
- or the issue's **description** was edited on Linear since the last push. None
97
- is an error — the repo wins on the next push — but all are the reason someone
98
- ran this. **Say which**, since the three call for different things: a pending
99
- push is routine, a moved state is usually someone else's automation, and an
100
- edited description means a person wrote something that the next push replaces.
98
+ - `⚠️` — N objects would push, or the issue's **description** was edited on
99
+ Linear since the last push. Neither is an error, but both are the reason
100
+ someone ran this. **Say which**, since they call for different things: a
101
+ pending push is routine, and an edited description means a person wrote
102
+ something that the next push replaces.
103
+ An `assignee` drift line is the third case: the assignee is a field the repo
104
+ owns, so the next push restores the spec's record.
101
105
  - `⏸` — no config, or the spec is not linked. Nothing to compare.
102
106
 
103
107
  **Fields:** `Tracker` · `Follow-ups` · `Next`
104
108
 
105
- `Tracker` is the drift in one line — what would push, and whether the tracker's
106
- state diverged. `Next` is `/spec-push` when a push is pending, and nothing to do
109
+ `Tracker` is the answer in one line — what would push, and whether the
110
+ description was edited. `Next` is `/spec-push` when a push is pending, and nothing to do
107
111
  when it is not.
108
112
 
109
113
  A **`phases: <mode>`** line names the phase mode that resolved for this spec's
@@ -46,8 +46,7 @@ In a project that installs the Linear superset the binary is
46
46
  | "mirror the whole backlog / every complete spec" | `apply --all <bucket>` — **confirm first** |
47
47
  | "is the team key stale?", "did Linear get renamed?" | `retarget` |
48
48
  | "what ticket am I on?", writing a commit | `ref` |
49
- | "what shipped in this release?" | `released` |
50
- | "move the shipped tickets on", "what's on test?" | `stage` — dry run unless `--apply` |
49
+ | "what shipped in this release?", "which tickets does CI mark deployed?" | `released` — `--json` for a script; recording deploys is the project's own |
51
50
  | "is any of this wired up?", "why isn't sync working?" | `doctor` — scaffold, isolation, tracker and key in one |
52
51
  | "set my Linear key", "am I authenticated?" | `credentials <status\|set\|unset>` |
53
52
  | "who am I in Linear?", "why is it assigning the wrong person?" | `whoami` — `--set` for a shared or bot key |
@@ -67,7 +66,7 @@ Two front doors to one write path is worse than none:
67
66
 
68
67
  - **Push one spec** → `/spec-push`. It owns the transport choice, the
69
68
  workspace-state gate, the plan, the apply, the stamping and the snapshot.
70
- - **Per-spec drift** ("is this spec in sync?", "what would push?") →
69
+ - **Per-spec status** ("is this spec in sync?", "what would push?") →
71
70
  `/spec-status`.
72
71
 
73
72
  Say which skill you're handing to and stop; don't reimplement either.
@@ -169,8 +168,10 @@ and never write `Refs: none`.
169
168
 
170
169
  `released` reports the tickets in a commit range — by default since the most
171
170
  recent tag, and it always prints the range it chose so a wrong default is
172
- visible. It is **read-only**: it does not move anything in Linear. A release can
173
- be cut and never deployed, so transitioning tickets stays a deliberate act.
171
+ visible. It is **read-only**: it does not move anything in Linear. Each ticket
172
+ row names the `spec` and `url` behind it (`null` when no spec linked the ref),
173
+ so `--json` is what a project's CI pipes into its own tooling to record a
174
+ release or a deploy. Recording those is the project's job, not skitterspec's.
174
175
 
175
176
  Relay the **unreferenced count** even when it is zero. A chore commit
176
177
  legitimately carries no ticket and a *missed* trailer looks identical, so
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@skitterbyte/skitterspec-linear",
3
- "version": "18.3.1",
3
+ "version": "19.0.0",
4
4
  "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.",
5
5
  "keywords": [
6
6
  "claude",
package/src/cli.js CHANGED
@@ -88,6 +88,8 @@ const {
88
88
  collectReview,
89
89
  reviewTierStack,
90
90
  reviewTierLine,
91
+ isTailnetAddress,
92
+ tailnetLabel,
91
93
  renderReviewPage,
92
94
  renderReviewBlock,
93
95
  reviewOutPath,
@@ -4258,6 +4260,10 @@ async function specEnvReview(dir, config, specArg, flags, invokedFrom = dir) {
4258
4260
  // use, and the engine cannot know — that guess failed three separate ways
4259
4261
  // in one day. Now every tier is listed, labelled, and either a URL or the
4260
4262
  // one command that turns it on.
4263
+ // The runners-up print as `also:` lines inside the network tier's own
4264
+ // rendering — `reviewTierLine` carries them, which is what puts them
4265
+ // under `network:` rather than dangling after the stack (they used to
4266
+ // print below `remote:`, against the comment that placed them).
4261
4267
  reviewTierStack({
4262
4268
  served,
4263
4269
  fileUrl: reviewFileUrl(out),
@@ -4266,11 +4272,6 @@ async function specEnvReview(dir, config, specArg, flags, invokedFrom = dir) {
4266
4272
  })
4267
4273
  .map((t) => reviewTierLine(t) + '\n')
4268
4274
  .join('') +
4269
- // The runners-up sit UNDER the network tier, because that is what they are
4270
- // alternatives to — and virtual adapters are gone from them entirely.
4271
- (served && !served.loopback && (served.alternates || []).length
4272
- ? served.alternates.map((u) => ` also: ${u}${tailnetLabel(u)}\n`).join('')
4273
- : '') +
4274
4275
  // WHICH TIERS THE WAIT COVERS, once, next to the stack. `local` and
4275
4276
  // `network` are two doors into one room — the page POSTs to
4276
4277
  // `location.pathname`, so both reach this server and this pending store.
@@ -4583,26 +4584,6 @@ function offerableLanAddresses(nets = require('node:os').networkInterfaces()) {
4583
4584
  .map((e) => e.address)
4584
4585
  }
4585
4586
 
4586
- // 100.64.0.0/10 — the CGNAT range Tailscale assigns from.
4587
- //
4588
- // WHAT WOULD FOOL THIS: a carrier-grade NAT or another overlay network using
4589
- // the same range on a utun adapter is offered too. That costs one dud `also:`
4590
- // line, where filtering it hides the only link a reader off the wifi can open.
4591
- function isTailnetAddress(address) {
4592
- const m = /^100\.(\d+)\./.exec(address)
4593
- return !!m && Number(m[1]) >= 64 && Number(m[1]) <= 127
4594
- }
4595
-
4596
- // The suffix on an `also:` line whose host is a tailnet address, so it reads
4597
- // apart from the LAN one — a reader off the wifi needs to know which to tap.
4598
- function tailnetLabel(url) {
4599
- let host = ''
4600
- try {
4601
- host = new URL(url).hostname
4602
- } catch {}
4603
- return isTailnetAddress(host) ? ' (tailnet)' : ''
4604
- }
4605
-
4606
4587
  /**
4607
4588
  * Bring the review server up, or adopt the one already running.
4608
4589
  *
package/src/env/review.js CHANGED
@@ -715,7 +715,21 @@ function reviewTierStack({ served, fileUrl, publishedUrl, config }) {
715
715
  if (!config.review.allowNetwork) {
716
716
  tiers.push({ tier: 'network', off: true, enable: 'skitterspec spec-env review allow network' })
717
717
  } else if (served && !served.loopback && served.url) {
718
- tiers.push({ tier: 'network', url: served.url, alternates: served.alternates || [] })
718
+ // LABELLED HERE, not by the renderer: `--json`'s `tiers` is the stack a
719
+ // skill copies, and an unlabelled alternate made the `(tailnet)` suffix a
720
+ // fact only the text render knew — so the one link a reader off the wifi
721
+ // could open reached the JSON indistinguishable from a second LAN address.
722
+ tiers.push({
723
+ tier: 'network',
724
+ url: served.url,
725
+ alternates: (served.alternates || []).map((u) => {
726
+ let host = ''
727
+ try {
728
+ host = new URL(u).hostname
729
+ } catch {}
730
+ return isTailnetAddress(host) ? { url: u, label: 'tailnet' } : { url: u }
731
+ }),
732
+ })
719
733
  } else {
720
734
  // Permitted, but there is no address to offer — a machine with no network,
721
735
  // or a server that could not take one. Not a problem to report as an error.
@@ -738,13 +752,42 @@ function reviewTierStack({ served, fileUrl, publishedUrl, config }) {
738
752
  }
739
753
 
740
754
  // One tier as a line, padded so the labels form a column the eye can run down.
755
+ // A tier with alternates renders them as indented `also:` lines of its own —
756
+ // they are PART of the tier, which is what puts them under `network:` rather
757
+ // than dangling after the stack (they used to print below `remote:`, against
758
+ // the comment that placed them).
741
759
  function reviewTierLine(t) {
742
760
  const label = ` ${t.tier}:`.padEnd(11)
743
- if (t.url) return `${label}${t.url}${t.note ? ` (${t.note})` : ''}`
761
+ if (t.url) {
762
+ return [
763
+ `${label}${t.url}${t.note ? ` (${t.note})` : ''}`,
764
+ ...(t.alternates || []).map((a) => ` also: ${a.url}${a.label ? ` (${a.label})` : ''}`),
765
+ ].join('\n')
766
+ }
744
767
  if (t.off) return `${label}off — turn on with: ${t.enable}`
745
768
  return `${label}— (${t.note})`
746
769
  }
747
770
 
771
+ // 100.64.0.0/10 — the CGNAT range Tailscale assigns from.
772
+ //
773
+ // WHAT WOULD FOOL THIS: a carrier-grade NAT or another overlay network using
774
+ // the same range on a utun adapter is offered too. That costs one dud `also:`
775
+ // line, where filtering it hides the only link a reader off the wifi can open.
776
+ function isTailnetAddress(address) {
777
+ const m = /^100\.(\d+)\./.exec(address)
778
+ return !!m && Number(m[1]) >= 64 && Number(m[1]) <= 127
779
+ }
780
+
781
+ // The suffix on an `also:` line whose host is a tailnet address, so it reads
782
+ // apart from the LAN one — a reader off the wifi needs to know which to tap.
783
+ function tailnetLabel(url) {
784
+ let host = ''
785
+ try {
786
+ host = new URL(url).hostname
787
+ } catch {}
788
+ return isTailnetAddress(host) ? ' (tailnet)' : ''
789
+ }
790
+
748
791
 
749
792
  // The verdicts that COMMIT, and are therefore blocked by an open comment. One
750
793
  // list, so a fifth verdict cannot become a way around the single refusal this
@@ -2482,6 +2525,8 @@ module.exports = {
2482
2525
  surfacesFor,
2483
2526
  reviewTierStack,
2484
2527
  reviewTierLine,
2528
+ isTailnetAddress,
2529
+ tailnetLabel,
2485
2530
  COMMITTING,
2486
2531
  BUTTON_SETS,
2487
2532
  DEFAULT_BUTTON_SET,
@@ -234,7 +234,26 @@ function makeClient({ apiKey, fetch: fetchImpl, endpoint = ENDPOINT, sleep, maxR
234
234
  { retryable: true },
235
235
  )
236
236
  }
237
- if (!res.ok) throw new Error(`Linear API returned HTTP ${res.status}`)
237
+ if (!res.ok) {
238
+ // A malformed query is answered with HTTP 400 AND a GraphQL `errors`
239
+ // payload naming the field at fault. Dropping that body turned a typo
240
+ // into a bare `HTTP 400` no CI log could diagnose, so read it when it is
241
+ // there. An unreadable or empty body keeps the old line: cannot tell is
242
+ // not evidence.
243
+ let errors = null
244
+ try {
245
+ const failed = await res.json()
246
+ if (failed && Array.isArray(failed.errors) && failed.errors.length) errors = failed.errors
247
+ } catch {
248
+ errors = null
249
+ }
250
+ if (errors) {
251
+ const refusal = refusalFrom(errors)
252
+ refusal.message = `Linear API returned HTTP ${res.status}: ${refusal.message.replace(/^Linear API error: /, '')}`
253
+ throw refusal
254
+ }
255
+ throw new Error(`Linear API returned HTTP ${res.status}`)
256
+ }
238
257
  const body = await res.json()
239
258
  if (body && Array.isArray(body.errors) && body.errors.length) {
240
259
  // NOT RETRIED, when Linear says it cannot succeed. The retry loop exists