@skitterbyte/skitterspec-linear 18.3.1 → 19.1.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.
Files changed (36) hide show
  1. package/MIGRATION.md +170 -1
  2. package/README.md +9 -7
  3. package/assets/core/SETUP.md +4 -4
  4. package/assets/core/env.config.md +1 -1
  5. package/assets/core/linear.config.json.example +2 -1
  6. package/assets/core/linear.config.md +59 -48
  7. package/assets/rules/spec-planning.md +35 -12
  8. package/assets/rules/spec-reports.md +47 -6
  9. package/assets/skills/no-spec/SKILL.md +2 -2
  10. package/assets/skills/spec/SKILL.md +32 -9
  11. package/assets/skills/spec-bug/SKILL.md +6 -4
  12. package/assets/skills/spec-hotfix/SKILL.md +4 -2
  13. package/assets/skills/spec-linear-setup/SKILL.md +9 -35
  14. package/assets/skills/spec-list/SKILL.md +13 -1
  15. package/assets/skills/spec-next/SKILL.md +5 -3
  16. package/assets/skills/spec-push/SKILL.md +1 -1
  17. package/assets/skills/spec-status/SKILL.md +30 -26
  18. package/assets/skills/spec-sync/SKILL.md +6 -5
  19. package/package.json +1 -1
  20. package/src/cli.js +114 -28
  21. package/src/env/resolve.js +11 -4
  22. package/src/env/review.js +126 -2
  23. package/src/vendor/linear/api.js +30 -1
  24. package/src/vendor/linear/cli-sync.js +64 -269
  25. package/src/vendor/linear/config.js +30 -49
  26. package/src/vendor/linear/doctor.js +4 -66
  27. package/src/vendor/provider-kit/src/config.js +101 -48
  28. package/src/vendor/provider-kit/src/list-assignee.js +71 -0
  29. package/src/vendor/provider-kit/src/list-rows.js +35 -0
  30. package/src/vendor/provider-kit/src/released.js +27 -77
  31. package/src/vendor/provider-kit/src/specs.js +89 -7
  32. package/src/vendor/sync-core/index.js +3 -4
  33. package/src/vendor/sync-core/src/compare.js +6 -6
  34. package/src/vendor/sync-core/src/normalize.js +60 -59
  35. package/assets/core/ci-stages.md +0 -110
  36. package/src/vendor/provider-kit/src/releases.js +0 -380
@@ -4,7 +4,8 @@
4
4
  * Pure spec/branch resolution for per-spec isolation.
5
5
  *
6
6
  * Given a spec argument (a folder name or path) it locates the spec folder under
7
- * `specs/**`, splits the `feat-`/`bug-` prefix into `{ type, slug }`, derives the
7
+ * `specs/**`, splits the `feat-`/`bug-`/`hotfix-`/`chore-` prefix into
8
+ * `{ type, slug }`, derives the
8
9
  * git branch from the config's `branch.pattern` (provider-neutral; `{identifier}`
9
10
  * is filled from a tracker id when one is configured, else it falls back to
10
11
  * `{type}/{slug}`), and expands the config's path/name tokens (`{repo}`,
@@ -294,10 +295,10 @@ function phaseIsDone(text) {
294
295
  return /^#\s.*✅\s*$/m.test(text)
295
296
  }
296
297
 
297
- // Split a `feat-`/`bug-`/`hotfix-` prefix. Unknown prefix → type defaults to
298
- // `feat` and the whole folder name is the slug.
298
+ // Split a `feat-`/`bug-`/`hotfix-`/`chore-` prefix. Unknown prefix → type
299
+ // defaults to `feat` and the whole folder name is the slug.
299
300
  function splitPrefix(folder) {
300
- const m = /^(feat|bug|hotfix)-(.+)$/.exec(folder)
301
+ const m = /^(feat|bug|hotfix|chore)-(.+)$/.exec(folder)
301
302
  if (m) return { type: m[1], slug: m[2] }
302
303
  return { type: 'feat', slug: folder }
303
304
  }
@@ -498,6 +499,12 @@ function assertPrimaryOnMain(config, git) {
498
499
  * was actually created against, and re-deriving it would go wrong the moment a
499
500
  * project changed its pattern under a standing branch.
500
501
  *
502
+ * A `chore-foo` SPEC derives the same `chore/foo` branch as `/no-spec foo`
503
+ * does, deliberately left colliding: both cannot exist at once, and git
504
+ * refuses the second `worktree add -b` loudly rather than either lane
505
+ * silently adopting the other's branch (spec feat-chore-kind-bug-bodies,
506
+ * decision 9).
507
+ *
501
508
  * Pure but for `repoInfo`, like `resolveSpec`.
502
509
  */
503
510
  function resolveSpecless(name, dir, config, entry = {}) {
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
@@ -1239,6 +1282,81 @@ const WAIT_POLL_MS = 400
1239
1282
  // whatever is supervising the process.
1240
1283
  const WAIT_HEARTBEAT_MS = 5 * 60 * 1000
1241
1284
 
1285
+ // Every this-many re-arms on one window, the wait prints the stack again. A
1286
+ // COUNT, not an interval, and deliberately: what buries the banner is how many
1287
+ // re-arms have scrolled past it, and a death every five minutes and one every
1288
+ // forty-five push it up the same distance each. This is not the count
1289
+ // `spec-reports.md` rejects — that one bounded how long to keep waiting, and
1290
+ // the 12-hour age bound below still does.
1291
+ const WAIT_RESHOW_EVERY = 5
1292
+
1293
+ // How old a window may be before its start count is pruned. The same 12 hours
1294
+ // the skills stop re-arming at: past it nobody is counting, so nothing is kept.
1295
+ const WAIT_WINDOW_MAX_MS = 12 * 60 * 60 * 1000
1296
+
1297
+ // Beside the pending store, under gitignored `.spec-env/`.
1298
+ const WAITS_SUFFIX = '.waits.json'
1299
+
1300
+ function reviewWaitsPath(outPath) {
1301
+ return outPath.replace(/\.html$/, '') + WAITS_SUFFIX
1302
+ }
1303
+
1304
+ /**
1305
+ * Record that a wait started on `since`, and say which start this is.
1306
+ * Returns `{ starts, rearm }` — `rearm` is 0 for the first wait on a window —
1307
+ * or `null` when it cannot tell.
1308
+ *
1309
+ * CANNOT-TELL IS NULL, and null means no re-show (`.claude/rules/negative-checks.md`
1310
+ * rule 4). A store that will not parse, a window that is not a timestamp, a
1311
+ * write that failed: each costs the reader one reminder, never a verdict, so
1312
+ * none of them is worth more than silence. An unreadable store is also never
1313
+ * written over — it may be someone's history.
1314
+ *
1315
+ * WHAT WOULD FOOL THIS: it counts STARTS, so anything that runs `review wait`
1316
+ * on the same window counts too — a second session waiting on one spec, or a
1317
+ * person running it by hand. That over-counts, and the cost is a banner shown
1318
+ * a little early, which is the harmless direction.
1319
+ */
1320
+ function recordWaitStart(outPath, specFolder, since, { now = Date.now() } = {}) {
1321
+ if (!Number.isFinite(Date.parse(since))) return null
1322
+ const file = reviewWaitsPath(outPath)
1323
+ let store = { version: 1, spec: specFolder, windows: {} }
1324
+ let raw = null
1325
+ try {
1326
+ raw = fs.readFileSync(file, 'utf8')
1327
+ } catch {}
1328
+ if (raw !== null) {
1329
+ try {
1330
+ const parsed = JSON.parse(raw)
1331
+ if (!parsed || typeof parsed.windows !== 'object' || parsed.windows === null) return null
1332
+ store = { version: parsed.version || 1, spec: parsed.spec || specFolder, windows: parsed.windows }
1333
+ } catch {
1334
+ return null
1335
+ }
1336
+ }
1337
+ const windows = {}
1338
+ for (const [key, count] of Object.entries(store.windows)) {
1339
+ const at = Date.parse(key)
1340
+ if (Number.isFinite(at) && now - at <= WAIT_WINDOW_MAX_MS) windows[key] = count
1341
+ }
1342
+ const prior = Number.isInteger(windows[since]) && windows[since] > 0 ? windows[since] : 0
1343
+ const starts = prior + 1
1344
+ windows[since] = starts
1345
+ try {
1346
+ fs.mkdirSync(path.dirname(file), { recursive: true })
1347
+ fs.writeFileSync(file, JSON.stringify({ ...store, windows }, null, 2) + '\n')
1348
+ } catch {
1349
+ return null
1350
+ }
1351
+ return { starts, rearm: starts - 1 }
1352
+ }
1353
+
1354
+ // Is this re-arm one that re-shows the stack? Pure. The first wait never does —
1355
+ // the banner is right above it — and `every` of 0 turns it off.
1356
+ function reshowDue(rearm, every = WAIT_RESHOW_EVERY) {
1357
+ return Number.isInteger(every) && every > 0 && Number.isInteger(rearm) && rearm > 0 && rearm % every === 0
1358
+ }
1359
+
1242
1360
  /**
1243
1361
  * Block until exactly one pass arrives inside a window. Impure only in that it
1244
1362
  * reads the store and sleeps; it writes nothing and claims nothing.
@@ -2482,6 +2600,8 @@ module.exports = {
2482
2600
  surfacesFor,
2483
2601
  reviewTierStack,
2484
2602
  reviewTierLine,
2603
+ isTailnetAddress,
2604
+ tailnetLabel,
2485
2605
  COMMITTING,
2486
2606
  BUTTON_SETS,
2487
2607
  DEFAULT_BUTTON_SET,
@@ -2510,6 +2630,10 @@ module.exports = {
2510
2630
  waitingPasses,
2511
2631
  waitForPass,
2512
2632
  WAIT_HEARTBEAT_MS,
2633
+ WAIT_RESHOW_EVERY,
2634
+ recordWaitStart,
2635
+ reshowDue,
2636
+ reviewWaitsPath,
2513
2637
  WAIT_POLL_MS,
2514
2638
  passState,
2515
2639
  describePending,
@@ -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
@@ -311,6 +330,16 @@ function makeApiAdapter({ apiKey, fetch: fetchImpl, endpoint, sleep, maxRetries
311
330
  )
312
331
  return (data && data.issues && data.issues.nodes) || []
313
332
  },
333
+ // A team's issue labels, for resolving a configured label NAME
334
+ // (linear.labelsByKind) to the id a create wants. Team-scoped labels and
335
+ // the workspace ones the team inherits both answer here.
336
+ async listLabels(teamId) {
337
+ const data = await call(
338
+ `query($id: String!) { team(id: $id) { labels { nodes { id name } } } }`,
339
+ { id: teamId },
340
+ )
341
+ return (data && data.team && data.team.labels && data.team.labels.nodes) || []
342
+ },
314
343
  async listProjects(teamId) {
315
344
  const data = teamId
316
345
  ? await call(`query($id: String!) { team(id: $id) { projects { nodes { id name } } } }`, { id: teamId })