@skitterbyte/skitterspec-jira 2.0.0 → 2.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/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)`}\n`,
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(`${JSON.stringify({ spec: spec.folder, since: flags.since, ...result }, null, 2)}\n`)
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' +
@@ -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-`/`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. Unknown prefix → type defaults to
298
- // `feat` and the whole folder name is the slug.
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,
@@ -152,6 +152,13 @@ function makeApiAdapter({ siteUrl, email, token, fetch: fetchImpl, sleep, maxRet
152
152
  if (input.assigneeId !== undefined) {
153
153
  fields.assignee = input.assigneeId == null ? null : { accountId: input.assigneeId }
154
154
  }
155
+ // Extra raw fields, keyed by field id — how `jira.severityField` writes a
156
+ // site's own Severity field without this adapter knowing its id.
157
+ if (input.extraFields) {
158
+ for (const [id, value] of Object.entries(input.extraFields)) {
159
+ if (value !== undefined) fields[id] = value
160
+ }
161
+ }
155
162
  return fields
156
163
  }
157
164
 
@@ -164,14 +171,42 @@ function makeApiAdapter({ siteUrl, email, token, fetch: fetchImpl, sleep, maxRet
164
171
  return normalizeIssue(raw)
165
172
  },
166
173
 
167
- async createIssue({ title, description, assigneeId, projectKey, issueTypeName }) {
174
+ async createIssue({ title, description, assigneeId, projectKey, issueTypeName, extraFields }) {
168
175
  const created = await request('POST', '/issue', {
169
- body: { fields: issueFields({ title, description, assigneeId }, { forCreate: true, projectKey, issueTypeName }) },
176
+ body: { fields: issueFields({ title, description, assigneeId, extraFields }, { forCreate: true, projectKey, issueTypeName }) },
170
177
  })
171
178
  if (!created || !created.key) throw new Error('Jira returned no issue for the create')
172
179
  return { id: String(created.id), identifier: created.key, url: urlOf(created.key) }
173
180
  },
174
181
 
182
+ /**
183
+ * The "Relates" links an issue already carries, as the other end's key —
184
+ * what lets a re-push skip a link that is already there instead of
185
+ * stacking a duplicate on every push.
186
+ */
187
+ async listRelatedLinks(keyOrId) {
188
+ const raw = await request('GET', `/issue/${encodeURIComponent(keyOrId)}`, {
189
+ query: { fields: 'issuelinks' },
190
+ allow404: true,
191
+ })
192
+ const links = (raw && raw.fields && raw.fields.issuelinks) || []
193
+ return links
194
+ .map((l) => (l.inwardIssue && l.inwardIssue.key) || (l.outwardIssue && l.outwardIssue.key))
195
+ .filter(Boolean)
196
+ },
197
+
198
+ /** Add a "Relates" issue link between two issues. */
199
+ async createRelatedLink(keyOrId, targetKeyOrId) {
200
+ await request('POST', '/issueLink', {
201
+ body: {
202
+ type: { name: 'Relates' },
203
+ inwardIssue: { key: String(keyOrId) },
204
+ outwardIssue: { key: String(targetKeyOrId) },
205
+ },
206
+ })
207
+ return { added: true }
208
+ },
209
+
175
210
  async createSubIssue(parentId, { title, description, projectKey, subtaskTypeName }) {
176
211
  const fields = issueFields({ title, description }, { forCreate: true, projectKey, issueTypeName: subtaskTypeName })
177
212
  fields.parent = { id: String(parentId) }
@@ -267,6 +302,27 @@ function makeApiAdapter({ siteUrl, email, token, fetch: fetchImpl, sleep, maxRet
267
302
  return [...names.values()]
268
303
  },
269
304
 
305
+ /**
306
+ * The same statuses KEYED BY ISSUE TYPE — Jira binds a workflow to the
307
+ * type, so a status one type lacks is exactly what per-type validation
308
+ * exists to catch, and the deduped list above hides it.
309
+ */
310
+ async listIssueStatesByType(projectKey) {
311
+ const raw = await request('GET', `/project/${encodeURIComponent(projectKey)}/statuses`)
312
+ const byType = {}
313
+ for (const type of raw || []) {
314
+ if (!type || !type.name) continue
315
+ byType[type.name] = (type.statuses || [])
316
+ .filter((status) => status && status.name)
317
+ .map((status) => ({
318
+ id: String(status.id),
319
+ name: status.name,
320
+ category: (status.statusCategory && status.statusCategory.name) || null,
321
+ }))
322
+ }
323
+ return byType
324
+ },
325
+
270
326
  async readViewer() {
271
327
  const raw = await request('GET', '/myself')
272
328
  if (!raw || !raw.accountId) return null