@skitterbyte/skitterspec-linear 18.0.1 → 18.1.1
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 +81 -0
- package/assets/core/env.config.md +36 -9
- package/assets/hooks/main-guard.cjs +1 -1
- package/assets/hooks/review-gate.cjs +1 -1
- package/assets/rules/spec-planning.md +4 -2
- package/assets/skills/spec-complete/SKILL.md +67 -25
- package/assets/skills/spec-hotfix/SKILL.md +21 -11
- package/assets/skills/spec-sync/SKILL.md +10 -1
- package/package.json +1 -1
- package/src/cli.js +289 -34
- package/src/env/config.js +14 -2
- package/src/env/hotfix.js +288 -16
- package/src/env/hotfixland.js +302 -0
- package/src/env/resolve.js +22 -8
- package/src/init.js +36 -4
- package/src/vendor/linear/api.js +43 -56
- package/src/vendor/linear/cli-sanitise.js +2 -2
- package/src/vendor/linear/cli-sync.js +87 -390
- package/src/vendor/linear/config.js +46 -171
- package/src/vendor/linear/credentials.js +40 -370
- package/src/vendor/linear/dialect.js +177 -0
- package/src/vendor/linear/doctor.js +7 -15
- package/src/vendor/linear/identity.js +20 -70
- package/src/vendor/linear/released.js +4 -222
- package/src/vendor/{sync-core/src → linear}/sanitise.js +4 -3
- package/src/vendor/provider-kit/index.js +41 -0
- package/src/vendor/provider-kit/src/adapter.js +23 -0
- package/src/vendor/provider-kit/src/apply.js +197 -0
- package/src/vendor/provider-kit/src/args.js +68 -0
- package/src/vendor/provider-kit/src/config.js +198 -0
- package/src/vendor/provider-kit/src/credentials.js +404 -0
- package/src/vendor/provider-kit/src/doctor.js +35 -0
- package/src/vendor/provider-kit/src/http.js +44 -0
- package/src/vendor/provider-kit/src/identity.js +93 -0
- package/src/vendor/provider-kit/src/md-compare.js +39 -0
- package/src/vendor/{sync-core/src/tables.js → provider-kit/src/md-tables.js} +10 -18
- package/src/vendor/provider-kit/src/prompt.js +50 -0
- package/src/vendor/provider-kit/src/released.js +226 -0
- package/src/vendor/provider-kit/src/specs.js +166 -0
- package/src/vendor/provider-kit/src/transport.js +22 -0
- package/src/vendor/sync-core/index.js +22 -5
- package/src/vendor/sync-core/src/compare.js +14 -12
- package/src/vendor/sync-core/src/dialect.js +51 -0
- package/src/vendor/sync-core/src/fields.js +36 -0
- package/src/vendor/sync-core/src/legacy.js +19 -9
- package/src/vendor/sync-core/src/normalize.js +30 -158
- package/src/vendor/sync-core/src/push.js +1 -1
- package/src/vendor/sync-core/src/retarget.js +21 -17
- package/src/vendor/sync-core/src/verify.js +24 -45
- package/src/vendor/sync-core/src/write.js +7 -5
package/src/env/resolve.js
CHANGED
|
@@ -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
|
|
174
|
-
*
|
|
175
|
-
*
|
|
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
|
-
|
|
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
|
|
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.
|
package/src/vendor/linear/api.js
CHANGED
|
@@ -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 =
|
|
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
|
-
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
|
|
223
|
-
}
|
|
224
|
-
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
|
|
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
|
|
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('
|
|
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) {
|