@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.
- package/assets/claude-md-section.md +8 -2
- package/assets/commands/allow-project.md +28 -0
- package/assets/core/env.config.md +29 -3
- package/assets/hooks/project-guard.cjs +161 -0
- package/assets/rules/spec-planning.md +44 -1
- package/assets/skills/spec/SKILL.md +30 -0
- package/assets/skills/spec-cancel/SKILL.md +22 -4
- package/assets/skills/spec-complete/SKILL.md +34 -6
- package/assets/skills/spec-idea/SKILL.md +115 -0
- package/assets/skills/spec-init/SKILL.md +3 -1
- package/assets/skills/spec-review/SKILL.md +22 -4
- package/assets/skills/spec-tada/SKILL.md +26 -4
- package/assets/skills/spec-todo/SKILL.md +104 -0
- package/bin/skitterspec-jira.js +4 -0
- package/package.json +1 -1
- package/src/cli.js +266 -21
- package/src/env/config.js +26 -3
- package/src/env/hooks.js +10 -0
- package/src/env/integrate.js +5 -34
- package/src/env/live.js +106 -4
- package/src/env/projectguard.js +389 -0
- package/src/env/triggered.js +50 -0
- package/src/idea.js +190 -0
- package/src/ideacmd.js +242 -0
- package/src/tada/digest.js +41 -2
- package/src/tada/format.js +4 -2
- package/src/tada/page.js +35 -7
- package/src/tada/repo.js +22 -2
- package/src/tada/serve.js +13 -7
- package/src/tada/todo.js +250 -0
- package/src/vendor/jira/cli-sync.js +33 -11
- package/src/vendor/provider-kit/src/apply.js +90 -5
package/src/tada/todo.js
ADDED
|
@@ -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
|
-
|
|
390
|
-
|
|
391
|
-
|
|
392
|
-
|
|
393
|
-
|
|
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
|
-
|
|
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>
|
|
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({
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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 }
|