@skitterbyte/skitterspec-linear 18.0.0 → 18.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 (51) hide show
  1. package/MIGRATION.md +81 -0
  2. package/assets/core/env.config.md +33 -9
  3. package/assets/hooks/main-guard.cjs +1 -1
  4. package/assets/hooks/review-gate.cjs +1 -1
  5. package/assets/rules/spec-planning.md +4 -2
  6. package/assets/skills/no-spec/SKILL.md +3 -2
  7. package/assets/skills/spec-complete/SKILL.md +67 -25
  8. package/assets/skills/spec-hotfix/SKILL.md +21 -11
  9. package/assets/skills/spec-sync/SKILL.md +10 -1
  10. package/package.json +1 -1
  11. package/src/cli.js +295 -37
  12. package/src/env/config.js +14 -2
  13. package/src/env/hotfix.js +261 -15
  14. package/src/env/hotfixland.js +302 -0
  15. package/src/env/resolve.js +22 -8
  16. package/src/init.js +36 -4
  17. package/src/vendor/linear/api.js +43 -56
  18. package/src/vendor/linear/cli-sanitise.js +2 -2
  19. package/src/vendor/linear/cli-sync.js +87 -390
  20. package/src/vendor/linear/config.js +46 -171
  21. package/src/vendor/linear/credentials.js +40 -370
  22. package/src/vendor/linear/dialect.js +177 -0
  23. package/src/vendor/linear/doctor.js +7 -15
  24. package/src/vendor/linear/identity.js +20 -70
  25. package/src/vendor/linear/released.js +4 -222
  26. package/src/vendor/{sync-core/src → linear}/sanitise.js +4 -3
  27. package/src/vendor/provider-kit/index.js +41 -0
  28. package/src/vendor/provider-kit/src/adapter.js +23 -0
  29. package/src/vendor/provider-kit/src/apply.js +197 -0
  30. package/src/vendor/provider-kit/src/args.js +68 -0
  31. package/src/vendor/provider-kit/src/config.js +198 -0
  32. package/src/vendor/provider-kit/src/credentials.js +404 -0
  33. package/src/vendor/provider-kit/src/doctor.js +35 -0
  34. package/src/vendor/provider-kit/src/http.js +44 -0
  35. package/src/vendor/provider-kit/src/identity.js +93 -0
  36. package/src/vendor/provider-kit/src/md-compare.js +39 -0
  37. package/src/vendor/{sync-core/src/tables.js → provider-kit/src/md-tables.js} +10 -18
  38. package/src/vendor/provider-kit/src/prompt.js +50 -0
  39. package/src/vendor/provider-kit/src/released.js +226 -0
  40. package/src/vendor/provider-kit/src/specs.js +166 -0
  41. package/src/vendor/provider-kit/src/transport.js +22 -0
  42. package/src/vendor/sync-core/index.js +22 -5
  43. package/src/vendor/sync-core/src/compare.js +14 -12
  44. package/src/vendor/sync-core/src/dialect.js +51 -0
  45. package/src/vendor/sync-core/src/fields.js +36 -0
  46. package/src/vendor/sync-core/src/legacy.js +19 -9
  47. package/src/vendor/sync-core/src/normalize.js +30 -158
  48. package/src/vendor/sync-core/src/push.js +1 -1
  49. package/src/vendor/sync-core/src/retarget.js +21 -17
  50. package/src/vendor/sync-core/src/verify.js +24 -45
  51. package/src/vendor/sync-core/src/write.js +7 -5
@@ -170,9 +170,12 @@ function parsePhase(text, name) {
170
170
  * The tracker ticket a spec is linked to, as `{ id, url }`, or null.
171
171
  *
172
172
  * Read straight out of the overview's frontmatter, where every provider stamps
173
- * it. The base is tracker-free, so this knows nothing about Linear beyond the
174
- * two key names a provider writes — an unlinked spec, or a project with no
175
- * provider installed, simply has neither and gets `null`.
173
+ * it. The base is tracker-free, so it hardcodes no provider's key names:
174
+ * every provider stamps `<prefix>_identifier` (`linear_identifier`,
175
+ * `jira_identifier`, …) with `<prefix>_url` beside it, so the id is whichever
176
+ * key matches that shape. A caller that knows the exact field (from
177
+ * `branch.identifierField`) may pass it; an unlinked spec, or a project with no
178
+ * provider installed, has no matching key and gets `null`.
176
179
  *
177
180
  * ONLY http(s) URLS SURVIVE. The value comes out of a file someone edits, and
178
181
  * the page turns it into an `href`; `javascript:` in that position is script
@@ -180,7 +183,7 @@ function parsePhase(text, name) {
180
183
  * still worth having, so the id is kept and the link dropped rather than the
181
184
  * whole ticket.
182
185
  */
183
- function readTicket(text) {
186
+ function readTicket(text, identifierField) {
184
187
  const fm = /^---\n([\s\S]*?)\n---/.exec(text)
185
188
  if (!fm) return null
186
189
  const field = (name) => {
@@ -189,9 +192,20 @@ function readTicket(text) {
189
192
  const v = m[1].trim().replace(/^["']|["']$/g, '').trim()
190
193
  return v || null
191
194
  }
192
- const id = field('linear_identifier')
195
+ let idField = identifierField || null
196
+ if (!idField) {
197
+ // First stamped `<prefix>_identifier` key wins. Two providers stamping one
198
+ // spec does not happen — the distributions are install-one-of.
199
+ const m = /^([A-Za-z][A-Za-z0-9]*)_identifier:/m.exec(fm[1])
200
+ idField = m ? `${m[1]}_identifier` : null
201
+ }
202
+ if (!idField) return null
203
+ const id = field(idField)
193
204
  if (!id) return null
194
- const url = field('linear_url')
205
+ const urlField = idField.endsWith('_identifier')
206
+ ? idField.replace(/_identifier$/, '_url')
207
+ : `${idField}_url`
208
+ const url = field(urlField)
195
209
  return { id, url: url && /^https?:\/\//i.test(url) ? url : null }
196
210
  }
197
211
 
@@ -204,7 +218,7 @@ function readTicket(text) {
204
218
  * routes to omitting the header — the page rendered without one yesterday and
205
219
  * still does (`.claude/rules/negative-checks.md` rule 4).
206
220
  */
207
- function readOverview(specDir, { overviewFile = '00-overview.md' } = {}) {
221
+ function readOverview(specDir, { overviewFile = '00-overview.md', identifierField = null } = {}) {
208
222
  let text
209
223
  try {
210
224
  text = fs.readFileSync(path.join(specDir, overviewFile), 'utf8')
@@ -213,7 +227,7 @@ function readOverview(specDir, { overviewFile = '00-overview.md' } = {}) {
213
227
  }
214
228
  const problem = sectionOf(text, 'Problem') || sectionOf(text, 'Symptom')
215
229
  const impact = impactRows(sectionOf(text, 'Impact'))
216
- const ticket = readTicket(text)
230
+ const ticket = readTicket(text, identifierField)
217
231
  // The ticket counts towards "is there anything to say": a spec linked to a
218
232
  // tracker but carrying neither section still has a header worth drawing.
219
233
  if (!problem && !impact && !ticket) return null
package/src/init.js CHANGED
@@ -125,7 +125,7 @@ function detectPackageManager(dir) {
125
125
 
126
126
  // The bin names a distribution may expose. A provider superset ships its own
127
127
  // name alongside `skitterspec`, and either proves the engine is reachable.
128
- const ENGINE_BINS = ['skitterspec', 'skitterspec-linear']
128
+ const ENGINE_BINS = ['skitterspec', 'skitterspec-linear', 'skitterspec-jira']
129
129
 
130
130
  function binNames() {
131
131
  return process.platform === 'win32'
@@ -272,7 +272,7 @@ function assertComposedAssets() {
272
272
  const SPEC_MARKER_START = '<!-- skitterspec:start -->'
273
273
  const SPEC_MARKER_END = '<!-- skitterspec:end -->'
274
274
 
275
- const report = { created: [], updated: [], skipped: [], refused: [], removed: [], customized: [], adopted: [], healed: [], warnings: [] }
275
+ const report = { created: [], updated: [], skipped: [], refused: [], removed: [], customized: [], adopted: [], healed: [], warnings: [], suggestions: [] }
276
276
 
277
277
  function resetReport() {
278
278
  for (const k of Object.keys(report)) report[k].length = 0
@@ -905,6 +905,7 @@ function resync(dir, { force = false, claudeMd = true, diff = false } = {}) {
905
905
  // asserts over the entry points rather than over this call.
906
906
  registerReviewGateHook(dir)
907
907
  if (claudeMd) installClaudeMd(dir, { mode: 'update' })
908
+ suggestReleaseWith(dir)
908
909
  flushManifest(dir)
909
910
  printReport(dir, 'resync', { diff })
910
911
  }
@@ -913,8 +914,8 @@ function resync(dir, { force = false, claudeMd = true, diff = false } = {}) {
913
914
  // never delete spec content or active config (defense-in-depth — the manifest
914
915
  // never lists these, but a tampered/foreign entry must still be refused).
915
916
  const PROTECTED_SPEC_BUCKETS = ['backlog', 'in-progress', 'complete', 'cancelled']
916
- const PROTECTED_CONFIG = ['env.config.json', 'linear.config.json']
917
- const PROTECTED_DIRS = ['linear-base', 'linear-backups']
917
+ const PROTECTED_CONFIG = ['env.config.json', 'linear.config.json', 'jira.config.json']
918
+ const PROTECTED_DIRS = ['linear-base', 'linear-backups', 'jira-base', 'jira-backups']
918
919
 
919
920
  function assertSafeToDelete(relPath, managedSet) {
920
921
  const norm = relPath.split(path.sep).join('/')
@@ -1003,6 +1004,10 @@ function printReport(dir, mode, { diff = false } = {}) {
1003
1004
  ' (rm <path>, then re-run), or leave it linked and edit the asset.\n',
1004
1005
  )
1005
1006
  }
1007
+ if (report.suggestions.length) {
1008
+ process.stdout.write('\nsuggestions:\n')
1009
+ for (const x of report.suggestions) process.stdout.write(` - ${x}\n`)
1010
+ }
1006
1011
  if (report.warnings.length) {
1007
1012
  process.stdout.write('\nwarnings:\n')
1008
1013
  for (const w of report.warnings) process.stdout.write(` ! ${w}\n`)
@@ -1066,6 +1071,32 @@ function printReport(dir, mode, { diff = false } = {}) {
1066
1071
  // `mode` here is the INSTALL mode ('init' | 'update'), long-standing and
1067
1072
  // unrelated to the config's own `mode` key — which arrives as `workspaceMode`
1068
1073
  // precisely so the two cannot be confused at a call site.
1074
+ /**
1075
+ * Suggest `hotfix.releaseWith` where skittership's hotfix release is installed
1076
+ * and nothing is configured yet. SUGGESTED, NEVER WRITTEN: it changes what a
1077
+ * hotfix land does — a version commit and the project's own tag scheme — and
1078
+ * that is the project's decision, not something an install makes for it.
1079
+ *
1080
+ * Silent unless both signals are present: the script on disk, and an
1081
+ * isolation config that leaves `releaseWith` empty. A config that cannot be
1082
+ * read is cannot-tell, and says nothing.
1083
+ */
1084
+ function suggestReleaseWith(dir) {
1085
+ if (!fs.existsSync(path.join(dir, 'scripts', 'release-hotfix.cjs'))) return
1086
+ let loaded
1087
+ try {
1088
+ loaded = require('./env/config.js').loadEnvConfig(dir)
1089
+ } catch {
1090
+ return
1091
+ }
1092
+ if (!loaded || !loaded.present || loaded.config.hotfix.releaseWith) return
1093
+ report.suggestions.push(
1094
+ 'scripts/release-hotfix.cjs is installed — to have hotfix land cut its release, set ' +
1095
+ '"hotfix": { "releaseWith": "node scripts/release-hotfix.cjs --json" } in ' +
1096
+ 'specs/.core/env.config.json',
1097
+ )
1098
+ }
1099
+
1069
1100
  async function init({ dir, force, claudeMd, mode, isolation, workspaceMode, gating }) {
1070
1101
  if (!fs.existsSync(dir)) throw new Error(`target dir does not exist: ${dir}`)
1071
1102
  resetReport()
@@ -1081,6 +1112,7 @@ async function init({ dir, force, claudeMd, mode, isolation, workspaceMode, gati
1081
1112
  if (mode !== 'update') installIsolation(dir, { enabled: isolation, workspaceMode }, { force })
1082
1113
  if (mode !== 'update') installGating(dir, { enabled: gating }, { force })
1083
1114
  if (claudeMd) installClaudeMd(dir, { mode })
1115
+ suggestReleaseWith(dir)
1084
1116
 
1085
1117
  // Record what we wrote (and migrate a pre-manifest repo) so a later resync can
1086
1118
  // tell our files from the user's.
@@ -26,8 +26,7 @@ const ENDPOINT = 'https://api.linear.app/graphql'
26
26
 
27
27
  // Rate-limit handling. Enough retries to ride out a burst without turning a
28
28
  // genuinely stuck run into an unbounded one.
29
- const MAX_RETRIES = 5
30
- const MAX_BACKOFF_MS = 60_000
29
+ const { withRateLimitRetry, MAX_RETRIES } = require('../provider-kit/src/http.js')
31
30
 
32
31
  // Linear's hard per-page ceiling on a connection. `listIssues` pages against
33
32
  // this rather than trusting a caller's `first` to be under it.
@@ -201,64 +200,52 @@ function makeClient({ apiKey, fetch: fetchImpl, endpoint = ENDPOINT, sleep, maxR
201
200
  const wait = sleep || ((ms) => new Promise((r) => setTimeout(r, ms)))
202
201
 
203
202
  return async function call(query, variables) {
204
- for (let attempt = 0; ; attempt++) {
205
- let res
206
- try {
207
- res = await doFetch(endpoint, {
208
- method: 'POST',
209
- headers: {
210
- 'Content-Type': 'application/json',
211
- // Raw, no `Bearer` — see the module comment.
212
- Authorization: apiKey,
213
- },
214
- body: JSON.stringify({ query, variables }),
215
- })
216
- } catch (cause) {
217
- throw new Error(`Linear API unreachable: ${cause && cause.message ? cause.message : cause}`)
218
- }
219
- if (res.status === 401 || res.status === 403) {
220
- throw new Error(
221
- `Linear rejected the API key (HTTP ${res.status}) — check the value of your key environment variable`,
222
- )
223
- }
224
- // Rate limited. A bulk backfill is exactly the workload that hits this, and
225
- // failing the run would strand a half-mirrored bucket — so wait and retry
226
- // rather than surfacing it. Linear says how long to wait; honour that over
227
- // guessing, and fall back to exponential backoff when it doesn't.
228
- if (res.status === 429 && attempt < maxRetries) {
229
- await wait(retryDelay(res, attempt))
230
- continue
231
- }
232
- if (res.status === 429) {
233
- // RETRYABLE, said out loud. This is the failure where waiting is the
234
- // whole answer, and the one a refusal must be distinguishable from.
235
- throw new LinearRefusal(
236
- `Linear rate-limited this request and did not recover after ${maxRetries} retries`,
237
- { retryable: true },
238
- )
239
- }
240
- if (!res.ok) throw new Error(`Linear API returned HTTP ${res.status}`)
241
- const body = await res.json()
242
- if (body && Array.isArray(body.errors) && body.errors.length) {
243
- // NOT RETRIED, when Linear says it cannot succeed. The loop above exists
244
- // for throttling; a usage cap retried three times is three identical
245
- // refusals and a slower failure.
246
- throw refusalFrom(body.errors)
247
- }
248
- return body && body.data
203
+ // The 429 wait-and-retry discipline is the kit's (`provider-kit/src/http.js`);
204
+ // what stays here is Linear's protocol — the raw Authorization header, the
205
+ // 401/403 phrasing, and GraphQL's `errors` payload.
206
+ const { response: res, exhausted } = await withRateLimitRetry(
207
+ async () => {
208
+ try {
209
+ return await doFetch(endpoint, {
210
+ method: 'POST',
211
+ headers: {
212
+ 'Content-Type': 'application/json',
213
+ // Raw, no `Bearer` — see the module comment.
214
+ Authorization: apiKey,
215
+ },
216
+ body: JSON.stringify({ query, variables }),
217
+ })
218
+ } catch (cause) {
219
+ throw new Error(`Linear API unreachable: ${cause && cause.message ? cause.message : cause}`)
220
+ }
221
+ },
222
+ { sleep: wait, maxRetries },
223
+ )
224
+ if (res.status === 401 || res.status === 403) {
225
+ throw new Error(
226
+ `Linear rejected the API key (HTTP ${res.status}) — check the value of your key environment variable`,
227
+ )
228
+ }
229
+ if (exhausted) {
230
+ // RETRYABLE, said out loud. This is the failure where waiting is the
231
+ // whole answer, and the one a refusal must be distinguishable from.
232
+ throw new LinearRefusal(
233
+ `Linear rate-limited this request and did not recover after ${maxRetries} retries`,
234
+ { retryable: true },
235
+ )
249
236
  }
237
+ if (!res.ok) throw new Error(`Linear API returned HTTP ${res.status}`)
238
+ const body = await res.json()
239
+ if (body && Array.isArray(body.errors) && body.errors.length) {
240
+ // NOT RETRIED, when Linear says it cannot succeed. The retry loop exists
241
+ // for throttling; a usage cap retried three times is three identical
242
+ // refusals and a slower failure.
243
+ throw refusalFrom(body.errors)
244
+ }
245
+ return body && body.data
250
246
  }
251
247
  }
252
248
 
253
- // How long to wait before retrying a 429: the server's `Retry-After` (seconds)
254
- // when it sends one, else exponential backoff from 1s.
255
- function retryDelay(res, attempt) {
256
- const header = res.headers && typeof res.headers.get === 'function' ? res.headers.get('retry-after') : null
257
- const seconds = header != null ? Number(header) : NaN
258
- if (Number.isFinite(seconds) && seconds >= 0) return Math.min(seconds * 1000, MAX_BACKOFF_MS)
259
- return Math.min(1000 * 2 ** attempt, MAX_BACKOFF_MS)
260
- }
261
-
262
249
  /**
263
250
  * Wrap a GraphQL client into the typed ops the engine uses — the same set
264
251
  * `mcp.js`'s `makeAdapter` returns, so the two are interchangeable.
@@ -10,7 +10,7 @@
10
10
  *
11
11
  * Dry-run by default (reports the files it WOULD change); pass `--write` to apply.
12
12
  * Minimal-diff and idempotent — only paragraphs/items that actually straddle are
13
- * reflowed (see sync-core `sanitizeSpecMarkdown`).
13
+ * reflowed (see `sanitise.js`).
14
14
  *
15
15
  * skitterspec-linear spec-sanitise [paths...] [--write] [--width N]
16
16
  *
@@ -20,7 +20,7 @@
20
20
 
21
21
  const fs = require('node:fs')
22
22
  const path = require('node:path')
23
- const { sanitizeSpecMarkdown } = require('../sync-core')
23
+ const { sanitizeSpecMarkdown } = require('./sanitise.js')
24
24
 
25
25
  // Recursively collect *.md files under a path (a file path is returned as-is).
26
26
  function collectMarkdown(target) {