@skitterbyte/skitterspec-jira 2.10.0 → 2.12.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.
@@ -0,0 +1,250 @@
1
+ 'use strict'
2
+
3
+ /**
4
+ * The morning half of the ta-da list (feat-spec-todo, phase 2): where each
5
+ * project was left on the last day with any activity, and what is ahead. It
6
+ * reads the same digest `skitterspec tada` does — once for the lookback, once
7
+ * for the day it found — so the two can never disagree about what happened.
8
+ * Pure: every input arrives already read.
9
+ */
10
+
11
+ const fs = require('node:fs')
12
+ const path = require('node:path')
13
+
14
+ const { localDay } = require('./window.js')
15
+ const { waitingPasses, readGate, gateState } = require('../env/review.js')
16
+
17
+ // Far enough to bridge a long weekend or a week away; past it, "where did I
18
+ // leave off" has no useful answer and the report says so.
19
+ const LOOKBACK_DAYS = 14
20
+
21
+ function daysBefore(d, n) {
22
+ return new Date(d.getFullYear(), d.getMonth(), d.getDate() - n)
23
+ }
24
+
25
+ /** Every instant a digest saw something happen: prompts, sessions, commits, moves. */
26
+ function activityTimes(digest) {
27
+ const times = []
28
+ for (const p of digest.projects) {
29
+ for (const g of p.groups) {
30
+ for (const s of g.sessions) {
31
+ times.push(s.start, s.end)
32
+ for (const pr of s.prompts) times.push(pr.at)
33
+ }
34
+ for (const c of g.commits) times.push(c.at)
35
+ for (const e of g.events) times.push(e.at)
36
+ }
37
+ }
38
+ return times.filter(Boolean)
39
+ }
40
+
41
+ /**
42
+ * The local midnight of the most recent day before `todayStart` with any
43
+ * activity, at most `lookback` days back — so Monday reads Friday and a day
44
+ * off is skipped. Null when nothing falls in the lookback.
45
+ *
46
+ * @param {string[]} times ISO instants (`activityTimes`)
47
+ * @param {Date} todayStart local midnight today
48
+ */
49
+ function lastActiveDay(times, todayStart, lookback = LOOKBACK_DAYS) {
50
+ const floor = daysBefore(todayStart, lookback).getTime()
51
+ const end = todayStart.getTime()
52
+ let best = null
53
+ for (const t of times) {
54
+ const ms = Date.parse(t)
55
+ if (Number.isNaN(ms) || ms < floor || ms >= end) continue
56
+ if (best === null || ms > best) best = ms
57
+ }
58
+ if (best === null) return null
59
+ const d = new Date(best)
60
+ return new Date(d.getFullYear(), d.getMonth(), d.getDate())
61
+ }
62
+
63
+ const EVENT = { written: 'written', started: 'started', completed: 'completed', cancelled: 'cancelled' }
64
+ const eventText = (e) => (e.kind === 'phase-done' ? `phase ${e.phase} done` : EVENT[e.kind] || e.kind)
65
+
66
+ /**
67
+ * Where one group was left: its last move or commit, whichever came later —
68
+ * a commit after a move is the newer fact. Null when the group only has
69
+ * sessions or an in-flight row.
70
+ */
71
+ function leftOf(g) {
72
+ const last = [
73
+ ...g.events.map((e) => ({ at: e.at, text: eventText(e) })),
74
+ ...g.commits.map((c) => ({ at: c.at, text: `${c.sha} ${c.subject}` })),
75
+ ].sort((a, b) => Date.parse(a.at) - Date.parse(b.at))
76
+ return last.length ? last[last.length - 1].text : null
77
+ }
78
+
79
+ // The last thing typed in the group's last session — what was on the
80
+ // person's mind when they stopped.
81
+ function lastPrompt(g) {
82
+ const s = g.sessions[g.sessions.length - 1]
83
+ const p = s && s.prompts[s.prompts.length - 1]
84
+ return p ? `${p.command ? `${p.command} ` : ''}${p.text}`.trim() : null
85
+ }
86
+
87
+ /**
88
+ * What stands in a project's way, read only for the specs in flight there: a
89
+ * pass waiting on the review page, or a gate armed by a phase that ended. A
90
+ * pass for a spec no longer in flight is an old one nobody is waiting on, and
91
+ * is left out rather than reported as a blocker.
92
+ *
93
+ * @param {object} a
94
+ * - `specs` the project's in-flight spec names
95
+ * - `passes` `waitingPasses(...).passes`
96
+ * - `gates` `{ [spec]: gateState(...) }`; a missing or `unknown` state is
97
+ * cannot-tell, and says nothing
98
+ */
99
+ function blockersFrom({ specs, passes = [], gates = {} }) {
100
+ const want = new Set(specs)
101
+ const out = []
102
+ for (const p of passes) {
103
+ if (want.has(p.spec)) out.push({ spec: p.spec, kind: 'verdict', verdict: p.verdict, code: p.code, at: p.at })
104
+ }
105
+ for (const spec of specs) {
106
+ const g = gates[spec]
107
+ if (g && g.state === 'armed') out.push({ spec, kind: 'gate', phase: g.gate ? g.gate.phase : null })
108
+ }
109
+ return out
110
+ }
111
+
112
+ /**
113
+ * `blockersFrom`, read off one repo's review store. A store that does not
114
+ * exist — a repo that never rendered a review — is nothing in the way, not a
115
+ * failure; an unreadable gate is `gateState`'s cannot-tell and says nothing.
116
+ *
117
+ * @param {string} reviews the repo's reviews dir (`<state dir>/reviews`)
118
+ * @param {string[]} specs its in-flight spec names
119
+ * @param {boolean} [required] `review.required`; false opts the gates out
120
+ */
121
+ function readBlockers(reviews, specs, required) {
122
+ if (!fs.existsSync(reviews)) return []
123
+ const gates = {}
124
+ for (const spec of specs) gates[spec] = gateState({ ...readGate(path.join(reviews, `${spec}.html`), spec), required })
125
+ return blockersFrom({ specs, passes: waitingPasses(reviews).passes, gates })
126
+ }
127
+
128
+ /**
129
+ * The to-do: the left-off day's projects, each open spec reduced to where it
130
+ * was left, the specs that day finished by name, today's activity so far, and
131
+ * what is blocking each project.
132
+ *
133
+ * @param {object} a
134
+ * - `leftOff` the digest for the left-off day, or null when none
135
+ * - `leftOffDay` that day's local midnight, or null
136
+ * - `today` today's digest so far
137
+ * - `home` the home project as a digest project (in-flight groups
138
+ * only) for when neither digest lists it, else null
139
+ * - `blockersFor` `(repo, specs) => blockers` — read only for a repo
140
+ */
141
+ function buildTodo({ leftOff, leftOffDay, today, home = null, blockersFor = () => [] }) {
142
+ const projects = new Map()
143
+ const keyOf = (p) => p.repo || p.name
144
+ const entry = (p) => {
145
+ const k = keyOf(p)
146
+ if (!projects.has(k)) projects.set(k, { repo: p.repo, name: p.name, here: false, groups: [], finished: [], today: { commits: 0, moves: 0 } })
147
+ const e = projects.get(k)
148
+ if (p.here) e.here = true
149
+ return e
150
+ }
151
+
152
+ for (const p of leftOff ? leftOff.projects : []) {
153
+ const e = entry(p)
154
+ for (const g of p.groups) {
155
+ // The morning wants what is still open. A spec the day finished is said
156
+ // once, by name; work on no spec is history, not a place to pick up.
157
+ if (!g.inFlight) {
158
+ if (g.spec && g.events.some((ev) => ev.kind === 'completed' || ev.kind === 'cancelled')) e.finished.push(g.spec)
159
+ continue
160
+ }
161
+ const left = leftOf(g)
162
+ const prompt = lastPrompt(g)
163
+ e.groups.push({ spec: g.spec, branch: g.branch, ...(g.ticket ? { ticket: g.ticket } : {}), left, prompt, inFlight: g.inFlight })
164
+ }
165
+ }
166
+ for (const p of today.projects) {
167
+ const e = entry(p)
168
+ const known = new Set(e.groups.map((g) => g.spec).filter(Boolean))
169
+ for (const g of p.groups) {
170
+ e.today.commits += g.commits.length
171
+ e.today.moves += g.events.length
172
+ // What is ahead in a project the left-off day did not touch.
173
+ if (g.spec && g.inFlight && !known.has(g.spec)) {
174
+ e.groups.push({ spec: g.spec, branch: g.branch, ...(g.ticket ? { ticket: g.ticket } : {}), left: null, prompt: null, inFlight: g.inFlight })
175
+ }
176
+ }
177
+ }
178
+ if (home && !projects.has(keyOf(home))) {
179
+ const e = entry({ ...home, here: true })
180
+ for (const g of home.groups) if (g.inFlight) e.groups.push({ spec: g.spec, branch: null, left: null, prompt: null, inFlight: g.inFlight })
181
+ }
182
+ // Ideas are counted for home only: the count is this project's to act on,
183
+ // and asking every project's tracker would turn a morning read into a crawl.
184
+ // Null — could not ask — and zero both print nothing.
185
+ if (home && home.ideas > 0) projects.get(keyOf(home)).ideas = home.ideas
186
+
187
+ const list = [...projects.values()]
188
+ .map((e) => {
189
+ const specs = e.groups.filter((g) => g.spec && g.inFlight).map((g) => g.spec)
190
+ return { ...e, blocked: e.repo && specs.length ? blockersFor(e.repo, specs) : [] }
191
+ })
192
+ .filter((e) => e.groups.length || e.finished.length || e.today.commits || e.today.moves || e.ideas)
193
+ // The home project first: it is the one this session acts on.
194
+ .sort((a, b) => (a.here !== b.here ? (a.here ? -1 : 1) : a.name.localeCompare(b.name)))
195
+
196
+ return {
197
+ kind: 'todo',
198
+ leftOff: leftOffDay ? { day: localDay(leftOffDay) } : null,
199
+ lookbackDays: LOOKBACK_DAYS,
200
+ ...(today.category ? { category: today.category } : {}),
201
+ projects: list,
202
+ notes: [...new Set([...(leftOff ? leftOff.notes : []), ...today.notes])],
203
+ }
204
+ }
205
+
206
+ const ageText = (at, now) => {
207
+ const ms = now - Date.parse(at)
208
+ if (Number.isNaN(ms) || ms < 0) return ''
209
+ const h = Math.floor(ms / 3_600_000)
210
+ return h < 24 ? ` · ${h}h` : ` · ${Math.floor(h / 24)}d`
211
+ }
212
+
213
+ function blockedText(b, now) {
214
+ if (b.kind === 'gate') return `${b.spec} — gate armed${b.phase ? `, phase ${b.phase}` : ''}: a verdict is owed`
215
+ return `${b.spec} — ${b.verdict || 'a'} verdict waiting (${b.code}${b.at ? ageText(b.at, now) : ''})`
216
+ }
217
+
218
+ /**
219
+ * The to-do as text — the same markers as `tada`, plus `left:` for where a
220
+ * group stopped, `finished:` for the specs that day closed, `blocked:` for what stands in a project's way, and `today:`
221
+ * for what has happened since midnight.
222
+ */
223
+ function formatTodo(todo, now = new Date()) {
224
+ const scope = todo.category ? ` · ${todo.category}` : ''
225
+ const head = todo.leftOff
226
+ ? `todo: left off ${todo.leftOff.label || todo.leftOff.day} · today ${todo.todayLabel || ''}`.trimEnd()
227
+ : `todo: nothing in the last ${todo.lookbackDays} days · today ${todo.todayLabel || ''}`.trimEnd()
228
+ const out = [`${head}${scope}`]
229
+ if (todo.projects.length === 0) out.push(' nothing in flight.')
230
+ for (const p of todo.projects) {
231
+ out.push('', `${p.name}${p.here ? ' (here)' : ''}${p.repo ? ` (${p.repo})` : ''}`)
232
+ for (const g of p.groups) {
233
+ out.push(` ${g.spec ? `${g.spec}${g.ticket ? ` [${g.ticket.id}]` : ''}` : `${g.branch || '(no branch)'} — no spec`}`)
234
+ if (g.left) out.push(` left: ${g.left}`)
235
+ if (g.prompt) out.push(` - ${g.prompt}`)
236
+ if (g.inFlight) out.push(` in flight: ${g.inFlight.detail}${g.inFlight.next ? ` · next: ${g.inFlight.next}` : ''}`)
237
+ }
238
+ if (p.finished.length) out.push(` finished: ${p.finished.join(', ')}`)
239
+ for (const b of p.blocked) out.push(` blocked: ${blockedText(b, now)}`)
240
+ if (p.ideas) out.push(` ideas: ${p.ideas} waiting · /spec-idea lists them`)
241
+ if (p.today.commits || p.today.moves) {
242
+ const parts = [p.today.commits && `${p.today.commits} commit${p.today.commits === 1 ? '' : 's'}`, p.today.moves && `${p.today.moves} move${p.today.moves === 1 ? '' : 's'}`]
243
+ out.push(` today: ${parts.filter(Boolean).join(', ')}`)
244
+ }
245
+ }
246
+ for (const n of todo.notes) out.push('', n)
247
+ return out.join('\n') + '\n'
248
+ }
249
+
250
+ module.exports = { LOOKBACK_DAYS, activityTimes, lastActiveDay, leftOf, blockersFrom, readBlockers, buildTodo, formatTodo, blockedText }
@@ -318,10 +318,15 @@ function specSyncPlan(dir, config, specArg, flags, out, err) {
318
318
  }
319
319
 
320
320
  async function specSyncApply(dir, config, specArg, flags, out, err) {
321
- if (!flags.plan && !flags.all) {
321
+ if (!flags.plan && !flags.all && !flags.sendHeld) {
322
322
  out.write(`${PROGRAM} apply: pass --plan <file> (from \`plan --json\`), or --all <bucket>\n`)
323
323
  return 1
324
324
  }
325
+ const held = kit.heldFlags(flags, PROGRAM)
326
+ if (held.error) {
327
+ out.write(held.error + '\n')
328
+ return 1
329
+ }
325
330
  const cred = apiAdapterFor(config, flags)
326
331
  const transport = kit.resolveTransport(flags, config, cred.ok)
327
332
  if (transport === 'mcp') {
@@ -335,6 +340,8 @@ async function specSyncApply(dir, config, specArg, flags, out, err) {
335
340
  ' editJiraIssue / transitionJiraIssue), then stamp the returned keys\n' +
336
341
  ' with `spec-sync stamp` and record with `spec-sync record`.\n',
337
342
  )
343
+ const heldNote = kit.heldOverMcp(held, PROGRAM)
344
+ if (heldNote) out.write(heldNote + '\n')
338
345
  return 0
339
346
  }
340
347
  if (!cred.ok) {
@@ -351,6 +358,8 @@ async function specSyncApply(dir, config, specArg, flags, out, err) {
351
358
  adapter: cred.adapter,
352
359
  ops: applyOps({ adapter: cred.adapter, config, kind: specKindOf(snapshotDir), snapshotDir, out }),
353
360
  forceNew: !!flags.forceNew,
361
+ holdState: held.holdState,
362
+ sendHeld: held.sendHeld,
354
363
  program: PROGRAM,
355
364
  })
356
365
 
@@ -386,13 +395,19 @@ async function specSyncApply(dir, config, specArg, flags, out, err) {
386
395
  const snapshotDir = resolveOrExit(specArg, dir, out)
387
396
  if (!snapshotDir) return 1
388
397
  let plan
389
- try {
390
- plan = JSON.parse(fs.readFileSync(flags.plan, 'utf-8'))
391
- } catch (error) {
392
- out.write(`${PROGRAM} apply: cannot read --plan: ${error.message}\n`)
393
- return 1
398
+ if (!flags.plan) {
399
+ // --send-held computes its own. After the merge it is normally empty, and
400
+ // that empty plan is what tells apply that run 1 held the state.
401
+ plan = push({ dir, snapshotDir, identifier: specIdentifier(snapshotDir, config), config }).plan
402
+ } else {
403
+ try {
404
+ plan = JSON.parse(fs.readFileSync(flags.plan, 'utf-8'))
405
+ } catch (error) {
406
+ out.write(`${PROGRAM} apply: cannot read --plan: ${error.message}\n`)
407
+ return 1
408
+ }
394
409
  }
395
- if (isEmptyPlan(plan)) {
410
+ if (!held.sendHeld && isEmptyPlan(plan)) {
396
411
  out.write(`${PROGRAM} apply: empty plan — nothing to do\n`)
397
412
  return 0
398
413
  }
@@ -477,10 +492,13 @@ async function specSyncStamp(dir, config, specArg, flags, out) {
477
492
  return 0
478
493
  }
479
494
 
480
- function specSyncRecord(dir, config, specArg, out) {
495
+ function specSyncRecord(dir, config, specArg, flags, out) {
481
496
  const snapshotDir = resolveOrExit(specArg, dir, out)
482
497
  if (!snapshotDir) return 1
483
- const file = recordPush({ dir, snapshotDir, identifier: specIdentifier(snapshotDir, config), config })
498
+ // --held: the hand-applied twin of `apply --hold-state` — the state was left
499
+ // out on purpose, and is recorded as sent so run 2 rewrites nothing.
500
+ const sent = flags && flags.held ? { issue: true, subIssues: new Set() } : null
501
+ const file = recordPush({ dir, snapshotDir, identifier: specIdentifier(snapshotDir, config), config, sent })
484
502
  out.write(`${PROGRAM} record: snapshot written — ${path.relative(dir, file).split(path.sep).join('/')}\n`)
485
503
  return 0
486
504
  }
@@ -1307,8 +1325,9 @@ const USAGE = `Usage: skitterspec-jira spec-sync <subcommand>
1307
1325
  normalize <spec> print the local projection as JSON
1308
1326
  plan <spec> --workspace-states <f> what a push would change (dry, JSON)
1309
1327
  apply <spec> --plan <f> | --all <b> apply a plan over the API
1328
+ apply <spec> --hold-state | --send-held PR-mode completion: hold Done for run 2, then send it
1310
1329
  stamp <spec> --issue KEY [--sub r=K] write returned keys into the spec
1311
- record <spec> write the last-pushed snapshot
1330
+ record <spec> [--held] write the last-pushed snapshot
1312
1331
  status <spec> [--remote <f>] read-only drift report
1313
1332
  verify <spec> --stored <f> compare a read-back against the repo
1314
1333
  splice <spec> --live <f> [--phase <ref>] the body to write over MCP (summary mode)
@@ -1382,7 +1401,7 @@ async function specSync(rest, io = {}) {
1382
1401
  case 'stamp':
1383
1402
  return specSyncStamp(dir, config, positional[0], flags, out)
1384
1403
  case 'record':
1385
- return specSyncRecord(dir, config, positional[0], out)
1404
+ return specSyncRecord(dir, config, positional[0], flags, out)
1386
1405
  case 'status':
1387
1406
  return specSyncStatus(dir, config, positional[0], flags, out, err)
1388
1407
  case 'splice': {
@@ -1447,6 +1466,9 @@ function parseArgs(args, sub) {
1447
1466
  '--via': { kind: 'string' },
1448
1467
  '--force': { kind: 'boolean' },
1449
1468
  '--force-new': { kind: 'boolean', name: 'forceNew' },
1469
+ '--hold-state': { kind: 'boolean', name: 'holdState' },
1470
+ '--send-held': { kind: 'boolean', name: 'sendHeld' },
1471
+ '--held': { kind: 'boolean' },
1450
1472
  '--issue': { kind: 'string' },
1451
1473
  '--url': { kind: 'value' },
1452
1474
  '--sub': { kind: 'list', name: 'subs' },
@@ -52,6 +52,7 @@ const path = require('node:path')
52
52
  const {
53
53
  readSnapshot,
54
54
  readBase,
55
+ isEmptyPlan,
55
56
  projectionOf,
56
57
  recordPush,
57
58
  writeFrontmatter,
@@ -85,16 +86,58 @@ async function applySpecPlan(args) {
85
86
  }
86
87
  }
87
88
 
88
- async function applyInner({ dir, config, snapshotDir, plan, adapter, ops, progress, forceNew = false, program = 'spec-sync' }) {
89
+ async function applyInner({
90
+ dir,
91
+ config,
92
+ snapshotDir,
93
+ plan,
94
+ adapter,
95
+ ops,
96
+ progress,
97
+ forceNew = false,
98
+ holdState = false,
99
+ sendHeld = false,
100
+ program = 'spec-sync',
101
+ }) {
89
102
  const fields = fieldsOf(config)
90
103
  const helpers = makeSpecHelpers({ program })
91
104
  const overviewFile = (config.snapshot && config.snapshot.overviewFile) || '00-overview.md'
92
105
  const identifier = helpers.linkedIdentifier(path.join(snapshotDir, overviewFile), config)
93
106
  const lines = []
94
107
  const result = { issue: null, subIssues: {} }
108
+
109
+ // PR-MODE COMPLETION, `branch` lane (spec bug-pr-complete-snapshot-on-base).
110
+ // Run 1 commits the move to ride the PR, but the Done waits for the merge —
111
+ // and run 2 sends it from the base branch, where no spec branch is left to
112
+ // commit a snapshot to. So run 1 HOLDS the state yet records it as sent, and
113
+ // run 2 SENDS only that state: the snapshot it records is byte-identical to
114
+ // the one the merge brought, and the base branch stays clean.
115
+ if (holdState && sendHeld) throw new Error(`${program} apply: --hold-state and --send-held are two runs, not one`)
116
+ if ((holdState || sendHeld) && !identifier) {
117
+ throw new Error(`${program} apply: an unlinked spec has no transition to hold — push it plainly`)
118
+ }
119
+ let heldState = false
120
+ let fellBack = false
121
+ if (holdState && plan.issue && plan.issue.state != null) {
122
+ const { state, stateResend, ...rest } = plan.issue
123
+ plan = { ...plan, issue: Object.keys(rest).length ? rest : undefined }
124
+ heldState = state
125
+ } else if (sendHeld) {
126
+ // A NON-EMPTY PLAN MEANS RUN 1 HELD NOTHING — it predates the hold, so the
127
+ // whole completion is still unsent. Sending the state alone would strand
128
+ // the rest; apply it all, as before, and say which file that leaves dirty.
129
+ if (isEmptyPlan(plan)) {
130
+ const status = projectionOf(snapshotDir, config).status
131
+ if (status != null) plan = { ...plan, issue: { state: status } }
132
+ } else {
133
+ fellBack = true
134
+ }
135
+ }
136
+
95
137
  // Which items this apply carried a state for — the snapshot records today's
96
- // state name for these and only these (`recordPush`).
97
- const sent = { issue: !!(plan.issue && plan.issue.state != null), subIssues: new Set() }
138
+ // state name for these and only these (`recordPush`). A held state counts:
139
+ // run 2 sends it, and what run 2 records has to match what run 1 committed.
140
+ const sent = { issue: !!heldState || !!(plan.issue && plan.issue.state != null), subIssues: new Set() }
98
141
  // Handed out immediately, so a throw from anywhere below still reports what
99
142
  // had been stamped by the time it happened.
100
143
  if (progress) progress.result = result
@@ -268,7 +311,12 @@ async function applyInner({ dir, config, snapshotDir, plan, adapter, ops, progre
268
311
  const file = recordPush({ dir, snapshotDir, identifier: helpers.specIdentifier(snapshotDir, config), config, sent, keepSubIssues })
269
312
  // A repo path, `/`-separated on every platform — the form every other
270
313
  // spec path in this output takes.
271
- lines.push(` snapshot: ${path.relative(dir, file).split(path.sep).join('/')}`)
314
+ const snapshotPath = path.relative(dir, file).split(path.sep).join('/')
315
+ lines.push(` snapshot: ${snapshotPath}`)
316
+ if (heldState) lines.push(` state held: ${identifier} → ${heldState} waits for the merge — run 2 sends it with --send-held`)
317
+ if (fellBack) {
318
+ lines.push(` !! nothing was held for ${identifier} — sent the whole plan; ${snapshotPath} now differs from the merged copy`)
319
+ }
272
320
  return { result, lines, lost }
273
321
  }
274
322
 
@@ -304,4 +352,41 @@ function resolvePhaseFileIn(snapshotDir, ref) {
304
352
  return listPhaseFiles(snapshotDir).find((f) => f.replace(/\.md$/, '') === want) || null
305
353
  }
306
354
 
307
- module.exports = { applySpecPlan }
355
+ /**
356
+ * `--hold-state` / `--send-held` as every provider's `apply` reads them: one
357
+ * spec, one of the two, never both. Returns `{ holdState, sendHeld }`, or
358
+ * `{ error }` for the provider to print and exit 1 on.
359
+ */
360
+ function heldFlags(flags, program) {
361
+ const holdState = !!(flags && flags.holdState)
362
+ const sendHeld = !!(flags && flags.sendHeld)
363
+ if (holdState && sendHeld) return { error: `${program} apply: --hold-state and --send-held are two runs, not one` }
364
+ if ((holdState || sendHeld) && flags.all != null) {
365
+ return { error: `${program} apply --all: --hold-state and --send-held act on one spec at a time` }
366
+ }
367
+ return { holdState, sendHeld }
368
+ }
369
+
370
+ /**
371
+ * What the MCP transport adds to its "nothing written" note, so the hand-applied
372
+ * push ends with the same snapshot the API path would record. Null when neither
373
+ * flag is set.
374
+ */
375
+ function heldOverMcp({ holdState, sendHeld }, program) {
376
+ if (holdState) {
377
+ return (
378
+ " --hold-state: apply the plan WITHOUT the spec issue's state, then record with\n" +
379
+ ` \`${program} record <spec> --held\` — run 2 sends the state after the merge.`
380
+ )
381
+ }
382
+ if (sendHeld) {
383
+ return (
384
+ " --send-held: if `plan` is empty, send the spec issue's state alone and record\n" +
385
+ ' nothing — the merged snapshot already says it. If it is not, run 1 held\n' +
386
+ ' nothing: apply it whole and record as usual.'
387
+ )
388
+ }
389
+ return null
390
+ }
391
+
392
+ module.exports = { applySpecPlan, heldFlags, heldOverMcp }