@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.
- package/MIGRATION.md +141 -1
- package/README.md +9 -7
- package/assets/core/SETUP.md +4 -4
- package/assets/core/linear.config.md +53 -47
- package/assets/rules/spec-planning.md +13 -3
- package/assets/rules/spec-reports.md +19 -4
- package/assets/skills/spec/SKILL.md +1 -1
- package/assets/skills/spec-bug/SKILL.md +4 -2
- package/assets/skills/spec-hotfix/SKILL.md +4 -2
- package/assets/skills/spec-linear-setup/SKILL.md +9 -35
- package/assets/skills/spec-list/SKILL.md +13 -1
- package/assets/skills/spec-next/SKILL.md +3 -1
- package/assets/skills/spec-push/SKILL.md +1 -1
- package/assets/skills/spec-status/SKILL.md +30 -26
- package/assets/skills/spec-sync/SKILL.md +6 -5
- package/package.json +1 -1
- package/src/cli.js +6 -25
- package/src/env/review.js +47 -2
- package/src/vendor/linear/api.js +20 -1
- package/src/vendor/linear/cli-sync.js +36 -267
- package/src/vendor/linear/config.js +8 -47
- package/src/vendor/linear/doctor.js +4 -66
- package/src/vendor/provider-kit/src/config.js +101 -48
- package/src/vendor/provider-kit/src/list-assignee.js +71 -0
- package/src/vendor/provider-kit/src/list-rows.js +35 -0
- package/src/vendor/provider-kit/src/released.js +27 -77
- package/src/vendor/provider-kit/src/specs.js +89 -7
- package/src/vendor/sync-core/index.js +3 -4
- package/src/vendor/sync-core/src/compare.js +6 -6
- package/src/vendor/sync-core/src/normalize.js +30 -57
- package/assets/core/ci-stages.md +0 -110
- package/src/vendor/provider-kit/src/releases.js +0 -380
|
@@ -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
|
|
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
|
|
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. **
|
|
19
|
-
|
|
20
|
-
|
|
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
|
|
24
|
-
|
|
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
|
|
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
|
|
37
|
-
skip the
|
|
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`.**
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
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
|
|
62
|
-
|
|
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
|
-
- `⚠️` —
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
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
|
|
106
|
-
|
|
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
|
|
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.
|
|
173
|
-
|
|
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": "
|
|
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
|
-
|
|
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)
|
|
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,
|
package/src/vendor/linear/api.js
CHANGED
|
@@ -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)
|
|
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
|