@skitterbyte/skitterspec-jira 2.5.1 → 2.7.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/commands/epic.md +21 -0
- package/assets/rules/spec-planning.md +53 -7
- package/assets/skills/spec/SKILL.md +37 -6
- package/assets/skills/spec-complete/SKILL.md +29 -0
- package/assets/skills/spec-list/SKILL.md +4 -0
- package/assets/skills/spec-next/SKILL.md +35 -2
- package/assets/skills/spec-push/SKILL.md +9 -0
- package/assets/skills/spec-start/SKILL.md +60 -2
- package/assets/skills/spec-to-main/SKILL.md +10 -0
- package/package.json +1 -1
- package/src/cli.js +337 -5
- package/src/env/epic.js +555 -0
- package/src/env/epicpage.js +128 -0
- package/src/env/epicread.js +109 -0
- package/src/env/inflight.js +13 -3
- package/src/env/nextaction.js +262 -0
- package/src/env/resolve.js +18 -7
- package/src/env/serve.js +61 -4
- package/src/env/specstate.js +7 -2
- package/src/vendor/jira/api.js +21 -0
- package/src/vendor/jira/cli-sync.js +22 -6
- package/src/vendor/jira/config.js +1 -1
- package/src/vendor/provider-kit/src/apply.js +24 -0
- package/src/vendor/provider-kit/src/epic-rows.js +44 -0
- package/src/vendor/sync-core/index.js +3 -1
- package/src/vendor/sync-core/src/normalize.js +91 -9
|
@@ -0,0 +1,109 @@
|
|
|
1
|
+
'use strict'
|
|
2
|
+
|
|
3
|
+
/**
|
|
4
|
+
* The disk half of an epic's answer, shared by the CLI (`skitterspec epic
|
|
5
|
+
* status`) and the review server's epic page (spec feat-epic-next, Decision 5),
|
|
6
|
+
* so a page and a terminal opened side by side cannot read the same epic two
|
|
7
|
+
* ways.
|
|
8
|
+
*
|
|
9
|
+
* Waits are read off the BASE BRANCH by git, never off whatever the primary
|
|
10
|
+
* checkout has checked out; each member's progress and review state off its
|
|
11
|
+
* OWN worktree, where they are true (`env/epic.js`).
|
|
12
|
+
*/
|
|
13
|
+
|
|
14
|
+
const fs = require('node:fs')
|
|
15
|
+
const path = require('node:path')
|
|
16
|
+
|
|
17
|
+
const { isEpic } = require('./resolve.js')
|
|
18
|
+
const { epicStatus, epicHeaders, indexSpecTree } = require('./epic.js')
|
|
19
|
+
const { epicRows, readNextInputs } = require('./nextaction.js')
|
|
20
|
+
const { reviewOutPath } = require('./review.js')
|
|
21
|
+
|
|
22
|
+
/**
|
|
23
|
+
* The base branch's spec tree: `{ index, readFile, candidates }`, or null when
|
|
24
|
+
* the branch cannot be read — cannot-tell, never an empty plan.
|
|
25
|
+
*/
|
|
26
|
+
function epicTree(git, base) {
|
|
27
|
+
const listing = git(['ls-tree', '-r', '--name-only', base, '--', 'specs'])
|
|
28
|
+
if (listing === null) return null
|
|
29
|
+
// `git grep` exits 1 on no match, which the reader returns as null. The tree
|
|
30
|
+
// above was readable, so here null is "no spec names an epic".
|
|
31
|
+
const grep = git(['grep', '-l', '-E', '^>[[:space:]]*\\*\\*Epic:\\*\\*', base, '--', 'specs'])
|
|
32
|
+
const candidates = (grep || '')
|
|
33
|
+
.split('\n')
|
|
34
|
+
.filter(Boolean)
|
|
35
|
+
.map((l) => l.slice(base.length + 1))
|
|
36
|
+
return { index: indexSpecTree(listing), readFile: (p) => git(['show', `${base}:${p}`]), candidates }
|
|
37
|
+
}
|
|
38
|
+
|
|
39
|
+
// A provisioned spec's own overview and bucket, read in its worktree — the
|
|
40
|
+
// copy where an in-flight spec's bucket and headers are true. null when the
|
|
41
|
+
// worktree holds no readable copy.
|
|
42
|
+
function worktreeOverview(root, folder) {
|
|
43
|
+
for (const bucket of ['in-progress', 'backlog', 'complete', 'cancelled']) {
|
|
44
|
+
const dir = path.join(root, 'specs', bucket, folder)
|
|
45
|
+
let overview
|
|
46
|
+
try {
|
|
47
|
+
overview = fs.readFileSync(path.join(dir, '00-overview.md'), 'utf8')
|
|
48
|
+
} catch {
|
|
49
|
+
continue
|
|
50
|
+
}
|
|
51
|
+
const phases = fs
|
|
52
|
+
.readdirSync(dir)
|
|
53
|
+
.filter((f) => /^\d\d-.+\.md$/.test(f) && f !== '00-overview.md')
|
|
54
|
+
.map((f) => {
|
|
55
|
+
let text = null
|
|
56
|
+
try {
|
|
57
|
+
text = fs.readFileSync(path.join(dir, f), 'utf8')
|
|
58
|
+
} catch {
|
|
59
|
+
// unreadable: a phase with nothing to say
|
|
60
|
+
}
|
|
61
|
+
return { n: Number(f.slice(0, 2)), text }
|
|
62
|
+
})
|
|
63
|
+
return { folder, bucket, overview, phases, root }
|
|
64
|
+
}
|
|
65
|
+
return null
|
|
66
|
+
}
|
|
67
|
+
|
|
68
|
+
// Epics with a member, or themselves, in flight on this machine — what a bare
|
|
69
|
+
// `epic status` offers when it cannot tell which one was meant, and what the
|
|
70
|
+
// review server's index lists.
|
|
71
|
+
function epicsInFlight(worktrees) {
|
|
72
|
+
const open = worktrees.filter((w) => w.bucket !== 'complete' && w.bucket !== 'cancelled')
|
|
73
|
+
const names = open.map((w) => (isEpic(w.folder) ? w.folder : epicHeaders(w.overview).epic)).filter(Boolean)
|
|
74
|
+
return [...new Set(names)].sort()
|
|
75
|
+
}
|
|
76
|
+
|
|
77
|
+
/**
|
|
78
|
+
* The callbacks `epicRows` reads each member through: its own worktree, the
|
|
79
|
+
* review sidecars beside its page in the primary checkout, and a link to that
|
|
80
|
+
* page from `linkFor` — absolute for a terminal, relative for the served page.
|
|
81
|
+
*/
|
|
82
|
+
function memberReaders({ dir, config, worktrees, linkFor = () => null, git }) {
|
|
83
|
+
const own = new Map(worktrees.map((w) => [w.folder, w]))
|
|
84
|
+
return {
|
|
85
|
+
inputsFor: (spec) => {
|
|
86
|
+
const w = own.get(spec)
|
|
87
|
+
if (!w) return null
|
|
88
|
+
return readNextInputs({
|
|
89
|
+
folder: spec,
|
|
90
|
+
bucket: w.bucket,
|
|
91
|
+
worktree: w.root,
|
|
92
|
+
outPath: reviewOutPath(dir, spec),
|
|
93
|
+
required: config ? config.review.required : true,
|
|
94
|
+
git: git(w.root),
|
|
95
|
+
})
|
|
96
|
+
},
|
|
97
|
+
tabFor: (spec) => (own.has(spec) ? path.relative(path.dirname(dir), own.get(spec).root) : null),
|
|
98
|
+
linkFor,
|
|
99
|
+
}
|
|
100
|
+
}
|
|
101
|
+
|
|
102
|
+
/** The whole answer for one epic: `epicStatus` plus a row per member. */
|
|
103
|
+
function epicAnswer(epic, inputs, readers) {
|
|
104
|
+
const status = epicStatus({ epic, ...inputs })
|
|
105
|
+
const { rows, next } = epicRows(status, readers)
|
|
106
|
+
return { ...status, rows, next }
|
|
107
|
+
}
|
|
108
|
+
|
|
109
|
+
module.exports = { epicTree, worktreeOverview, epicsInFlight, memberReaders, epicAnswer }
|
package/src/env/inflight.js
CHANGED
|
@@ -18,6 +18,7 @@ const path = require('node:path')
|
|
|
18
18
|
|
|
19
19
|
const { readSpecState } = require('./specstate.js')
|
|
20
20
|
const { progressText } = require('./phases.js')
|
|
21
|
+
const { actionText } = require('./nextaction.js')
|
|
21
22
|
|
|
22
23
|
/**
|
|
23
24
|
* @param {object} a
|
|
@@ -81,9 +82,18 @@ function formatInFlight(rows, { dir }) {
|
|
|
81
82
|
const width = Math.max(...rows.map((r) => r.spec.length))
|
|
82
83
|
const live = rows.filter(isInFlight).length
|
|
83
84
|
const out = [live ? `${live} spec${live === 1 ? '' : 's'} in flight` : 'no specs in flight']
|
|
84
|
-
|
|
85
|
-
out.push(
|
|
86
|
-
out.push(
|
|
85
|
+
const row = (r, indent) => {
|
|
86
|
+
out.push(`${indent}${r.spec.padEnd(width)} ${detailOf(r)}`)
|
|
87
|
+
out.push(`${indent} ${path.relative(dir, r.worktree) || r.worktree}`)
|
|
88
|
+
if (r.next) out.push(`${indent} next: ${actionText(r.next)}`)
|
|
89
|
+
}
|
|
90
|
+
// Members are listed under their epic, read off each spec's own copy; a spec
|
|
91
|
+
// in no epic — the common case — prints exactly as it always has.
|
|
92
|
+
for (const r of rows.filter((x) => !x.epic)) row(r, ' ')
|
|
93
|
+
const epics = [...new Set(rows.map((r) => r.epic).filter(Boolean))].sort()
|
|
94
|
+
for (const epic of epics) {
|
|
95
|
+
out.push(` ${epic}`)
|
|
96
|
+
for (const r of rows.filter((x) => x.epic === epic)) row(r, ' ')
|
|
87
97
|
}
|
|
88
98
|
// SAID ONLY WHEN TRUE. On an idle repo, or one whose worktrees all agree with
|
|
89
99
|
// this checkout, the line would explain a discrepancy that is not there.
|
|
@@ -0,0 +1,262 @@
|
|
|
1
|
+
'use strict'
|
|
2
|
+
|
|
3
|
+
/**
|
|
4
|
+
* The one thing to do next for a spec, and where — the cell behind the `next`
|
|
5
|
+
* column of `skitterspec epic status` and `skitterspec status` (spec
|
|
6
|
+
* feat-epic-next, Decision 1).
|
|
7
|
+
*
|
|
8
|
+
* `nextAction` is pure: every input arrives already read, with `null` meaning
|
|
9
|
+
* the reader could not tell. `readNextInputs` is the half that touches disk —
|
|
10
|
+
* the gate, the pending store, the worktree's tree and its phase files — and
|
|
11
|
+
* its io is injectable so the command layer is testable without a worktree.
|
|
12
|
+
*
|
|
13
|
+
* Positive signals only (`.claude/rules/negative-checks.md`). A verb is a
|
|
14
|
+
* claim about the spec, so every input that is unreadable routes to
|
|
15
|
+
* `cannot-tell` and never to a verb: telling someone to `/spec-complete` a spec
|
|
16
|
+
* whose phase files could not be read is the accusation this exists to avoid.
|
|
17
|
+
*/
|
|
18
|
+
|
|
19
|
+
const fs = require('node:fs')
|
|
20
|
+
const path = require('node:path')
|
|
21
|
+
|
|
22
|
+
const { phaseIsDone } = require('./resolve.js')
|
|
23
|
+
const { readGate, readPending, gateState } = require('./review.js')
|
|
24
|
+
const { dirtyPaths } = require('./classify.js')
|
|
25
|
+
|
|
26
|
+
const plural = (n, word) => `${n} ${word}${n === 1 ? '' : 's'}`
|
|
27
|
+
|
|
28
|
+
const tell = (state, why) => ({ verb: 'cannot-tell', state, command: null, link: null, why })
|
|
29
|
+
|
|
30
|
+
function backlogAction(spec, { waits = [], freeLanes = null, clashWith = [] }) {
|
|
31
|
+
const unmet = waits.filter((w) => w.state === 'unmet')
|
|
32
|
+
if (unmet.length) {
|
|
33
|
+
return { verb: 'blocked', state: 'backlog', command: null, link: null, why: `waits on ${unmet.map((w) => w.raw).join(', ')}` }
|
|
34
|
+
}
|
|
35
|
+
const unknown = waits.filter((w) => w.state !== 'met')
|
|
36
|
+
if (unknown.length) return tell('backlog', `cannot tell whether ${unknown.map((w) => w.raw).join(', ')} has landed`)
|
|
37
|
+
// Both qualifiers advise and never withhold the command: `Lanes:` is a cap
|
|
38
|
+
// the operator chose and `Area:` is declared rather than measured, so the
|
|
39
|
+
// operator may know better (spec feat-epics, Decision 4).
|
|
40
|
+
const held = []
|
|
41
|
+
if (freeLanes === 0) held.push('no free lane')
|
|
42
|
+
if (clashWith.length) held.push(`clashes with ${clashWith.join(', ')}`)
|
|
43
|
+
return {
|
|
44
|
+
verb: 'start',
|
|
45
|
+
state: 'backlog · ready',
|
|
46
|
+
command: `/spec-start ${spec}`,
|
|
47
|
+
link: null,
|
|
48
|
+
why: held.length ? held.join(' · ') : null,
|
|
49
|
+
}
|
|
50
|
+
}
|
|
51
|
+
|
|
52
|
+
/**
|
|
53
|
+
* @param {object} a
|
|
54
|
+
* - `spec` the spec's folder name
|
|
55
|
+
* - `bucket` where its own copy sits, or null when it could not be read
|
|
56
|
+
* - `phases` `[{ n, done }]` from its own copy, or null when unreadable
|
|
57
|
+
* - `gate` `armed` · `clear` · `off` (the project opted out) ·
|
|
58
|
+
* `unreadable`
|
|
59
|
+
* - `passes` codes of the passes waiting unclaimed, or null when the
|
|
60
|
+
* pending store could not be read
|
|
61
|
+
* - `dirty` uncommitted paths in its worktree, or null when git could
|
|
62
|
+
* not answer
|
|
63
|
+
* - `syncWaits` `[{ phase, state, raw }]` — this spec's phase-level waits
|
|
64
|
+
* - `waits` its start waits, resolved — a backlog member's only
|
|
65
|
+
* - `freeLanes` the epic's free lanes, or null with no cap
|
|
66
|
+
* - `clashWith` in-flight members whose `Area:` meets this one's
|
|
67
|
+
* @returns {{ verb, state, command, link, why }}
|
|
68
|
+
*/
|
|
69
|
+
function nextAction(a) {
|
|
70
|
+
const { spec, bucket } = a
|
|
71
|
+
if (bucket === 'complete') return { verb: 'done', state: 'complete', command: null, link: null, why: null }
|
|
72
|
+
if (bucket === 'cancelled') return { verb: 'done', state: 'cancelled', command: null, link: null, why: null }
|
|
73
|
+
if (bucket === 'backlog') return backlogAction(spec, a)
|
|
74
|
+
if (bucket !== 'in-progress') return tell('unknown', `${spec}'s own copy could not be read`)
|
|
75
|
+
|
|
76
|
+
const phases = a.phases
|
|
77
|
+
if (phases === null || phases === undefined) return tell('in-progress', 'its phase files could not be read')
|
|
78
|
+
const done = phases.filter((p) => p.done).length
|
|
79
|
+
const progress = `phase ${Math.min(done + 1, phases.length)} of ${phases.length}`
|
|
80
|
+
|
|
81
|
+
// A pass first: someone already answered, and only a person in that tab can
|
|
82
|
+
// pick it up (`/spec-reviewed` is user-only by harness enforcement).
|
|
83
|
+
if (a.passes === null || a.passes === undefined) return tell(progress, 'the pending store is not readable')
|
|
84
|
+
if (a.passes.length === 1) {
|
|
85
|
+
return { verb: 'claim', state: `${progress} · pass waiting`, command: `/spec-reviewed ${a.passes[0]}`, link: null, why: null }
|
|
86
|
+
}
|
|
87
|
+
if (a.passes.length > 1) {
|
|
88
|
+
return {
|
|
89
|
+
verb: 'claim',
|
|
90
|
+
state: `${progress} · ${a.passes.length} passes waiting`,
|
|
91
|
+
command: '/spec-reviewed <code>',
|
|
92
|
+
link: null,
|
|
93
|
+
why: `name one: ${a.passes.join(', ')}`,
|
|
94
|
+
}
|
|
95
|
+
}
|
|
96
|
+
|
|
97
|
+
// `off` is a project that set `review.required: false` — silence, not a
|
|
98
|
+
// finding, so it falls through to the rest of the precedence.
|
|
99
|
+
if (a.gate === 'unreadable') return tell(progress, 'the review gate is not readable')
|
|
100
|
+
if (a.gate === 'armed') {
|
|
101
|
+
return { verb: 'verdict', state: `${progress} · page waits`, command: null, link: null, why: 'press a verdict on its page' }
|
|
102
|
+
}
|
|
103
|
+
|
|
104
|
+
// DIRTY WITH NO PHASE ENDED IS NOT "COMMIT". The engine cannot tell an agent
|
|
105
|
+
// mid-build from work left sitting, and `/commit` said to a tab that is
|
|
106
|
+
// building is the wrong advice — so it is a state with no verb (Decision 2).
|
|
107
|
+
if (a.dirty === null || a.dirty === undefined) return tell(progress, 'git could not read its worktree')
|
|
108
|
+
if (a.dirty > 0) {
|
|
109
|
+
return { verb: 'building', state: `${progress} · ${plural(a.dirty, 'file')} uncommitted`, command: null, link: null, why: 'building — nothing to run yet' }
|
|
110
|
+
}
|
|
111
|
+
|
|
112
|
+
// A spec with no phase files yet has nothing for `/spec-next` to build;
|
|
113
|
+
// naming the command would send the operator to a refusal.
|
|
114
|
+
if (!phases.length) return { verb: 'idle', state: 'no phase files', command: null, link: null, why: null }
|
|
115
|
+
if (done === phases.length) {
|
|
116
|
+
return { verb: 'complete', state: `${done} of ${phases.length} ✅ · clean`, command: '/spec-complete', link: null, why: null }
|
|
117
|
+
}
|
|
118
|
+
|
|
119
|
+
const next = phases.find((p) => !p.done).n
|
|
120
|
+
const held = (a.syncWaits || []).filter((w) => w.phase === next)
|
|
121
|
+
const unmet = held.filter((w) => w.state === 'unmet')
|
|
122
|
+
if (unmet.length) {
|
|
123
|
+
return { verb: 'held', state: progress, command: null, link: null, why: `phase ${next} waits on ${unmet.map((w) => w.raw).join(', ')}` }
|
|
124
|
+
}
|
|
125
|
+
const unknown = held.filter((w) => w.state !== 'met')
|
|
126
|
+
return {
|
|
127
|
+
verb: 'next',
|
|
128
|
+
state: progress,
|
|
129
|
+
command: '/spec-next',
|
|
130
|
+
link: null,
|
|
131
|
+
why: unknown.length ? `phase ${next} · cannot tell whether ${unknown.map((w) => w.raw).join(', ')} has landed` : `phase ${next}`,
|
|
132
|
+
}
|
|
133
|
+
}
|
|
134
|
+
|
|
135
|
+
/**
|
|
136
|
+
* The epic's own row: `/spec-complete <epic>` once no member is open, and
|
|
137
|
+
* nothing before — an epic completes after its members (feat-epics, Decision
|
|
138
|
+
* 7). An epic with no members has nothing to complete after, so it says
|
|
139
|
+
* nothing rather than inviting a completion of an empty plan.
|
|
140
|
+
*/
|
|
141
|
+
function epicNext(epic, members) {
|
|
142
|
+
if (!members.length) return null
|
|
143
|
+
if (members.some((m) => m.bucket !== 'complete' && m.bucket !== 'cancelled')) return null
|
|
144
|
+
return { verb: 'complete', state: 'every member finished', command: `/spec-complete ${epic}`, link: null, why: null }
|
|
145
|
+
}
|
|
146
|
+
|
|
147
|
+
const defaultIo = {
|
|
148
|
+
readdir: (dir) => fs.readdirSync(dir),
|
|
149
|
+
readFile: (file) => fs.readFileSync(file, 'utf8'),
|
|
150
|
+
}
|
|
151
|
+
|
|
152
|
+
function tryRead(fn) {
|
|
153
|
+
try {
|
|
154
|
+
return fn()
|
|
155
|
+
} catch {
|
|
156
|
+
return null
|
|
157
|
+
}
|
|
158
|
+
}
|
|
159
|
+
|
|
160
|
+
/**
|
|
161
|
+
* A spec's phases as its own copy has them, `[{ n, done }]`, or null when the
|
|
162
|
+
* folder could not be read. Read in the worktree because that is the copy that
|
|
163
|
+
* is true for a spec being built; the base branch still files it in backlog.
|
|
164
|
+
*/
|
|
165
|
+
function readPhases(root, bucket, folder, io = defaultIo) {
|
|
166
|
+
const dir = path.join(root, 'specs', bucket, folder)
|
|
167
|
+
const files = tryRead(() => io.readdir(dir))
|
|
168
|
+
if (!files) return null
|
|
169
|
+
const out = []
|
|
170
|
+
for (const f of files.filter((x) => /^(?!00-)\d{2}-.*\.md$/.test(x)).sort()) {
|
|
171
|
+
const text = tryRead(() => io.readFile(path.join(dir, f)))
|
|
172
|
+
// One unreadable phase makes the count a guess, and a guess here is what
|
|
173
|
+
// would print `/spec-complete` for a spec with a phase left to build.
|
|
174
|
+
if (text === null) return null
|
|
175
|
+
out.push({ n: Number(f.slice(0, 2)), done: phaseIsDone(text) })
|
|
176
|
+
}
|
|
177
|
+
return out
|
|
178
|
+
}
|
|
179
|
+
|
|
180
|
+
/**
|
|
181
|
+
* The disk half: everything `nextAction` needs about one in-flight spec that is
|
|
182
|
+
* not the epic's to say.
|
|
183
|
+
*
|
|
184
|
+
* @param {object} a
|
|
185
|
+
* - `folder` the spec
|
|
186
|
+
* - `bucket` its bucket in its own copy
|
|
187
|
+
* - `worktree` its worktree root
|
|
188
|
+
* - `outPath` its review page path in the primary checkout, where the gate
|
|
189
|
+
* and the pending store sit beside it
|
|
190
|
+
* - `required` `review.required` from the project config
|
|
191
|
+
* - `git` a reader for the worktree, `argv → stdout | null`
|
|
192
|
+
*/
|
|
193
|
+
function readNextInputs({ folder, bucket, worktree, outPath, required, git, io = defaultIo }) {
|
|
194
|
+
const gateRead = readGate(outPath, folder)
|
|
195
|
+
const g = gateState({ ...gateRead, required })
|
|
196
|
+
// `unknown` covers three readings and only one is a fault: the project
|
|
197
|
+
// opting out is silence, a corrupt or newer sidecar is cannot-tell.
|
|
198
|
+
const gate = g.state === 'armed' ? 'armed' : g.state === 'clear' ? 'clear' : required === false ? 'off' : 'unreadable'
|
|
199
|
+
const pending = readPending(outPath, folder)
|
|
200
|
+
const passes = pending.corrupt ? null : pending.pending.passes.filter((p) => p && p.code).map((p) => p.code)
|
|
201
|
+
const dirty = dirtyPaths(git)
|
|
202
|
+
return {
|
|
203
|
+
bucket,
|
|
204
|
+
phases: bucket ? readPhases(worktree, bucket, folder, io) : null,
|
|
205
|
+
gate,
|
|
206
|
+
passes,
|
|
207
|
+
dirty: dirty === null ? null : dirty.length,
|
|
208
|
+
}
|
|
209
|
+
}
|
|
210
|
+
|
|
211
|
+
/**
|
|
212
|
+
* The `next` cell as words — one string shared by every rendering, so the
|
|
213
|
+
* terminal, `status` and the page cannot word the same action differently.
|
|
214
|
+
*/
|
|
215
|
+
function actionText(a) {
|
|
216
|
+
if (!a) return '—'
|
|
217
|
+
if (a.verb === 'verdict') return a.link ? `verdict → ${a.link}` : 'verdict — /spec-diff in its tab'
|
|
218
|
+
if (a.verb === 'cannot-tell') return `cannot tell — ${a.why}`
|
|
219
|
+
if (a.command) return a.why ? `${a.command} — ${a.why}` : a.command
|
|
220
|
+
return a.why || '—'
|
|
221
|
+
}
|
|
222
|
+
|
|
223
|
+
/**
|
|
224
|
+
* One row per member, in `epicStatus` order: `{ spec, bucket, tab, next }`,
|
|
225
|
+
* plus the epic's own action. Pure — the disk arrives through three callbacks,
|
|
226
|
+
* each answering for one spec:
|
|
227
|
+
*
|
|
228
|
+
* - `inputsFor(spec)` → `readNextInputs`' answer, or null when the spec has
|
|
229
|
+
* no worktree on this machine
|
|
230
|
+
* - `tabFor(spec)` → where its tab stands, or null
|
|
231
|
+
* - `linkFor(spec)` → its served page, or null when nothing is serving
|
|
232
|
+
*
|
|
233
|
+
* An in-flight member with no worktree HERE is cannot-tell rather than
|
|
234
|
+
* guessed: it may be in flight on a colleague's machine, and its gate and its
|
|
235
|
+
* tree are there, not here.
|
|
236
|
+
*/
|
|
237
|
+
function epicRows(status, { inputsFor = () => null, tabFor = () => null, linkFor = () => null } = {}) {
|
|
238
|
+
const flying = new Set(status.inFlight.map((m) => m.spec))
|
|
239
|
+
const rows = status.members.map((m) => {
|
|
240
|
+
const clashWith = status.clashes
|
|
241
|
+
.filter((c) => c.specs.includes(m.spec))
|
|
242
|
+
.map((c) => c.specs.find((x) => x !== m.spec))
|
|
243
|
+
.filter((x) => flying.has(x))
|
|
244
|
+
const syncWaits = status.syncPoints
|
|
245
|
+
.filter((p) => p.spec === m.spec && p.phase !== null)
|
|
246
|
+
.map((p) => ({ phase: p.phase, state: p.wait.state, raw: p.wait.raw }))
|
|
247
|
+
let next
|
|
248
|
+
if (m.bucket === 'in-progress') {
|
|
249
|
+
const inputs = inputsFor(m.spec)
|
|
250
|
+
next = inputs
|
|
251
|
+
? nextAction({ spec: m.spec, ...inputs, bucket: 'in-progress', syncWaits })
|
|
252
|
+
: tell('in-progress', 'no worktree for it on this machine')
|
|
253
|
+
} else {
|
|
254
|
+
next = nextAction({ spec: m.spec, bucket: m.bucket, waits: m.waits, freeLanes: status.freeLanes, clashWith })
|
|
255
|
+
}
|
|
256
|
+
if (next.verb === 'verdict') next = { ...next, link: linkFor(m.spec) }
|
|
257
|
+
return { spec: m.spec, bucket: m.bucket, tab: m.bucket === 'in-progress' ? tabFor(m.spec) : null, next }
|
|
258
|
+
})
|
|
259
|
+
return { rows, next: epicNext(status.epic, status.members) }
|
|
260
|
+
}
|
|
261
|
+
|
|
262
|
+
module.exports = { nextAction, epicNext, epicRows, actionText, readNextInputs, readPhases }
|
package/src/env/resolve.js
CHANGED
|
@@ -4,7 +4,7 @@
|
|
|
4
4
|
* Pure spec/branch resolution for per-spec isolation.
|
|
5
5
|
*
|
|
6
6
|
* Given a spec argument (a folder name or path) it locates the spec folder under
|
|
7
|
-
* `specs/**`, splits the `feat-`/`bug-`/`hotfix-`/`chore-`/`issue-`/`incident-` prefix into
|
|
7
|
+
* `specs/**`, splits the `feat-`/`bug-`/`hotfix-`/`chore-`/`issue-`/`incident-`/`epic-` prefix into
|
|
8
8
|
* `{ type, slug }`, derives the
|
|
9
9
|
* git branch from the config's `branch.pattern` (provider-neutral; `{identifier}`
|
|
10
10
|
* is filled from a tracker id when one is configured, else it falls back to
|
|
@@ -77,8 +77,10 @@ function readPhases(specDir, { overviewFile = '00-overview.md' } = {}) {
|
|
|
77
77
|
.map((e) => e.name)
|
|
78
78
|
.sort()
|
|
79
79
|
// No phase files is not "no phases" — it is a legacy layout whose phases live
|
|
80
|
-
// inline in the overview, and this reader cannot see them.
|
|
81
|
-
|
|
80
|
+
// inline in the overview, and this reader cannot see them. The one exception
|
|
81
|
+
// is an epic, whose prefix says positively that it has none: there is no
|
|
82
|
+
// phase for `/spec-next` to build, and that is an answer, not a cannot-tell.
|
|
83
|
+
if (!files.length) return isEpic(specDir) ? { total: 0, done: 0, hasNextPhase: false, live: null } : null
|
|
82
84
|
|
|
83
85
|
let done = 0
|
|
84
86
|
for (const name of files) {
|
|
@@ -296,15 +298,23 @@ function phaseIsDone(text) {
|
|
|
296
298
|
return /^#\s.*✅\s*$/m.test(text)
|
|
297
299
|
}
|
|
298
300
|
|
|
299
|
-
// Split a `feat-`/`bug-`/`hotfix-`/`chore-`/`issue-`/`incident-`
|
|
300
|
-
// Unknown prefix → type defaults to `feat` and the whole folder name is
|
|
301
|
-
// slug.
|
|
301
|
+
// Split a `feat-`/`bug-`/`hotfix-`/`chore-`/`issue-`/`incident-`/`epic-`
|
|
302
|
+
// prefix. Unknown prefix → type defaults to `feat` and the whole folder name is
|
|
303
|
+
// the slug.
|
|
302
304
|
function splitPrefix(folder) {
|
|
303
|
-
const m = /^(feat|bug|hotfix|chore|issue|incident)-(.+)$/.exec(folder)
|
|
305
|
+
const m = /^(feat|bug|hotfix|chore|issue|incident|epic)-(.+)$/.exec(folder)
|
|
304
306
|
if (m) return { type: m[1], slug: m[2] }
|
|
305
307
|
return { type: 'feat', slug: folder }
|
|
306
308
|
}
|
|
307
309
|
|
|
310
|
+
// An epic is a spec of specs: a folder with an overview and no phase files of
|
|
311
|
+
// its own, its progress being its members'. Decided off the folder prefix — the
|
|
312
|
+
// positive signal every other kind uses — never off the absence of phase files,
|
|
313
|
+
// which is also what a legacy inline-phase spec looks like.
|
|
314
|
+
function isEpic(folder) {
|
|
315
|
+
return splitPrefix(path.basename(String(folder || ''))).type === 'epic'
|
|
316
|
+
}
|
|
317
|
+
|
|
308
318
|
// Repo identity used for token expansion.
|
|
309
319
|
function repoInfo(dir) {
|
|
310
320
|
const repo = path.basename(dir)
|
|
@@ -831,6 +841,7 @@ module.exports = {
|
|
|
831
841
|
assertPrimaryOnMain,
|
|
832
842
|
branchFor,
|
|
833
843
|
splitPrefix,
|
|
844
|
+
isEpic,
|
|
834
845
|
repoInfo,
|
|
835
846
|
expandTokens,
|
|
836
847
|
findSpecFolder,
|
package/src/env/serve.js
CHANGED
|
@@ -35,7 +35,10 @@ const {
|
|
|
35
35
|
allSpecs,
|
|
36
36
|
resolveSpec,
|
|
37
37
|
resolveBaseBranch,
|
|
38
|
+
isEpic,
|
|
38
39
|
} = require('./resolve.js')
|
|
40
|
+
const { epicTree, worktreeOverview, epicsInFlight, memberReaders, epicAnswer } = require('./epicread.js')
|
|
41
|
+
const { renderEpicPage } = require('./epicpage.js')
|
|
39
42
|
const { readRegistry } = require('./registry.js')
|
|
40
43
|
const { loadEnvConfig } = require('./config.js')
|
|
41
44
|
const { primaryAnchor, attachProject, repoRootOf, prefixOf, fromRepoPath, toRepoPath } = require('./project.js')
|
|
@@ -124,8 +127,16 @@ function escapeHtml(s) {
|
|
|
124
127
|
* palette on bare `:root`, redefined under `prefers-color-scheme`) so the two
|
|
125
128
|
* do not disagree when opened side by side.
|
|
126
129
|
*/
|
|
127
|
-
function renderIndex(entries, { token = null } = {}) {
|
|
130
|
+
function renderIndex(entries, { token = null, epics = [] } = {}) {
|
|
128
131
|
const prefix = token ? `/${token}` : ''
|
|
132
|
+
// Epics with a member in flight, each a doorway to its epic page. Listed
|
|
133
|
+
// above the diffs because an epic page is where a reader running several
|
|
134
|
+
// members starts; absent entirely on a repo with no epic in flight.
|
|
135
|
+
const epicList = epics.length
|
|
136
|
+
? `<h2>epics</h2>\n<ul>\n${epics
|
|
137
|
+
.map((e) => `<li><a href="${prefix}/${encodeURIComponent(e)}">${escapeHtml(e)}</a><span class="b">what to run next, per member</span></li>`)
|
|
138
|
+
.join('\n')}\n</ul>\n<h2>diffs</h2>`
|
|
139
|
+
: ''
|
|
129
140
|
const rows = entries
|
|
130
141
|
.map((e) => {
|
|
131
142
|
const t = e.totals || { files: 0, additions: 0, deletions: 0 }
|
|
@@ -161,6 +172,7 @@ body { margin:0; padding:2rem 1.25rem; background:var(--bg); color:var(--fg);
|
|
|
161
172
|
font:15px/1.5 ui-sans-serif,system-ui,-apple-system,Segoe UI,Roboto,sans-serif }
|
|
162
173
|
main { max-width:52rem; margin:0 auto }
|
|
163
174
|
h1 { font-size:1.1rem; margin:0 0 1.25rem; font-weight:600 }
|
|
175
|
+
h2 { font-size:.9rem; margin:1.25rem 0 .25rem; font-weight:600; color:var(--dim) }
|
|
164
176
|
ul { list-style:none; margin:0; padding:0 }
|
|
165
177
|
li { display:flex; flex-wrap:wrap; gap:.75rem; align-items:baseline;
|
|
166
178
|
padding:.7rem 0; border-top:1px solid var(--line) }
|
|
@@ -177,6 +189,7 @@ code { font-family:ui-monospace,SFMono-Regular,Menlo,monospace }
|
|
|
177
189
|
<body>
|
|
178
190
|
<main>
|
|
179
191
|
<h1>spec diffs</h1>
|
|
192
|
+
${epicList}
|
|
180
193
|
${body}
|
|
181
194
|
</main>
|
|
182
195
|
</body>
|
|
@@ -792,7 +805,7 @@ function readBody(req, limit = MAX_PASS_BYTES) {
|
|
|
792
805
|
})
|
|
793
806
|
}
|
|
794
807
|
|
|
795
|
-
function createReviewServer({ resolveEntries, render, receive = null, passState = null, token = null }) {
|
|
808
|
+
function createReviewServer({ resolveEntries, resolveEpics = () => [], render, receive = null, passState = null, token = null }) {
|
|
796
809
|
return http.createServer((req, res) => {
|
|
797
810
|
const send = (code, body, type = 'text/html; charset=utf-8') => {
|
|
798
811
|
res.writeHead(code, { 'content-type': type, 'cache-control': 'no-store' })
|
|
@@ -846,7 +859,7 @@ function createReviewServer({ resolveEntries, render, receive = null, passState
|
|
|
846
859
|
}
|
|
847
860
|
|
|
848
861
|
try {
|
|
849
|
-
if (route.kind === 'index') return send(200, renderIndex(resolveEntries(), { token }))
|
|
862
|
+
if (route.kind === 'index') return send(200, renderIndex(resolveEntries(), { token, epics: resolveEpics() }))
|
|
850
863
|
const out = render(route.spec, { branch: route.branch })
|
|
851
864
|
if (!out) return send(404, 'not found', 'text/plain; charset=utf-8')
|
|
852
865
|
if (out.error) return send(409, out.error, 'text/plain; charset=utf-8')
|
|
@@ -995,9 +1008,53 @@ function serverHooks(dir, config) {
|
|
|
995
1008
|
}
|
|
996
1009
|
})
|
|
997
1010
|
|
|
1011
|
+
// Every provisioned spec's own copy — what an epic's members are read off.
|
|
1012
|
+
const worktrees = () =>
|
|
1013
|
+
allSpecs(dir, config, liveWorktreePaths(trimmedGit), specless())
|
|
1014
|
+
.filter((s) => !s.specless && s.worktreePath && s.worktreePath !== dir && fs.existsSync(s.worktreePath))
|
|
1015
|
+
.map((s) => worktreeOverview(s.projectPath || s.worktreePath, s.folder))
|
|
1016
|
+
.filter(Boolean)
|
|
1017
|
+
|
|
1018
|
+
// The epic page, read per request like every other page. null — a 404 — when
|
|
1019
|
+
// no such epic exists and no spec names it; an unreadable base branch is a
|
|
1020
|
+
// 409 saying so, never an empty plan.
|
|
1021
|
+
const epicPage = (folder) => {
|
|
1022
|
+
let base
|
|
1023
|
+
try {
|
|
1024
|
+
base = resolveBaseBranch(config, trimmedGit)
|
|
1025
|
+
} catch (err) {
|
|
1026
|
+
return { error: `cannot tell — ${err.message}` }
|
|
1027
|
+
}
|
|
1028
|
+
const tree = epicTree(trimmedGit, base)
|
|
1029
|
+
if (!tree) return { error: `cannot tell — the base branch ${base} could not be read` }
|
|
1030
|
+
const inputs = { dir, config, base, ...tree, worktrees: worktrees() }
|
|
1031
|
+
const answer = epicAnswer(folder, inputs, memberReaders({ ...inputs, git: trimmedGitReader, linkFor: (s) => encodeURIComponent(s) }))
|
|
1032
|
+
if (!answer.found && !answer.members.length) return null
|
|
1033
|
+
return { html: renderEpicPage(answer) }
|
|
1034
|
+
}
|
|
1035
|
+
|
|
998
1036
|
return {
|
|
999
1037
|
resolveEntries,
|
|
1000
|
-
|
|
1038
|
+
resolveEpics: () => {
|
|
1039
|
+
try {
|
|
1040
|
+
return epicsInFlight(worktrees())
|
|
1041
|
+
} catch {
|
|
1042
|
+
// The index is a doorway; an unreadable worktree costs a link, never the page.
|
|
1043
|
+
return []
|
|
1044
|
+
}
|
|
1045
|
+
},
|
|
1046
|
+
render: (folder, opts) => {
|
|
1047
|
+
// AN EPIC BEING WRITTEN KEEPS ITS AUTHORING PAGE. `/spec` renders a new
|
|
1048
|
+
// epic's own documents at this same address, with verdict buttons, and
|
|
1049
|
+
// that page must still be the one a reader gets while the documents are
|
|
1050
|
+
// uncommitted. Every other epic address is the epic page.
|
|
1051
|
+
if (isEpic(folder)) {
|
|
1052
|
+
const one = resolveOne(folder)
|
|
1053
|
+
const view = one ? viewFor(dir, config, one, trimmedGit) : null
|
|
1054
|
+
if (!view || view.kind !== 'docs') return epicPage(folder)
|
|
1055
|
+
}
|
|
1056
|
+
return renderSpecPage(dir, config, resolveOne(folder), opts)
|
|
1057
|
+
},
|
|
1001
1058
|
receive: (folder, blob) => receivePass(dir, config, resolveOne(folder), blob),
|
|
1002
1059
|
// A spec this daemon cannot resolve is not a pass that was claimed — it is
|
|
1003
1060
|
// a lookup that could not see, so it says nothing rather than reporting the
|
package/src/env/specstate.js
CHANGED
|
@@ -24,6 +24,7 @@ const fs = require('node:fs')
|
|
|
24
24
|
const path = require('node:path')
|
|
25
25
|
|
|
26
26
|
const { phaseProgress } = require('./phases.js')
|
|
27
|
+
const { isEpic } = require('./resolve.js')
|
|
27
28
|
|
|
28
29
|
// Most live first: a spec that exists in two buckets mid-`git mv` is reported
|
|
29
30
|
// where it is going, not where it was.
|
|
@@ -64,7 +65,7 @@ function tryRead(io, fn) {
|
|
|
64
65
|
* @param {string} root the checkout to read — a spec's worktree, normally
|
|
65
66
|
* @param {string} folder the spec's folder name (`feat-x`)
|
|
66
67
|
* @param {object} [io] `{ readdir, readFile }`, each throwing on failure
|
|
67
|
-
* @returns {{ found: true, bucket, legacy, phasesDone, phasesTotal, currentPhase, status, developer }
|
|
68
|
+
* @returns {{ found: true, bucket, legacy, phasesDone, phasesTotal, currentPhase, status, developer, epic }
|
|
68
69
|
* | { found: false, reason }}
|
|
69
70
|
*/
|
|
70
71
|
function readSpecState(root, folder, io = defaultIo) {
|
|
@@ -76,7 +77,10 @@ function readSpecState(root, folder, io = defaultIo) {
|
|
|
76
77
|
if (overview === null) return { found: false, reason: `${bucket}/${folder} has no readable 00-overview.md` }
|
|
77
78
|
const phaseFiles = files.filter((f) => /^(?!00-)\d{2}-.*\.md$/.test(f)).sort()
|
|
78
79
|
const phases = phaseFiles.map((f) => ({ file: f, content: tryRead(io, () => io.readFile(path.join(dir, f))) }))
|
|
79
|
-
|
|
80
|
+
// An epic has no phases by construction (its prefix says so), so zero is
|
|
81
|
+
// an answer for it — where any other folder without phase files is a
|
|
82
|
+
// legacy overview to read inline.
|
|
83
|
+
const progress = phases.length || isEpic(folder) ? phaseProgress(phases) : inlineProgress(overview)
|
|
80
84
|
return state(bucket, false, overview, progress)
|
|
81
85
|
}
|
|
82
86
|
const bare = tryRead(io, () => io.readFile(path.join(root, 'specs', bucket, `${folder}.md`)))
|
|
@@ -95,6 +99,7 @@ function state(bucket, legacy, text, progress) {
|
|
|
95
99
|
currentPhase: progress ? progress.current : null,
|
|
96
100
|
status: header(text, 'Status'),
|
|
97
101
|
developer: header(text, 'Developer'),
|
|
102
|
+
epic: (header(text, 'Epic') || '').replace(/^`(.*)`$/, '$1') || null,
|
|
98
103
|
}
|
|
99
104
|
}
|
|
100
105
|
|
package/src/vendor/jira/api.js
CHANGED
|
@@ -215,6 +215,27 @@ function makeApiAdapter({ siteUrl, email, token, fetch: fetchImpl, sleep, maxRet
|
|
|
215
215
|
return { id: String(created.id), identifier: created.key, url: urlOf(created.key) }
|
|
216
216
|
},
|
|
217
217
|
|
|
218
|
+
/**
|
|
219
|
+
* Make `keyOrId` a child of the Epic `parentKey` — an epic member under its
|
|
220
|
+
* epic (spec feat-epics), through the `parent` field every Jira Cloud
|
|
221
|
+
* project now takes for an Epic. Idempotent: an issue already under it is
|
|
222
|
+
* left alone; one under another epic is moved. Read back, and refused when
|
|
223
|
+
* Jira holds anything else. BLIND SPOT: a site still on the legacy
|
|
224
|
+
* "Epic Link" field refuses the write, and the push reports that refusal
|
|
225
|
+
* rather than reaching for a custom field it cannot name.
|
|
226
|
+
*/
|
|
227
|
+
async setParent(keyOrId, parentKey) {
|
|
228
|
+
const issue = await this.readIssue(keyOrId)
|
|
229
|
+
if (!issue) throw new Error(`no Jira issue ${keyOrId} to put under ${parentKey}`)
|
|
230
|
+
if (issue.parent && issue.parent.identifier === parentKey) return { changed: false }
|
|
231
|
+
await request('PUT', `/issue/${encodeURIComponent(issue.identifier)}`, { body: { fields: { parent: { key: parentKey } } } })
|
|
232
|
+
const back = await this.readIssue(issue.identifier)
|
|
233
|
+
if (!back || !back.parent || back.parent.identifier !== parentKey) {
|
|
234
|
+
throw new Error(`${issue.identifier} was put under ${parentKey} but Jira reads it back under ${back && back.parent ? back.parent.identifier : 'no parent'}`)
|
|
235
|
+
}
|
|
236
|
+
return { changed: true, moved: !!issue.parent }
|
|
237
|
+
},
|
|
238
|
+
|
|
218
239
|
async updateIssue(keyOrId, updates) {
|
|
219
240
|
const fields = issueFields(updates)
|
|
220
241
|
if (!Object.keys(fields).length) return {}
|