@skitterbyte/skitterspec-jira 2.7.0 → 2.9.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 +6 -0
- package/assets/core/env.config.json.example +5 -0
- package/assets/core/env.config.md +26 -5
- package/assets/review/page.html +9 -0
- package/assets/rules/spec-planning.md +65 -12
- package/assets/rules/spec-reports.md +8 -1
- package/assets/skills/spec/SKILL.md +31 -14
- package/assets/skills/spec-cancel/SKILL.md +7 -0
- package/assets/skills/spec-complete/SKILL.md +6 -0
- package/assets/skills/spec-epic-next/SKILL.md +83 -0
- package/assets/skills/spec-init/SKILL.md +35 -3
- package/assets/skills/spec-next/SKILL.md +38 -1
- package/assets/skills/spec-start/SKILL.md +2 -2
- package/assets/skills/spec-tada/SKILL.md +153 -0
- package/bin/skitterspec-jira.js +5 -0
- package/package.json +1 -1
- package/src/cli.js +473 -25
- package/src/env/config.js +57 -6
- package/src/env/epic.js +69 -19
- package/src/env/epicpage.js +87 -39
- package/src/env/epicread.js +41 -3
- package/src/env/integrate.js +48 -1
- package/src/env/nextaction.js +78 -1
- package/src/env/project.js +54 -3
- package/src/env/projectedit.js +148 -0
- package/src/env/resolve.js +1 -0
- package/src/env/review.js +21 -3
- package/src/env/serve.js +44 -8
- package/src/env/specbranches.js +120 -0
- package/src/env/teardown.js +18 -3
- package/src/gating.js +16 -4
- package/src/init.js +11 -3
- package/src/tada/commits.js +145 -0
- package/src/tada/digest.js +260 -0
- package/src/tada/format.js +37 -0
- package/src/tada/page.js +213 -0
- package/src/tada/repo.js +102 -0
- package/src/tada/serve.js +127 -0
- package/src/tada/specs.js +146 -0
- package/src/tada/transcripts.js +258 -0
- package/src/tada/window.js +156 -0
- package/src/vendor/provider-kit/src/apply.js +25 -1
- package/src/vendor/sync-core/src/compare.js +10 -2
- package/src/vendor/sync-core/src/push.js +14 -3
- /package/assets/commands/{epic.md → spec-epic.md} +0 -0
package/src/env/nextaction.js
CHANGED
|
@@ -259,4 +259,81 @@ function epicRows(status, { inputsFor = () => null, tabFor = () => null, linkFor
|
|
|
259
259
|
return { rows, next: epicNext(status.epic, status.members) }
|
|
260
260
|
}
|
|
261
261
|
|
|
262
|
-
|
|
262
|
+
// In-flight actions before starts, and among those the one a person is
|
|
263
|
+
// already holding first: a pass, then a page, then a finish, then a build.
|
|
264
|
+
const TAB_ORDER = ['claim', 'verdict', 'complete', 'next']
|
|
265
|
+
|
|
266
|
+
/**
|
|
267
|
+
* What the epic view is laid out from (spec feat-spec-epic-commands,
|
|
268
|
+
* Decisions 9–10): how far along it is, every member in exactly one group, and
|
|
269
|
+
* the numbered next steps. Computed once here so the page, the terminal and
|
|
270
|
+
* `/spec-epic-next` cannot give three answers.
|
|
271
|
+
*
|
|
272
|
+
* GROUPS ARE BY POSITIVE SIGNAL. `ready` is a member the engine said may start
|
|
273
|
+
* (`verb: start`); everything else in the backlog — blocked, or a wait that
|
|
274
|
+
* cannot be read — is `waiting`, never `ready`
|
|
275
|
+
* (`.claude/rules/negative-checks.md`). A row whose bucket could not be read is
|
|
276
|
+
* waiting too.
|
|
277
|
+
*
|
|
278
|
+
* A STEP IS SOMETHING TO TYPE. A member that is building, held or cannot-tell
|
|
279
|
+
* gets no step: naming one would be advice the engine cannot back.
|
|
280
|
+
*/
|
|
281
|
+
function epicPlan(status, { rows = [], next = null } = {}) {
|
|
282
|
+
const groups = { inFlight: [], ready: [], waiting: [], done: [] }
|
|
283
|
+
for (const r of rows) {
|
|
284
|
+
if (r.bucket === 'complete' || r.bucket === 'cancelled') groups.done.push(r.spec)
|
|
285
|
+
else if (r.bucket === 'in-progress') groups.inFlight.push(r.spec)
|
|
286
|
+
else if (r.bucket === 'backlog' && r.next.verb === 'start') groups.ready.push(r.spec)
|
|
287
|
+
else groups.waiting.push(r.spec)
|
|
288
|
+
}
|
|
289
|
+
const progress = { done: groups.done.length, total: rows.length, inFlight: groups.inFlight.length }
|
|
290
|
+
|
|
291
|
+
// Everyone not yet finished who waits on `raw` — the whole spec, or one of
|
|
292
|
+
// its phases.
|
|
293
|
+
const open = new Set([...groups.ready, ...groups.waiting])
|
|
294
|
+
const waitersOn = (raw) =>
|
|
295
|
+
(status.members || []).filter((m) => open.has(m.spec) && (m.waits || []).some((w) => w.raw === raw && w.state !== 'met')).map((m) => m.spec)
|
|
296
|
+
|
|
297
|
+
if (next) return { progress, groups, steps: [{ where: 'epic', spec: status.epic, verb: next.verb, command: next.command, link: null, unblocks: [], caution: null }] }
|
|
298
|
+
|
|
299
|
+
const steps = []
|
|
300
|
+
const tabRows = rows
|
|
301
|
+
.filter((r) => r.bucket === 'in-progress' && TAB_ORDER.includes(r.next.verb))
|
|
302
|
+
.sort((a, b) => TAB_ORDER.indexOf(a.next.verb) - TAB_ORDER.indexOf(b.next.verb))
|
|
303
|
+
const stepOf = new Map()
|
|
304
|
+
for (const r of tabRows) {
|
|
305
|
+
let unblocks = []
|
|
306
|
+
if (r.next.verb === 'complete') unblocks = waitersOn(r.spec)
|
|
307
|
+
if (r.next.verb === 'next') {
|
|
308
|
+
const m = /^phase (\d+)/.exec(r.next.why || '')
|
|
309
|
+
if (m) unblocks = waitersOn(`${r.spec} phase ${m[1]}`)
|
|
310
|
+
}
|
|
311
|
+
steps.push({ where: 'tab', spec: r.spec, tab: r.tab, verb: r.next.verb, command: r.next.command, link: r.next.link, unblocks, caution: null })
|
|
312
|
+
stepOf.set(r.spec, steps.length)
|
|
313
|
+
}
|
|
314
|
+
|
|
315
|
+
const flying = new Set(groups.inFlight)
|
|
316
|
+
const clashesOf = (spec) =>
|
|
317
|
+
(status.clashes || [])
|
|
318
|
+
.filter((c) => c.specs.includes(spec))
|
|
319
|
+
.map((c) => c.specs.find((x) => x !== spec))
|
|
320
|
+
.filter((x) => flying.has(x))
|
|
321
|
+
// A start that clashes with nothing in flight first: with one lane, the
|
|
322
|
+
// safer start is the one to take.
|
|
323
|
+
const starts = rows
|
|
324
|
+
.filter((r) => groups.ready.includes(r.spec))
|
|
325
|
+
.map((r) => ({ r, clash: clashesOf(r.spec) }))
|
|
326
|
+
.sort((a, b) => Number(a.clash.length > 0) - Number(b.clash.length > 0))
|
|
327
|
+
const cap = status.freeLanes === null || status.freeLanes === undefined ? starts.length : status.freeLanes
|
|
328
|
+
for (const { r, clash } of starts.slice(0, cap)) {
|
|
329
|
+
let caution = null
|
|
330
|
+
if (clash.length) {
|
|
331
|
+
const after = clash.map((x) => stepOf.get(x)).filter(Boolean)
|
|
332
|
+
caution = `clashes with ${clash.join(', ')}${after.length ? `; safer after step ${after.join(', ')}` : ''}`
|
|
333
|
+
}
|
|
334
|
+
steps.push({ where: 'new-tab', spec: r.spec, tab: null, verb: 'start', command: r.next.command, link: null, unblocks: [], caution })
|
|
335
|
+
}
|
|
336
|
+
return { progress, groups, steps }
|
|
337
|
+
}
|
|
338
|
+
|
|
339
|
+
module.exports = { nextAction, epicNext, epicRows, epicPlan, actionText, readNextInputs, readPhases }
|
package/src/env/project.js
CHANGED
|
@@ -154,7 +154,9 @@ function toRepoPath(rel, prefix) {
|
|
|
154
154
|
* config.
|
|
155
155
|
*/
|
|
156
156
|
function attachProject(config, anchor) {
|
|
157
|
-
|
|
157
|
+
// `checkout`, not `project`: `project` is the config's own key (name,
|
|
158
|
+
// category), and the anchor is where this checkout sits on disk.
|
|
159
|
+
Object.defineProperty(config, 'checkout', {
|
|
158
160
|
value: Object.freeze({ root: anchor.root, prefix: anchor.prefix }),
|
|
159
161
|
enumerable: false,
|
|
160
162
|
configurable: true,
|
|
@@ -162,6 +164,52 @@ function attachProject(config, anchor) {
|
|
|
162
164
|
return config
|
|
163
165
|
}
|
|
164
166
|
|
|
167
|
+
/**
|
|
168
|
+
* The name a generated page calls this project by: `project.name` when set,
|
|
169
|
+
* else the superseded `review.projectName`, else the project folder's name in
|
|
170
|
+
* the PRIMARY checkout.
|
|
171
|
+
*
|
|
172
|
+
* NEVER THE CWD'S NAME. A worktree's folder is named after its spec, so a page
|
|
173
|
+
* rendered from one would repeat the spec name where the project's belongs —
|
|
174
|
+
* which is why this reads the anchor `attachProject` recorded. `null` when there
|
|
175
|
+
* is none: cannot tell, and the pages then render exactly as they did before.
|
|
176
|
+
*/
|
|
177
|
+
function projectName(config) {
|
|
178
|
+
for (const set of [config && config.project && config.project.name, config && config.review && config.review.projectName]) {
|
|
179
|
+
if (typeof set === 'string' && set.trim()) return set.trim()
|
|
180
|
+
}
|
|
181
|
+
const at = config && config.checkout
|
|
182
|
+
if (!at || !at.root) return null
|
|
183
|
+
return path.basename(projectIn(at.root, at.prefix || '')) || null
|
|
184
|
+
}
|
|
185
|
+
|
|
186
|
+
/**
|
|
187
|
+
* The name and category with where each came from — what `skitterspec project`
|
|
188
|
+
* shows, so a reader can tell a name they set from one inherited from the
|
|
189
|
+
* folder. `source` is `project.name` · `review.projectName` · `folder` ·
|
|
190
|
+
* `unset` for the name, `project.category` · `unset` for the category.
|
|
191
|
+
*/
|
|
192
|
+
function describeProject(config) {
|
|
193
|
+
const set = (v) => typeof v === 'string' && v.trim()
|
|
194
|
+
const p = (config && config.project) || {}
|
|
195
|
+
const r = (config && config.review) || {}
|
|
196
|
+
let name = { value: null, source: 'unset' }
|
|
197
|
+
if (set(p.name)) name = { value: p.name.trim(), source: 'project.name' }
|
|
198
|
+
else if (set(r.projectName)) name = { value: r.projectName.trim(), source: 'review.projectName' }
|
|
199
|
+
else {
|
|
200
|
+
const folder = projectName({ checkout: config && config.checkout })
|
|
201
|
+
if (folder) name = { value: folder, source: 'folder' }
|
|
202
|
+
}
|
|
203
|
+
const category = set(p.category) ? { value: p.category.trim(), source: 'project.category' } : { value: null, source: 'unset' }
|
|
204
|
+
return { name, category }
|
|
205
|
+
}
|
|
206
|
+
|
|
207
|
+
/** The project's category, trimmed — or null when none is set. */
|
|
208
|
+
function projectCategory(config) {
|
|
209
|
+
const c = config && config.project && config.project.category
|
|
210
|
+
return typeof c === 'string' && c.trim() ? c.trim() : null
|
|
211
|
+
}
|
|
212
|
+
|
|
165
213
|
/**
|
|
166
214
|
* A path as one shell word, for the commands the engine PRINTS for a person or
|
|
167
215
|
* a skill to run. Quoted only when it has to be, so a path without spaces or
|
|
@@ -189,12 +237,12 @@ function shellPath(p, platform = process.platform) {
|
|
|
189
237
|
|
|
190
238
|
/** The repo root a config was loaded for, else `dir` — today's behaviour. */
|
|
191
239
|
function repoRootOf(dir, config) {
|
|
192
|
-
return (config && config.
|
|
240
|
+
return (config && config.checkout && config.checkout.root) || dir
|
|
193
241
|
}
|
|
194
242
|
|
|
195
243
|
/** The project prefix a config was loaded for, else `''`. */
|
|
196
244
|
function prefixOf(config) {
|
|
197
|
-
return (config && config.
|
|
245
|
+
return (config && config.checkout && config.checkout.prefix) || ''
|
|
198
246
|
}
|
|
199
247
|
|
|
200
248
|
/**
|
|
@@ -217,6 +265,9 @@ module.exports = {
|
|
|
217
265
|
toPosix,
|
|
218
266
|
shellPath,
|
|
219
267
|
attachProject,
|
|
268
|
+
projectName,
|
|
269
|
+
projectCategory,
|
|
270
|
+
describeProject,
|
|
220
271
|
repoRootOf,
|
|
221
272
|
prefixOf,
|
|
222
273
|
projectLine,
|
|
@@ -0,0 +1,148 @@
|
|
|
1
|
+
'use strict'
|
|
2
|
+
|
|
3
|
+
/**
|
|
4
|
+
* Setting `project.name` / `project.category` in `env.config.json` by EDITING
|
|
5
|
+
* its text, never by regenerating it. PURE — text in, text out.
|
|
6
|
+
*
|
|
7
|
+
* WHY NOT `JSON.stringify(parsed, null, 2)`: a person wrote this file, and the
|
|
8
|
+
* way they wrote it — an array on one line, a blank line between blocks — is
|
|
9
|
+
* theirs. A regenerated file would turn a two-key change into a diff of the
|
|
10
|
+
* whole thing, and the reviewer of that commit would have to read all of it to
|
|
11
|
+
* find the two lines that mattered. So the value spans are found and replaced,
|
|
12
|
+
* and everything else is left byte for byte.
|
|
13
|
+
*
|
|
14
|
+
* And it checks itself: the edited text must parse to exactly the object the
|
|
15
|
+
* change describes. If it does not — a shape this scanner did not anticipate —
|
|
16
|
+
* it throws rather than writing something it cannot vouch for.
|
|
17
|
+
*/
|
|
18
|
+
|
|
19
|
+
const KEYS = ['name', 'category']
|
|
20
|
+
|
|
21
|
+
// The end of the JSON value starting at `i` (exclusive), skipping strings so a
|
|
22
|
+
// brace inside one is not counted.
|
|
23
|
+
function valueEnd(text, i) {
|
|
24
|
+
const open = text[i]
|
|
25
|
+
if (open === '"') {
|
|
26
|
+
for (let j = i + 1; j < text.length; j++) {
|
|
27
|
+
if (text[j] === '\\') j++
|
|
28
|
+
else if (text[j] === '"') return j + 1
|
|
29
|
+
}
|
|
30
|
+
throw new Error('unterminated string')
|
|
31
|
+
}
|
|
32
|
+
if (open === '{' || open === '[') {
|
|
33
|
+
let depth = 0
|
|
34
|
+
for (let j = i; j < text.length; j++) {
|
|
35
|
+
const c = text[j]
|
|
36
|
+
if (c === '"') j = valueEnd(text, j) - 1
|
|
37
|
+
else if (c === '{' || c === '[') depth++
|
|
38
|
+
else if (c === '}' || c === ']') {
|
|
39
|
+
depth--
|
|
40
|
+
if (depth === 0) return j + 1
|
|
41
|
+
}
|
|
42
|
+
}
|
|
43
|
+
throw new Error('unbalanced brackets')
|
|
44
|
+
}
|
|
45
|
+
const m = /^[^,}\]\s]+/.exec(text.slice(i))
|
|
46
|
+
if (!m) throw new Error(`no value at ${i}`)
|
|
47
|
+
return i + m[0].length
|
|
48
|
+
}
|
|
49
|
+
|
|
50
|
+
const skipSpace = (text, i) => {
|
|
51
|
+
while (i < text.length && /\s/.test(text[i])) i++
|
|
52
|
+
return i
|
|
53
|
+
}
|
|
54
|
+
|
|
55
|
+
/**
|
|
56
|
+
* The members of the object whose `{` is at `open`, as
|
|
57
|
+
* `[{ key, keyStart, valueStart, valueEnd }]`, and where it closes. Only this
|
|
58
|
+
* object's own members — a `mode` inside `seedFiles` is not the top-level one.
|
|
59
|
+
*/
|
|
60
|
+
function members(text, open) {
|
|
61
|
+
const out = []
|
|
62
|
+
let i = skipSpace(text, open + 1)
|
|
63
|
+
while (text[i] !== '}') {
|
|
64
|
+
if (text[i] !== '"') throw new Error(`expected a key at ${i}`)
|
|
65
|
+
const keyEnd = valueEnd(text, i)
|
|
66
|
+
const key = JSON.parse(text.slice(i, keyEnd))
|
|
67
|
+
let j = skipSpace(text, keyEnd)
|
|
68
|
+
if (text[j] !== ':') throw new Error(`expected ':' at ${j}`)
|
|
69
|
+
const valueStart = skipSpace(text, j + 1)
|
|
70
|
+
const end = valueEnd(text, valueStart)
|
|
71
|
+
out.push({ key, keyStart: i, valueStart, valueEnd: end })
|
|
72
|
+
i = skipSpace(text, end)
|
|
73
|
+
if (text[i] === ',') i = skipSpace(text, i + 1)
|
|
74
|
+
}
|
|
75
|
+
return { members: out, close: i }
|
|
76
|
+
}
|
|
77
|
+
|
|
78
|
+
/**
|
|
79
|
+
* @param {string} text the file as written
|
|
80
|
+
* @param {{ name?: string, category?: string }} changes a key left out is left
|
|
81
|
+
* alone; `''` clears it
|
|
82
|
+
* @returns {string} the edited text
|
|
83
|
+
* @throws when the file is not a JSON object, or the edit would not round-trip
|
|
84
|
+
*/
|
|
85
|
+
function setProjectKeys(text, changes) {
|
|
86
|
+
const parsed = JSON.parse(text)
|
|
87
|
+
if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) throw new Error('env.config.json is not a JSON object')
|
|
88
|
+
const wanted = KEYS.filter((k) => typeof changes[k] === 'string')
|
|
89
|
+
if (!wanted.length) return text
|
|
90
|
+
|
|
91
|
+
const indent = (/\n([ \t]+)"/.exec(text) || [null, ' '])[1]
|
|
92
|
+
const root = text.indexOf('{')
|
|
93
|
+
const top = members(text, root)
|
|
94
|
+
const project = top.members.find((m) => m.key === 'project')
|
|
95
|
+
const edits = [] // [start, end, replacement], applied from the back
|
|
96
|
+
|
|
97
|
+
if (project && text[project.valueStart] === '{') {
|
|
98
|
+
const inner = members(text, project.valueStart)
|
|
99
|
+
const missing = []
|
|
100
|
+
for (const k of wanted) {
|
|
101
|
+
const m = inner.members.find((x) => x.key === k)
|
|
102
|
+
if (m) edits.push([m.valueStart, m.valueEnd, JSON.stringify(changes[k])])
|
|
103
|
+
else missing.push(k)
|
|
104
|
+
}
|
|
105
|
+
if (missing.length) {
|
|
106
|
+
const deeper = indent + indent
|
|
107
|
+
const lines = missing.map((k) => `${deeper}${JSON.stringify(k)}: ${JSON.stringify(changes[k])}`)
|
|
108
|
+
// After the last member, or into an empty `{}`.
|
|
109
|
+
const last = inner.members[inner.members.length - 1]
|
|
110
|
+
const at = last ? last.valueEnd : project.valueStart + 1
|
|
111
|
+
const lead = last ? ',\n' : '\n'
|
|
112
|
+
const tail = last ? '' : `\n${indent}`
|
|
113
|
+
edits.push([at, at, `${lead}${lines.join(',\n')}${tail}`])
|
|
114
|
+
}
|
|
115
|
+
} else if (project) {
|
|
116
|
+
throw new Error('project in env.config.json is not an object — fix it by hand')
|
|
117
|
+
} else {
|
|
118
|
+
const block = [
|
|
119
|
+
`${indent}"project": {`,
|
|
120
|
+
KEYS.map((k) => `${indent}${indent}${JSON.stringify(k)}: ${JSON.stringify(typeof changes[k] === 'string' ? changes[k] : '')}`).join(',\n'),
|
|
121
|
+
`${indent}}`,
|
|
122
|
+
].join('\n')
|
|
123
|
+
// After `mode` where the file has one — where the shipped example puts it —
|
|
124
|
+
// else first.
|
|
125
|
+
const mode = top.members.find((m) => m.key === 'mode')
|
|
126
|
+
if (mode) edits.push([mode.valueEnd, mode.valueEnd, `,\n${block}`])
|
|
127
|
+
else edits.push([root + 1, root + 1, `\n${block}${top.members.length ? ',' : ''}`])
|
|
128
|
+
}
|
|
129
|
+
|
|
130
|
+
let out = text
|
|
131
|
+
for (const [start, end, rep] of edits.sort((a, b) => b[0] - a[0])) out = out.slice(0, start) + rep + out.slice(end)
|
|
132
|
+
|
|
133
|
+
const expect = JSON.parse(text)
|
|
134
|
+
expect.project = { ...(expect.project || { name: '', category: '' }) }
|
|
135
|
+
for (const k of wanted) expect.project[k] = changes[k]
|
|
136
|
+
if (JSON.stringify(sortKeys(JSON.parse(out))) !== JSON.stringify(sortKeys(expect))) {
|
|
137
|
+
throw new Error('the edit did not produce the expected config — nothing was written')
|
|
138
|
+
}
|
|
139
|
+
return out
|
|
140
|
+
}
|
|
141
|
+
|
|
142
|
+
function sortKeys(v) {
|
|
143
|
+
if (Array.isArray(v)) return v.map(sortKeys)
|
|
144
|
+
if (v && typeof v === 'object') return Object.fromEntries(Object.keys(v).sort().map((k) => [k, sortKeys(v[k])]))
|
|
145
|
+
return v
|
|
146
|
+
}
|
|
147
|
+
|
|
148
|
+
module.exports = { setProjectKeys }
|
package/src/env/resolve.js
CHANGED
package/src/env/review.js
CHANGED
|
@@ -269,7 +269,7 @@ function resolveReader(config, env = {}) {
|
|
|
269
269
|
* `buttons` is the button set the page renders — see `BUTTON_SETS`. It is the
|
|
270
270
|
* caller's declaration about the work, not a reading of the gate.
|
|
271
271
|
*/
|
|
272
|
-
function collectReview({ spec, git, mode = 'working', ref, base = null, now, notes = null, gate = null, fellBack = false, buttons = null, only = null, treePath = null, live = null, tiers = null }) {
|
|
272
|
+
function collectReview({ spec, git, mode = 'working', ref, base = null, now, notes = null, gate = null, fellBack = false, buttons = null, only = null, treePath = null, live = null, tiers = null, project = null }) {
|
|
273
273
|
// WHICH TREE THE SPEC'S OWN DOCUMENTS ARE READ FROM. Every render but one
|
|
274
274
|
// reads the spec's worktree, and for those the two are the same path — so
|
|
275
275
|
// `treePath` left null keeps the existing behaviour exactly. The `docs` mode
|
|
@@ -360,6 +360,9 @@ function collectReview({ spec, git, mode = 'working', ref, base = null, now, not
|
|
|
360
360
|
return {
|
|
361
361
|
spec: spec.folder,
|
|
362
362
|
title: spec.folder,
|
|
363
|
+
// The project's name, for the tab and the line above the heading. Absent
|
|
364
|
+
// when the caller could not tell, and the page then renders as before.
|
|
365
|
+
...(project ? { project } : {}),
|
|
363
366
|
branch: spec.branch,
|
|
364
367
|
// The tree the diff was read from. Identical to the worktree for every
|
|
365
368
|
// mode but `docs`, where there is no worktree and this is the checkout the
|
|
@@ -603,6 +606,10 @@ const ACTIONS = ['live-on', 'allow-network', 'allow-remote']
|
|
|
603
606
|
*/
|
|
604
607
|
function tierAction(tier) {
|
|
605
608
|
if (!tier || !tier.off) return null
|
|
609
|
+
// A loopback bind is off for a reason no press can fix: widening it restarts
|
|
610
|
+
// the server, which mints a new token and kills every link already open. Its
|
|
611
|
+
// command is named on the line; the page offers nothing.
|
|
612
|
+
if (tier.bound === 'loopback') return null
|
|
606
613
|
if (tier.tier === 'network') return 'allow-network'
|
|
607
614
|
if (tier.tier === 'remote') return 'allow-remote'
|
|
608
615
|
return null
|
|
@@ -742,6 +749,11 @@ function reviewTierStack({ served, fileUrl, publishedUrl, config }) {
|
|
|
742
749
|
return isTailnetAddress(host) ? { url: u, label: 'tailnet' } : { url: u }
|
|
743
750
|
}),
|
|
744
751
|
})
|
|
752
|
+
} else if (served && served.loopback && served.widen) {
|
|
753
|
+
// Permitted, and the machine has addresses — but the running server is
|
|
754
|
+
// bound to loopback. "No network address" here sent readers looking for a
|
|
755
|
+
// network problem; the fix is one command, so the line names it.
|
|
756
|
+
tiers.push({ tier: 'network', off: true, bound: 'loopback', enable: served.widen })
|
|
745
757
|
} else {
|
|
746
758
|
// Permitted, but there is no address to offer — a machine with no network,
|
|
747
759
|
// or a server that could not take one. Not a problem to report as an error.
|
|
@@ -2309,16 +2321,22 @@ function fragmentTemplate(template = null) {
|
|
|
2309
2321
|
*/
|
|
2310
2322
|
function renderReviewFragment(data, { template = null, reviewHtml = '' } = {}) {
|
|
2311
2323
|
const values = {
|
|
2312
|
-
[TITLE_PLACEHOLDER]: escapeHtml(data
|
|
2324
|
+
[TITLE_PLACEHOLDER]: escapeHtml(tabTitle(data)),
|
|
2313
2325
|
[REVIEW_PLACEHOLDER]: reviewHtml,
|
|
2314
2326
|
[DATA_PLACEHOLDER]: escapeIsland(JSON.stringify(data)),
|
|
2315
2327
|
}
|
|
2316
2328
|
return fragmentTemplate(template).replace(PLACEHOLDER_RE, (m) => values[m])
|
|
2317
2329
|
}
|
|
2318
2330
|
|
|
2331
|
+
// The tab name: `<project> · <spec>`, so pages from two projects open side by
|
|
2332
|
+
// side can be told apart from the tab alone — all a phone shows.
|
|
2333
|
+
function tabTitle(data) {
|
|
2334
|
+
return data.project ? `${data.project} · ${data.title}` : data.title
|
|
2335
|
+
}
|
|
2336
|
+
|
|
2319
2337
|
function renderReviewPage(data, { template = null, reviewHtml = '' } = {}) {
|
|
2320
2338
|
const values = {
|
|
2321
|
-
[TITLE_PLACEHOLDER]: escapeHtml(data
|
|
2339
|
+
[TITLE_PLACEHOLDER]: escapeHtml(tabTitle(data)),
|
|
2322
2340
|
[REVIEW_PLACEHOLDER]: reviewHtml,
|
|
2323
2341
|
[DATA_PLACEHOLDER]: escapeIsland(JSON.stringify(data)),
|
|
2324
2342
|
}
|
package/src/env/serve.js
CHANGED
|
@@ -38,13 +38,15 @@ const {
|
|
|
38
38
|
isEpic,
|
|
39
39
|
} = require('./resolve.js')
|
|
40
40
|
const { epicTree, worktreeOverview, epicsInFlight, memberReaders, epicAnswer } = require('./epicread.js')
|
|
41
|
+
const { specBranchDocs } = require('./specbranches.js')
|
|
41
42
|
const { renderEpicPage } = require('./epicpage.js')
|
|
42
43
|
const { readRegistry } = require('./registry.js')
|
|
43
44
|
const { loadEnvConfig } = require('./config.js')
|
|
44
|
-
const { primaryAnchor, attachProject, repoRootOf, prefixOf, fromRepoPath, toRepoPath } = require('./project.js')
|
|
45
|
+
const { primaryAnchor, attachProject, projectName, repoRootOf, prefixOf, fromRepoPath, toRepoPath } = require('./project.js')
|
|
45
46
|
const { specDocsIn, classifyDirtyTree, dirtyPaths } = require('./classify.js')
|
|
46
47
|
const { liveStateFor } = require('./live.js')
|
|
47
48
|
const { preferRemoteBase } = require('./host.js')
|
|
49
|
+
const { ROUTE: TADA_ROUTE, renderServedTada } = require('../tada/serve.js')
|
|
48
50
|
const {
|
|
49
51
|
rawGitReader,
|
|
50
52
|
collectReview,
|
|
@@ -95,6 +97,9 @@ function routeFor(url, { token = null } = {}) {
|
|
|
95
97
|
|
|
96
98
|
if (segments.length === 0) return { kind: 'index' }
|
|
97
99
|
if (segments.length > 1) return { kind: 'notfound' }
|
|
100
|
+
// The ta-da page: a window, not a spec. Its query is the window and passed
|
|
101
|
+
// through whole, to be read — and refused if unreadable — by `tada/serve.js`.
|
|
102
|
+
if (segments[0] === TADA_ROUTE) return { kind: 'tada', search: rawQuery || '' }
|
|
98
103
|
|
|
99
104
|
// `?pass=<code>` asks what became of ONE pass, and it is checked BEFORE
|
|
100
105
|
// `?branch` because it is not a view of the diff at all — it is the page
|
|
@@ -127,8 +132,11 @@ function escapeHtml(s) {
|
|
|
127
132
|
* palette on bare `:root`, redefined under `prefers-color-scheme`) so the two
|
|
128
133
|
* do not disagree when opened side by side.
|
|
129
134
|
*/
|
|
130
|
-
function renderIndex(entries, { token = null, epics = [] } = {}) {
|
|
135
|
+
function renderIndex(entries, { token = null, epics = [], project = null } = {}) {
|
|
131
136
|
const prefix = token ? `/${token}` : ''
|
|
137
|
+
// The heading and tab name the project, so two servers' indexes open side by
|
|
138
|
+
// side can be told apart. No name — cannot tell — reads as it always did.
|
|
139
|
+
const heading = project ? `${escapeHtml(project)} · spec diffs` : 'spec diffs'
|
|
132
140
|
// Epics with a member in flight, each a doorway to its epic page. Listed
|
|
133
141
|
// above the diffs because an epic page is where a reader running several
|
|
134
142
|
// members starts; absent entirely on a repo with no epic in flight.
|
|
@@ -161,7 +169,7 @@ function renderIndex(entries, { token = null, epics = [] } = {}) {
|
|
|
161
169
|
<head>
|
|
162
170
|
<meta charset="utf-8">
|
|
163
171
|
<meta name="viewport" content="width=device-width, initial-scale=1">
|
|
164
|
-
<title
|
|
172
|
+
<title>${heading}</title>
|
|
165
173
|
<style>
|
|
166
174
|
:root { --bg:#fff; --fg:#1a1a1a; --dim:#6b6b6b; --line:#e3e3e3; --add:#0a7b34; --del:#b3261e; --link:#0b5fbd }
|
|
167
175
|
@media (prefers-color-scheme: dark) {
|
|
@@ -188,7 +196,7 @@ code { font-family:ui-monospace,SFMono-Regular,Menlo,monospace }
|
|
|
188
196
|
</head>
|
|
189
197
|
<body>
|
|
190
198
|
<main>
|
|
191
|
-
<h1
|
|
199
|
+
<h1>${heading}</h1>
|
|
192
200
|
${epicList}
|
|
193
201
|
${body}
|
|
194
202
|
</main>
|
|
@@ -561,6 +569,7 @@ function renderSpecPage(dir, config, spec, { branch = false } = {}) {
|
|
|
561
569
|
notes,
|
|
562
570
|
gate: gateRead.corrupt ? null : gateRead.gate,
|
|
563
571
|
buttons,
|
|
572
|
+
project: projectName(config),
|
|
564
573
|
only: view.owned,
|
|
565
574
|
treePath: view.tree,
|
|
566
575
|
})
|
|
@@ -638,6 +647,7 @@ function renderSpecPage(dir, config, spec, { branch = false } = {}) {
|
|
|
638
647
|
buttons,
|
|
639
648
|
live,
|
|
640
649
|
tiers,
|
|
650
|
+
project: projectName(config),
|
|
641
651
|
})
|
|
642
652
|
|
|
643
653
|
if (!branch && data.totals.files === 0) {
|
|
@@ -660,6 +670,7 @@ function renderSpecPage(dir, config, spec, { branch = false } = {}) {
|
|
|
660
670
|
buttons,
|
|
661
671
|
live,
|
|
662
672
|
tiers,
|
|
673
|
+
project: projectName(config),
|
|
663
674
|
fellBack: true,
|
|
664
675
|
})
|
|
665
676
|
if (wider.totals.files > 0) {
|
|
@@ -805,7 +816,7 @@ function readBody(req, limit = MAX_PASS_BYTES) {
|
|
|
805
816
|
})
|
|
806
817
|
}
|
|
807
818
|
|
|
808
|
-
function createReviewServer({ resolveEntries, resolveEpics = () => [], render, receive = null, passState = null, token = null }) {
|
|
819
|
+
function createReviewServer({ resolveEntries, resolveEpics = () => [], render, receive = null, passState = null, tada = null, token = null, project = null }) {
|
|
809
820
|
return http.createServer((req, res) => {
|
|
810
821
|
const send = (code, body, type = 'text/html; charset=utf-8') => {
|
|
811
822
|
res.writeHead(code, { 'content-type': type, 'cache-control': 'no-store' })
|
|
@@ -858,8 +869,22 @@ function createReviewServer({ resolveEntries, resolveEpics = () => [], render, r
|
|
|
858
869
|
return send(200, JSON.stringify({ state }), 'application/json; charset=utf-8')
|
|
859
870
|
}
|
|
860
871
|
|
|
872
|
+
// ASYNC, unlike the diff page: the digest is the CLI's own answer, run in a
|
|
873
|
+
// child process, so the one request waits and the server does not. A
|
|
874
|
+
// server built without the hook is an older one, and says not found.
|
|
875
|
+
if (route.kind === 'tada') {
|
|
876
|
+
if (!tada) return send(404, 'not found', 'text/plain; charset=utf-8')
|
|
877
|
+
Promise.resolve()
|
|
878
|
+
.then(() => tada(route.search))
|
|
879
|
+
.then(
|
|
880
|
+
(out) => (out.html ? send(200, out.html) : send(out.status || 500, out.error, 'text/plain; charset=utf-8')),
|
|
881
|
+
(err) => send(500, `render failed: ${err.message}`, 'text/plain; charset=utf-8'),
|
|
882
|
+
)
|
|
883
|
+
return
|
|
884
|
+
}
|
|
885
|
+
|
|
861
886
|
try {
|
|
862
|
-
if (route.kind === 'index') return send(200, renderIndex(resolveEntries(), { token, epics: resolveEpics() }))
|
|
887
|
+
if (route.kind === 'index') return send(200, renderIndex(resolveEntries(), { token, epics: resolveEpics(), project }))
|
|
863
888
|
const out = render(route.spec, { branch: route.branch })
|
|
864
889
|
if (!out) return send(404, 'not found', 'text/plain; charset=utf-8')
|
|
865
890
|
if (out.error) return send(409, out.error, 'text/plain; charset=utf-8')
|
|
@@ -1027,14 +1052,16 @@ function serverHooks(dir, config) {
|
|
|
1027
1052
|
}
|
|
1028
1053
|
const tree = epicTree(trimmedGit, base)
|
|
1029
1054
|
if (!tree) return { error: `cannot tell — the base branch ${base} could not be read` }
|
|
1030
|
-
const inputs = { dir, config, base, ...tree, worktrees: worktrees() }
|
|
1055
|
+
const inputs = { dir, config, base, ...tree, worktrees: worktrees(), branches: specBranchDocs(trimmedGit, config, base) }
|
|
1031
1056
|
const answer = epicAnswer(folder, inputs, memberReaders({ ...inputs, git: trimmedGitReader, linkFor: (s) => encodeURIComponent(s) }))
|
|
1032
1057
|
if (!answer.found && !answer.members.length) return null
|
|
1033
|
-
return { html: renderEpicPage(answer) }
|
|
1058
|
+
return { html: renderEpicPage(answer, { project: projectName(config) }) }
|
|
1034
1059
|
}
|
|
1035
1060
|
|
|
1036
1061
|
return {
|
|
1037
1062
|
resolveEntries,
|
|
1063
|
+
// What the index calls this project. Read once: the server is per project.
|
|
1064
|
+
project: projectName(config),
|
|
1038
1065
|
resolveEpics: () => {
|
|
1039
1066
|
try {
|
|
1040
1067
|
return epicsInFlight(worktrees())
|
|
@@ -1064,6 +1091,15 @@ function serverHooks(dir, config) {
|
|
|
1064
1091
|
if (!one) return { state: 'unknown' }
|
|
1065
1092
|
return readPassState(reviewOutPath(dir, one.folder, null), one.folder, code)
|
|
1066
1093
|
},
|
|
1094
|
+
// The ta-da page, scoped to THIS project's category, its recap read from
|
|
1095
|
+
// the same state folder the review notes live in.
|
|
1096
|
+
tada: (search) =>
|
|
1097
|
+
renderServedTada({
|
|
1098
|
+
dir,
|
|
1099
|
+
stateDir: path.join(dir, path.posix.dirname(config.registry) || '.spec-env'),
|
|
1100
|
+
search,
|
|
1101
|
+
project: projectName(config),
|
|
1102
|
+
}),
|
|
1067
1103
|
}
|
|
1068
1104
|
}
|
|
1069
1105
|
|
|
@@ -0,0 +1,120 @@
|
|
|
1
|
+
'use strict'
|
|
2
|
+
|
|
3
|
+
/**
|
|
4
|
+
* Specs that live only on their own branch (feat-tracker-spec-branches).
|
|
5
|
+
*
|
|
6
|
+
* Under `land.specDocs: "branch"` — the default once a ticketing provider is
|
|
7
|
+
* configured — a spec document never lands on the base branch until its work
|
|
8
|
+
* does, so `ls specs/backlog/` on base cannot see it. The checks that read the
|
|
9
|
+
* backlog (`gating check`, `epic status`, `docs-freshness check`) ask this
|
|
10
|
+
* instead, so the specs that mode produces are not invisible to them.
|
|
11
|
+
*
|
|
12
|
+
* What a branch is FOR is read off what it changed: the spec folders its range
|
|
13
|
+
* (`<base>...<ref>`) touches. Every spec branch forks from base and so carries
|
|
14
|
+
* every base spec too; only the ones it changed are its own.
|
|
15
|
+
*
|
|
16
|
+
* Read with git and never fetched. An advisory check that can hang on the
|
|
17
|
+
* network is worse than one that is a fetch behind, so remote-tracking refs are
|
|
18
|
+
* read as they stand and a caller labels them "as of last fetch".
|
|
19
|
+
*
|
|
20
|
+
* WHAT WOULD FOOL THIS: a remote that was never fetched (its specs are simply
|
|
21
|
+
* absent — an extra miss, never an accusation), and a spec branch whose name
|
|
22
|
+
* does not match `branch.pattern` (renamed by hand; it is not found). Every
|
|
23
|
+
* unreadable git call reads as nothing found.
|
|
24
|
+
*/
|
|
25
|
+
|
|
26
|
+
const { BUCKETS } = require('./resolve.js')
|
|
27
|
+
|
|
28
|
+
const OVERVIEW_RE = /^specs\/([^/]+)\/([^/]+)\/00-overview\.md$/
|
|
29
|
+
const SPEC_PATH_RE = /^specs\/([^/]+)\/([^/]+)\//
|
|
30
|
+
|
|
31
|
+
// `branch.pattern` as a for-each-ref glob: every `{token}` becomes `*`.
|
|
32
|
+
function refGlob(config) {
|
|
33
|
+
const pattern = (config && config.branch && config.branch.pattern) || '{type}/{slug}'
|
|
34
|
+
return pattern.replace(/\{[^}]+\}/g, '*')
|
|
35
|
+
}
|
|
36
|
+
|
|
37
|
+
function lines(out) {
|
|
38
|
+
return String(out || '').split('\n').map((l) => l.trim()).filter(Boolean)
|
|
39
|
+
}
|
|
40
|
+
|
|
41
|
+
/**
|
|
42
|
+
* The spec branches this clone can see: local first, then remote-tracking, as
|
|
43
|
+
* `{ ref, name, local }`. The base branch itself is never a spec branch.
|
|
44
|
+
*/
|
|
45
|
+
function specRefs(git, config, base) {
|
|
46
|
+
const glob = refGlob(config)
|
|
47
|
+
const remote = (config && config.land && config.land.remote) || 'origin'
|
|
48
|
+
const local = lines(git(['for-each-ref', '--format=%(refname)', `refs/heads/${glob}`]))
|
|
49
|
+
.map((ref) => ({ ref, name: ref.slice('refs/heads/'.length), local: true }))
|
|
50
|
+
const prefix = `refs/remotes/${remote}/`
|
|
51
|
+
const tracking = lines(git(['for-each-ref', '--format=%(refname)', `${prefix}${glob}`]))
|
|
52
|
+
.map((ref) => ({ ref, name: ref.slice(prefix.length), local: false }))
|
|
53
|
+
return [...local, ...tracking].filter((r) => r.name !== base && r.name !== 'HEAD')
|
|
54
|
+
}
|
|
55
|
+
|
|
56
|
+
/**
|
|
57
|
+
* Every spec folder a spec branch changed, read off that branch:
|
|
58
|
+
* `[{ folder, bucket, ref, local, overview, phases: [{ n, text }] }]`.
|
|
59
|
+
*
|
|
60
|
+
* Precedence (Decision 7): a folder the base branch has FINISHED — in
|
|
61
|
+
* `complete/` or `cancelled/` — is dropped, since the work is done and a
|
|
62
|
+
* lingering branch is history; otherwise a local branch beats a
|
|
63
|
+
* remote-tracking one. Base's own `backlog/` copy losing to a branch copy is
|
|
64
|
+
* the caller's merge, via `preferBranches`.
|
|
65
|
+
*/
|
|
66
|
+
function specBranchDocs(git, config, base) {
|
|
67
|
+
if (!base) return []
|
|
68
|
+
const finished = new Set()
|
|
69
|
+
for (const p of lines(git(['ls-tree', '-r', '--name-only', base, '--', 'specs/complete', 'specs/cancelled']))) {
|
|
70
|
+
const m = OVERVIEW_RE.exec(p)
|
|
71
|
+
if (m) finished.add(m[2])
|
|
72
|
+
}
|
|
73
|
+
const found = new Map()
|
|
74
|
+
for (const { ref, local } of specRefs(git, config, base)) {
|
|
75
|
+
const changed = new Set()
|
|
76
|
+
for (const p of lines(git(['diff', '--name-only', `${base}...${ref}`, '--', 'specs']))) {
|
|
77
|
+
const m = SPEC_PATH_RE.exec(p)
|
|
78
|
+
if (m && BUCKETS.includes(m[1])) changed.add(m[2])
|
|
79
|
+
}
|
|
80
|
+
if (!changed.size) continue
|
|
81
|
+
const tree = lines(git(['ls-tree', '-r', '--name-only', ref, '--', 'specs']))
|
|
82
|
+
for (const folder of changed) {
|
|
83
|
+
if (finished.has(folder)) continue
|
|
84
|
+
if (found.has(folder) && (found.get(folder).local || !local)) continue
|
|
85
|
+
const overviewPath = tree.find((p) => {
|
|
86
|
+
const m = OVERVIEW_RE.exec(p)
|
|
87
|
+
return m && m[2] === folder
|
|
88
|
+
})
|
|
89
|
+
if (!overviewPath) continue // the branch deleted it, or moved it out of specs/
|
|
90
|
+
const overview = git(['show', `${ref}:${overviewPath}`])
|
|
91
|
+
if (overview === null) continue
|
|
92
|
+
const bucket = OVERVIEW_RE.exec(overviewPath)[1]
|
|
93
|
+
const dirPrefix = `specs/${bucket}/${folder}/`
|
|
94
|
+
const phases = tree
|
|
95
|
+
.filter((p) => p.startsWith(dirPrefix) && /^\d\d-.+\.md$/.test(p.slice(dirPrefix.length)) && !p.endsWith('/00-overview.md'))
|
|
96
|
+
.map((p) => ({ n: Number(p.slice(dirPrefix.length, dirPrefix.length + 2)), text: git(['show', `${ref}:${p}`]) }))
|
|
97
|
+
found.set(folder, { folder, bucket, ref, local, overview, phases })
|
|
98
|
+
}
|
|
99
|
+
}
|
|
100
|
+
return [...found.values()].sort((a, b) => a.folder.localeCompare(b.folder))
|
|
101
|
+
}
|
|
102
|
+
|
|
103
|
+
/**
|
|
104
|
+
* Merge a disk scan with branch copies: a branch copy replaces the disk entry
|
|
105
|
+
* for the same folder, and adds one where there is none. Both lists carry
|
|
106
|
+
* `folder`; the result keeps the disk entries' order, then the new ones.
|
|
107
|
+
*/
|
|
108
|
+
function preferBranches(disk, branches) {
|
|
109
|
+
const byFolder = new Map(branches.map((b) => [b.folder, b]))
|
|
110
|
+
const merged = disk.map((d) => byFolder.get(d.folder) || d)
|
|
111
|
+
const seen = new Set(disk.map((d) => d.folder))
|
|
112
|
+
return [...merged, ...branches.filter((b) => !seen.has(b.folder))]
|
|
113
|
+
}
|
|
114
|
+
|
|
115
|
+
/** The label a branch-sourced row carries. */
|
|
116
|
+
function branchLabel(entry) {
|
|
117
|
+
return entry.local ? `on ${entry.ref.replace(/^refs\/heads\//, '')}` : `on ${entry.ref.replace(/^refs\/remotes\//, '')}, as of last fetch`
|
|
118
|
+
}
|
|
119
|
+
|
|
120
|
+
module.exports = { specBranchDocs, specRefs, preferBranches, branchLabel, refGlob }
|