@skitterbyte/skitterspec-linear 19.0.0 → 19.2.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 +71 -0
- package/README.md +1 -0
- package/assets/core/env.config.md +1 -1
- package/assets/core/linear.config.json.example +2 -1
- package/assets/core/linear.config.md +16 -1
- package/assets/rules/spec-planning.md +52 -11
- package/assets/rules/spec-reports.md +28 -2
- package/assets/skills/no-spec/SKILL.md +2 -2
- package/assets/skills/spec/SKILL.md +47 -8
- package/assets/skills/spec-bug/SKILL.md +6 -2
- package/assets/skills/spec-complete/SKILL.md +39 -0
- package/assets/skills/spec-hotfix/SKILL.md +4 -0
- package/assets/skills/spec-incident/SKILL.md +142 -0
- package/assets/skills/spec-init/SKILL.md +2 -1
- package/assets/skills/spec-next/SKILL.md +2 -2
- package/package.json +1 -1
- package/src/cli.js +108 -3
- package/src/env/resolve.js +12 -4
- package/src/env/review.js +79 -0
- package/src/vendor/linear/api.js +37 -2
- package/src/vendor/linear/cli-sync.js +119 -3
- package/src/vendor/linear/config.js +35 -3
- package/src/vendor/provider-kit/src/config.js +44 -0
- package/src/vendor/sync-core/index.js +4 -1
- package/src/vendor/sync-core/src/normalize.js +137 -16
package/src/cli.js
CHANGED
|
@@ -119,6 +119,9 @@ const {
|
|
|
119
119
|
passesSince,
|
|
120
120
|
waitForPass,
|
|
121
121
|
WAIT_HEARTBEAT_MS,
|
|
122
|
+
WAIT_RESHOW_EVERY,
|
|
123
|
+
recordWaitStart,
|
|
124
|
+
reshowDue,
|
|
122
125
|
waitingPasses,
|
|
123
126
|
describePending,
|
|
124
127
|
pendingAge,
|
|
@@ -903,7 +906,7 @@ function specEnvUp(dir, config, specArg, flags = {}) {
|
|
|
903
906
|
try {
|
|
904
907
|
spec = resolveSpecWithWorktree(dir, config, specArg)
|
|
905
908
|
} catch (err) {
|
|
906
|
-
const specShaped = typeof specArg === 'string' && /^(feat|bug|hotfix)-./.test(specArg)
|
|
909
|
+
const specShaped = typeof specArg === 'string' && /^(feat|bug|hotfix|chore|issue|incident)-./.test(specArg)
|
|
907
910
|
if (err.code !== 'SPEC_NOT_FOUND' || !docs || !specShaped || config.mode === 'checkout') {
|
|
908
911
|
throw err
|
|
909
912
|
}
|
|
@@ -2761,6 +2764,74 @@ function resolveHeartbeatMs(flags) {
|
|
|
2761
2764
|
return seconds * 1000
|
|
2762
2765
|
}
|
|
2763
2766
|
|
|
2767
|
+
/**
|
|
2768
|
+
* Every this-many re-arms the stack is printed again. Default 5, `0` disables.
|
|
2769
|
+
* A value that is not a whole number takes the DEFAULT rather than disabling
|
|
2770
|
+
* (`.claude/rules/negative-checks.md` rule 4), the same as `--heartbeat`.
|
|
2771
|
+
*/
|
|
2772
|
+
function resolveReshowEvery(flags) {
|
|
2773
|
+
if (flags.reshowEvery === undefined || flags.reshowEvery === null) return WAIT_RESHOW_EVERY
|
|
2774
|
+
const n = Number(flags.reshowEvery)
|
|
2775
|
+
if (!Number.isInteger(n) || n < 0) return WAIT_RESHOW_EVERY
|
|
2776
|
+
return n
|
|
2777
|
+
}
|
|
2778
|
+
|
|
2779
|
+
/**
|
|
2780
|
+
* The review server that is running, read and never touched — or null.
|
|
2781
|
+
*
|
|
2782
|
+
* NOT `ensureReviewServer`. That one adopts, and where a server is stale it
|
|
2783
|
+
* replaces it, and a re-show that restarted the server would kill the link
|
|
2784
|
+
* open on the reader's phone in order to remind them of it. This reads the
|
|
2785
|
+
* pidfile and the settings and stops there.
|
|
2786
|
+
*
|
|
2787
|
+
* WHAT WOULD FOOL THIS: a pidfile left by a crash names a pid the OS may have
|
|
2788
|
+
* reused for something else. `isAlive` cannot tell those apart, so the URL it
|
|
2789
|
+
* offers could point at nothing — the same blind spot every adopt has, and the
|
|
2790
|
+
* cost is a dead link in a reminder, never a lost pass.
|
|
2791
|
+
*/
|
|
2792
|
+
function readRunningReviewServer(dir, config) {
|
|
2793
|
+
const abs = (rel) => path.resolve(dir, rel)
|
|
2794
|
+
const settingsFile = `${stateDirLabel(config)}/review-serve.json`
|
|
2795
|
+
const proc = serveProcFor(config, abs(settingsFile), { root: dir })
|
|
2796
|
+
const pid = readPid(abs(proc.pidFile))
|
|
2797
|
+
if (!pid || !isAlive(pid)) return null
|
|
2798
|
+
let settings = null
|
|
2799
|
+
try {
|
|
2800
|
+
settings = JSON.parse(fs.readFileSync(abs(settingsFile), 'utf-8'))
|
|
2801
|
+
} catch {
|
|
2802
|
+
return null
|
|
2803
|
+
}
|
|
2804
|
+
if (!settings || !settings.port) return null
|
|
2805
|
+
return {
|
|
2806
|
+
port: settings.port,
|
|
2807
|
+
token: settings.token || null,
|
|
2808
|
+
loopback: settings.host === '127.0.0.1' || settings.host === 'localhost',
|
|
2809
|
+
}
|
|
2810
|
+
}
|
|
2811
|
+
|
|
2812
|
+
/**
|
|
2813
|
+
* The stack a re-show prints: the same tiers and `live` a render reports, from
|
|
2814
|
+
* the same functions, with nothing rendered and nothing started.
|
|
2815
|
+
*/
|
|
2816
|
+
function reshowStack(dir, config, spec, out) {
|
|
2817
|
+
const cfg = withSpecRemote(config, out)
|
|
2818
|
+
const up = readRunningReviewServer(dir, cfg)
|
|
2819
|
+
const served = up ? reviewServedUrls(up, offerableLanAddresses(), spec.folder) : null
|
|
2820
|
+
const tiers = reviewTierStack({ served, fileUrl: reviewFileUrl(out), publishedUrl: readReviewUrl(out), config: cfg })
|
|
2821
|
+
let live = null
|
|
2822
|
+
try {
|
|
2823
|
+
const primaryState = assertPrimaryOnMain(cfg, gitReader(dir))
|
|
2824
|
+
live = liveStateFor(
|
|
2825
|
+
spec,
|
|
2826
|
+
liveContext(dir, cfg, spec, { onBase: primaryState.onBase, primaryBranch: primaryState.branch }),
|
|
2827
|
+
)
|
|
2828
|
+
} catch {
|
|
2829
|
+
// Cannot tell whether it is live — print no line rather than a wrong one.
|
|
2830
|
+
live = null
|
|
2831
|
+
}
|
|
2832
|
+
return { tiers, live }
|
|
2833
|
+
}
|
|
2834
|
+
|
|
2764
2835
|
async function specEnvReviewWait(dir, config, specArg, flags) {
|
|
2765
2836
|
let spec
|
|
2766
2837
|
try {
|
|
@@ -2794,10 +2865,28 @@ async function specEnvReviewWait(dir, config, specArg, flags) {
|
|
|
2794
2865
|
// SAID BEFORE THE FIRST POLL, not after it. The whole point is that a caller
|
|
2795
2866
|
// knows the wait is running; a line printed on the way out would arrive only
|
|
2796
2867
|
// for the waits that already worked.
|
|
2868
|
+
//
|
|
2869
|
+
// WHICH START THIS IS, counted per window. A wait that dies is re-armed on the
|
|
2870
|
+
// same `--since`, and every re-arm leaves a trace in the conversation, so
|
|
2871
|
+
// after enough of them the banner and its links have scrolled out of sight.
|
|
2872
|
+
// Every `reshowEvery`th re-arm prints the stack again, read-only, for the
|
|
2873
|
+
// skill to relay as the banner.
|
|
2874
|
+
const reshowEvery = resolveReshowEvery(flags)
|
|
2875
|
+
const started = recordWaitStart(out, spec.folder, flags.since)
|
|
2876
|
+
const rearm = started ? started.rearm : null
|
|
2877
|
+
const reshow = reshowDue(rearm, reshowEvery)
|
|
2878
|
+
const stack = reshow ? reshowStack(dir, config, spec, out) : null
|
|
2879
|
+
|
|
2797
2880
|
if (!flags.json) {
|
|
2798
2881
|
process.stdout.write(
|
|
2799
2882
|
`spec-env review wait: ${spec.folder} — waiting for a verdict sent since ${flags.since}` +
|
|
2800
|
-
`${timeoutMs === null ? '' : ` (up to ${flags.timeout}s)`}
|
|
2883
|
+
`${timeoutMs === null ? '' : ` (up to ${flags.timeout}s)`}` +
|
|
2884
|
+
`${rearm ? ` (re-arm ${rearm})` : ''}\n` +
|
|
2885
|
+
(stack
|
|
2886
|
+
? ` re-show: banner (re-arm ${rearm})\n` +
|
|
2887
|
+
stack.tiers.map((t) => reviewTierLine(t) + '\n').join('') +
|
|
2888
|
+
(liveStateLine(stack.live) ? `${liveStateLine(stack.live)}\n` : '')
|
|
2889
|
+
: ''),
|
|
2801
2890
|
)
|
|
2802
2891
|
}
|
|
2803
2892
|
|
|
@@ -2827,7 +2916,20 @@ async function specEnvReviewWait(dir, config, specArg, flags) {
|
|
|
2827
2916
|
})
|
|
2828
2917
|
|
|
2829
2918
|
if (flags.json) {
|
|
2830
|
-
process.stdout.write(
|
|
2919
|
+
process.stdout.write(
|
|
2920
|
+
`${JSON.stringify(
|
|
2921
|
+
{
|
|
2922
|
+
spec: spec.folder,
|
|
2923
|
+
since: flags.since,
|
|
2924
|
+
rearm,
|
|
2925
|
+
reshow,
|
|
2926
|
+
...(stack ? { tiers: stack.tiers, live: stack.live } : {}),
|
|
2927
|
+
...result,
|
|
2928
|
+
},
|
|
2929
|
+
null,
|
|
2930
|
+
2,
|
|
2931
|
+
)}\n`,
|
|
2932
|
+
)
|
|
2831
2933
|
}
|
|
2832
2934
|
|
|
2833
2935
|
if (result.state === 'arrived') {
|
|
@@ -5617,6 +5719,7 @@ async function specEnv(rest) {
|
|
|
5617
5719
|
claim: null,
|
|
5618
5720
|
offered: false,
|
|
5619
5721
|
heartbeat: null,
|
|
5722
|
+
reshowEvery: null,
|
|
5620
5723
|
drop: null,
|
|
5621
5724
|
buttons: null,
|
|
5622
5725
|
json: false,
|
|
@@ -5652,6 +5755,7 @@ async function specEnv(rest) {
|
|
|
5652
5755
|
else if (args[i] === '--claim') flags.claim = args[++i]
|
|
5653
5756
|
else if (args[i] === '--claim-since') flags.claimSince = args[++i]
|
|
5654
5757
|
else if (args[i] === '--heartbeat') flags.heartbeat = args[++i]
|
|
5758
|
+
else if (args[i] === '--reshow-every') flags.reshowEvery = args[++i]
|
|
5655
5759
|
else if (args[i] === '--since') flags.since = args[++i]
|
|
5656
5760
|
else if (args[i] === '--timeout') flags.timeout = args[++i]
|
|
5657
5761
|
else if (args[i] === '--drop') flags.drop = args[++i]
|
|
@@ -5831,6 +5935,7 @@ async function specEnv(rest) {
|
|
|
5831
5935
|
' review skip [spec] "<reason>" move on without one, on the record\n' +
|
|
5832
5936
|
' review gate [spec] --offered record that the bypass was offered (spends it)\n' +
|
|
5833
5937
|
' review wait [spec] --heartbeat <secs> proof-of-life cadence on stderr; 0 disables\n' +
|
|
5938
|
+
' review wait [spec] --reshow-every <n> print the stack again every nth re-arm (5); 0 disables\n' +
|
|
5834
5939
|
' review wait [spec] --since <iso> block until a verdict arrives ([--timeout <s>])\n' +
|
|
5835
5940
|
' review waiting [--json] every pass waiting, across every spec\n' +
|
|
5836
5941
|
' review [spec] --claim-since <iso> claim the one pass that arrived since <iso>\n' +
|
package/src/env/resolve.js
CHANGED
|
@@ -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
|
|
7
|
+
* `specs/**`, splits the `feat-`/`bug-`/`hotfix-`/`chore-`/`issue-`/`incident-` 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,11 @@ function phaseIsDone(text) {
|
|
|
294
295
|
return /^#\s.*✅\s*$/m.test(text)
|
|
295
296
|
}
|
|
296
297
|
|
|
297
|
-
// Split a `feat-`/`bug-`/`hotfix-` prefix.
|
|
298
|
-
// `feat` and the whole folder name is the
|
|
298
|
+
// Split a `feat-`/`bug-`/`hotfix-`/`chore-`/`issue-`/`incident-` prefix.
|
|
299
|
+
// Unknown prefix → type defaults to `feat` and the whole folder name is the
|
|
300
|
+
// slug.
|
|
299
301
|
function splitPrefix(folder) {
|
|
300
|
-
const m = /^(feat|bug|hotfix)-(.+)$/.exec(folder)
|
|
302
|
+
const m = /^(feat|bug|hotfix|chore|issue|incident)-(.+)$/.exec(folder)
|
|
301
303
|
if (m) return { type: m[1], slug: m[2] }
|
|
302
304
|
return { type: 'feat', slug: folder }
|
|
303
305
|
}
|
|
@@ -498,6 +500,12 @@ function assertPrimaryOnMain(config, git) {
|
|
|
498
500
|
* was actually created against, and re-deriving it would go wrong the moment a
|
|
499
501
|
* project changed its pattern under a standing branch.
|
|
500
502
|
*
|
|
503
|
+
* A `chore-foo` SPEC derives the same `chore/foo` branch as `/no-spec foo`
|
|
504
|
+
* does, deliberately left colliding: both cannot exist at once, and git
|
|
505
|
+
* refuses the second `worktree add -b` loudly rather than either lane
|
|
506
|
+
* silently adopting the other's branch (spec feat-chore-kind-bug-bodies,
|
|
507
|
+
* decision 9).
|
|
508
|
+
*
|
|
501
509
|
* Pure but for `repoInfo`, like `resolveSpec`.
|
|
502
510
|
*/
|
|
503
511
|
function resolveSpecless(name, dir, config, entry = {}) {
|
package/src/env/review.js
CHANGED
|
@@ -1282,6 +1282,81 @@ const WAIT_POLL_MS = 400
|
|
|
1282
1282
|
// whatever is supervising the process.
|
|
1283
1283
|
const WAIT_HEARTBEAT_MS = 5 * 60 * 1000
|
|
1284
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
|
+
|
|
1285
1360
|
/**
|
|
1286
1361
|
* Block until exactly one pass arrives inside a window. Impure only in that it
|
|
1287
1362
|
* reads the store and sleeps; it writes nothing and claims nothing.
|
|
@@ -2555,6 +2630,10 @@ module.exports = {
|
|
|
2555
2630
|
waitingPasses,
|
|
2556
2631
|
waitForPass,
|
|
2557
2632
|
WAIT_HEARTBEAT_MS,
|
|
2633
|
+
WAIT_RESHOW_EVERY,
|
|
2634
|
+
recordWaitStart,
|
|
2635
|
+
reshowDue,
|
|
2636
|
+
reviewWaitsPath,
|
|
2558
2637
|
WAIT_POLL_MS,
|
|
2559
2638
|
passState,
|
|
2560
2639
|
describePending,
|
package/src/vendor/linear/api.js
CHANGED
|
@@ -294,6 +294,26 @@ function makeApiAdapter({ apiKey, fetch: fetchImpl, endpoint, sleep, maxRetries
|
|
|
294
294
|
)
|
|
295
295
|
return unwrap(data, 'issueUpdate')
|
|
296
296
|
},
|
|
297
|
+
/**
|
|
298
|
+
* Add a "related" relation between two issues (by uuid). Idempotent at
|
|
299
|
+
* this level: Linear refuses a relation that already exists, and that
|
|
300
|
+
* refusal comes back as `{ added: false, already: true }` — a re-push per
|
|
301
|
+
* phase is the normal case, not a failure.
|
|
302
|
+
*/
|
|
303
|
+
async createIssueRelation(issueId, relatedIssueId) {
|
|
304
|
+
try {
|
|
305
|
+
const data = await call(
|
|
306
|
+
'mutation($input: IssueRelationCreateInput!) { issueRelationCreate(input: $input) { success } }',
|
|
307
|
+
{ input: { issueId, relatedIssueId, type: 'related' } },
|
|
308
|
+
)
|
|
309
|
+
return { added: !!(data && data.issueRelationCreate && data.issueRelationCreate.success) }
|
|
310
|
+
} catch (error) {
|
|
311
|
+
if (/already exists|duplicate/i.test(String(error && error.message))) {
|
|
312
|
+
return { added: false, already: true }
|
|
313
|
+
}
|
|
314
|
+
throw error
|
|
315
|
+
}
|
|
316
|
+
},
|
|
297
317
|
// A phase sub-issue is an ordinary issue carrying `parentId`. Same mutation,
|
|
298
318
|
// so there is no separate sub-issue surface to keep in step.
|
|
299
319
|
async createSubIssue(parentId, subIssue) {
|
|
@@ -330,6 +350,16 @@ function makeApiAdapter({ apiKey, fetch: fetchImpl, endpoint, sleep, maxRetries
|
|
|
330
350
|
)
|
|
331
351
|
return (data && data.issues && data.issues.nodes) || []
|
|
332
352
|
},
|
|
353
|
+
// A team's issue labels, for resolving a configured label NAME
|
|
354
|
+
// (linear.labelsByKind) to the id a create wants. Team-scoped labels and
|
|
355
|
+
// the workspace ones the team inherits both answer here.
|
|
356
|
+
async listLabels(teamId) {
|
|
357
|
+
const data = await call(
|
|
358
|
+
`query($id: String!) { team(id: $id) { labels { nodes { id name } } } }`,
|
|
359
|
+
{ id: teamId },
|
|
360
|
+
)
|
|
361
|
+
return (data && data.team && data.team.labels && data.team.labels.nodes) || []
|
|
362
|
+
},
|
|
333
363
|
async listProjects(teamId) {
|
|
334
364
|
const data = teamId
|
|
335
365
|
? await call(`query($id: String!) { team(id: $id) { projects { nodes { id name } } } }`, { id: teamId })
|
|
@@ -521,8 +551,13 @@ async function fetchWorkspaceStates(adapter, teamId) {
|
|
|
521
551
|
* from the workspace, so a `config.states` value the workspace lacks fails here
|
|
522
552
|
* with the same vocabulary the state check already uses.
|
|
523
553
|
*/
|
|
524
|
-
function stateIdFor(bucket, config, states) {
|
|
525
|
-
|
|
554
|
+
function stateIdFor(bucket, config, states, kind) {
|
|
555
|
+
// Per-kind resolution: Linear has no work item types, so statesByKind keys
|
|
556
|
+
// the override by the SPEC's kind. An entry of null means "send no state
|
|
557
|
+
// for this bucket", which lands on the same `return null` an unmapped
|
|
558
|
+
// bucket always took — the caller already treats null as "no transition".
|
|
559
|
+
const over = config && config.statesByKind && kind ? config.statesByKind[kind] : null
|
|
560
|
+
const name = over && bucket in over ? over[bucket] : config && config.states && config.states[bucket]
|
|
526
561
|
if (!name) return null
|
|
527
562
|
const hit = states.find((s) => s && s.name === name)
|
|
528
563
|
if (!hit) {
|
|
@@ -56,6 +56,8 @@ const {
|
|
|
56
56
|
phaseModeFor,
|
|
57
57
|
ownsField,
|
|
58
58
|
remoteDescriptionEdited,
|
|
59
|
+
specHeaders,
|
|
60
|
+
linkedIncident,
|
|
59
61
|
} = require('../sync-core')
|
|
60
62
|
|
|
61
63
|
const {
|
|
@@ -2226,8 +2228,67 @@ function describeRefusal(error) {
|
|
|
2226
2228
|
* stripped (`withoutNull`) except the assignee clear, and the refusal texts
|
|
2227
2229
|
* name Linear and its commands.
|
|
2228
2230
|
*/
|
|
2229
|
-
|
|
2230
|
-
|
|
2231
|
+
// A spec's KIND, read off its folder prefix — the same convention the
|
|
2232
|
+
// lifecycle skills stamp into `> **Type:**`, but greppable with no file read.
|
|
2233
|
+
function specKindOf(snapshotDir) {
|
|
2234
|
+
const name = path.basename(String(snapshotDir || ''))
|
|
2235
|
+
if (name.startsWith('bug-')) return 'bug'
|
|
2236
|
+
if (name.startsWith('hotfix-')) return 'hotfix'
|
|
2237
|
+
if (name.startsWith('chore-')) return 'chore'
|
|
2238
|
+
if (name.startsWith('issue-')) return 'issue'
|
|
2239
|
+
if (name.startsWith('incident-')) return 'incident'
|
|
2240
|
+
return 'feature'
|
|
2241
|
+
}
|
|
2242
|
+
|
|
2243
|
+
async function applyOneSpec({ dir, config, snapshotDir, plan, adapter, teamId, project, states, forceNew = false, out = null }) {
|
|
2244
|
+
const kind = specKindOf(snapshotDir)
|
|
2245
|
+
// Per-kind state resolution: statesByKind[kind] overlays states inside
|
|
2246
|
+
// stateIdFor, and a bucket overridden to null resolves to no transition.
|
|
2247
|
+
const stateId = (bucket) => (bucket ? stateIdFor(bucket, config, states, kind) : null)
|
|
2248
|
+
// THIS spec's kind label (linear.labelsByKind), resolved name → id once per
|
|
2249
|
+
// apply. A label Linear does not have is a one-line note and an unlabelled
|
|
2250
|
+
// mint, never a failed push — and with nothing configured, no label call is
|
|
2251
|
+
// made at all.
|
|
2252
|
+
const kindLabelName = (config.linear && config.linear.labelsByKind && config.linear.labelsByKind[kind]) || ''
|
|
2253
|
+
// The `Severity:` header's label (linear.severityLabels, keyed by the
|
|
2254
|
+
// leading digit — "2 - High" → "2"). Opt-in: unset, the header stays
|
|
2255
|
+
// repo-only and no extra label call is made.
|
|
2256
|
+
const severity = specHeaders(snapshotDir, config).severity
|
|
2257
|
+
const severityDigit = severity ? (/^([1-4])/.exec(severity) || [])[1] : null
|
|
2258
|
+
const severityLabelName =
|
|
2259
|
+
(severityDigit && config.linear && config.linear.severityLabels && config.linear.severityLabels[severityDigit]) || ''
|
|
2260
|
+
const wantedLabels = [kindLabelName, severityLabelName].filter(Boolean)
|
|
2261
|
+
let kindLabelIds = null
|
|
2262
|
+
if (wantedLabels.length && teamId && typeof adapter.listLabels === 'function') {
|
|
2263
|
+
const labels = await adapter.listLabels(teamId)
|
|
2264
|
+
const ids = []
|
|
2265
|
+
for (const name of wantedLabels) {
|
|
2266
|
+
const hit = labels.find((l) => l && String(l.name).toLowerCase() === name.toLowerCase())
|
|
2267
|
+
if (hit) ids.push(hit.id)
|
|
2268
|
+
else if (out) out.write(` !! label "${name}" is not on the team — minted without it\n`)
|
|
2269
|
+
}
|
|
2270
|
+
if (ids.length) kindLabelIds = ids
|
|
2271
|
+
} else if (wantedLabels.length && out && typeof adapter.listLabels !== 'function') {
|
|
2272
|
+
out.write(` !! label "${wantedLabels.join('", "')}" skipped — this transport cannot list labels\n`)
|
|
2273
|
+
}
|
|
2274
|
+
// The `Incident:` header's related link, added after the mint/update. The
|
|
2275
|
+
// repo owns the link; an incident not linked yet is a line, never a failure.
|
|
2276
|
+
const incident = linkedIncident(snapshotDir, config)
|
|
2277
|
+
const relateToIncident = async (issueId) => {
|
|
2278
|
+
if (!incident) return
|
|
2279
|
+
if (!incident.identifier) {
|
|
2280
|
+
if (out) out.write(` !! related incident ${incident.name} is not linked yet — link skipped\n`)
|
|
2281
|
+
return
|
|
2282
|
+
}
|
|
2283
|
+
if (typeof adapter.createIssueRelation !== 'function' || typeof adapter.readIssue !== 'function') return
|
|
2284
|
+
const target = await adapter.readIssue(incident.identifier)
|
|
2285
|
+
if (!target || !target.id) {
|
|
2286
|
+
if (out) out.write(` !! related incident ${incident.identifier} not found on Linear — link skipped\n`)
|
|
2287
|
+
return
|
|
2288
|
+
}
|
|
2289
|
+
const r = await adapter.createIssueRelation(issueId, target.id)
|
|
2290
|
+
if (out && r && r.added) out.write(` related link added: ${incident.identifier}\n`)
|
|
2291
|
+
}
|
|
2231
2292
|
const ops = {
|
|
2232
2293
|
prevalidateStates: (buckets) => {
|
|
2233
2294
|
for (const bucket of buckets) stateId(bucket)
|
|
@@ -2250,8 +2311,11 @@ async function applyOneSpec({ dir, config, snapshotDir, plan, adapter, teamId, p
|
|
|
2250
2311
|
// Assert only. An issue being minted has no assignee to retract, so
|
|
2251
2312
|
// `withoutNull` dropping a null here is exactly right.
|
|
2252
2313
|
assigneeId: (issue && issue.assignee) || null,
|
|
2314
|
+
// The kind's label, when configured and resolved above; null drops out.
|
|
2315
|
+
labelIds: kindLabelIds,
|
|
2253
2316
|
}))
|
|
2254
2317
|
if (!created || !created.identifier) throw new Error('Linear returned no issue for the spec create')
|
|
2318
|
+
await relateToIncident(created.id)
|
|
2255
2319
|
return created
|
|
2256
2320
|
},
|
|
2257
2321
|
updateIssue: async (existing, issue) => {
|
|
@@ -2266,6 +2330,7 @@ async function applyOneSpec({ dir, config, snapshotDir, plan, adapter, teamId, p
|
|
|
2266
2330
|
// is something to say, so `in` is the test, not truthiness.
|
|
2267
2331
|
if ('assignee' in issue) updates.assigneeId = issue.assignee ?? null
|
|
2268
2332
|
await adapter.updateIssue(existing.id, updates)
|
|
2333
|
+
await relateToIncident(existing.id)
|
|
2269
2334
|
},
|
|
2270
2335
|
mintSubIssue: async (parentId, sub) => {
|
|
2271
2336
|
const created = await adapter.createSubIssue(parentId, withoutNull({
|
|
@@ -2404,7 +2469,7 @@ async function specSyncApply(dir, config, specArg, flags, out) {
|
|
|
2404
2469
|
out.write(`spec-sync apply: ${error.message}\n`)
|
|
2405
2470
|
return 1
|
|
2406
2471
|
}
|
|
2407
|
-
const shared = { dir, config, adapter, teamId, project: flags.project, states, forceNew: flags.forceNew }
|
|
2472
|
+
const shared = { dir, config, adapter, teamId, project: flags.project, states, forceNew: flags.forceNew, out }
|
|
2408
2473
|
|
|
2409
2474
|
if (!bulk) {
|
|
2410
2475
|
const lines = ['spec-sync apply: transport = api']
|
|
@@ -2974,6 +3039,53 @@ function originalPreserved(comments) {
|
|
|
2974
3039
|
})
|
|
2975
3040
|
}
|
|
2976
3041
|
|
|
3042
|
+
|
|
3043
|
+
// `comment <spec> --file <f>` — post a file's markdown onto the spec's issue
|
|
3044
|
+
// as a comment: the one surface one-way sync never touches, so no later push
|
|
3045
|
+
// can clobber it. `/spec-complete` posts an incident's log through this.
|
|
3046
|
+
// Misuse (no readable file) exits 1; every cannot-tell exits 0 and says so.
|
|
3047
|
+
async function specSyncComment(dir, config, specArg, flags, out) {
|
|
3048
|
+
const snapshotDir = resolveOrExit(specArg, dir, out)
|
|
3049
|
+
if (!snapshotDir) return 1
|
|
3050
|
+
const done = (msg) => {
|
|
3051
|
+
out.write(`spec-sync comment: ${msg}\n`)
|
|
3052
|
+
return 0
|
|
3053
|
+
}
|
|
3054
|
+
if (!flags.file) {
|
|
3055
|
+
out.write('spec-sync comment: pass --file <markdown file to post>\n')
|
|
3056
|
+
return 1
|
|
3057
|
+
}
|
|
3058
|
+
let body
|
|
3059
|
+
try {
|
|
3060
|
+
body = fs.readFileSync(flags.file, 'utf-8')
|
|
3061
|
+
} catch (error) {
|
|
3062
|
+
out.write(`spec-sync comment: cannot read --file: ${error.message}\n`)
|
|
3063
|
+
return 1
|
|
3064
|
+
}
|
|
3065
|
+
if (!body.trim()) {
|
|
3066
|
+
out.write('spec-sync comment: --file is empty — nothing to post\n')
|
|
3067
|
+
return 1
|
|
3068
|
+
}
|
|
3069
|
+
const overviewFile = (config.snapshot && config.snapshot.overviewFile) || '00-overview.md'
|
|
3070
|
+
const identifier = linkedIdentifier(path.join(snapshotDir, overviewFile))
|
|
3071
|
+
if (!identifier) return done(`${path.basename(snapshotDir)} is not linked — nothing posted`)
|
|
3072
|
+
const key = resolveApiKey(config, flags.env || process.env)
|
|
3073
|
+
const transport = resolveTransport(flags, config, key.ok)
|
|
3074
|
+
if (transport === 'mcp') {
|
|
3075
|
+
return done(`transport = mcp — post the file's contents onto ${identifier} with the Linear comment tool yourself`)
|
|
3076
|
+
}
|
|
3077
|
+
if (!key.ok) return done(`no API key — ${key.error.split('\n')[0]}; nothing posted`)
|
|
3078
|
+
const adapter = flags.adapter || makeApiAdapter({ apiKey: key.key, fetch: flags.fetch })
|
|
3079
|
+
try {
|
|
3080
|
+
const issue = await adapter.readIssue(identifier)
|
|
3081
|
+
if (!issue || !issue.id) return done(`${identifier} not found on Linear — nothing posted`)
|
|
3082
|
+
await adapter.createComment(issue.id, body)
|
|
3083
|
+
return done(`${identifier} — comment posted (${body.length} characters)`)
|
|
3084
|
+
} catch (error) {
|
|
3085
|
+
return done(`could not reach Linear (${String(error.message).split('\n')[0]}); nothing posted`)
|
|
3086
|
+
}
|
|
3087
|
+
}
|
|
3088
|
+
|
|
2977
3089
|
/**
|
|
2978
3090
|
* `spec-sync preserve <spec> [--text <file>] [--json]` — post the issue's
|
|
2979
3091
|
* current description as a comment, before a push replaces it with the spec.
|
|
@@ -3208,6 +3320,7 @@ async function specSync(rest, io = {}) {
|
|
|
3208
3320
|
// `preserve --text <file>`: the description to keep, when the caller read it
|
|
3209
3321
|
// over MCP and the engine cannot.
|
|
3210
3322
|
else if (args[i] === '--text') flags.text = path.resolve(args[++i])
|
|
3323
|
+
else if (args[i] === '--file') flags.file = path.resolve(args[++i])
|
|
3211
3324
|
else if (args[i] === '--mcp') flags.mcp = path.resolve(args[++i])
|
|
3212
3325
|
else if (args[i] === '--plan') flags.plan = path.resolve(args[++i])
|
|
3213
3326
|
else if (args[i] === '--via') flags.via = args[++i]
|
|
@@ -3381,6 +3494,8 @@ async function specSync(rest, io = {}) {
|
|
|
3381
3494
|
return specSyncVerify(dir, config, positional[0], flags, out) || 0
|
|
3382
3495
|
case 'preserve':
|
|
3383
3496
|
return (await specSyncPreserve(dir, config, positional[0], flags, out)) || 0
|
|
3497
|
+
case 'comment':
|
|
3498
|
+
return (await specSyncComment(dir, config, positional[0], flags, out)) || 0
|
|
3384
3499
|
case 'linked':
|
|
3385
3500
|
specSyncLinked(dir, config, flags, out)
|
|
3386
3501
|
return 0
|
|
@@ -3400,6 +3515,7 @@ async function specSync(rest, io = {}) {
|
|
|
3400
3515
|
' skitterspec spec-sync apply --all <bucket> [--via api|mcp] [--json]\n' +
|
|
3401
3516
|
' skitterspec spec-sync verify <spec> --stored <file>\n' +
|
|
3402
3517
|
' skitterspec spec-sync preserve <spec> [--text <file>] [--via api|mcp] [--json]\n' +
|
|
3518
|
+
' skitterspec spec-sync comment <spec> --file <file> [--via api|mcp]\n' +
|
|
3403
3519
|
' skitterspec spec-sync list [--state <name> …|--all|--in-progress] [--next N] [--mine|--by <user>] [--limit N] [--archived] [--json]\n' +
|
|
3404
3520
|
' skitterspec spec-sync linked [--json]\n' +
|
|
3405
3521
|
' skitterspec spec-sync ref [<spec>] [--json]\n' +
|
|
@@ -113,7 +113,18 @@ const DEFAULT_CONFIG = Object.freeze({
|
|
|
113
113
|
// call only and never stored in the spec or the snapshot, so a PM re-homing the
|
|
114
114
|
// issue in Linear is invisible to sync. (The old `initiativeId` grouped
|
|
115
115
|
// Projects, which no longer exist.)
|
|
116
|
-
linear: Object.freeze({
|
|
116
|
+
linear: Object.freeze({
|
|
117
|
+
teamKey: '',
|
|
118
|
+
teamId: '',
|
|
119
|
+
projectId: '',
|
|
120
|
+
// One label per SPEC KIND (`feature`/`bug`/`hotfix`/`chore`, from the spec
|
|
121
|
+
// folder's prefix), applied at mint when set — `{ "chore": "Chore" }`
|
|
122
|
+
// keeps tooling work filterable out of release views. The label must
|
|
123
|
+
// already exist on the team; a missing one is a one-line note, never a
|
|
124
|
+
// failed push. Empty means no kind label, as before.
|
|
125
|
+
labelsByKind: Object.freeze({}),
|
|
126
|
+
severityLabels: Object.freeze({}),
|
|
127
|
+
}),
|
|
117
128
|
// Issue intake (`/spec <ISSUE-REF>`, `/spec --from-issue`). `label` is the
|
|
118
129
|
// inbox filter — issues carrying it are what the web app files; `bugLabels`
|
|
119
130
|
// route an issue to `/spec-bug` instead of `/spec`, and `hotfixLabels` route it
|
|
@@ -264,7 +275,7 @@ const LIFECYCLE_BUCKETS = Object.freeze(Object.keys(DEFAULT_CONFIG.states))
|
|
|
264
275
|
// A fresh, deeply-mutable copy of the defaults to merge onto.
|
|
265
276
|
function defaults() {
|
|
266
277
|
return {
|
|
267
|
-
linear: { ...DEFAULT_CONFIG.linear },
|
|
278
|
+
linear: { ...DEFAULT_CONFIG.linear, labelsByKind: { ...DEFAULT_CONFIG.linear.labelsByKind }, severityLabels: { ...DEFAULT_CONFIG.linear.severityLabels } },
|
|
268
279
|
intake: {
|
|
269
280
|
label: DEFAULT_CONFIG.intake.label,
|
|
270
281
|
bugLabels: [...DEFAULT_CONFIG.intake.bugLabels],
|
|
@@ -273,6 +284,7 @@ function defaults() {
|
|
|
273
284
|
},
|
|
274
285
|
mapping: { ...DEFAULT_CONFIG.mapping },
|
|
275
286
|
states: { ...DEFAULT_CONFIG.states },
|
|
287
|
+
statesByKind: {},
|
|
276
288
|
stateAliases: {},
|
|
277
289
|
snapshot: { ...DEFAULT_CONFIG.snapshot },
|
|
278
290
|
fields: { ...DEFAULT_CONFIG.fields },
|
|
@@ -296,7 +308,7 @@ function defaults() {
|
|
|
296
308
|
// vocabularies; `mergeConfig` below is the part that is Linear's — which keys
|
|
297
309
|
// exist and how they nest.
|
|
298
310
|
const { isObject, stringList, assign } = kitConfig
|
|
299
|
-
const { mergeStates, mergeFieldOwnership, mergePhaseMapping, mergeReleaseIgnorePaths, mergeKeyedFields } =
|
|
311
|
+
const { mergeStates, mergeStateOverrides, mergeFieldOwnership, mergePhaseMapping, mergeReleaseIgnorePaths, mergeKeyedFields } =
|
|
300
312
|
kitConfig.makeMergeHelpers({
|
|
301
313
|
configFile: CONFIG_FILE,
|
|
302
314
|
ownership: OWNERSHIP,
|
|
@@ -315,6 +327,25 @@ function mergeConfig(base, parsed) {
|
|
|
315
327
|
assign(base.linear, parsed.linear, 'teamKey', 'string?')
|
|
316
328
|
assign(base.linear, parsed.linear, 'teamId', 'string?')
|
|
317
329
|
assign(base.linear, parsed.linear, 'projectId', 'string?')
|
|
330
|
+
if (isObject(parsed.linear.labelsByKind)) {
|
|
331
|
+
// Only the kinds a spec folder can actually be — an unknown key is
|
|
332
|
+
// dropped, matching the other providers' by-kind validation.
|
|
333
|
+
const byKind = {}
|
|
334
|
+
for (const kind of ['feature', 'bug', 'hotfix', 'chore', 'issue', 'incident']) {
|
|
335
|
+
const value = parsed.linear.labelsByKind[kind]
|
|
336
|
+
if (typeof value === 'string' && value.trim()) byKind[kind] = value.trim()
|
|
337
|
+
}
|
|
338
|
+
base.linear.labelsByKind = byKind
|
|
339
|
+
}
|
|
340
|
+
if (isObject(parsed.linear.severityLabels)) {
|
|
341
|
+
// Keyed by the Severity header's leading digit ("2 - High" → "2").
|
|
342
|
+
const bySeverity = {}
|
|
343
|
+
for (const digit of ['1', '2', '3', '4']) {
|
|
344
|
+
const value = parsed.linear.severityLabels[digit]
|
|
345
|
+
if (typeof value === 'string' && value.trim()) bySeverity[digit] = value.trim()
|
|
346
|
+
}
|
|
347
|
+
base.linear.severityLabels = bySeverity
|
|
348
|
+
}
|
|
318
349
|
}
|
|
319
350
|
|
|
320
351
|
if (isObject(parsed.intake)) {
|
|
@@ -346,6 +377,7 @@ function mergeConfig(base, parsed) {
|
|
|
346
377
|
}
|
|
347
378
|
|
|
348
379
|
mergeStates(base, parsed)
|
|
380
|
+
mergeStateOverrides(base, parsed, 'statesByKind')
|
|
349
381
|
|
|
350
382
|
if (isObject(parsed.snapshot)) {
|
|
351
383
|
assign(base.snapshot, parsed.snapshot, 'overviewFile', 'string')
|
|
@@ -193,8 +193,52 @@ function makeMergeHelpers({ configFile, ownership, lifecycleBuckets, phaseMappin
|
|
|
193
193
|
base.stateAliases = aliases
|
|
194
194
|
}
|
|
195
195
|
|
|
196
|
+
// Merge (and validate) a per-type/kind state override table — `statesByType`
|
|
197
|
+
// keyed by work item / issue type (Azure, Jira), `statesByKind` keyed by spec
|
|
198
|
+
// kind (GitHub, Linear). Each entry is a PARTIAL bucket map laid over
|
|
199
|
+
// `states` for that type/kind: a bucket set to null means "send no state for
|
|
200
|
+
// this bucket", and a bucket the entry lacks falls through to `states`.
|
|
201
|
+
// An unknown bucket is refused — a typo'd bucket would silently change
|
|
202
|
+
// nothing at push time. Call after mergeStates, so buckets are final.
|
|
203
|
+
function mergeStateOverrides(base, parsed, key) {
|
|
204
|
+
const value = parsed[key]
|
|
205
|
+
if (!isObject(value)) return
|
|
206
|
+
const table = {}
|
|
207
|
+
for (const [name, entry] of Object.entries(value)) {
|
|
208
|
+
if (!isObject(entry)) {
|
|
209
|
+
throw new Error(
|
|
210
|
+
`Invalid ${configFile}: ${key}.${JSON.stringify(name)} = ${JSON.stringify(entry)} ` +
|
|
211
|
+
'(expected an object mapping lifecycle buckets to a state name, or null to send no state)',
|
|
212
|
+
)
|
|
213
|
+
}
|
|
214
|
+
const row = {}
|
|
215
|
+
for (const [bucket, state] of Object.entries(entry)) {
|
|
216
|
+
if (!(bucket in base.states)) {
|
|
217
|
+
throw new Error(
|
|
218
|
+
`Invalid ${configFile}: ${key}.${JSON.stringify(name)}.${bucket} — not a lifecycle bucket ` +
|
|
219
|
+
`(${Object.keys(base.states).join(', ')})`,
|
|
220
|
+
)
|
|
221
|
+
}
|
|
222
|
+
if (state === null) {
|
|
223
|
+
row[bucket] = null
|
|
224
|
+
continue
|
|
225
|
+
}
|
|
226
|
+
if (typeof state !== 'string' || !state.trim()) {
|
|
227
|
+
throw new Error(
|
|
228
|
+
`Invalid ${configFile}: ${key}.${JSON.stringify(name)}.${bucket} = ${JSON.stringify(state)} ` +
|
|
229
|
+
'(expected a state name, or null to send no state)',
|
|
230
|
+
)
|
|
231
|
+
}
|
|
232
|
+
row[bucket] = state.trim()
|
|
233
|
+
}
|
|
234
|
+
if (Object.keys(row).length) table[name] = row
|
|
235
|
+
}
|
|
236
|
+
base[key] = table
|
|
237
|
+
}
|
|
238
|
+
|
|
196
239
|
return {
|
|
197
240
|
mergeStates,
|
|
241
|
+
mergeStateOverrides,
|
|
198
242
|
mergeFieldOwnership,
|
|
199
243
|
mergePhaseMapping,
|
|
200
244
|
mergeReleaseIgnorePaths,
|