@skitterbyte/skitterspec-jira 2.6.0 → 2.8.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.
@@ -0,0 +1,129 @@
1
+ 'use strict'
2
+
3
+ /**
4
+ * The epic page the review server serves at `/<token>/epic-<name>` — the same
5
+ * answer `skitterspec epic status` prints, as a page that refreshes itself
6
+ * (spec feat-epic-next, Decisions 5–7). PURE: it takes the answer `epicAnswer`
7
+ * built and returns HTML.
8
+ *
9
+ * READ-ONLY. It carries no verdict buttons and no form; a member whose page is
10
+ * waiting is a link to that page, where the buttons already are.
11
+ *
12
+ * NO PASS CODE, EVER. The server keeps every route from listing what is
13
+ * waiting — the six digits are an address only the reader's own page shows —
14
+ * so a waiting pass is named here by what to type, never by its code.
15
+ *
16
+ * LINKS ARE RELATIVE. The page is opened through whichever door the reader
17
+ * has — loopback, LAN, tailnet — and `feat-a` resolves against that door, so
18
+ * no cell ever has to list tiers.
19
+ */
20
+
21
+ const { actionText } = require('./nextaction.js')
22
+
23
+ const REFRESH_SECONDS = 30
24
+
25
+ function escapeHtml(s) {
26
+ return String(s).replace(/[&<>"]/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;' })[c])
27
+ }
28
+
29
+ const href = (spec) => escapeHtml(encodeURIComponent(spec))
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
+ function memberCell(row) {
44
+ // An in-flight member with a tab has a page of its own on this server.
45
+ return row.tab ? `<a href="${href(row.spec)}">${escapeHtml(row.spec)}</a>` : escapeHtml(row.spec)
46
+ }
47
+
48
+ function syncLine({ spec, phase, wait }) {
49
+ const who = phase === null ? `${spec} starts` : `${spec} phase ${phase}`
50
+ const mark = { met: 'met', unmet: 'not yet', 'cannot-tell': 'cannot tell' }[wait.state]
51
+ return `${who} after ${wait.raw} (${mark})`
52
+ }
53
+
54
+ function renderEpicPage(answer, { refreshSeconds = REFRESH_SECONDS, project = null } = {}) {
55
+ 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>`
68
+ : `<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>` : ''
70
+ const shape = [
71
+ ['waves', answer.waves.map((w, i) => `${i + 1}: ${w.join(', ')}`).join(' · ')],
72
+ ['sync points', answer.syncPoints.map(syncLine).join(' · ')],
73
+ ['never together', answer.clashes.map((c) => `${c.specs.join(' ‖ ')}`).join(' · ')],
74
+ ['cycle', answer.cycles.map((c) => c.join(' → ')).join(' · ')],
75
+ ]
76
+ .filter(([, v]) => v)
77
+ .map(([k, v]) => `<dt>${k}</dt><dd>${escapeHtml(v)}</dd>`)
78
+ .join('\n')
79
+
80
+ return `<!doctype html>
81
+ <html lang="en">
82
+ <head>
83
+ <meta charset="utf-8">
84
+ <meta name="viewport" content="width=device-width, initial-scale=1">
85
+ <meta http-equiv="refresh" content="${Number(refreshSeconds)}">
86
+ <title>${project ? `${escapeHtml(project)} · ` : ''}${escapeHtml(answer.epic)}</title>
87
+ <style>
88
+ :root { --bg:#fff; --fg:#1a1a1a; --dim:#6b6b6b; --line:#e3e3e3; --link:#0b5fbd; --hot:#a15c00 }
89
+ @media (prefers-color-scheme: dark) {
90
+ :root:not([data-theme="light"]) { --bg:#16181c; --fg:#e6e6e6; --dim:#9a9a9a; --line:#2c2f36; --link:#7cb7ff; --hot:#f0b35a }
91
+ }
92
+ * { box-sizing:border-box }
93
+ body { margin:0; padding:2rem 1rem; background:var(--bg); color:var(--fg);
94
+ font:15px/1.5 ui-sans-serif,system-ui,-apple-system,Segoe UI,Roboto,sans-serif }
95
+ main { max-width:60rem; margin:0 auto }
96
+ h1 { font-size:1.1rem; margin:0 0 .25rem; font-weight:600 }
97
+ .eyebrow { color:var(--dim); font-size:.8rem; margin:0 0 .1rem }
98
+ .sub { color:var(--dim); margin:0 0 1.25rem }
99
+ .wrap { overflow-x:auto }
100
+ table { border-collapse:collapse; width:100% }
101
+ th { text-align:left; color:var(--dim); font-weight:500; font-size:.85em }
102
+ th, td { padding:.55rem .6rem .55rem 0; border-top:1px solid var(--line); vertical-align:top }
103
+ a { color:var(--link); text-decoration:none; font-weight:600 }
104
+ a:hover { text-decoration:underline }
105
+ 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 }
110
+ dt { color:var(--dim) } dd { margin:0 }
111
+ .empty, .foot { color:var(--dim) }
112
+ .foot { margin-top:1.5rem; font-size:.85em }
113
+ </style>
114
+ </head>
115
+ <body>
116
+ <main>
117
+ ${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>` : ''}
122
+ <p class="foot">Refreshes every ${Number(refreshSeconds)} s. Type commands in the member's own tab.</p>
123
+ </main>
124
+ </body>
125
+ </html>
126
+ `
127
+ }
128
+
129
+ module.exports = { renderEpicPage, REFRESH_SECONDS }
@@ -0,0 +1,147 @@
1
+ 'use strict'
2
+
3
+ /**
4
+ * The disk half of an epic's answer, shared by the CLI (`skitterspec epic
5
+ * status`) and the review server's epic page (spec feat-epic-next, Decision 5),
6
+ * so a page and a terminal opened side by side cannot read the same epic two
7
+ * ways.
8
+ *
9
+ * Waits are read off the BASE BRANCH by git, never off whatever the primary
10
+ * checkout has checked out; each member's progress and review state off its
11
+ * OWN worktree, where they are true (`env/epic.js`).
12
+ */
13
+
14
+ const fs = require('node:fs')
15
+ const path = require('node:path')
16
+
17
+ const { isEpic } = require('./resolve.js')
18
+ const { epicStatus, epicHeaders, indexSpecTree } = require('./epic.js')
19
+ const { epicRows, readNextInputs } = require('./nextaction.js')
20
+ const { reviewOutPath } = require('./review.js')
21
+
22
+ /**
23
+ * The base branch's spec tree: `{ index, readFile, candidates }`, or null when
24
+ * the branch cannot be read — cannot-tell, never an empty plan.
25
+ */
26
+ function epicTree(git, base) {
27
+ const listing = git(['ls-tree', '-r', '--name-only', base, '--', 'specs'])
28
+ if (listing === null) return null
29
+ // `git grep` exits 1 on no match, which the reader returns as null. The tree
30
+ // above was readable, so here null is "no spec names an epic".
31
+ const grep = git(['grep', '-l', '-E', '^>[[:space:]]*\\*\\*Epic:\\*\\*', base, '--', 'specs'])
32
+ const candidates = (grep || '')
33
+ .split('\n')
34
+ .filter(Boolean)
35
+ .map((l) => l.slice(base.length + 1))
36
+ return { index: indexSpecTree(listing), readFile: (p) => git(['show', `${base}:${p}`]), candidates }
37
+ }
38
+
39
+ /**
40
+ * The same shape as `epicTree`, read off a WORKING TREE on disk — uncommitted
41
+ * edits included. It is what `epic status --here` reads members and headers
42
+ * from, so a conversion can be checked in the worktree it is made in before it
43
+ * lands. Waits are still met only on the base branch: that is the caller's
44
+ * `waitIndex`, never this.
45
+ *
46
+ * WHAT WOULD FOOL THIS: a file git would ignore is read like any other. Under
47
+ * `specs/` there is nothing ignored by design, so the cost is a stray editor
48
+ * backup named `*.md`, read as one more phase file.
49
+ */
50
+ function workingTree(root) {
51
+ const files = []
52
+ const walk = (rel) => {
53
+ let entries
54
+ try {
55
+ entries = fs.readdirSync(path.join(root, rel), { withFileTypes: true })
56
+ } catch {
57
+ return
58
+ }
59
+ for (const e of entries) {
60
+ const p = `${rel}/${e.name}`
61
+ if (e.isDirectory()) walk(p)
62
+ else if (e.isFile()) files.push(p)
63
+ }
64
+ }
65
+ walk('specs')
66
+ const readFile = (p) => {
67
+ try {
68
+ return fs.readFileSync(path.join(root, p), 'utf8')
69
+ } catch {
70
+ return null
71
+ }
72
+ }
73
+ const candidates = files.filter((p) => p.endsWith('/00-overview.md') && /^>\s*\*\*Epic:\*\*/m.test(readFile(p) || ''))
74
+ return { index: indexSpecTree(files.join('\n')), readFile, candidates }
75
+ }
76
+
77
+ // A provisioned spec's own overview and bucket, read in its worktree — the
78
+ // copy where an in-flight spec's bucket and headers are true. null when the
79
+ // worktree holds no readable copy.
80
+ function worktreeOverview(root, folder) {
81
+ for (const bucket of ['in-progress', 'backlog', 'complete', 'cancelled']) {
82
+ const dir = path.join(root, 'specs', bucket, folder)
83
+ let overview
84
+ try {
85
+ overview = fs.readFileSync(path.join(dir, '00-overview.md'), 'utf8')
86
+ } catch {
87
+ continue
88
+ }
89
+ const phases = fs
90
+ .readdirSync(dir)
91
+ .filter((f) => /^\d\d-.+\.md$/.test(f) && f !== '00-overview.md')
92
+ .map((f) => {
93
+ let text = null
94
+ try {
95
+ text = fs.readFileSync(path.join(dir, f), 'utf8')
96
+ } catch {
97
+ // unreadable: a phase with nothing to say
98
+ }
99
+ return { n: Number(f.slice(0, 2)), text }
100
+ })
101
+ return { folder, bucket, overview, phases, root }
102
+ }
103
+ return null
104
+ }
105
+
106
+ // Epics with a member, or themselves, in flight on this machine — what a bare
107
+ // `epic status` offers when it cannot tell which one was meant, and what the
108
+ // review server's index lists.
109
+ function epicsInFlight(worktrees) {
110
+ const open = worktrees.filter((w) => w.bucket !== 'complete' && w.bucket !== 'cancelled')
111
+ const names = open.map((w) => (isEpic(w.folder) ? w.folder : epicHeaders(w.overview).epic)).filter(Boolean)
112
+ return [...new Set(names)].sort()
113
+ }
114
+
115
+ /**
116
+ * The callbacks `epicRows` reads each member through: its own worktree, the
117
+ * review sidecars beside its page in the primary checkout, and a link to that
118
+ * page from `linkFor` — absolute for a terminal, relative for the served page.
119
+ */
120
+ function memberReaders({ dir, config, worktrees, linkFor = () => null, git }) {
121
+ const own = new Map(worktrees.map((w) => [w.folder, w]))
122
+ return {
123
+ inputsFor: (spec) => {
124
+ const w = own.get(spec)
125
+ if (!w) return null
126
+ return readNextInputs({
127
+ folder: spec,
128
+ bucket: w.bucket,
129
+ worktree: w.root,
130
+ outPath: reviewOutPath(dir, spec),
131
+ required: config ? config.review.required : true,
132
+ git: git(w.root),
133
+ })
134
+ },
135
+ tabFor: (spec) => (own.has(spec) ? path.relative(path.dirname(dir), own.get(spec).root) : null),
136
+ linkFor,
137
+ }
138
+ }
139
+
140
+ /** The whole answer for one epic: `epicStatus` plus a row per member. */
141
+ function epicAnswer(epic, inputs, readers) {
142
+ const status = epicStatus({ epic, ...inputs })
143
+ const { rows, next } = epicRows(status, readers)
144
+ return { ...status, rows, next }
145
+ }
146
+
147
+ module.exports = { epicTree, workingTree, worktreeOverview, epicsInFlight, memberReaders, epicAnswer }
@@ -18,6 +18,7 @@ const path = require('node:path')
18
18
 
19
19
  const { readSpecState } = require('./specstate.js')
20
20
  const { progressText } = require('./phases.js')
21
+ const { actionText } = require('./nextaction.js')
21
22
 
22
23
  /**
23
24
  * @param {object} a
@@ -84,6 +85,7 @@ function formatInFlight(rows, { dir }) {
84
85
  const row = (r, indent) => {
85
86
  out.push(`${indent}${r.spec.padEnd(width)} ${detailOf(r)}`)
86
87
  out.push(`${indent} ${path.relative(dir, r.worktree) || r.worktree}`)
88
+ if (r.next) out.push(`${indent} next: ${actionText(r.next)}`)
87
89
  }
88
90
  // Members are listed under their epic, read off each spec's own copy; a spec
89
91
  // in no epic — the common case — prints exactly as it always has.
@@ -243,6 +243,53 @@ function planIntegratePr(spec, config, ctx) {
243
243
  }
244
244
  }
245
245
 
246
+ /**
247
+ * Pure planner for the AUTHORING land of a spec document under
248
+ * `land.specDocs: "branch"` (`spec-env integrate --docs`).
249
+ *
250
+ * The document rides its own branch rather than landing on base, so the plan
251
+ * touches no base at all — no rebase, no fast-forward, no PR. What it does is
252
+ * publish the branch, because a spec on an unpushed branch is on one machine
253
+ * and nowhere else (the ticket's summary block cannot rebuild it). The push is
254
+ * consent-gated with `planIntegratePr`'s shape: already on the remote at HEAD
255
+ * is honoured (`via: "remote"`), `--push` is the recorded yes (`via: "push"`),
256
+ * otherwise it HOLDS (`via: "hold"`) with the push in `holdCommands`.
257
+ *
258
+ * NO REMOTE IS A HOLD, NEVER AN ERROR. A clone with no remote of that name
259
+ * cannot publish, and refusing would accuse a healthy local-only repo; the
260
+ * plan says so (`noRemote`) and the spec stays on its local branch.
261
+ *
262
+ * ctx: { worktreeState: { dirty }, remote, treePath, remoteConfigured,
263
+ * pushedAtHead, push }
264
+ */
265
+ function planIntegrateDocs(spec, config, ctx) {
266
+ const { worktreeState = {}, treePath, remoteConfigured } = ctx || {}
267
+ const remote = (ctx && ctx.remote) || 'origin'
268
+ const branch = spec.branch
269
+ const result = {
270
+ blocked: false, noop: false, reason: null, commands: [],
271
+ push: null, holdCommands: [], noRemote: false,
272
+ afterLand: noAfterLand(), branch, remote,
273
+ }
274
+
275
+ // The verdict's commit ran first, so anything still uncommitted is not this
276
+ // spec's — and a push would publish a branch missing it.
277
+ if (worktreeState.dirty) {
278
+ return { ...result, blocked: true, reason: 'worktree has uncommitted changes — commit the spec first' }
279
+ }
280
+ if (!remoteConfigured) {
281
+ return { ...result, noRemote: true, push: { kind: 'push', via: 'hold', remote, branch } }
282
+ }
283
+ if (ctx.pushedAtHead) {
284
+ return { ...result, noop: true, push: { kind: 'push', via: 'remote', remote, branch } }
285
+ }
286
+ const pushCommand = `git -C ${shellPath(treePath)} push -u ${remote} ${branch}`
287
+ if (ctx.push) {
288
+ return { ...result, commands: [pushCommand], push: { kind: 'push', via: 'push', remote, branch } }
289
+ }
290
+ return { ...result, push: { kind: 'push', via: 'hold', remote, branch }, holdCommands: [pushCommand] }
291
+ }
292
+
246
293
  // The after-land half of a plan: `config.afterLand`, to run in `cwd` (the
247
294
  // primary checkout, standing on base) once the land commands have succeeded.
248
295
  // A blocked plan carries the empty form — nothing landed, so nothing follows.
@@ -291,4 +338,4 @@ function noAfterLand() {
291
338
  return { cwd: null, commands: [], entries: [], range: null }
292
339
  }
293
340
 
294
- module.exports = { planIntegrate, planIntegrateCheckout, planIntegratePr, afterLandFor, rangeOf }
341
+ module.exports = { planIntegrate, planIntegrateCheckout, planIntegratePr, planIntegrateDocs, afterLandFor, rangeOf }
@@ -0,0 +1,262 @@
1
+ 'use strict'
2
+
3
+ /**
4
+ * The one thing to do next for a spec, and where — the cell behind the `next`
5
+ * column of `skitterspec epic status` and `skitterspec status` (spec
6
+ * feat-epic-next, Decision 1).
7
+ *
8
+ * `nextAction` is pure: every input arrives already read, with `null` meaning
9
+ * the reader could not tell. `readNextInputs` is the half that touches disk —
10
+ * the gate, the pending store, the worktree's tree and its phase files — and
11
+ * its io is injectable so the command layer is testable without a worktree.
12
+ *
13
+ * Positive signals only (`.claude/rules/negative-checks.md`). A verb is a
14
+ * claim about the spec, so every input that is unreadable routes to
15
+ * `cannot-tell` and never to a verb: telling someone to `/spec-complete` a spec
16
+ * whose phase files could not be read is the accusation this exists to avoid.
17
+ */
18
+
19
+ const fs = require('node:fs')
20
+ const path = require('node:path')
21
+
22
+ const { phaseIsDone } = require('./resolve.js')
23
+ const { readGate, readPending, gateState } = require('./review.js')
24
+ const { dirtyPaths } = require('./classify.js')
25
+
26
+ const plural = (n, word) => `${n} ${word}${n === 1 ? '' : 's'}`
27
+
28
+ const tell = (state, why) => ({ verb: 'cannot-tell', state, command: null, link: null, why })
29
+
30
+ function backlogAction(spec, { waits = [], freeLanes = null, clashWith = [] }) {
31
+ const unmet = waits.filter((w) => w.state === 'unmet')
32
+ if (unmet.length) {
33
+ return { verb: 'blocked', state: 'backlog', command: null, link: null, why: `waits on ${unmet.map((w) => w.raw).join(', ')}` }
34
+ }
35
+ const unknown = waits.filter((w) => w.state !== 'met')
36
+ if (unknown.length) return tell('backlog', `cannot tell whether ${unknown.map((w) => w.raw).join(', ')} has landed`)
37
+ // Both qualifiers advise and never withhold the command: `Lanes:` is a cap
38
+ // the operator chose and `Area:` is declared rather than measured, so the
39
+ // operator may know better (spec feat-epics, Decision 4).
40
+ const held = []
41
+ if (freeLanes === 0) held.push('no free lane')
42
+ if (clashWith.length) held.push(`clashes with ${clashWith.join(', ')}`)
43
+ return {
44
+ verb: 'start',
45
+ state: 'backlog · ready',
46
+ command: `/spec-start ${spec}`,
47
+ link: null,
48
+ why: held.length ? held.join(' · ') : null,
49
+ }
50
+ }
51
+
52
+ /**
53
+ * @param {object} a
54
+ * - `spec` the spec's folder name
55
+ * - `bucket` where its own copy sits, or null when it could not be read
56
+ * - `phases` `[{ n, done }]` from its own copy, or null when unreadable
57
+ * - `gate` `armed` · `clear` · `off` (the project opted out) ·
58
+ * `unreadable`
59
+ * - `passes` codes of the passes waiting unclaimed, or null when the
60
+ * pending store could not be read
61
+ * - `dirty` uncommitted paths in its worktree, or null when git could
62
+ * not answer
63
+ * - `syncWaits` `[{ phase, state, raw }]` — this spec's phase-level waits
64
+ * - `waits` its start waits, resolved — a backlog member's only
65
+ * - `freeLanes` the epic's free lanes, or null with no cap
66
+ * - `clashWith` in-flight members whose `Area:` meets this one's
67
+ * @returns {{ verb, state, command, link, why }}
68
+ */
69
+ function nextAction(a) {
70
+ const { spec, bucket } = a
71
+ if (bucket === 'complete') return { verb: 'done', state: 'complete', command: null, link: null, why: null }
72
+ if (bucket === 'cancelled') return { verb: 'done', state: 'cancelled', command: null, link: null, why: null }
73
+ if (bucket === 'backlog') return backlogAction(spec, a)
74
+ if (bucket !== 'in-progress') return tell('unknown', `${spec}'s own copy could not be read`)
75
+
76
+ const phases = a.phases
77
+ if (phases === null || phases === undefined) return tell('in-progress', 'its phase files could not be read')
78
+ const done = phases.filter((p) => p.done).length
79
+ const progress = `phase ${Math.min(done + 1, phases.length)} of ${phases.length}`
80
+
81
+ // A pass first: someone already answered, and only a person in that tab can
82
+ // pick it up (`/spec-reviewed` is user-only by harness enforcement).
83
+ if (a.passes === null || a.passes === undefined) return tell(progress, 'the pending store is not readable')
84
+ if (a.passes.length === 1) {
85
+ return { verb: 'claim', state: `${progress} · pass waiting`, command: `/spec-reviewed ${a.passes[0]}`, link: null, why: null }
86
+ }
87
+ if (a.passes.length > 1) {
88
+ return {
89
+ verb: 'claim',
90
+ state: `${progress} · ${a.passes.length} passes waiting`,
91
+ command: '/spec-reviewed <code>',
92
+ link: null,
93
+ why: `name one: ${a.passes.join(', ')}`,
94
+ }
95
+ }
96
+
97
+ // `off` is a project that set `review.required: false` — silence, not a
98
+ // finding, so it falls through to the rest of the precedence.
99
+ if (a.gate === 'unreadable') return tell(progress, 'the review gate is not readable')
100
+ if (a.gate === 'armed') {
101
+ return { verb: 'verdict', state: `${progress} · page waits`, command: null, link: null, why: 'press a verdict on its page' }
102
+ }
103
+
104
+ // DIRTY WITH NO PHASE ENDED IS NOT "COMMIT". The engine cannot tell an agent
105
+ // mid-build from work left sitting, and `/commit` said to a tab that is
106
+ // building is the wrong advice — so it is a state with no verb (Decision 2).
107
+ if (a.dirty === null || a.dirty === undefined) return tell(progress, 'git could not read its worktree')
108
+ if (a.dirty > 0) {
109
+ return { verb: 'building', state: `${progress} · ${plural(a.dirty, 'file')} uncommitted`, command: null, link: null, why: 'building — nothing to run yet' }
110
+ }
111
+
112
+ // A spec with no phase files yet has nothing for `/spec-next` to build;
113
+ // naming the command would send the operator to a refusal.
114
+ if (!phases.length) return { verb: 'idle', state: 'no phase files', command: null, link: null, why: null }
115
+ if (done === phases.length) {
116
+ return { verb: 'complete', state: `${done} of ${phases.length} ✅ · clean`, command: '/spec-complete', link: null, why: null }
117
+ }
118
+
119
+ const next = phases.find((p) => !p.done).n
120
+ const held = (a.syncWaits || []).filter((w) => w.phase === next)
121
+ const unmet = held.filter((w) => w.state === 'unmet')
122
+ if (unmet.length) {
123
+ return { verb: 'held', state: progress, command: null, link: null, why: `phase ${next} waits on ${unmet.map((w) => w.raw).join(', ')}` }
124
+ }
125
+ const unknown = held.filter((w) => w.state !== 'met')
126
+ return {
127
+ verb: 'next',
128
+ state: progress,
129
+ command: '/spec-next',
130
+ link: null,
131
+ why: unknown.length ? `phase ${next} · cannot tell whether ${unknown.map((w) => w.raw).join(', ')} has landed` : `phase ${next}`,
132
+ }
133
+ }
134
+
135
+ /**
136
+ * The epic's own row: `/spec-complete <epic>` once no member is open, and
137
+ * nothing before — an epic completes after its members (feat-epics, Decision
138
+ * 7). An epic with no members has nothing to complete after, so it says
139
+ * nothing rather than inviting a completion of an empty plan.
140
+ */
141
+ function epicNext(epic, members) {
142
+ if (!members.length) return null
143
+ if (members.some((m) => m.bucket !== 'complete' && m.bucket !== 'cancelled')) return null
144
+ return { verb: 'complete', state: 'every member finished', command: `/spec-complete ${epic}`, link: null, why: null }
145
+ }
146
+
147
+ const defaultIo = {
148
+ readdir: (dir) => fs.readdirSync(dir),
149
+ readFile: (file) => fs.readFileSync(file, 'utf8'),
150
+ }
151
+
152
+ function tryRead(fn) {
153
+ try {
154
+ return fn()
155
+ } catch {
156
+ return null
157
+ }
158
+ }
159
+
160
+ /**
161
+ * A spec's phases as its own copy has them, `[{ n, done }]`, or null when the
162
+ * folder could not be read. Read in the worktree because that is the copy that
163
+ * is true for a spec being built; the base branch still files it in backlog.
164
+ */
165
+ function readPhases(root, bucket, folder, io = defaultIo) {
166
+ const dir = path.join(root, 'specs', bucket, folder)
167
+ const files = tryRead(() => io.readdir(dir))
168
+ if (!files) return null
169
+ const out = []
170
+ for (const f of files.filter((x) => /^(?!00-)\d{2}-.*\.md$/.test(x)).sort()) {
171
+ const text = tryRead(() => io.readFile(path.join(dir, f)))
172
+ // One unreadable phase makes the count a guess, and a guess here is what
173
+ // would print `/spec-complete` for a spec with a phase left to build.
174
+ if (text === null) return null
175
+ out.push({ n: Number(f.slice(0, 2)), done: phaseIsDone(text) })
176
+ }
177
+ return out
178
+ }
179
+
180
+ /**
181
+ * The disk half: everything `nextAction` needs about one in-flight spec that is
182
+ * not the epic's to say.
183
+ *
184
+ * @param {object} a
185
+ * - `folder` the spec
186
+ * - `bucket` its bucket in its own copy
187
+ * - `worktree` its worktree root
188
+ * - `outPath` its review page path in the primary checkout, where the gate
189
+ * and the pending store sit beside it
190
+ * - `required` `review.required` from the project config
191
+ * - `git` a reader for the worktree, `argv → stdout | null`
192
+ */
193
+ function readNextInputs({ folder, bucket, worktree, outPath, required, git, io = defaultIo }) {
194
+ const gateRead = readGate(outPath, folder)
195
+ const g = gateState({ ...gateRead, required })
196
+ // `unknown` covers three readings and only one is a fault: the project
197
+ // opting out is silence, a corrupt or newer sidecar is cannot-tell.
198
+ const gate = g.state === 'armed' ? 'armed' : g.state === 'clear' ? 'clear' : required === false ? 'off' : 'unreadable'
199
+ const pending = readPending(outPath, folder)
200
+ const passes = pending.corrupt ? null : pending.pending.passes.filter((p) => p && p.code).map((p) => p.code)
201
+ const dirty = dirtyPaths(git)
202
+ return {
203
+ bucket,
204
+ phases: bucket ? readPhases(worktree, bucket, folder, io) : null,
205
+ gate,
206
+ passes,
207
+ dirty: dirty === null ? null : dirty.length,
208
+ }
209
+ }
210
+
211
+ /**
212
+ * The `next` cell as words — one string shared by every rendering, so the
213
+ * terminal, `status` and the page cannot word the same action differently.
214
+ */
215
+ function actionText(a) {
216
+ if (!a) return '—'
217
+ if (a.verb === 'verdict') return a.link ? `verdict → ${a.link}` : 'verdict — /spec-diff in its tab'
218
+ if (a.verb === 'cannot-tell') return `cannot tell — ${a.why}`
219
+ if (a.command) return a.why ? `${a.command} — ${a.why}` : a.command
220
+ return a.why || '—'
221
+ }
222
+
223
+ /**
224
+ * One row per member, in `epicStatus` order: `{ spec, bucket, tab, next }`,
225
+ * plus the epic's own action. Pure — the disk arrives through three callbacks,
226
+ * each answering for one spec:
227
+ *
228
+ * - `inputsFor(spec)` → `readNextInputs`' answer, or null when the spec has
229
+ * no worktree on this machine
230
+ * - `tabFor(spec)` → where its tab stands, or null
231
+ * - `linkFor(spec)` → its served page, or null when nothing is serving
232
+ *
233
+ * An in-flight member with no worktree HERE is cannot-tell rather than
234
+ * guessed: it may be in flight on a colleague's machine, and its gate and its
235
+ * tree are there, not here.
236
+ */
237
+ function epicRows(status, { inputsFor = () => null, tabFor = () => null, linkFor = () => null } = {}) {
238
+ const flying = new Set(status.inFlight.map((m) => m.spec))
239
+ const rows = status.members.map((m) => {
240
+ const clashWith = status.clashes
241
+ .filter((c) => c.specs.includes(m.spec))
242
+ .map((c) => c.specs.find((x) => x !== m.spec))
243
+ .filter((x) => flying.has(x))
244
+ const syncWaits = status.syncPoints
245
+ .filter((p) => p.spec === m.spec && p.phase !== null)
246
+ .map((p) => ({ phase: p.phase, state: p.wait.state, raw: p.wait.raw }))
247
+ let next
248
+ if (m.bucket === 'in-progress') {
249
+ const inputs = inputsFor(m.spec)
250
+ next = inputs
251
+ ? nextAction({ spec: m.spec, ...inputs, bucket: 'in-progress', syncWaits })
252
+ : tell('in-progress', 'no worktree for it on this machine')
253
+ } else {
254
+ next = nextAction({ spec: m.spec, bucket: m.bucket, waits: m.waits, freeLanes: status.freeLanes, clashWith })
255
+ }
256
+ if (next.verb === 'verdict') next = { ...next, link: linkFor(m.spec) }
257
+ return { spec: m.spec, bucket: m.bucket, tab: m.bucket === 'in-progress' ? tabFor(m.spec) : null, next }
258
+ })
259
+ return { rows, next: epicNext(status.epic, status.members) }
260
+ }
261
+
262
+ module.exports = { nextAction, epicNext, epicRows, actionText, readNextInputs, readPhases }
@@ -162,6 +162,23 @@ function attachProject(config, anchor) {
162
162
  return config
163
163
  }
164
164
 
165
+ /**
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
+ *
169
+ * NEVER THE CWD'S NAME. A worktree's folder is named after its spec, so a page
170
+ * rendered from one would repeat the spec name where the project's belongs —
171
+ * which is why this reads the anchor `attachProject` recorded. `null` when there
172
+ * is none: cannot tell, and the pages then render exactly as they did before.
173
+ */
174
+ 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
180
+ }
181
+
165
182
  /**
166
183
  * A path as one shell word, for the commands the engine PRINTS for a person or
167
184
  * a skill to run. Quoted only when it has to be, so a path without spaces or
@@ -217,6 +234,7 @@ module.exports = {
217
234
  toPosix,
218
235
  shellPath,
219
236
  attachProject,
237
+ projectName,
220
238
  repoRootOf,
221
239
  prefixOf,
222
240
  projectLine,