@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.
Files changed (45) hide show
  1. package/assets/claude-md-section.md +6 -0
  2. package/assets/core/env.config.json.example +5 -0
  3. package/assets/core/env.config.md +26 -5
  4. package/assets/review/page.html +9 -0
  5. package/assets/rules/spec-planning.md +65 -12
  6. package/assets/rules/spec-reports.md +8 -1
  7. package/assets/skills/spec/SKILL.md +31 -14
  8. package/assets/skills/spec-cancel/SKILL.md +7 -0
  9. package/assets/skills/spec-complete/SKILL.md +6 -0
  10. package/assets/skills/spec-epic-next/SKILL.md +83 -0
  11. package/assets/skills/spec-init/SKILL.md +35 -3
  12. package/assets/skills/spec-next/SKILL.md +38 -1
  13. package/assets/skills/spec-start/SKILL.md +2 -2
  14. package/assets/skills/spec-tada/SKILL.md +153 -0
  15. package/bin/skitterspec-jira.js +5 -0
  16. package/package.json +1 -1
  17. package/src/cli.js +473 -25
  18. package/src/env/config.js +57 -6
  19. package/src/env/epic.js +69 -19
  20. package/src/env/epicpage.js +87 -39
  21. package/src/env/epicread.js +41 -3
  22. package/src/env/integrate.js +48 -1
  23. package/src/env/nextaction.js +78 -1
  24. package/src/env/project.js +54 -3
  25. package/src/env/projectedit.js +148 -0
  26. package/src/env/resolve.js +1 -0
  27. package/src/env/review.js +21 -3
  28. package/src/env/serve.js +44 -8
  29. package/src/env/specbranches.js +120 -0
  30. package/src/env/teardown.js +18 -3
  31. package/src/gating.js +16 -4
  32. package/src/init.js +11 -3
  33. package/src/tada/commits.js +145 -0
  34. package/src/tada/digest.js +260 -0
  35. package/src/tada/format.js +37 -0
  36. package/src/tada/page.js +213 -0
  37. package/src/tada/repo.js +102 -0
  38. package/src/tada/serve.js +127 -0
  39. package/src/tada/specs.js +146 -0
  40. package/src/tada/transcripts.js +258 -0
  41. package/src/tada/window.js +156 -0
  42. package/src/vendor/provider-kit/src/apply.js +25 -1
  43. package/src/vendor/sync-core/src/compare.js +10 -2
  44. package/src/vendor/sync-core/src/push.js +14 -3
  45. /package/assets/commands/{epic.md → spec-epic.md} +0 -0
@@ -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
- module.exports = { nextAction, epicNext, epicRows, actionText, readNextInputs, readPhases }
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 }
@@ -154,7 +154,9 @@ function toRepoPath(rel, prefix) {
154
154
  * config.
155
155
  */
156
156
  function attachProject(config, anchor) {
157
- Object.defineProperty(config, 'project', {
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.project && config.project.root) || dir
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.project && config.project.prefix) || ''
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 }
@@ -850,6 +850,7 @@ module.exports = {
850
850
  phaseIsStarted,
851
851
  parsePhase,
852
852
  readOverview,
853
+ readTicket,
853
854
  readFrontmatterField,
854
855
  readStackField,
855
856
  readBaseVersionField,
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.title),
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.title),
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>spec diffs</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>spec diffs</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 }