@skitterbyte/skitterspec-jira 2.8.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.
@@ -18,7 +18,7 @@
18
18
  * no cell ever has to list tiers.
19
19
  */
20
20
 
21
- const { actionText } = require('./nextaction.js')
21
+ const { actionText, epicRows, epicPlan } = require('./nextaction.js')
22
22
 
23
23
  const REFRESH_SECONDS = 30
24
24
 
@@ -28,18 +28,6 @@ function escapeHtml(s) {
28
28
 
29
29
  const href = (spec) => escapeHtml(encodeURIComponent(spec))
30
30
 
31
- // The `next` cell. Each verb that names a code or a page is handled here; the
32
- // rest are `actionText`, the same words the terminal prints.
33
- function nextCell(row) {
34
- const a = row.next
35
- if (a.verb === 'claim') return 'verdict waiting — <code>/spec-reviewed</code> in its tab'
36
- if (a.verb === 'verdict') return `<a href="${href(row.spec)}">press a verdict on its page →</a>`
37
- if (a.command) {
38
- return `<code>${escapeHtml(a.command)}</code>${a.why ? ` <span class="why">${escapeHtml(a.why)}</span>` : ''}`
39
- }
40
- return escapeHtml(actionText(a))
41
- }
42
-
43
31
  function memberCell(row) {
44
32
  // An in-flight member with a tab has a page of its own on this server.
45
33
  return row.tab ? `<a href="${href(row.spec)}">${escapeHtml(row.spec)}</a>` : escapeHtml(row.spec)
@@ -51,22 +39,66 @@ function syncLine({ spec, phase, wait }) {
51
39
  return `${who} after ${wait.raw} (${mark})`
52
40
  }
53
41
 
42
+ // One numbered step. A pass is named by what to type and never its code, like
43
+ // the `next` cell; a verdict links to the member's page.
44
+ function stepItem(st, freeLanes) {
45
+ const where =
46
+ st.where === 'epic'
47
+ ? "In the epic's tab"
48
+ : st.where === 'new-tab'
49
+ ? `In a new tab${freeLanes === null || freeLanes === undefined ? '' : ` (${freeLanes} lane${freeLanes === 1 ? '' : 's'} free)`}`
50
+ : `In <code>${escapeHtml(st.tab || `${st.spec}'s tab`)}</code>`
51
+ const what =
52
+ st.verb === 'claim'
53
+ ? 'verdict waiting — <code>/spec-reviewed</code>'
54
+ : st.verb === 'verdict'
55
+ ? `<a href="${href(st.spec)}">press a verdict on ${escapeHtml(st.spec)}'s page →</a>`
56
+ : `<code>${escapeHtml(st.command)}</code>`
57
+ const notes = [
58
+ st.unblocks.length ? `<div class="un">→ unblocks ${escapeHtml(st.unblocks.join(', '))}</div>` : '',
59
+ st.caution ? `<div class="warn">⚠ ${escapeHtml(st.caution)}</div>` : '',
60
+ ].join('')
61
+ return `<li><div class="where">${where}</div><div class="what">${what}</div>${notes}</li>`
62
+ }
63
+
54
64
  function renderEpicPage(answer, { refreshSeconds = REFRESH_SECONDS, project = null } = {}) {
55
65
  const lanes = answer.lanes === null ? 'no lane cap' : `${answer.lanes} lanes, ${answer.freeLanes} free`
56
- const count = `${answer.members.length} member${answer.members.length === 1 ? '' : 's'}`
57
- const rows = (answer.rows || [])
58
- .map(
59
- (r) =>
60
- `<tr class="v-${escapeHtml(r.next.verb)}"><td class="m">${memberCell(r)}</td>` +
61
- `<td class="s">${escapeHtml(r.next.state || r.bucket || '')}</td>` +
62
- `<td class="x">${nextCell(r)}</td>` +
63
- `<td class="t">${r.tab ? `<code>${escapeHtml(r.tab)}</code>` : '—'}</td></tr>`,
64
- )
65
- .join('\n')
66
- const table = answer.members.length
67
- ? `<table>\n<thead><tr><th>member</th><th>state</th><th>next</th><th>tab</th></tr></thead>\n<tbody>\n${rows}\n</tbody>\n</table>`
66
+ const { rows, next } = answer.rows ? { rows: answer.rows, next: answer.next } : epicRows(answer)
67
+ const { progress, groups, steps } = answer.steps ? answer : epicPlan(answer, { rows, next })
68
+ const byName = new Map(rows.map((r) => [r.spec, r]))
69
+
70
+ const section = (title, cls, names, cell) =>
71
+ names.length
72
+ ? `<section class="${cls}"><h2>${title} <span class="n">${names.length}</span></h2>\n<table><tbody>\n${names
73
+ .map((n) => {
74
+ const r = byName.get(n)
75
+ return `<tr class="v-${escapeHtml(r.next.verb)}"><td class="m">${memberCell(r)}</td>${cell(r)}</tr>`
76
+ })
77
+ .join('\n')}\n</tbody></table></section>`
78
+ : ''
79
+ const groupsHtml = answer.members.length
80
+ ? [
81
+ section('In flight', 'g-flight', groups.inFlight, (r) =>
82
+ `<td class="s">${escapeHtml(r.next.state || 'in-progress')}</td><td class="t">${r.tab ? `<code>${escapeHtml(r.tab)}</code>` : '—'}</td>`),
83
+ section('Ready to start', 'g-ready', groups.ready, (r) =>
84
+ `<td class="s">${r.next.why ? `<span class="warn">⚠ ${escapeHtml(r.next.why)}</span>` : 'ready'}</td>`),
85
+ section('Waiting', 'g-wait', groups.waiting, (r) => `<td class="s">${escapeHtml(r.next.why || actionText(r.next))}</td>`),
86
+ groups.done.length
87
+ ? `<details class="g-done"><summary><h2>Done <span class="n">${groups.done.length}</span></h2></summary><p class="dim">${escapeHtml(groups.done.join(' · '))}</p></details>`
88
+ : '',
89
+ ]
90
+ .filter(Boolean)
91
+ .join('\n')
68
92
  : `<p class="empty">No member yet — no spec carries <code>&gt; **Epic:** ${escapeHtml(answer.epic)}</code>.</p>`
69
- const own = answer.next ? `<p class="own"><code>${escapeHtml(answer.next.command)}</code> — every member is finished</p>` : ''
93
+
94
+ const stepsHtml = answer.members.length
95
+ ? `<section class="steps"><h2>Next steps</h2>\n${
96
+ steps.length
97
+ ? `<ol>\n${steps.map((st) => stepItem(st, answer.freeLanes)).join('\n')}\n</ol>`
98
+ : '<p class="dim">Nothing to type — every open member is building, held or waiting.</p>'
99
+ }</section>`
100
+ : ''
101
+ const pct = progress.total ? Math.round((progress.done / progress.total) * 100) : 0
70
102
  const shape = [
71
103
  ['waves', answer.waves.map((w, i) => `${i + 1}: ${w.join(', ')}`).join(' · ')],
72
104
  ['sync points', answer.syncPoints.map(syncLine).join(' · ')],
@@ -85,9 +117,9 @@ function renderEpicPage(answer, { refreshSeconds = REFRESH_SECONDS, project = nu
85
117
  <meta http-equiv="refresh" content="${Number(refreshSeconds)}">
86
118
  <title>${project ? `${escapeHtml(project)} · ` : ''}${escapeHtml(answer.epic)}</title>
87
119
  <style>
88
- :root { --bg:#fff; --fg:#1a1a1a; --dim:#6b6b6b; --line:#e3e3e3; --link:#0b5fbd; --hot:#a15c00 }
120
+ :root { --bg:#fff; --fg:#1a1a1a; --dim:#6b6b6b; --line:#e3e3e3; --link:#0b5fbd; --hot:#a15c00; --ok:#1f7a3a }
89
121
  @media (prefers-color-scheme: dark) {
90
- :root:not([data-theme="light"]) { --bg:#16181c; --fg:#e6e6e6; --dim:#9a9a9a; --line:#2c2f36; --link:#7cb7ff; --hot:#f0b35a }
122
+ :root:not([data-theme="light"]) { --bg:#16181c; --fg:#e6e6e6; --dim:#9a9a9a; --line:#2c2f36; --link:#7cb7ff; --hot:#f0b35a; --ok:#5fc27e }
91
123
  }
92
124
  * { box-sizing:border-box }
93
125
  body { margin:0; padding:2rem 1rem; background:var(--bg); color:var(--fg);
@@ -103,10 +135,24 @@ th, td { padding:.55rem .6rem .55rem 0; border-top:1px solid var(--line); vertic
103
135
  a { color:var(--link); text-decoration:none; font-weight:600 }
104
136
  a:hover { text-decoration:underline }
105
137
  code { font-family:ui-monospace,SFMono-Regular,Menlo,monospace; font-size:.9em }
106
- .why, .s, .t { color:var(--dim) }
107
- .v-verdict .x, .v-claim .x { color:var(--hot) }
108
- .own { margin:1rem 0 0 }
109
- dl { margin:1.5rem 0 0; display:grid; grid-template-columns:max-content 1fr; gap:.3rem 1rem }
138
+ .why, .s, .t, .dim { color:var(--dim) }
139
+ .bar { height:.5rem; background:var(--line); border-radius:.25rem; overflow:hidden; margin:0 0 1.5rem }
140
+ .bar > span { display:block; height:100%; background:var(--ok) }
141
+ h2 { font-size:.8rem; text-transform:uppercase; letter-spacing:.06em; color:var(--dim); font-weight:600; margin:1.5rem 0 .4rem; display:inline-block }
142
+ h2 .n { font-weight:400 }
143
+ section table td.m { width:40% }
144
+ .warn { color:var(--hot) }
145
+ .v-verdict .s, .v-claim .s { color:var(--hot) }
146
+ details summary { cursor:pointer; list-style:none }
147
+ details summary::-webkit-details-marker { display:none }
148
+ details summary h2::after { content:' ▸' } details[open] summary h2::after { content:' ▾' }
149
+ .steps { border-top:2px solid var(--line); margin-top:1.75rem }
150
+ .steps ol { margin:.25rem 0 0; padding-left:1.5rem }
151
+ .steps li { margin:0 0 .9rem }
152
+ .steps .where { color:var(--dim); font-size:.9em }
153
+ .steps .what { margin:.1rem 0 }
154
+ .steps .un { color:var(--ok) }
155
+ dl { margin:.5rem 0 0; display:grid; grid-template-columns:max-content 1fr; gap:.3rem 1rem }
110
156
  dt { color:var(--dim) } dd { margin:0 }
111
157
  .empty, .foot { color:var(--dim) }
112
158
  .foot { margin-top:1.5rem; font-size:.85em }
@@ -115,10 +161,11 @@ dt { color:var(--dim) } dd { margin:0 }
115
161
  <body>
116
162
  <main>
117
163
  ${project ? `<p class="eyebrow">${escapeHtml(project)}</p>\n` : ''}<h1>${escapeHtml(answer.epic)}</h1>
118
- <p class="sub">${count} · ${escapeHtml(lanes)}</p>
119
- <div class="wrap">${table}</div>
120
- ${own}
121
- ${shape ? `<dl>\n${shape}\n</dl>` : ''}
164
+ <p class="sub">${progress.done} of ${progress.total} done · ${progress.inFlight} in flight · ${escapeHtml(lanes)}</p>
165
+ <div class="bar" role="img" aria-label="${progress.done} of ${progress.total} done"><span style="width:${pct}%"></span></div>
166
+ <div class="wrap">${groupsHtml}</div>
167
+ ${stepsHtml}
168
+ ${shape ? `<details class="shape"><summary><h2>Waves · never together</h2></summary>\n<dl>\n${shape}\n</dl></details>` : ''}
122
169
  <p class="foot">Refreshes every ${Number(refreshSeconds)} s. Type commands in the member's own tab.</p>
123
170
  </main>
124
171
  </body>
@@ -16,7 +16,7 @@ const path = require('node:path')
16
16
 
17
17
  const { isEpic } = require('./resolve.js')
18
18
  const { epicStatus, epicHeaders, indexSpecTree } = require('./epic.js')
19
- const { epicRows, readNextInputs } = require('./nextaction.js')
19
+ const { epicRows, epicPlan, readNextInputs } = require('./nextaction.js')
20
20
  const { reviewOutPath } = require('./review.js')
21
21
 
22
22
  /**
@@ -141,7 +141,7 @@ function memberReaders({ dir, config, worktrees, linkFor = () => null, git }) {
141
141
  function epicAnswer(epic, inputs, readers) {
142
142
  const status = epicStatus({ epic, ...inputs })
143
143
  const { rows, next } = epicRows(status, readers)
144
- return { ...status, rows, next }
144
+ return { ...status, rows, next, ...epicPlan(status, { rows, next }) }
145
145
  }
146
146
 
147
147
  module.exports = { epicTree, workingTree, worktreeOverview, epicsInFlight, memberReaders, epicAnswer }
@@ -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,
@@ -163,8 +165,9 @@ function attachProject(config, anchor) {
163
165
  }
164
166
 
165
167
  /**
166
- * The name a generated page calls this project by: `review.projectName` when
167
- * set, else the project folder's name in the PRIMARY checkout.
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.
168
171
  *
169
172
  * NEVER THE CWD'S NAME. A worktree's folder is named after its spec, so a page
170
173
  * rendered from one would repeat the spec name where the project's belongs —
@@ -172,11 +175,39 @@ function attachProject(config, anchor) {
172
175
  * is none: cannot tell, and the pages then render exactly as they did before.
173
176
  */
174
177
  function projectName(config) {
175
- const set = config && config.review && config.review.projectName
176
- if (typeof set === 'string' && set.trim()) return set.trim()
177
- const p = config && config.project
178
- if (!p || !p.root) return null
179
- return path.basename(projectIn(p.root, p.prefix || '')) || null
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
180
211
  }
181
212
 
182
213
  /**
@@ -206,12 +237,12 @@ function shellPath(p, platform = process.platform) {
206
237
 
207
238
  /** The repo root a config was loaded for, else `dir` — today's behaviour. */
208
239
  function repoRootOf(dir, config) {
209
- return (config && config.project && config.project.root) || dir
240
+ return (config && config.checkout && config.checkout.root) || dir
210
241
  }
211
242
 
212
243
  /** The project prefix a config was loaded for, else `''`. */
213
244
  function prefixOf(config) {
214
- return (config && config.project && config.project.prefix) || ''
245
+ return (config && config.checkout && config.checkout.prefix) || ''
215
246
  }
216
247
 
217
248
  /**
@@ -235,6 +266,8 @@ module.exports = {
235
266
  shellPath,
236
267
  attachProject,
237
268
  projectName,
269
+ projectCategory,
270
+ describeProject,
238
271
  repoRootOf,
239
272
  prefixOf,
240
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/serve.js CHANGED
@@ -46,6 +46,7 @@ const { primaryAnchor, attachProject, projectName, repoRootOf, prefixOf, fromRep
46
46
  const { specDocsIn, classifyDirtyTree, dirtyPaths } = require('./classify.js')
47
47
  const { liveStateFor } = require('./live.js')
48
48
  const { preferRemoteBase } = require('./host.js')
49
+ const { ROUTE: TADA_ROUTE, renderServedTada } = require('../tada/serve.js')
49
50
  const {
50
51
  rawGitReader,
51
52
  collectReview,
@@ -96,6 +97,9 @@ function routeFor(url, { token = null } = {}) {
96
97
 
97
98
  if (segments.length === 0) return { kind: 'index' }
98
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 || '' }
99
103
 
100
104
  // `?pass=<code>` asks what became of ONE pass, and it is checked BEFORE
101
105
  // `?branch` because it is not a view of the diff at all — it is the page
@@ -812,7 +816,7 @@ function readBody(req, limit = MAX_PASS_BYTES) {
812
816
  })
813
817
  }
814
818
 
815
- function createReviewServer({ resolveEntries, resolveEpics = () => [], render, receive = null, passState = null, token = null, project = null }) {
819
+ function createReviewServer({ resolveEntries, resolveEpics = () => [], render, receive = null, passState = null, tada = null, token = null, project = null }) {
816
820
  return http.createServer((req, res) => {
817
821
  const send = (code, body, type = 'text/html; charset=utf-8') => {
818
822
  res.writeHead(code, { 'content-type': type, 'cache-control': 'no-store' })
@@ -865,6 +869,20 @@ function createReviewServer({ resolveEntries, resolveEpics = () => [], render, r
865
869
  return send(200, JSON.stringify({ state }), 'application/json; charset=utf-8')
866
870
  }
867
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
+
868
886
  try {
869
887
  if (route.kind === 'index') return send(200, renderIndex(resolveEntries(), { token, epics: resolveEpics(), project }))
870
888
  const out = render(route.spec, { branch: route.branch })
@@ -1073,6 +1091,15 @@ function serverHooks(dir, config) {
1073
1091
  if (!one) return { state: 'unknown' }
1074
1092
  return readPassState(reviewOutPath(dir, one.folder, null), one.folder, code)
1075
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
+ }),
1076
1103
  }
1077
1104
  }
1078
1105
 
package/src/init.js CHANGED
@@ -9,6 +9,7 @@ const { ensureWorktreeDirTrusted } = require('./env/trust.js')
9
9
  const { ensureHooks } = require('./env/hooks.js')
10
10
  const { repoInfo, expandTokens } = require('./env/resolve.js')
11
11
  const { primaryAnchor } = require('./env/project.js')
12
+ const { setProjectKeys } = require('./env/projectedit.js')
12
13
 
13
14
  const ASSETS = path.join(__dirname, '..', 'assets')
14
15
 
@@ -691,7 +692,7 @@ function installCore(dir, opts) {
691
692
  // Only called when the operator opts in, and never on `update` (adopting isolation
692
693
  // is a deliberate choice, not something a re-sync flips on). Idempotent: writeFile
693
694
  // never clobbers an existing env.config.json without --force.
694
- function installIsolation(dir, { enabled, workspaceMode }, opts) {
695
+ function installIsolation(dir, { enabled, workspaceMode, project = {} }, opts) {
695
696
  if (!enabled) return
696
697
  const target = path.join(dir, 'specs', '.core', 'env.config.json')
697
698
  copyAsset(dir, path.join('core', 'env.config.json.example'), target, opts)
@@ -705,6 +706,13 @@ function installIsolation(dir, { enabled, workspaceMode }, opts) {
705
706
  parsed.mode = 'checkout'
706
707
  fs.writeFileSync(target, `${JSON.stringify(parsed, null, 2)}\n`)
707
708
  }
709
+ // --name / --category, edited in rather than regenerated, so a config the
710
+ // operator already customized keeps everything but the two values asked for.
711
+ if ((typeof project.name === 'string' || typeof project.category === 'string') && fs.existsSync(target)) {
712
+ const text = fs.readFileSync(target, 'utf8')
713
+ const edited = setProjectKeys(text, project)
714
+ if (edited !== text) fs.writeFileSync(target, edited)
715
+ }
708
716
  trustWorktreeRoot(dir)
709
717
  }
710
718
 
@@ -1137,7 +1145,7 @@ function suggestReleaseWith(dir) {
1137
1145
  )
1138
1146
  }
1139
1147
 
1140
- async function init({ dir, force, claudeMd, mode, isolation, workspaceMode, gating }) {
1148
+ async function init({ dir, force, claudeMd, mode, isolation, workspaceMode, gating, project }) {
1141
1149
  if (!fs.existsSync(dir)) throw new Error(`target dir does not exist: ${dir}`)
1142
1150
  resetReport()
1143
1151
 
@@ -1149,7 +1157,7 @@ async function init({ dir, force, claudeMd, mode, isolation, workspaceMode, gati
1149
1157
  removeRetiredFiles(dir)
1150
1158
  installCore(dir, { force })
1151
1159
  // Adopting isolation writes the live env.config.json — init only, never update.
1152
- if (mode !== 'update') installIsolation(dir, { enabled: isolation, workspaceMode }, { force })
1160
+ if (mode !== 'update') installIsolation(dir, { enabled: isolation, workspaceMode, project }, { force })
1153
1161
  if (mode !== 'update') installGating(dir, { enabled: gating }, { force })
1154
1162
  if (claudeMd) installClaudeMd(dir, { mode })
1155
1163
  suggestReleaseWith(dir)