@skitterbyte/skitterspec-jira 2.3.0 → 2.4.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 +20 -1
- package/assets/core/env.config.json.example +1 -0
- package/assets/core/env.config.md +90 -6
- package/assets/core/jira.config.md +4 -2
- package/assets/hooks/main-guard.cjs +18 -2
- package/assets/hooks/review-gate.cjs +19 -2
- package/assets/rules/commit-trailers.md +24 -1
- package/assets/rules/spec-planning.md +81 -18
- package/assets/rules/spec-reports.md +1 -1
- package/assets/skills/spec/SKILL.md +55 -2
- package/assets/skills/spec-bug/SKILL.md +25 -1
- package/assets/skills/spec-cancel/SKILL.md +35 -0
- package/assets/skills/spec-complete/SKILL.md +113 -0
- package/assets/skills/spec-hotfix/SKILL.md +40 -2
- package/assets/skills/spec-incident/SKILL.md +22 -0
- package/assets/skills/spec-jira-setup/SKILL.md +23 -1
- package/assets/skills/spec-next/SKILL.md +9 -4
- package/assets/skills/spec-push/SKILL.md +22 -0
- package/assets/skills/spec-review/SKILL.md +32 -0
- package/assets/skills/spec-start/SKILL.md +39 -1
- package/assets/skills/spec-status/SKILL.md +18 -3
- package/assets/skills/spec-sync/SKILL.md +1 -0
- package/assets/skills/spec-to-main/SKILL.md +47 -1
- package/package.json +1 -1
- package/src/cli.js +1091 -39
- package/src/env/base.js +104 -0
- package/src/env/config.js +75 -3
- package/src/env/disposition.js +62 -0
- package/src/env/handoff.js +80 -0
- package/src/env/host.js +262 -0
- package/src/env/hotfix.js +225 -0
- package/src/env/hotfixland.js +103 -9
- package/src/env/inflight.js +95 -0
- package/src/env/integrate.js +130 -4
- package/src/env/mainguard.js +6 -0
- package/src/env/phases.js +28 -0
- package/src/env/provision.js +18 -6
- package/src/env/resolve.js +108 -9
- package/src/env/serve.js +6 -1
- package/src/env/specstate.js +101 -0
- package/src/env/teardown.js +42 -0
- package/src/vendor/jira/cli-sync.js +45 -3
- package/src/vendor/jira/config.js +17 -5
- package/src/vendor/provider-kit/index.js +4 -0
- package/src/vendor/provider-kit/src/apply.js +49 -4
- package/src/vendor/provider-kit/src/assignment.js +78 -1
- package/src/vendor/provider-kit/src/config.js +34 -1
- package/src/vendor/provider-kit/src/list-rows.js +35 -11
- package/src/vendor/provider-kit/src/released.js +14 -1
- package/src/vendor/provider-kit/src/specs.js +4 -2
- package/src/vendor/provider-kit/src/splice.js +64 -0
- package/src/vendor/provider-kit/src/status.js +137 -0
- package/src/vendor/sync-core/index.js +14 -1
- package/src/vendor/sync-core/src/compare.js +17 -5
- package/src/vendor/sync-core/src/normalize.js +50 -7
- package/src/vendor/sync-core/src/push.js +26 -2
- package/src/vendor/sync-core/src/summary.js +257 -0
|
@@ -36,6 +36,7 @@
|
|
|
36
36
|
* - `updateSubIssue(sub)` apply a sub-issue update
|
|
37
37
|
* - `remoteEditedLine(identifier)` the someone-else-edited warning
|
|
38
38
|
* - `twinAdvice(twin, title, specName)` the refusal message for a twin
|
|
39
|
+
* - `afterIssue(issue)` optional; → a report line or null
|
|
39
40
|
*/
|
|
40
41
|
|
|
41
42
|
const path = require('node:path')
|
|
@@ -51,6 +52,8 @@ const {
|
|
|
51
52
|
remoteDescriptionEdited,
|
|
52
53
|
remoteSubIssueEdited,
|
|
53
54
|
listPhaseFiles,
|
|
55
|
+
descriptionMode,
|
|
56
|
+
spliceBlock,
|
|
54
57
|
} = require('../../sync-core')
|
|
55
58
|
const { makeSpecHelpers } = require('./specs.js')
|
|
56
59
|
|
|
@@ -140,11 +143,23 @@ async function applyInner({ dir, config, snapshotDir, plan, adapter, ops, progre
|
|
|
140
143
|
lines.push(ops.remoteEditedLine(identifier))
|
|
141
144
|
}
|
|
142
145
|
if (plan.issue) {
|
|
143
|
-
|
|
146
|
+
const issue = spliced(plan.issue, 'description', existing, config, identifier, lines)
|
|
147
|
+
await ops.updateIssue(existing, issue)
|
|
144
148
|
lines.push(` issue updated: ${identifier}`)
|
|
145
149
|
}
|
|
146
150
|
}
|
|
147
151
|
|
|
152
|
+
// A provider's per-push extra on the spec issue (e.g. progress mirrored into
|
|
153
|
+
// a native field). Never fatal: the repo and the block already carry it.
|
|
154
|
+
if (ops.afterIssue && result.issue) {
|
|
155
|
+
try {
|
|
156
|
+
const line = await ops.afterIssue(result.issue)
|
|
157
|
+
if (line) lines.push(line)
|
|
158
|
+
} catch (error) {
|
|
159
|
+
lines.push(` ?? ${result.issue.identifier}: ${String((error && error.message) || error).split('\n')[0]}`)
|
|
160
|
+
}
|
|
161
|
+
}
|
|
162
|
+
|
|
148
163
|
// 4. Sub-issue creates — each stamped as it lands, for the same reason.
|
|
149
164
|
for (const sub of (plan.subIssues && plan.subIssues.create) || []) {
|
|
150
165
|
const created = await ops.mintSubIssue(parentId, sub)
|
|
@@ -167,11 +182,15 @@ async function applyInner({ dir, config, snapshotDir, plan, adapter, ops, progre
|
|
|
167
182
|
// issue. The read is spent only where the snapshot recorded something to
|
|
168
183
|
// compare against, so an old snapshot costs no extra calls.
|
|
169
184
|
const base = readBase(dir, identifier, config)
|
|
170
|
-
|
|
185
|
+
const summary = descriptionMode(config) === 'summary'
|
|
186
|
+
for (let sub of (plan.subIssues && plan.subIssues.update) || []) {
|
|
171
187
|
const streams = base && base.subIssueStreams
|
|
172
|
-
|
|
188
|
+
const compare = sub.goal != null && streams && streams[String(sub.id)]
|
|
189
|
+
// Summary mode always reads the live body: the block is spliced into it.
|
|
190
|
+
if (compare || (summary && sub.goal != null)) {
|
|
173
191
|
const before = await adapter.readIssue(sub.id)
|
|
174
|
-
if (remoteSubIssueEdited(base, sub.id, before, config) === true) lines.push(ops.remoteEditedLine(sub.id))
|
|
192
|
+
if (compare && remoteSubIssueEdited(base, sub.id, before, config) === true) lines.push(ops.remoteEditedLine(sub.id))
|
|
193
|
+
sub = spliced(sub, 'goal', before, config, sub.id, lines)
|
|
175
194
|
}
|
|
176
195
|
await ops.updateSubIssue(sub)
|
|
177
196
|
result.subIssues[sub.ref || refById.get(String(sub.id)) || sub.id] = sub.id
|
|
@@ -198,6 +217,32 @@ async function applyInner({ dir, config, snapshotDir, plan, adapter, ops, progre
|
|
|
198
217
|
return { result, lines, lost }
|
|
199
218
|
}
|
|
200
219
|
|
|
220
|
+
/**
|
|
221
|
+
* Under `mapping.description: "summary"` the planned body is the block alone,
|
|
222
|
+
* and the write must be the block SPLICED into what the tracker holds, so the
|
|
223
|
+
* team's text around it survives. `spec` mode returns the payload untouched.
|
|
224
|
+
*
|
|
225
|
+
* A damaged block (a delimiter someone edited) is cannot-tell: the body is
|
|
226
|
+
* left out of the write entirely and the run says so. Guessing the edges would
|
|
227
|
+
* eat the team's text, and prepending would leave two blocks.
|
|
228
|
+
*/
|
|
229
|
+
function spliced(payload, key, live, config, label, lines) {
|
|
230
|
+
if (descriptionMode(config) !== 'summary' || payload[key] == null) return payload
|
|
231
|
+
const hook = config && config.remote && config.remote.description
|
|
232
|
+
const current = live && typeof hook === 'function' ? hook(live) : live ? live.description : undefined
|
|
233
|
+
// Nothing read back is not an empty body: write nothing rather than guess.
|
|
234
|
+
if (typeof current !== 'string') {
|
|
235
|
+
lines.push(` ?? ${label}: could not read its body — summary block not written`)
|
|
236
|
+
return { ...payload, [key]: undefined }
|
|
237
|
+
}
|
|
238
|
+
const next = spliceBlock(current, payload[key], config)
|
|
239
|
+
if (next == null) {
|
|
240
|
+
lines.push(` !! ${label}: its summary block's delimiters were edited — block not written; repair them and re-push`)
|
|
241
|
+
return { ...payload, [key]: undefined }
|
|
242
|
+
}
|
|
243
|
+
return { ...payload, [key]: next }
|
|
244
|
+
}
|
|
245
|
+
|
|
201
246
|
// The phase file a sub-issue ref names — the ref is the phase-file basename.
|
|
202
247
|
function resolvePhaseFileIn(snapshotDir, ref) {
|
|
203
248
|
const want = String(ref).replace(/\.md$/, '')
|
|
@@ -13,6 +13,12 @@
|
|
|
13
13
|
* the operator is in the tracker, which is the fact assignment rests on.
|
|
14
14
|
* - `users [<query>]` finds a person to hand a spec to.
|
|
15
15
|
*
|
|
16
|
+
* Under `sync.fieldOwnership.assignee: "pull"` the TRACKER owns the field, so
|
|
17
|
+
* `assign` writes the ticket directly and stamps nothing into the repo — there
|
|
18
|
+
* is no projection to carry it, and a stamp would be a copy someone has to
|
|
19
|
+
* keep in step. `--if-unassigned` is how `/spec-start` claims a ticket nobody
|
|
20
|
+
* holds without ever taking one from someone who does.
|
|
21
|
+
*
|
|
16
22
|
* Everything tracker-shaped arrives as a hook (`makeAssignmentCommands`): the
|
|
17
23
|
* tracker's name for messages, the frontmatter fields, the store scope, how a
|
|
18
24
|
* credential resolves and how an adapter is made. The behaviour is the Linear
|
|
@@ -21,9 +27,10 @@
|
|
|
21
27
|
|
|
22
28
|
const path = require('node:path')
|
|
23
29
|
|
|
24
|
-
const { ownsField, writeFrontmatter, deleteFrontmatter, fieldsOf } = require('../../sync-core')
|
|
30
|
+
const { ownsField, ownershipOf, writeFrontmatter, deleteFrontmatter, fieldsOf, readSnapshot } = require('../../sync-core')
|
|
25
31
|
const { resolveTransport } = require('./transport.js')
|
|
26
32
|
const { makeSpecHelpers } = require('./specs.js')
|
|
33
|
+
const { readStatus } = require('./status.js')
|
|
27
34
|
|
|
28
35
|
/**
|
|
29
36
|
* @param {object} p
|
|
@@ -58,6 +65,7 @@ function makeAssignmentCommands(p) {
|
|
|
58
65
|
|
|
59
66
|
const problems = []
|
|
60
67
|
if (flags.release && flags.to) problems.push('--release and --to are opposites — pass one')
|
|
68
|
+
if (flags.release && flags.ifUnassigned) problems.push('--if-unassigned guards an assignment — it has nothing to say about --release')
|
|
61
69
|
if (!flags.release && !flags.to) problems.push('nothing to do — pass --to <user-id> or --release')
|
|
62
70
|
// An unlinked spec has no issue to assign. Refusing beats stamping a field
|
|
63
71
|
// that would sit in the file doing nothing until someone noticed.
|
|
@@ -86,6 +94,19 @@ function makeAssignmentCommands(p) {
|
|
|
86
94
|
return 1
|
|
87
95
|
}
|
|
88
96
|
|
|
97
|
+
if (ownershipOf(config, 'assignee') === 'pull') return assignOnTracker(config, identifier, flags, out)
|
|
98
|
+
|
|
99
|
+
// Under `push` the repo's stamp IS the record, so that is what the guard asks.
|
|
100
|
+
if (flags.ifUnassigned) {
|
|
101
|
+
const { frontmatter } = readSnapshot(snapshotDir, config)
|
|
102
|
+
const recorded = frontmatter[fields.assigneeId]
|
|
103
|
+
if (recorded) {
|
|
104
|
+
const shown = (fields.assigneeName && frontmatter[fields.assigneeName]) || recorded
|
|
105
|
+
out.write(`spec-sync assign: ${rel} is already assigned to ${shown} — left alone\n`)
|
|
106
|
+
return 0
|
|
107
|
+
}
|
|
108
|
+
}
|
|
109
|
+
|
|
89
110
|
if (flags.release) {
|
|
90
111
|
const removed = deleteFrontmatter(snapshotDir, config, [fields.assigneeId, fields.assigneeName].filter(Boolean))
|
|
91
112
|
if (flags.json) {
|
|
@@ -116,6 +137,62 @@ function makeAssignmentCommands(p) {
|
|
|
116
137
|
return 0
|
|
117
138
|
}
|
|
118
139
|
|
|
140
|
+
/**
|
|
141
|
+
* The `pull` half of `assign`: write the ticket, stamp nothing.
|
|
142
|
+
*
|
|
143
|
+
* `--if-unassigned` reads the ticket first and acts only on a POSITIVE
|
|
144
|
+
* "nobody holds it". A read that could not run is cannot-tell, and the
|
|
145
|
+
* harmless branch is to assign nobody: taking a ticket from a colleague is
|
|
146
|
+
* the one mistake here that costs someone else their afternoon.
|
|
147
|
+
*
|
|
148
|
+
* Exits 0 on every cannot-tell (MCP transport, no credential, an unreadable
|
|
149
|
+
* ticket) and 1 only when the tracker refused a write it was asked to make.
|
|
150
|
+
*/
|
|
151
|
+
async function assignOnTracker(config, identifier, flags, out) {
|
|
152
|
+
const say = (line) => {
|
|
153
|
+
out.write(`spec-sync assign: ${line}\n`)
|
|
154
|
+
return 0
|
|
155
|
+
}
|
|
156
|
+
const report = (result) => {
|
|
157
|
+
if (flags.json) {
|
|
158
|
+
out.write(JSON.stringify({ issue: identifier, owner: 'tracker', ...result }, null, 2) + '\n')
|
|
159
|
+
return 0
|
|
160
|
+
}
|
|
161
|
+
return say(result.line)
|
|
162
|
+
}
|
|
163
|
+
const cred = flags.adapter ? { ok: true } : p.resolveCredential(config, flags.env || process.env)
|
|
164
|
+
const transport = resolveTransport(flags, config, cred.ok)
|
|
165
|
+
if (transport === 'mcp' || !cred.ok) {
|
|
166
|
+
const what = flags.release ? 'unassign it' : `assign it to ${flags.to}`
|
|
167
|
+
return report({
|
|
168
|
+
written: false,
|
|
169
|
+
line: `${p.tracker} owns the assignee here, and there is no API transport — ${what} on ${identifier} with the tracker's own tool; nothing was written`,
|
|
170
|
+
})
|
|
171
|
+
}
|
|
172
|
+
const adapter = flags.adapter || p.makeAdapter(config, cred, flags)
|
|
173
|
+
|
|
174
|
+
if (flags.ifUnassigned) {
|
|
175
|
+
const now = await readStatus({ adapter, ref: identifier, config })
|
|
176
|
+
if (!now.ok) {
|
|
177
|
+
return report({ written: false, line: `could not read ${identifier} (${now.reason}) — assigned nobody` })
|
|
178
|
+
}
|
|
179
|
+
if (now.assignee) {
|
|
180
|
+
const who = now.assignee.name || now.assignee.id
|
|
181
|
+
return report({ written: false, assignee: now.assignee, line: `${identifier} is already assigned to ${who} — left alone` })
|
|
182
|
+
}
|
|
183
|
+
}
|
|
184
|
+
|
|
185
|
+
try {
|
|
186
|
+
await adapter.updateIssue(identifier, { assigneeId: flags.release ? null : flags.to })
|
|
187
|
+
} catch (error) {
|
|
188
|
+
out.write(`spec-sync assign: ${p.tracker} refused — ${String(error.message).split('\n')[0]}\n`)
|
|
189
|
+
return 1
|
|
190
|
+
}
|
|
191
|
+
if (flags.release) return report({ written: true, released: true, line: `${identifier} unassigned on ${p.tracker}` })
|
|
192
|
+
const who = flags.name ? `${flags.name} (${flags.to})` : flags.to
|
|
193
|
+
return report({ written: true, id: flags.to, name: flags.name || null, line: `${identifier} assigned to ${who} on ${p.tracker}` })
|
|
194
|
+
}
|
|
195
|
+
|
|
119
196
|
/**
|
|
120
197
|
* Exit 0 even when the answer is "unknown": this answers a question, and
|
|
121
198
|
* "nobody is identified here" is a valid answer — a shared key, an offline
|
|
@@ -236,6 +236,33 @@ function makeMergeHelpers({ configFile, ownership, lifecycleBuckets, phaseMappin
|
|
|
236
236
|
base[key] = table
|
|
237
237
|
}
|
|
238
238
|
|
|
239
|
+
// Merge (and validate) what a ticket's description carries —
|
|
240
|
+
// `mapping.description` (`spec` · `summary`) and the block's delimiter style
|
|
241
|
+
// (`summary.delimiter`: `comment` · `heading`). Loud on a bad value: a typo
|
|
242
|
+
// must not read as a choice to keep pushing the whole spec.
|
|
243
|
+
function mergeDescription(base, parsed) {
|
|
244
|
+
if (isObject(parsed.mapping) && parsed.mapping.description !== undefined) {
|
|
245
|
+
const mode = parsed.mapping.description
|
|
246
|
+
if (!DESCRIPTION_MODES.includes(mode)) {
|
|
247
|
+
throw new Error(
|
|
248
|
+
`Invalid ${configFile}: mapping.description = ${JSON.stringify(mode)} ` +
|
|
249
|
+
`(expected one of ${DESCRIPTION_MODES.join('|')})`,
|
|
250
|
+
)
|
|
251
|
+
}
|
|
252
|
+
base.mapping.description = mode
|
|
253
|
+
}
|
|
254
|
+
if (isObject(parsed.summary) && parsed.summary.delimiter !== undefined) {
|
|
255
|
+
const style = parsed.summary.delimiter
|
|
256
|
+
if (!DELIMITER_STYLES.includes(style)) {
|
|
257
|
+
throw new Error(
|
|
258
|
+
`Invalid ${configFile}: summary.delimiter = ${JSON.stringify(style)} ` +
|
|
259
|
+
`(expected one of ${DELIMITER_STYLES.join('|')})`,
|
|
260
|
+
)
|
|
261
|
+
}
|
|
262
|
+
base.summary = { ...(base.summary || {}), delimiter: style }
|
|
263
|
+
}
|
|
264
|
+
}
|
|
265
|
+
|
|
239
266
|
return {
|
|
240
267
|
mergeStates,
|
|
241
268
|
mergeStateOverrides,
|
|
@@ -243,9 +270,15 @@ function makeMergeHelpers({ configFile, ownership, lifecycleBuckets, phaseMappin
|
|
|
243
270
|
mergePhaseMapping,
|
|
244
271
|
mergeReleaseIgnorePaths,
|
|
245
272
|
mergeKeyedFields,
|
|
273
|
+
mergeDescription,
|
|
246
274
|
}
|
|
247
275
|
}
|
|
248
276
|
|
|
277
|
+
// What `mapping.description` may be. `spec` is the default and what a config
|
|
278
|
+
// that predates the key gets, so an upgrade rewrites no ticket.
|
|
279
|
+
const DESCRIPTION_MODES = Object.freeze(['spec', 'summary'])
|
|
280
|
+
const DELIMITER_STYLES = Object.freeze(['comment', 'heading'])
|
|
281
|
+
|
|
249
282
|
// Keys no provider reads any more. The merge already ignores them, as it does
|
|
250
283
|
// every unknown key — so a config still carrying one is a stale file, not a
|
|
251
284
|
// broken one, and `doctor` says so as a `warn` without touching the exit code.
|
|
@@ -292,4 +325,4 @@ function retiredKeysRow(file, configFile, row) {
|
|
|
292
325
|
)
|
|
293
326
|
}
|
|
294
327
|
|
|
295
|
-
module.exports = { isObject, stringList, assign, makeMergeHelpers, retiredKeys, retiredKeysRow, RETIRED_KEYS }
|
|
328
|
+
module.exports = { isObject, stringList, assign, makeMergeHelpers, retiredKeys, retiredKeysRow, RETIRED_KEYS, DESCRIPTION_MODES, DELIMITER_STYLES }
|
|
@@ -14,22 +14,46 @@ function expandStateArgs(args, config) {
|
|
|
14
14
|
return (args || []).flatMap((arg) => (LIFECYCLE_BUCKETS.includes(arg) ? stateNamesFor(arg, config) : [arg]))
|
|
15
15
|
}
|
|
16
16
|
|
|
17
|
-
//
|
|
18
|
-
//
|
|
19
|
-
//
|
|
20
|
-
//
|
|
17
|
+
// A spec's bucket is a CODE FACT — whether `/spec-start`, `/spec-complete` or
|
|
18
|
+
// `/spec-cancel` has run — and the board holds the planning status. So almost
|
|
19
|
+
// every difference between the two is the board doing its job: a backlog spec
|
|
20
|
+
// the board calls Ready or Blocked, an in-flight one it calls In Review. Neither
|
|
21
|
+
// is a claim about the repo, and flagging them would teach a reader to ignore
|
|
22
|
+
// the column.
|
|
23
|
+
//
|
|
24
|
+
// One difference IS worth a reader's time: the board says the work is finished
|
|
25
|
+
// (Done or Cancelled) and the repo has not done the matching cleanup. Only that
|
|
26
|
+
// pairing disagrees, and it carries the command that would close it.
|
|
27
|
+
const LIVE_BUCKETS = ['backlog', 'in-progress']
|
|
28
|
+
const FINISHED_BUCKETS = ['complete', 'cancelled']
|
|
29
|
+
|
|
30
|
+
// `{ board, cleanup }` when the board has finished what the repo has not, else
|
|
31
|
+
// null. Done against a spec in flight is `/spec-complete`; every other pairing
|
|
32
|
+
// (Cancelled, or Done on a spec that never started) is `/spec-cancel`, because
|
|
33
|
+
// there is no work here to complete.
|
|
34
|
+
function boardDisagreement(specBucket, boardBucket) {
|
|
35
|
+
if (!LIVE_BUCKETS.includes(specBucket) || !FINISHED_BUCKETS.includes(boardBucket)) return null
|
|
36
|
+
const cleanup = specBucket === 'in-progress' && boardBucket === 'complete' ? '/spec-complete' : '/spec-cancel'
|
|
37
|
+
return { board: boardBucket, cleanup }
|
|
38
|
+
}
|
|
39
|
+
|
|
40
|
+
// The spec's status beside the board's, and whether they disagree in the one
|
|
41
|
+
// way above. A board state that maps to no bucket never disagrees: it is
|
|
42
|
+
// somewhere push does not manage, which is not a claim about the spec. Nor does
|
|
43
|
+
// a row whose spec is not on this machine — there is nothing to disagree WITH.
|
|
21
44
|
function specColumn(stateName, spec, config) {
|
|
22
45
|
const specStatus = spec ? spec.bucket : null
|
|
23
46
|
const seen = stateName == null ? null : remoteStateReading({ state: { name: stateName } }, config)
|
|
24
|
-
const
|
|
25
|
-
return { specStatus, disagrees }
|
|
47
|
+
const found = specStatus && seen && seen.mapped ? boardDisagreement(specStatus, seen.bucket) : null
|
|
48
|
+
return found ? { specStatus, disagrees: true, cleanup: found.cleanup } : { specStatus, disagrees: false }
|
|
26
49
|
}
|
|
27
50
|
|
|
28
|
-
// The cell itself: `in-progress`, `≠
|
|
29
|
-
// spec is not here.
|
|
30
|
-
function specCell({ specStatus, disagrees }) {
|
|
51
|
+
// The cell itself: `in-progress`, `≠ in-progress → /spec-cancel` when the board
|
|
52
|
+
// finished it, `—` when the spec is not here.
|
|
53
|
+
function specCell({ specStatus, disagrees, cleanup }) {
|
|
31
54
|
if (!specStatus) return '—'
|
|
32
|
-
|
|
55
|
+
if (!disagrees) return specStatus
|
|
56
|
+
return cleanup ? `≠ ${specStatus} → ${cleanup}` : `≠ ${specStatus}`
|
|
33
57
|
}
|
|
34
58
|
|
|
35
|
-
module.exports = { expandStateArgs, specColumn, specCell }
|
|
59
|
+
module.exports = { expandStateArgs, specColumn, specCell, boardDisagreement }
|
|
@@ -146,7 +146,10 @@ function ticketsInRange(commits, options = {}) {
|
|
|
146
146
|
let unreferenced = 0
|
|
147
147
|
let ignored = 0
|
|
148
148
|
let historical = 0
|
|
149
|
+
let merges = 0
|
|
150
|
+
let sawMergeFlag = false
|
|
149
151
|
for (const commit of commits || []) {
|
|
152
|
+
if (commit && commit.isMerge !== undefined) sawMergeFlag = true
|
|
150
153
|
if (onlyIgnoredPaths(commit && commit.paths, ignorePaths)) {
|
|
151
154
|
// Not counted as unreferenced either: that number exists to surface a
|
|
152
155
|
// MISSED trailer, and a paperwork commit is not a gap someone should hunt.
|
|
@@ -157,8 +160,15 @@ function ticketsInRange(commits, options = {}) {
|
|
|
157
160
|
if (!refs.length) {
|
|
158
161
|
// A POSITIVE signal, never an absence: only a trailer that actually
|
|
159
162
|
// carries an older tracker's ref makes a commit historical. A commit with
|
|
160
|
-
// no trailer at all is still the gap `unreferenced` is there to name
|
|
163
|
+
// no trailer at all is still the gap `unreferenced` is there to name —
|
|
164
|
+
// unless it is a MERGE commit, which is transport: under PR landing the
|
|
165
|
+
// host writes one per merged PR, and counting each as a missed trailer
|
|
166
|
+
// buries the real gaps. A merge that CARRIES a trailer still counted
|
|
167
|
+
// above, deliberately — a hand merge is where a ticket's only trailer
|
|
168
|
+
// sometimes lives, which is why these are read rather than skipped
|
|
169
|
+
// (`--no-merges` was tried and dropped for exactly that loss).
|
|
161
170
|
if (foreign.some((p) => refsInBody(commit && commit.body, p).length)) historical++
|
|
171
|
+
else if (commit && commit.isMerge) merges++
|
|
162
172
|
else unreferenced++
|
|
163
173
|
continue
|
|
164
174
|
}
|
|
@@ -171,6 +181,9 @@ function ticketsInRange(commits, options = {}) {
|
|
|
171
181
|
total: (commits || []).length,
|
|
172
182
|
}
|
|
173
183
|
if (foreign.length) report.historical = historical
|
|
184
|
+
// Present only when a caller supplied the flag at all, so a provider that
|
|
185
|
+
// passes no parent info sees exactly the report shape it always did.
|
|
186
|
+
if (sawMergeFlag) report.merges = merges
|
|
174
187
|
return report
|
|
175
188
|
}
|
|
176
189
|
|
|
@@ -24,7 +24,7 @@ const {
|
|
|
24
24
|
resolvePrimaryCheckout,
|
|
25
25
|
} = require('../../../env/resolve.js')
|
|
26
26
|
const { loadEnvConfig } = require('../../../env/config.js')
|
|
27
|
-
const { readSnapshot, parseFrontmatter, lintPhases, fieldsOf, projectionOf, compareStored } = require('../../sync-core')
|
|
27
|
+
const { readSnapshot, parseFrontmatter, lintPhases, fieldsOf, projectionOf, compareStored, comparableDescription } = require('../../sync-core')
|
|
28
28
|
|
|
29
29
|
function makeSpecHelpers({ program = 'spec-sync' } = {}) {
|
|
30
30
|
// Resolve a spec argument to its snapshot dir. Accepts a spec name/folder
|
|
@@ -227,7 +227,9 @@ function makeSpecHelpers({ program = 'spec-sync' } = {}) {
|
|
|
227
227
|
bad++
|
|
228
228
|
continue
|
|
229
229
|
}
|
|
230
|
-
|
|
230
|
+
// Summary mode compares the block alone: the text around it is the
|
|
231
|
+
// team's. Right after a write a missing block IS a loss, so it reads as ''.
|
|
232
|
+
const r = compareStored(sent, comparableDescription(got, config) ?? '', config)
|
|
231
233
|
if (r.ok) continue
|
|
232
234
|
bad++
|
|
233
235
|
lines.push(
|
|
@@ -0,0 +1,64 @@
|
|
|
1
|
+
'use strict'
|
|
2
|
+
|
|
3
|
+
/**
|
|
4
|
+
* `spec-sync splice <spec> --live <file> [--phase <ref>]` — the body to write,
|
|
5
|
+
* for an apply the ENGINE is not doing (the skills' MCP path).
|
|
6
|
+
*
|
|
7
|
+
* Under `mapping.description: "summary"` a plan carries the block alone, and
|
|
8
|
+
* writing that over the whole description would delete the team's text around
|
|
9
|
+
* it. So the skill reads the live body, hands it here, and writes back exactly
|
|
10
|
+
* what this prints — the splice is the engine's, never composed in a skill.
|
|
11
|
+
* In `spec` mode it prints the projection as it is: the whole body is the
|
|
12
|
+
* repo's there.
|
|
13
|
+
*
|
|
14
|
+
* Exit codes: 0 with the body on stdout; 1 when nothing must be written — a
|
|
15
|
+
* damaged block (a delimiter someone edited), an unknown phase ref, or a live
|
|
16
|
+
* file that could not be read. Nothing is printed to stdout then, so a caller
|
|
17
|
+
* that pipes stdout into a write can never write a partial or empty body.
|
|
18
|
+
*/
|
|
19
|
+
|
|
20
|
+
const fs = require('node:fs')
|
|
21
|
+
|
|
22
|
+
const { projectionOf, descriptionMode, spliceBlock } = require('../../sync-core')
|
|
23
|
+
|
|
24
|
+
function spliceBody(snapshotDir, config, live, phaseRef) {
|
|
25
|
+
const projection = projectionOf(snapshotDir, config)
|
|
26
|
+
let planned = projection.description
|
|
27
|
+
if (phaseRef) {
|
|
28
|
+
const want = String(phaseRef).replace(/\.md$/, '')
|
|
29
|
+
const sub = (projection.subIssues || []).find((s) => s.ref === want)
|
|
30
|
+
if (!sub) return { ok: false, reason: `no phase ${want} in the projection` }
|
|
31
|
+
planned = sub.goal
|
|
32
|
+
}
|
|
33
|
+
if (planned == null) return { ok: false, reason: 'the projection has no body for that object' }
|
|
34
|
+
if (descriptionMode(config) !== 'summary') return { ok: true, text: planned }
|
|
35
|
+
const text = spliceBlock(live, planned, config)
|
|
36
|
+
if (text == null) {
|
|
37
|
+
return { ok: false, reason: "its summary block's delimiters were edited — write nothing; repair them and re-run" }
|
|
38
|
+
}
|
|
39
|
+
return { ok: true, text }
|
|
40
|
+
}
|
|
41
|
+
|
|
42
|
+
function specSyncSplice({ snapshotDir, config, flags, out, err, program = 'spec-sync' }) {
|
|
43
|
+
const say = (msg) => (err || out).write(`${program} splice: ${msg}\n`)
|
|
44
|
+
if (!flags.live) {
|
|
45
|
+
say('pass --live <file> holding the description the tracker has now (an empty file for a new issue)')
|
|
46
|
+
return 1
|
|
47
|
+
}
|
|
48
|
+
let live
|
|
49
|
+
try {
|
|
50
|
+
live = fs.readFileSync(flags.live, 'utf-8')
|
|
51
|
+
} catch (error) {
|
|
52
|
+
say(`cannot read --live: ${error.message}`)
|
|
53
|
+
return 1
|
|
54
|
+
}
|
|
55
|
+
const r = spliceBody(snapshotDir, config, live, flags.phase)
|
|
56
|
+
if (!r.ok) {
|
|
57
|
+
say(r.reason)
|
|
58
|
+
return 1
|
|
59
|
+
}
|
|
60
|
+
out.write(r.text)
|
|
61
|
+
return 0
|
|
62
|
+
}
|
|
63
|
+
|
|
64
|
+
module.exports = { spliceBody, specSyncSplice }
|
|
@@ -0,0 +1,137 @@
|
|
|
1
|
+
'use strict'
|
|
2
|
+
|
|
3
|
+
/**
|
|
4
|
+
* `readStatus` — what the tracker says about one spec's ticket, read live.
|
|
5
|
+
*
|
|
6
|
+
* Under `sync.fieldOwnership: "pull"` the tracker is the record for status and
|
|
7
|
+
* assignee, so the repo reads them when it needs to SAY something and never
|
|
8
|
+
* stores what it read. Every provider's adapter already answers `readIssue`
|
|
9
|
+
* with the same normalised shape — `state: { name }`, `assignee: { id, name }`
|
|
10
|
+
* — and each provider's `config.remote.stateName` hook reads its own status
|
|
11
|
+
* (GitHub's board column, Azure's System.State), so one function serves all
|
|
12
|
+
* four.
|
|
13
|
+
*
|
|
14
|
+
* THREE ANSWERS, and the third is most of them: a reading, a reading whose
|
|
15
|
+
* state maps to no bucket (`bucket: null` — somewhere the repo does not manage,
|
|
16
|
+
* never a disagreement), and cannot-tell. No adapter, no credential, a network
|
|
17
|
+
* failure and a missing ticket are all cannot-tell; none is evidence about the
|
|
18
|
+
* spec, so a caller that accuses on one is wrong (`negative-checks.md`).
|
|
19
|
+
*/
|
|
20
|
+
|
|
21
|
+
const path = require('node:path')
|
|
22
|
+
|
|
23
|
+
const { remoteStateReading, ownershipOf } = require('../../sync-core')
|
|
24
|
+
const { makeSpecHelpers } = require('./specs.js')
|
|
25
|
+
const { boardDisagreement } = require('./list-rows.js')
|
|
26
|
+
const { doctorRow } = require('./doctor.js')
|
|
27
|
+
|
|
28
|
+
const firstLine = (error) => String((error && error.message) || error).split('\n')[0]
|
|
29
|
+
|
|
30
|
+
/**
|
|
31
|
+
* @param {object} p
|
|
32
|
+
* - `adapter` an API adapter with `readIssue`
|
|
33
|
+
* - `ref` the ticket's identifier, as the adapter takes it
|
|
34
|
+
* - `config` the provider config (for the state mapping)
|
|
35
|
+
* @returns {Promise<{ ok: true, state: string|null, bucket: string|null, assignee: object|null }
|
|
36
|
+
* | { ok: false, reason: string }>}
|
|
37
|
+
*/
|
|
38
|
+
async function readStatus({ adapter, ref, config }) {
|
|
39
|
+
if (!adapter || typeof adapter.readIssue !== 'function') return { ok: false, reason: 'no API adapter' }
|
|
40
|
+
if (!ref) return { ok: false, reason: 'not linked' }
|
|
41
|
+
let issue
|
|
42
|
+
try {
|
|
43
|
+
issue = await adapter.readIssue(ref)
|
|
44
|
+
} catch (error) {
|
|
45
|
+
return { ok: false, reason: firstLine(error) }
|
|
46
|
+
}
|
|
47
|
+
if (!issue) return { ok: false, reason: `${ref} not found` }
|
|
48
|
+
const reading = remoteStateReading(issue, config)
|
|
49
|
+
const assignee = issue.assignee && issue.assignee.id ? { id: issue.assignee.id, name: issue.assignee.name || null } : null
|
|
50
|
+
return {
|
|
51
|
+
ok: true,
|
|
52
|
+
state: reading ? reading.name : null,
|
|
53
|
+
bucket: reading && reading.mapped ? reading.bucket : null,
|
|
54
|
+
assignee,
|
|
55
|
+
}
|
|
56
|
+
}
|
|
57
|
+
|
|
58
|
+
/**
|
|
59
|
+
* `spec-sync ownership [--json]` — who owns a spec's status and assignee here.
|
|
60
|
+
*
|
|
61
|
+
* This is the question the shared skills ask before writing a `Status:` header,
|
|
62
|
+
* a `Developer:` line or a State-log row: the base skills are tracker-free and
|
|
63
|
+
* cannot read a provider config, so they ask the provider's CLI rather than
|
|
64
|
+
* deciding from which provider is installed. Offline, and always exit 0 — a
|
|
65
|
+
* missing config never reaches here (the CLI reports sync is off first), and
|
|
66
|
+
* that is the skills' cannot-tell, which writes the headers as before.
|
|
67
|
+
*/
|
|
68
|
+
function specSyncOwnership(config, flags, out, program = 'spec-sync') {
|
|
69
|
+
const owners = { workflowState: ownershipOf(config, 'workflowState'), assignee: ownershipOf(config, 'assignee') }
|
|
70
|
+
if (flags && flags.json) {
|
|
71
|
+
out.write(JSON.stringify(owners, null, 2) + '\n')
|
|
72
|
+
return 0
|
|
73
|
+
}
|
|
74
|
+
out.write(`${program} ownership: status ${owners.workflowState} · assignee ${owners.assignee}\n`)
|
|
75
|
+
return 0
|
|
76
|
+
}
|
|
77
|
+
|
|
78
|
+
/**
|
|
79
|
+
* `spec-sync board <spec> [--json]` — has the board finished what this repo has
|
|
80
|
+
* not? Asked by `/spec-start` and `/spec-next` in pre-flight and by
|
|
81
|
+
* `/spec-status`, so a ticket someone Cancelled or closed as Done reaches the
|
|
82
|
+
* person holding the branch rather than waiting for them to look.
|
|
83
|
+
*
|
|
84
|
+
* SILENT UNLESS IT HAS SOMETHING TO SAY. One line when the board says Done or
|
|
85
|
+
* Cancelled against a spec still in `backlog`/`in-progress`, naming the command
|
|
86
|
+
* that closes it — and nothing at all otherwise: agreement, a board that merely
|
|
87
|
+
* re-planned, an unlinked spec, no credential, an unreadable ticket. Every one of
|
|
88
|
+
* those is either healthy or cannot-tell, and a line about it would teach the
|
|
89
|
+
* reader to skip the one line that matters (`negative-checks.md`). `--json`
|
|
90
|
+
* always answers, so a caller can tell the cases apart. Always exits 0: this
|
|
91
|
+
* reports, and nothing refuses on it.
|
|
92
|
+
*
|
|
93
|
+
* @param {object} p
|
|
94
|
+
* - `snapshotDir` the resolved spec folder (its bucket is its parent folder)
|
|
95
|
+
* - `config` the provider config
|
|
96
|
+
* - `credential` `{ ok, adapter, error }` — the provider's API adapter, or why not
|
|
97
|
+
* - `flags`, `out`, `tracker` (the name in messages), `program`
|
|
98
|
+
*/
|
|
99
|
+
async function specSyncBoard({ snapshotDir, config, credential, flags = {}, out, tracker, program = 'spec-sync' }) {
|
|
100
|
+
const spec = path.basename(snapshotDir)
|
|
101
|
+
const bucket = path.basename(path.dirname(snapshotDir))
|
|
102
|
+
const overviewFile = (config.snapshot && config.snapshot.overviewFile) || '00-overview.md'
|
|
103
|
+
const ref = makeSpecHelpers({ program }).linkedIdentifier(path.join(snapshotDir, overviewFile), config)
|
|
104
|
+
const answer = (body, line) => {
|
|
105
|
+
if (flags.json) out.write(JSON.stringify({ spec, bucket, issue: ref || null, ...body }, null, 2) + '\n')
|
|
106
|
+
else if (line) out.write(`${program} board: ${line}\n`)
|
|
107
|
+
return 0
|
|
108
|
+
}
|
|
109
|
+
|
|
110
|
+
if (!ref) return answer({ reading: null, reason: 'not linked' })
|
|
111
|
+
if (!credential || !credential.ok) {
|
|
112
|
+
return answer({ reading: null, reason: (credential && credential.error ? String(credential.error) : 'no API transport').split('\n')[0] })
|
|
113
|
+
}
|
|
114
|
+
const reading = await readStatus({ adapter: credential.adapter, ref, config })
|
|
115
|
+
if (!reading.ok) return answer({ reading: null, reason: reading.reason })
|
|
116
|
+
|
|
117
|
+
const { ok, ...seen } = reading
|
|
118
|
+
const found = reading.bucket ? boardDisagreement(bucket, reading.bucket) : null
|
|
119
|
+
if (!found) return answer({ reading: seen, disagrees: false })
|
|
120
|
+
return answer(
|
|
121
|
+
{ reading: seen, disagrees: true, cleanup: found.cleanup },
|
|
122
|
+
`${ref} is ${reading.state} on ${tracker}, but ${spec} is ${bucket} here — ${found.cleanup} closes it`,
|
|
123
|
+
)
|
|
124
|
+
}
|
|
125
|
+
|
|
126
|
+
/**
|
|
127
|
+
* The doctor's one line on ownership: who holds status and assignee here. Always
|
|
128
|
+
* `ok` — both answers are valid configurations, and the line exists so a reader
|
|
129
|
+
* can see which one is in force without opening the config.
|
|
130
|
+
*/
|
|
131
|
+
function ownershipDoctorRow(config) {
|
|
132
|
+
const status = ownershipOf(config, 'workflowState')
|
|
133
|
+
const assignee = ownershipOf(config, 'assignee')
|
|
134
|
+
return doctorRow('ownership', 'Ownership', 'ok', `status ${status} · assignee ${assignee}`)
|
|
135
|
+
}
|
|
136
|
+
|
|
137
|
+
module.exports = { readStatus, specSyncOwnership, specSyncBoard, ownershipDoctorRow }
|
|
@@ -13,13 +13,14 @@
|
|
|
13
13
|
* stored matches what was sent — it merges nothing (see `src/verify.js`).
|
|
14
14
|
*/
|
|
15
15
|
|
|
16
|
-
const { ownsField, normalizeLocal, LIFECYCLE_BUCKETS, lintPhases, readSnapshot, parseFrontmatter, remoteWorkflowState, remoteStateReading, stateNamesFor, titleFromText, validateStates, stateSuggestions, effectiveStates, specHeaders, linkedIncident, phaseModeFor } = require('./src/normalize.js')
|
|
16
|
+
const { ownsField, ownershipOf, normalizeLocal, LIFECYCLE_BUCKETS, lintPhases, readSnapshot, parseFrontmatter, remoteWorkflowState, remoteStateReading, stateNamesFor, titleFromText, validateStates, stateSuggestions, effectiveStates, specHeaders, linkedIncident, phaseModeFor } = require('./src/normalize.js')
|
|
17
17
|
const { planChanges, snapshotOf, isEmptyPlan, hashField, stableStringify, remoteDescriptionEdited, remoteSubIssueEdited } = require('./src/compare.js')
|
|
18
18
|
const { readBase, writeBase } = require('./src/base.js')
|
|
19
19
|
const { push, recordPush, projectionOf } = require('./src/push.js')
|
|
20
20
|
const { writeFrontmatter, deleteFrontmatter, stampSubIssueId, stampIssueId, findPhaseFileByTitle, listPhaseFiles } = require('./src/write.js')
|
|
21
21
|
const { detectLegacyMirror } = require('./src/legacy.js')
|
|
22
22
|
const { compareStored, stream } = require('./src/verify.js')
|
|
23
|
+
const { descriptionMode, delimitersFor, blockOf, wrapBlock, spliceBlock, comparableDescription, progressOf, DELIMITERS } = require('./src/summary.js')
|
|
23
24
|
const { identityDialect, dialectOf } = require('./src/dialect.js')
|
|
24
25
|
const { fieldsOf } = require('./src/fields.js')
|
|
25
26
|
const { renderTaskBlock, findTaskBlocks, wrapEmphasisAware, collapseHyphenAware, inferWidth, fenceMask, DEFAULT_WIDTH } = require('./src/task-block.js')
|
|
@@ -27,6 +28,7 @@ const { planRetarget, applyRetarget, deriveRecordedKey, isEmptyRetarget, dirtyPa
|
|
|
27
28
|
|
|
28
29
|
module.exports = {
|
|
29
30
|
ownsField,
|
|
31
|
+
ownershipOf,
|
|
30
32
|
normalizeLocal,
|
|
31
33
|
// Exported for `spec-sync list`: an `inline`-mode spec has no phase sub-issues
|
|
32
34
|
// to read, so the listing must resolve the mode rather than assume `subissue`.
|
|
@@ -61,6 +63,17 @@ module.exports = {
|
|
|
61
63
|
listPhaseFiles,
|
|
62
64
|
detectLegacyMirror,
|
|
63
65
|
compareStored,
|
|
66
|
+
// The summary block: what a ticket carries under `mapping.description:
|
|
67
|
+
// "summary"`, and the splice that writes it beside the team's own text.
|
|
68
|
+
descriptionMode,
|
|
69
|
+
delimitersFor,
|
|
70
|
+
blockOf,
|
|
71
|
+
wrapBlock,
|
|
72
|
+
spliceBlock,
|
|
73
|
+
comparableDescription,
|
|
74
|
+
// How far along a spec is, from its own checkboxes (null: no checkboxes).
|
|
75
|
+
progressOf,
|
|
76
|
+
DELIMITERS,
|
|
64
77
|
// The tolerant reduction behind both `compareStored` and the snapshot's
|
|
65
78
|
// `descriptionStream` hash — exported so a provider can reduce a read-back the
|
|
66
79
|
// same way rather than writing a second one that disagrees.
|