@skitterbyte/skitterspec-jira 2.3.0 → 2.5.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/SETUP.md +5 -0
- package/assets/core/env.config.json.example +1 -0
- package/assets/core/env.config.md +143 -8
- package/assets/core/jira.config.md +4 -2
- package/assets/hooks/main-guard.cjs +40 -6
- package/assets/hooks/review-gate.cjs +42 -7
- 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 +1188 -79
- package/src/env/base.js +104 -0
- package/src/env/bootstrap.js +22 -3
- package/src/env/classify.js +12 -4
- package/src/env/config.js +77 -5
- package/src/env/disposition.js +62 -0
- package/src/env/handoff.js +81 -0
- package/src/env/host.js +262 -0
- package/src/env/hotfix.js +237 -9
- package/src/env/hotfixland.js +105 -10
- package/src/env/inflight.js +98 -0
- package/src/env/integrate.js +136 -9
- package/src/env/live.js +8 -7
- package/src/env/mainguard.js +20 -5
- package/src/env/phases.js +28 -0
- package/src/env/project.js +223 -0
- package/src/env/provision.js +30 -8
- package/src/env/resolve.js +147 -25
- package/src/env/review.js +21 -7
- package/src/env/reviewers.js +7 -10
- package/src/env/serve.js +27 -11
- package/src/env/specstate.js +101 -0
- package/src/env/supervise.js +15 -2
- package/src/env/teardown.js +46 -3
- package/src/init.js +49 -9
- package/src/vendor/jira/cli-sync.js +48 -4
- 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 +58 -6
- 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/credentials.js +7 -2
- package/src/vendor/provider-kit/src/list-rows.js +35 -11
- package/src/vendor/provider-kit/src/released.js +48 -4
- package/src/vendor/provider-kit/src/specs.js +18 -7
- 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 +81 -6
- package/src/vendor/sync-core/src/normalize.js +50 -7
- package/src/vendor/sync-core/src/push.js +65 -5
- package/src/vendor/sync-core/src/summary.js +257 -0
|
@@ -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.
|
|
@@ -24,6 +24,7 @@ const { createHash } = require('node:crypto')
|
|
|
24
24
|
// two reductions that disagree would be two different answers to one question.
|
|
25
25
|
// Dialect-parameterised: the provider's `config.dialect` names the transforms.
|
|
26
26
|
const { stream } = require('./verify.js')
|
|
27
|
+
const { comparableDescription } = require('./summary.js')
|
|
27
28
|
|
|
28
29
|
// Deterministic JSON: object keys sorted recursively; array order preserved.
|
|
29
30
|
// undefined normalises to null.
|
|
@@ -132,7 +133,10 @@ function remoteDescriptionEdited(snapshot, remote, config) {
|
|
|
132
133
|
if (!remote || typeof remote !== 'object') return null
|
|
133
134
|
// A provider whose remote shape differs supplies `config.remote.description`.
|
|
134
135
|
const hook = config && config.remote && config.remote.description
|
|
135
|
-
const
|
|
136
|
+
const raw = typeof hook === 'function' ? hook(remote) : 'description' in remote ? remote.description : undefined
|
|
137
|
+
// In summary mode only the block is the repo's: text around it is the team's
|
|
138
|
+
// and is never drift. A block that is missing or damaged is cannot-tell.
|
|
139
|
+
const text = comparableDescription(raw, config)
|
|
136
140
|
if (typeof text !== 'string') return null
|
|
137
141
|
|
|
138
142
|
return hashField(stream(text, config)) !== recorded
|
|
@@ -194,6 +198,49 @@ function snapshotOf(projection, config) {
|
|
|
194
198
|
}
|
|
195
199
|
}
|
|
196
200
|
|
|
201
|
+
/**
|
|
202
|
+
* The `stateNames` record for a snapshot: the tracker state name each item was
|
|
203
|
+
* last SENT, `{ issue, subIssues: { <id>: name } }`, or null when there is
|
|
204
|
+
* nothing to record (no provider hook, nothing ever sent).
|
|
205
|
+
*
|
|
206
|
+
* An item this push sent a state for (`sent`) records today's resolution. Any
|
|
207
|
+
* other item keeps the name the previous snapshot had for it, or gets none —
|
|
208
|
+
* the absence `planChanges` reads as cannot-tell. Writing today's name for an
|
|
209
|
+
* item that was not sent would record a claim about the tracker nobody made.
|
|
210
|
+
*
|
|
211
|
+
* @param {object} projection the projection, carrying `stateName`s
|
|
212
|
+
* @param {object|null} previous the snapshot being replaced
|
|
213
|
+
* @param {{ issue?: boolean, subIssues?: Set<string> }|null} sent
|
|
214
|
+
*/
|
|
215
|
+
function stateNamesRecord(projection, previous, sent) {
|
|
216
|
+
const p = projection || {}
|
|
217
|
+
const before = (previous && previous.stateNames) || {}
|
|
218
|
+
const beforeSubs = before.subIssues || {}
|
|
219
|
+
const sentSubs = (sent && sent.subIssues) || new Set()
|
|
220
|
+
const has = (obj, key) => Object.prototype.hasOwnProperty.call(obj, key)
|
|
221
|
+
const out = { subIssues: {} }
|
|
222
|
+
if (sent && sent.issue && p.stateName !== undefined) out.issue = p.stateName
|
|
223
|
+
else if (has(before, 'issue')) out.issue = before.issue
|
|
224
|
+
for (const s of p.subIssues || []) {
|
|
225
|
+
if (!s || s.id == null) continue
|
|
226
|
+
const id = String(s.id)
|
|
227
|
+
if (sentSubs.has(id) && s.stateName !== undefined) out.subIssues[id] = s.stateName
|
|
228
|
+
else if (has(beforeSubs, id)) out.subIssues[id] = beforeSubs[id]
|
|
229
|
+
}
|
|
230
|
+
if (!has(out, 'issue') && !Object.keys(out.subIssues).length) return null
|
|
231
|
+
return out
|
|
232
|
+
}
|
|
233
|
+
|
|
234
|
+
// Has the state an unchanged item maps to moved under it — a state-map edit in
|
|
235
|
+
// the config rather than a move of the spec? Only a RECORDED name can say: an
|
|
236
|
+
// item with none is cannot-tell and plans nothing, so an upgrade or a config
|
|
237
|
+
// change never turns into a workspace-wide resend. A bucket that now sends no
|
|
238
|
+
// state (`null`) has nothing to resend.
|
|
239
|
+
function remapped(recorded, current) {
|
|
240
|
+
if (recorded === undefined || current === undefined || current === null) return false
|
|
241
|
+
return recorded !== current
|
|
242
|
+
}
|
|
243
|
+
|
|
197
244
|
/**
|
|
198
245
|
* Diff the local projection against the last-pushed snapshot.
|
|
199
246
|
* @returns {{ issue?: object, subIssues: {create,update} }}
|
|
@@ -205,10 +252,13 @@ function snapshotOf(projection, config) {
|
|
|
205
252
|
* `plan.issue` (when present) is the spec issue's description + state; the push
|
|
206
253
|
* skill applies its provider's project/grouping choice on top of it.
|
|
207
254
|
*/
|
|
208
|
-
function planChanges(projection, snapshot) {
|
|
255
|
+
function planChanges(projection, snapshot, { linked = false } = {}) {
|
|
209
256
|
const p = projection || {}
|
|
210
257
|
const snap = snapshot || {}
|
|
211
258
|
const snapS = snap.subIssues || {}
|
|
259
|
+
const names = snap.stateNames || {}
|
|
260
|
+
const recordedSub = (id) =>
|
|
261
|
+
names.subIssues && Object.prototype.hasOwnProperty.call(names.subIssues, id) ? names.subIssues[id] : undefined
|
|
212
262
|
|
|
213
263
|
// Ids the last push minted that no phase claims any more. A phase file's stamp
|
|
214
264
|
// is the only link back to its sub-issue, and it lives in frontmatter — so a
|
|
@@ -235,13 +285,21 @@ function planChanges(projection, snapshot) {
|
|
|
235
285
|
subIssues.create.push({ ref: s.ref, name: s.name, goal: s.goal, state: s.state })
|
|
236
286
|
}
|
|
237
287
|
} else if (snapS[String(s.id)] !== subIssueHash(s)) {
|
|
238
|
-
|
|
288
|
+
const update = { ref: s.ref, id: s.id, name: s.name, goal: s.goal, state: s.state }
|
|
289
|
+
// No hash on record for an id the spec carries: the snapshot was lost or
|
|
290
|
+
// predates it, so this is a resend, not a move the spec made.
|
|
291
|
+
if (snapS[String(s.id)] === undefined) update.stateResend = 'unknown'
|
|
292
|
+
subIssues.update.push(update)
|
|
293
|
+
} else if (remapped(recordedSub(String(s.id)), s.stateName)) {
|
|
294
|
+
// STATE ONLY: the phase itself is unchanged, so its title and body stay
|
|
295
|
+
// as they are on the tracker.
|
|
296
|
+
subIssues.update.push({ ref: s.ref, id: s.id, state: s.state, stateResend: 'remap' })
|
|
239
297
|
}
|
|
240
298
|
}
|
|
241
299
|
|
|
242
300
|
const plan = { subIssues }
|
|
243
301
|
if (unstamped.length) plan.unstamped = unstamped
|
|
244
|
-
const issue = issueChanges(p, snap)
|
|
302
|
+
const issue = issueChanges(p, snap, { linked })
|
|
245
303
|
if (issue) plan.issue = issue
|
|
246
304
|
return plan
|
|
247
305
|
}
|
|
@@ -259,11 +317,22 @@ function planChanges(projection, snapshot) {
|
|
|
259
317
|
* that is the failure worth avoiding. The push rewrites the snapshot in the new
|
|
260
318
|
* shape, so a spec passes through `unknown` exactly once.
|
|
261
319
|
*/
|
|
262
|
-
function issueChanges(projection, snapshot) {
|
|
320
|
+
function issueChanges(projection, snapshot, { linked = false } = {}) {
|
|
263
321
|
const p = projection || {}
|
|
264
322
|
const snap = snapshot || {}
|
|
265
323
|
const both = () => {
|
|
266
|
-
const out = { description: p.description ?? null
|
|
324
|
+
const out = { description: p.description ?? null }
|
|
325
|
+
// UNDER `pull`, THE UNKNOWN PATH SENDS NO STATE. Without split hashes there
|
|
326
|
+
// is no positive signal that the spec moved, and the tracker owns the state
|
|
327
|
+
// — so the harmless reading of "cannot tell" flips: re-asserting would drag
|
|
328
|
+
// back a ticket someone moved on the board. Only a CREATE still sends it,
|
|
329
|
+
// because an issue with no state yet gets its first one from the repo.
|
|
330
|
+
// `linked` is what tells the two apart: an adopted issue has no snapshot
|
|
331
|
+
// either, and its board status is a person's, not ours.
|
|
332
|
+
if (!p.statePulled || !linked) out.state = p.status ?? null
|
|
333
|
+
// A linked issue with no split hashes is a resend: nothing says the spec
|
|
334
|
+
// moved, so the apply must not drag the issue out of a later state.
|
|
335
|
+
if (linked && out.state != null) out.stateResend = 'unknown'
|
|
267
336
|
// ASSERT, NEVER CLEAR, on this path. There are no split hashes here, so
|
|
268
337
|
// whether an assignee was ever pushed is unknown — and the harmless reading
|
|
269
338
|
// of "unknown" is to send one we have and stay silent about one we don't.
|
|
@@ -290,6 +359,11 @@ function issueChanges(projection, snapshot) {
|
|
|
290
359
|
const changed = {}
|
|
291
360
|
if (fields.description !== want.description) changed.description = p.description ?? null
|
|
292
361
|
if (fields.state !== want.state) changed.state = p.status ?? null
|
|
362
|
+
else if (!p.statePulled && remapped(snap.stateNames && snap.stateNames.issue, p.stateName)) {
|
|
363
|
+
// The tracker owns a pulled state, so a remap never re-asserts it there.
|
|
364
|
+
changed.state = p.status ?? null
|
|
365
|
+
changed.stateResend = 'remap'
|
|
366
|
+
}
|
|
293
367
|
|
|
294
368
|
// ASSIGNEE — AN ABSENT SNAPSHOT KEY MEANS "NEVER PUSHED", NOT "WAS NULL".
|
|
295
369
|
//
|
|
@@ -330,6 +404,7 @@ module.exports = {
|
|
|
330
404
|
issueChanges,
|
|
331
405
|
specIssueFieldHashes,
|
|
332
406
|
snapshotOf,
|
|
407
|
+
stateNamesRecord,
|
|
333
408
|
isEmptyPlan,
|
|
334
409
|
hashField,
|
|
335
410
|
stableStringify,
|
|
@@ -17,6 +17,7 @@
|
|
|
17
17
|
const fs = require('node:fs')
|
|
18
18
|
const path = require('node:path')
|
|
19
19
|
const { dialectOf } = require('./dialect.js')
|
|
20
|
+
const { descriptionMode, wrapBlock, specBlockInner, phaseBlockInner } = require('./summary.js')
|
|
20
21
|
const { fieldsOf } = require('./fields.js')
|
|
21
22
|
const { fenceMask, findTaskBlocks, collapse, collapseHyphenAware } = require('./task-block.js')
|
|
22
23
|
|
|
@@ -374,17 +375,46 @@ function ownsField(config, field) {
|
|
|
374
375
|
return !!owned && field in owned && owned[field] !== 'none'
|
|
375
376
|
}
|
|
376
377
|
|
|
378
|
+
/**
|
|
379
|
+
* WHO owns `field`: `push` (the repo), `pull` (the tracker), or `none` (it is
|
|
380
|
+
* not in play). `both` reads as `push` — it was accepted long before `pull`
|
|
381
|
+
* meant anything, and every config that wrote it meant the repo's behaviour.
|
|
382
|
+
*
|
|
383
|
+
* `pull` means the TRACKER is the record. The repo reads it live for display
|
|
384
|
+
* and sends it only as a transition it made itself (a spec changing bucket).
|
|
385
|
+
*
|
|
386
|
+
* WHAT WOULD MAKE `pull` LIE: reading the tracker's value and writing it into a
|
|
387
|
+
* spec file. Nothing that pulls ever writes a repo file — the moment one does,
|
|
388
|
+
* the repo holds a copy again, and the copy is the manual sync this exists to
|
|
389
|
+
* remove. `ownsField` stays "in play at all", so a pulled field still answers
|
|
390
|
+
* true there and no existing caller changes meaning.
|
|
391
|
+
*/
|
|
392
|
+
function ownershipOf(config, field) {
|
|
393
|
+
if (!ownsField(config, field)) return 'none'
|
|
394
|
+
return config.sync.fieldOwnership[field] === 'pull' ? 'pull' : 'push'
|
|
395
|
+
}
|
|
396
|
+
|
|
397
|
+
// The pulled fields the repo still has something to say about. A spec changing
|
|
398
|
+
// bucket is a transition the repo made, so `workflowState` stays projected (its
|
|
399
|
+
// hash is what tells a transition from a routine push). The assignee has no such
|
|
400
|
+
// moment — the board assigns people — so under `pull` the repo projects none.
|
|
401
|
+
const TRANSITION_FIELDS = ['workflowState']
|
|
402
|
+
|
|
377
403
|
// Reduce an `extracted` map to exactly the configured field keys, defaulting a
|
|
378
404
|
// missing field to `null` so local and remote always share an identical set.
|
|
379
405
|
//
|
|
380
406
|
// A declined field is OMITTED, not set null. The two are not interchangeable
|
|
381
407
|
// here: `null` is a value this projection asserts — it is how a finished spec
|
|
382
408
|
// hands its issue back — so writing it for a field the repo does not own would
|
|
383
|
-
// clear in Linear exactly what declining ownership promised not to touch.
|
|
409
|
+
// clear in Linear exactly what declining ownership promised not to touch. A
|
|
410
|
+
// pulled field with no transition is omitted for the same reason: the tracker
|
|
411
|
+
// owns it, so the repo asserts nothing about it, not even `null`.
|
|
384
412
|
function toFieldSet(extracted, config) {
|
|
385
413
|
const out = {}
|
|
386
414
|
for (const field of Object.keys(config.sync.fieldOwnership)) {
|
|
387
|
-
|
|
415
|
+
const owner = ownershipOf(config, field)
|
|
416
|
+
if (owner === 'none') continue
|
|
417
|
+
if (owner === 'pull' && !TRANSITION_FIELDS.includes(field)) continue
|
|
388
418
|
out[field] = field in extracted ? extracted[field] : null
|
|
389
419
|
}
|
|
390
420
|
return out
|
|
@@ -735,7 +765,9 @@ function phaseProjection(phases, workflowState, config) {
|
|
|
735
765
|
// They differ only in where an unlinked phase goes — nowhere yet, or into the
|
|
736
766
|
// spec issue's own description.
|
|
737
767
|
const deferring = mode === 'deferred' && UNSTARTED_BUCKETS.includes(workflowState)
|
|
738
|
-
|
|
768
|
+
// `none` holds every unlinked phase back for good — the ticket is one ticket.
|
|
769
|
+
// A phase already linked keeps projecting, for the same no-delete reason.
|
|
770
|
+
const projected = deferring || mode === 'inline' || mode === 'none' ? named.filter((p) => p.id != null) : named
|
|
739
771
|
const unlinked = named.filter((p) => p.id == null)
|
|
740
772
|
return {
|
|
741
773
|
projected,
|
|
@@ -751,8 +783,11 @@ function phaseProjection(phases, workflowState, config) {
|
|
|
751
783
|
|
|
752
784
|
function normalizeLocal(snapshotDir, config) {
|
|
753
785
|
const dialect = dialectOf(config)
|
|
754
|
-
const { frontmatter, title, sections, phases } = readSnapshot(snapshotDir, config)
|
|
786
|
+
const { frontmatter, title, sections, phases, body } = readSnapshot(snapshotDir, config)
|
|
755
787
|
const tasksMode = (config.mapping && config.mapping.tasks) || 'checklist'
|
|
788
|
+
// `summary` replaces both bodies with a delimited block (src/summary.js);
|
|
789
|
+
// `spec`, the default, is everything below exactly as it was.
|
|
790
|
+
const summaryMode = descriptionMode(config) === 'summary'
|
|
756
791
|
// Status is the spec's lifecycle bucket. The folder is the source of truth; an
|
|
757
792
|
// explicit `spec_status` frontmatter key overrides it if present. Resolved
|
|
758
793
|
// BEFORE the sub-issue projection because deferral withholds phases by this
|
|
@@ -777,8 +812,13 @@ function normalizeLocal(snapshotDir, config) {
|
|
|
777
812
|
const phasesCarriedBySubIssues =
|
|
778
813
|
syncsSubIssues && phaseModeFor(workflowState, config) !== 'inline' && withheld === 0
|
|
779
814
|
const extracted = {
|
|
780
|
-
description:
|
|
781
|
-
|
|
815
|
+
description: summaryMode
|
|
816
|
+
? wrapBlock(
|
|
817
|
+
dialect.flattenTables(dialect.canonicalize(specBlockInner({ snapshotDir, sections, body, phases }))) +
|
|
818
|
+
relatedIncidentLine(snapshotDir, config),
|
|
819
|
+
config,
|
|
820
|
+
)
|
|
821
|
+
: withInlinePhases(
|
|
782
822
|
buildDescription(
|
|
783
823
|
title,
|
|
784
824
|
sections,
|
|
@@ -805,7 +845,9 @@ function normalizeLocal(snapshotDir, config) {
|
|
|
805
845
|
id: p.id,
|
|
806
846
|
ref: p.phase,
|
|
807
847
|
name: p.name,
|
|
808
|
-
goal:
|
|
848
|
+
goal: summaryMode
|
|
849
|
+
? wrapBlock(dialect.flattenTables(phaseBlockInner(p)), config)
|
|
850
|
+
: subIssueBody(p, tasksMode, config.sync.localOnlySections, dialect),
|
|
809
851
|
state: phaseStateUnder(workflowState, p.state),
|
|
810
852
|
})),
|
|
811
853
|
workflowState,
|
|
@@ -1065,6 +1107,7 @@ function stateSuggestions(config, workspaceStates) {
|
|
|
1065
1107
|
|
|
1066
1108
|
module.exports = {
|
|
1067
1109
|
ownsField,
|
|
1110
|
+
ownershipOf,
|
|
1068
1111
|
stateSuggestions,
|
|
1069
1112
|
configuredStateNames,
|
|
1070
1113
|
effectiveStates,
|
|
@@ -15,8 +15,10 @@
|
|
|
15
15
|
* Date.now(). `recordPush` writes the snapshot sidecar.
|
|
16
16
|
*/
|
|
17
17
|
|
|
18
|
-
const { normalizeLocal, phasesWithheld, phaseModeFor } = require('./normalize.js')
|
|
19
|
-
const {
|
|
18
|
+
const { normalizeLocal, phasesWithheld, phaseModeFor, ownershipOf, readSnapshot } = require('./normalize.js')
|
|
19
|
+
const { descriptionMode } = require('./summary.js')
|
|
20
|
+
const { fieldsOf } = require('./fields.js')
|
|
21
|
+
const { planChanges, snapshotOf, stateNamesRecord, isEmptyPlan } = require('./compare.js')
|
|
20
22
|
const { readBase, writeBase } = require('./base.js')
|
|
21
23
|
const { detectLegacyMirror } = require('./legacy.js')
|
|
22
24
|
|
|
@@ -49,13 +51,58 @@ function projectionOf(snapshotDir, config) {
|
|
|
49
51
|
// push. `normalizeLocal` omits the key entirely when `sync.fieldOwnership`
|
|
50
52
|
// does not list it.
|
|
51
53
|
if ('assignee' in local) projection.assignee = local.assignee ?? null
|
|
54
|
+
// The tracker owns the state (`sync.fieldOwnership.workflowState: "pull"`), so
|
|
55
|
+
// a push sends it only as a transition — see `issueChanges`. Set only when
|
|
56
|
+
// pulled, and read by name, so it can never reach a hash.
|
|
57
|
+
if (ownershipOf(config, 'workflowState') === 'pull') projection.statePulled = true
|
|
58
|
+
attachStateNames(projection, snapshotDir, config)
|
|
52
59
|
return projection
|
|
53
60
|
}
|
|
54
61
|
|
|
62
|
+
// The tracker state NAME each bucket resolves to today, from the provider's
|
|
63
|
+
// `config.remote.writtenStateName(bucket, role, snapshotDir)` hook: a string,
|
|
64
|
+
// `null` for "this bucket sends no state", or `undefined` for cannot-tell — no
|
|
65
|
+
// hook, a hook that threw, or no bucket to resolve. Read by name, so it never
|
|
66
|
+
// reaches a hash: recorded beside them as `stateNames`, it is what lets a plan
|
|
67
|
+
// see a state-map change the bucket hashes are blind to.
|
|
68
|
+
function attachStateNames(projection, snapshotDir, config) {
|
|
69
|
+
const hook = config && config.remote && config.remote.writtenStateName
|
|
70
|
+
if (typeof hook !== 'function') return
|
|
71
|
+
const resolve = (bucket, role) => {
|
|
72
|
+
if (!bucket) return undefined
|
|
73
|
+
try {
|
|
74
|
+
const name = hook(bucket, role, snapshotDir)
|
|
75
|
+
return name === null || typeof name === 'string' ? name : undefined
|
|
76
|
+
} catch {
|
|
77
|
+
return undefined
|
|
78
|
+
}
|
|
79
|
+
}
|
|
80
|
+
const name = resolve(projection.status, 'issue')
|
|
81
|
+
if (name !== undefined) projection.stateName = name
|
|
82
|
+
projection.subIssues = projection.subIssues.map((s) => {
|
|
83
|
+
const sub = resolve(s && s.state, 'subIssue')
|
|
84
|
+
return sub === undefined ? s : { ...s, stateName: sub }
|
|
85
|
+
})
|
|
86
|
+
}
|
|
87
|
+
|
|
88
|
+
// Does the spec carry its issue stamp? NOT `identifier`: callers fall back to the
|
|
89
|
+
// folder name for an unlinked spec, so a truthy identifier proves nothing. The
|
|
90
|
+
// stamp is the positive signal — it tells a create (no issue yet, so the spec's
|
|
91
|
+
// first state IS a transition) from a linked spec whose snapshot cannot say what
|
|
92
|
+
// was last sent.
|
|
93
|
+
function isLinked(snapshotDir, config) {
|
|
94
|
+
try {
|
|
95
|
+
const { frontmatter } = readSnapshot(snapshotDir, config)
|
|
96
|
+
return !!(frontmatter && frontmatter[fieldsOf(config).identifier])
|
|
97
|
+
} catch {
|
|
98
|
+
return false
|
|
99
|
+
}
|
|
100
|
+
}
|
|
101
|
+
|
|
55
102
|
function push({ dir, snapshotDir, identifier, config }) {
|
|
56
103
|
const projection = projectionOf(snapshotDir, config)
|
|
57
104
|
const snapshot = readBase(dir, identifier, config)
|
|
58
|
-
const plan = planChanges(projection, snapshot)
|
|
105
|
+
const plan = planChanges(projection, snapshot, { linked: isLinked(snapshotDir, config) })
|
|
59
106
|
// A spec still linked under the pre-9.0 model reads as unlinked here, so the
|
|
60
107
|
// plan above is all-creates and would abandon a live mirror. Carry the finding
|
|
61
108
|
// ON THE PLAN, not as a warning: `--json` routes warnings to stderr, and the
|
|
@@ -70,6 +117,10 @@ function push({ dir, snapshotDir, identifier, config }) {
|
|
|
70
117
|
// know that an absent field means `subissue`. `isEmptyPlan` and `snapshotOf`
|
|
71
118
|
// both read named fields, so an extra key cannot make a spec look edited.
|
|
72
119
|
plan.phaseMode = projection.phaseMode
|
|
120
|
+
// Always set too: under `summary` the planned bodies are BLOCKS, and an
|
|
121
|
+
// apply that writes one over the whole description deletes the team's text.
|
|
122
|
+
// The MCP path reads this to know it must splice (`spec-sync splice`).
|
|
123
|
+
plan.descriptionMode = descriptionMode(config)
|
|
73
124
|
return { ok: true, empty: isEmptyPlan(plan), plan, projection }
|
|
74
125
|
}
|
|
75
126
|
|
|
@@ -77,9 +128,18 @@ function push({ dir, snapshotDir, identifier, config }) {
|
|
|
77
128
|
* Record the last-pushed snapshot from the CURRENT files — call after the skill
|
|
78
129
|
* has applied the plan and stamped new ids. Returns the snapshot path.
|
|
79
130
|
*/
|
|
80
|
-
|
|
131
|
+
// `sent` says which items this push carried a state for — `{ issue, subIssues }`,
|
|
132
|
+
// the latter a set of ids. Only those get today's name recorded; anything else
|
|
133
|
+
// keeps the name it already had, or none. Recording today's name for an item
|
|
134
|
+
// that was NOT sent would claim the tracker holds it, and silence the very remap
|
|
135
|
+
// this record exists to catch. Without `sent` (a hand-applied MCP push) nothing
|
|
136
|
+
// new is recorded and what was there is kept.
|
|
137
|
+
function recordPush({ dir, snapshotDir, identifier, config, sent = null }) {
|
|
81
138
|
const projection = projectionOf(snapshotDir, config)
|
|
82
|
-
|
|
139
|
+
const snapshot = snapshotOf(projection, config)
|
|
140
|
+
const names = stateNamesRecord(projection, readBase(dir, identifier, config), sent)
|
|
141
|
+
if (names) snapshot.stateNames = names
|
|
142
|
+
return writeBase(dir, identifier, config, snapshot)
|
|
83
143
|
}
|
|
84
144
|
|
|
85
145
|
module.exports = { push, recordPush, projectionOf }
|