@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.
- package/assets/commands/epic.md +21 -0
- package/assets/core/env.config.json.example +1 -0
- package/assets/core/env.config.md +16 -5
- package/assets/review/page.html +9 -0
- package/assets/rules/spec-planning.md +48 -11
- package/assets/rules/spec-reports.md +8 -1
- package/assets/skills/spec/SKILL.md +30 -13
- package/assets/skills/spec-cancel/SKILL.md +7 -0
- package/assets/skills/spec-next/SKILL.md +38 -1
- package/assets/skills/spec-start/SKILL.md +30 -3
- package/bin/skitterspec-jira.js +5 -0
- package/package.json +1 -1
- package/src/cli.js +216 -57
- package/src/env/config.js +47 -6
- package/src/env/epic.js +55 -26
- package/src/env/epicpage.js +129 -0
- package/src/env/epicread.js +147 -0
- package/src/env/inflight.js +2 -0
- package/src/env/integrate.js +48 -1
- package/src/env/nextaction.js +262 -0
- package/src/env/project.js +18 -0
- package/src/env/review.js +21 -3
- package/src/env/serve.js +73 -7
- package/src/env/specbranches.js +120 -0
- package/src/env/teardown.js +18 -3
- package/src/gating.js +16 -4
- package/src/vendor/provider-kit/src/apply.js +25 -1
- package/src/vendor/sync-core/src/compare.js +10 -2
- package/src/vendor/sync-core/src/push.js +14 -3
|
@@ -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) => ({ '&': '&', '<': '<', '>': '>', '"': '"' })[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>> **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 }
|
package/src/env/inflight.js
CHANGED
|
@@ -18,6 +18,7 @@ const path = require('node:path')
|
|
|
18
18
|
|
|
19
19
|
const { readSpecState } = require('./specstate.js')
|
|
20
20
|
const { progressText } = require('./phases.js')
|
|
21
|
+
const { actionText } = require('./nextaction.js')
|
|
21
22
|
|
|
22
23
|
/**
|
|
23
24
|
* @param {object} a
|
|
@@ -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.
|
package/src/env/integrate.js
CHANGED
|
@@ -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 }
|
package/src/env/project.js
CHANGED
|
@@ -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,
|