@skitterbyte/skitterspec-jira 2.6.0 → 2.7.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/rules/spec-planning.md +8 -0
- package/assets/skills/spec-start/SKILL.md +30 -3
- package/package.json +1 -1
- package/src/cli.js +89 -47
- package/src/env/epic.js +33 -19
- package/src/env/epicpage.js +128 -0
- package/src/env/epicread.js +109 -0
- package/src/env/inflight.js +2 -0
- package/src/env/nextaction.js +262 -0
- package/src/env/serve.js +61 -4
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
---
|
|
2
|
+
description: What every member of an epic needs next, in which tab, and the epic page — bare uses the epic or member worktree you are in
|
|
3
|
+
argument-hint: "[<epic>]"
|
|
4
|
+
allowed-tools: Bash({{exec}} skitterspec epic status:*)
|
|
5
|
+
disable-model-invocation: true
|
|
6
|
+
---
|
|
7
|
+
!`{{exec}} skitterspec epic status $ARGUMENTS`
|
|
8
|
+
|
|
9
|
+
Relay the engine output above verbatim. Add nothing and run nothing else.
|
|
10
|
+
|
|
11
|
+
**It is for coming back to the epic's tab.** Each member is built in a tab of
|
|
12
|
+
its own; this one is where you return to see what each needs. On a phone the
|
|
13
|
+
in-app browser closes to switch tabs, so the epic page's link is what you came
|
|
14
|
+
back for — it is the last thing printed.
|
|
15
|
+
|
|
16
|
+
**It reads, and nothing more.** It starts no server, claims no pass and runs no
|
|
17
|
+
member's next command: those are typed in that member's own tab. A waiting pass
|
|
18
|
+
it names is picked up there with `/spec-reviewed`.
|
|
19
|
+
|
|
20
|
+
**Only you can run it**, for `/spec-connect`'s reason: there is no judgement to
|
|
21
|
+
apply, so no model turn is spent finding one.
|
|
@@ -124,6 +124,14 @@ skip — never a flag. Putting the flag on `/commit` was the other suggestion an
|
|
|
124
124
|
is worse: `/commit` belongs to skittership, which is why the gate is enforced
|
|
125
125
|
by a hook rather than by editing that skill.
|
|
126
126
|
|
|
127
|
+
**`/epic` is the sixth command**, and it is user-only for the mild reason: it
|
|
128
|
+
pre-executes `skitterspec epic status` and relays it, so there is no judgement
|
|
129
|
+
to apply. It exists for the tab an epic is run from — each member is built in
|
|
130
|
+
a tab of its own, and on a phone the in-app browser has to close to switch
|
|
131
|
+
tabs, so the epic page's link has to be one command away rather than scrolled
|
|
132
|
+
past. Bare, it means the epic of the worktree it runs in. It reads and nothing
|
|
133
|
+
more: the next action it names for a member is typed in that member's tab.
|
|
134
|
+
|
|
127
135
|
**A refusal may OFFER its own exit, and that is a different thing again.**
|
|
128
136
|
Where the engine declares one, a skill relays the refusal and **then** offers it
|
|
129
137
|
— once per obligation, with the choice recorded, and answered by the operator
|
|
@@ -451,8 +451,31 @@ invoke it yourself.
|
|
|
451
451
|
|
|
452
452
|
**An epic has no phase 1.** `spec-env up` gives it a documents-only tree (no
|
|
453
453
|
`setup`, no Docker) whether or not `--docs` was passed, because its work is its
|
|
454
|
-
members'. Skip this step and step 5, end with the block
|
|
455
|
-
|
|
454
|
+
members'. Skip this step and step 5, and end with the block — but first ask
|
|
455
|
+
what the epic needs started:
|
|
456
|
+
|
|
457
|
+
```
|
|
458
|
+
skitterspec epic status <name> --json
|
|
459
|
+
```
|
|
460
|
+
|
|
461
|
+
Its `rows` carry each member's next action, and its `page` the epic page's
|
|
462
|
+
tiers. Two things go in the block, both copied from it rather than composed:
|
|
463
|
+
|
|
464
|
+
- **`Next`** names the first members to start — one `/spec-start <member>`
|
|
465
|
+
for each row whose `next.verb` is `start`, **in a new tab each**, and only as
|
|
466
|
+
many as there are free lanes (`freeLanes`; all of them when it is null). A
|
|
467
|
+
start qualified `no free lane` or `clashes with …` is not offered here. None
|
|
468
|
+
ready is a true answer: say what the first wave waits on.
|
|
469
|
+
- **`Review`** carries the epic page's stack — `local`, `network`, `remote`,
|
|
470
|
+
as `page.tiers` gives them — or, where `page.off`, the command that starts
|
|
471
|
+
the server. It is a page to come back to, not one to answer: nothing waits
|
|
472
|
+
on it, so it is the row and never the banner.
|
|
473
|
+
|
|
474
|
+
**This tab is the epic's from here.** The members are built in tabs of their
|
|
475
|
+
own; this one is where the operator comes back to see what each needs. On a
|
|
476
|
+
phone the in-app browser has to close to switch tabs, so the page link must be
|
|
477
|
+
one command away rather than scrolled past: **`/epic`** re-shows the table and
|
|
478
|
+
the page, and the block names it.
|
|
456
479
|
|
|
457
480
|
**`checkout` mode — carry straight on into `/spec-next`** in this session: it
|
|
458
481
|
marks phase 1 started, refreshes the mirror again, builds it with tests and
|
|
@@ -518,11 +541,15 @@ the shape; this section carries only what is specific here.
|
|
|
518
541
|
is **not** on this list in `worktree` mode — it is an `Untouched` row on a
|
|
519
542
|
`✅`.
|
|
520
543
|
|
|
521
|
-
**Fields:** `Tracker` · `Branch` · `Spec` · `Worktree` · `Untouched` · `Follow-ups` · `Next`
|
|
544
|
+
**Fields:** `Tracker` · `Branch` · `Spec` · `Worktree` · `Untouched` · `Review` · `Follow-ups` · `Next`
|
|
522
545
|
|
|
523
546
|
`Worktree` carries the path, because the session is now standing in it and the
|
|
524
547
|
operator's next command depends on knowing that. `Next` is `/spec-next`.
|
|
525
548
|
|
|
549
|
+
**An epic is the one exception, both ways.** `Review` appears only for an epic,
|
|
550
|
+
carrying its page's stack, and its `Next` is the members to start in new tabs
|
|
551
|
+
— with `/epic` to bring the table and the page back (step 6).
|
|
552
|
+
|
|
526
553
|
`Untouched` appears only when `spec-env up` reported uncommitted work that was
|
|
527
554
|
not this spec's — say how much and whose, and **keep the verdict `✅`**. Nothing
|
|
528
555
|
went wrong: a worktree carries nothing, so that work was never in play.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@skitterbyte/skitterspec-jira",
|
|
3
|
-
"version": "2.
|
|
3
|
+
"version": "2.7.0",
|
|
4
4
|
"description": "Spec-driven development for Claude Code, with one-way Jira Cloud sync — a superset of @skitterbyte/skitterspec: the base filesystem workflow plus /spec-status · /spec-push and the spec-sync CLI. The repo is canonical; Jira is a generated mirror. Install this OR the base OR the Linear superset — exactly one.",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"claude",
|
package/src/cli.js
CHANGED
|
@@ -198,6 +198,8 @@ const {
|
|
|
198
198
|
appendChangelog,
|
|
199
199
|
waitsMetByRebase,
|
|
200
200
|
} = require('./env/epic.js')
|
|
201
|
+
const { nextAction, readNextInputs } = require('./env/nextaction.js')
|
|
202
|
+
const { epicTree, worktreeOverview, epicsInFlight, memberReaders, epicAnswer } = require('./env/epicread.js')
|
|
201
203
|
const { planHotfixLand, planBranchHotfixLand, planBranchHotfixFinish, planHotfixFinish } = require('./env/hotfix.js')
|
|
202
204
|
const { runHotfixLand, describeStep: describeHotfixStep } = require('./env/hotfixland.js')
|
|
203
205
|
const { planDev } = require('./env/dev.js')
|
|
@@ -565,7 +567,26 @@ function inFlightStatus(argv) {
|
|
|
565
567
|
const dir = anchor.dir
|
|
566
568
|
const { config, present } = loadEnvConfig(dir)
|
|
567
569
|
attachProject(config, anchor)
|
|
568
|
-
const rows = present ? collectInFlight({ dir, provisioned: provisionedSpecs(dir, config) }) : []
|
|
570
|
+
const rows = (present ? collectInFlight({ dir, provisioned: provisionedSpecs(dir, config) }) : []).map((r) =>
|
|
571
|
+
// Only a spec whose own copy was read, and which is still in flight, gets
|
|
572
|
+
// a next action — a finished or unreadable one has nothing true to offer.
|
|
573
|
+
isInFlight(r) && r.found
|
|
574
|
+
? {
|
|
575
|
+
...r,
|
|
576
|
+
next: nextAction({
|
|
577
|
+
spec: r.spec,
|
|
578
|
+
...readNextInputs({
|
|
579
|
+
folder: r.spec,
|
|
580
|
+
bucket: r.bucket,
|
|
581
|
+
worktree: r.worktree,
|
|
582
|
+
outPath: reviewOutPath(dir, r.spec),
|
|
583
|
+
required: config.review.required,
|
|
584
|
+
git: gitReader(r.worktree),
|
|
585
|
+
}),
|
|
586
|
+
}),
|
|
587
|
+
}
|
|
588
|
+
: r,
|
|
589
|
+
)
|
|
569
590
|
if (json) {
|
|
570
591
|
const specs = rows.map((r) => ({ ...r, inFlight: isInFlight(r) }))
|
|
571
592
|
process.stdout.write(JSON.stringify({ isolation: present, specs }, null, 2) + '\n')
|
|
@@ -586,15 +607,73 @@ function inFlightStatus(argv) {
|
|
|
586
607
|
*/
|
|
587
608
|
function epicStatusCommand(argv) {
|
|
588
609
|
const json = argv.includes('--json')
|
|
589
|
-
const
|
|
610
|
+
const named = epicPositional(argv)
|
|
611
|
+
const inputs = epicInputs(argv, json, named || null)
|
|
612
|
+
if (!inputs) return
|
|
613
|
+
const epic = named || epicFromHere(inputs)
|
|
590
614
|
if (!epic) {
|
|
591
|
-
|
|
615
|
+
const flying = epicsInFlight(inputs.worktrees)
|
|
616
|
+
const line = flying.length
|
|
617
|
+
? `name an epic — in flight here: ${flying.join(', ')}`
|
|
618
|
+
: 'name an epic — none has a member in flight here'
|
|
619
|
+
process.stdout.write(
|
|
620
|
+
json ? JSON.stringify({ epic: null, inFlight: flying }, null, 2) + '\n' : `Usage: skitterspec epic status [<epic>] [--json] [--dir <path>]\n${line}\n`,
|
|
621
|
+
)
|
|
592
622
|
return
|
|
593
623
|
}
|
|
594
|
-
const
|
|
595
|
-
|
|
596
|
-
|
|
597
|
-
|
|
624
|
+
const up = inputs.config ? readRunningReviewServer(inputs.dir, inputs.config) : null
|
|
625
|
+
const readers = memberReaders({
|
|
626
|
+
...inputs,
|
|
627
|
+
git: gitReader,
|
|
628
|
+
// A link only where a server is already serving: this reads the server and
|
|
629
|
+
// never starts one, so a status asked from a phone never restarts the
|
|
630
|
+
// server whose link that phone has open.
|
|
631
|
+
linkFor: (spec) => (up ? `${serveUrl('127.0.0.1', up)}${encodeURIComponent(spec)}` : null),
|
|
632
|
+
})
|
|
633
|
+
const answer = epicAnswer(epic, inputs, readers)
|
|
634
|
+
const page = epicPageTiers(inputs, up, epic)
|
|
635
|
+
if (json) {
|
|
636
|
+
process.stdout.write(JSON.stringify({ base: inputs.base, ...answer, page }, null, 2) + '\n')
|
|
637
|
+
return
|
|
638
|
+
}
|
|
639
|
+
// No such epic is a plain answer; a page link for it would be a link to nothing.
|
|
640
|
+
const found = answer.found || answer.members.length
|
|
641
|
+
process.stdout.write(formatEpicStatus(answer) + (found ? '\n' + epicPageLines(page) : ''))
|
|
642
|
+
}
|
|
643
|
+
|
|
644
|
+
/**
|
|
645
|
+
* Where the epic page can be read: the same tiers a review render prints, for
|
|
646
|
+
* the epic's own route — or, with no server running, the one command that
|
|
647
|
+
* starts it. Never null where isolation is configured, because the page is the
|
|
648
|
+
* thing a phone reader comes back to (Decision 8).
|
|
649
|
+
*/
|
|
650
|
+
function epicPageTiers(inputs, up, epic) {
|
|
651
|
+
if (!inputs.config) return null
|
|
652
|
+
if (!up) return { off: true, start: 'skitterspec spec-env review serve --host 0.0.0.0' }
|
|
653
|
+
const served = reviewServedUrls(up, offerableLanAddresses(), epic)
|
|
654
|
+
return { tiers: reviewTierStack({ served, fileUrl: null, publishedUrl: null, config: inputs.config }) }
|
|
655
|
+
}
|
|
656
|
+
|
|
657
|
+
function epicPageLines(page) {
|
|
658
|
+
if (!page) return ''
|
|
659
|
+
if (page.off) return `epic page: no review server running — start it with: ${page.start}\n`
|
|
660
|
+
return `epic page:\n${page.tiers.map(reviewTierLine).join('\n')}\n`
|
|
661
|
+
}
|
|
662
|
+
|
|
663
|
+
/**
|
|
664
|
+
* The epic a bare `epic status` means: the one whose worktree this command runs
|
|
665
|
+
* in, or the epic named by the member whose worktree it runs in. A positive
|
|
666
|
+
* signal or nothing — standing anywhere else names no epic, and the caller says
|
|
667
|
+
* so rather than picking one.
|
|
668
|
+
*/
|
|
669
|
+
function epicFromHere(inputs) {
|
|
670
|
+
const top = gitReader(process.cwd())(['rev-parse', '--show-toplevel'])
|
|
671
|
+
if (!top) return null
|
|
672
|
+
const here = path.resolve(top)
|
|
673
|
+
const own = inputs.worktrees.find((w) => here === path.resolve(w.root) || here.startsWith(path.resolve(w.root) + path.sep))
|
|
674
|
+
if (!own) return null
|
|
675
|
+
if (isEpic(own.folder)) return own.folder
|
|
676
|
+
return epicHeaders(own.overview).epic
|
|
598
677
|
}
|
|
599
678
|
|
|
600
679
|
/**
|
|
@@ -744,52 +823,15 @@ function epicInputs(argv, json, subject) {
|
|
|
744
823
|
} catch (err) {
|
|
745
824
|
return say(err.message)
|
|
746
825
|
}
|
|
747
|
-
const
|
|
748
|
-
if (
|
|
749
|
-
// `git grep` exits 1 on no match, which the reader returns as null. The tree
|
|
750
|
-
// above was readable, so here null is "no spec names an epic".
|
|
751
|
-
const grep = git(['grep', '-l', '-E', '^>[[:space:]]*\\*\\*Epic:\\*\\*', base, '--', 'specs'])
|
|
752
|
-
const candidates = (grep || '')
|
|
753
|
-
.split('\n')
|
|
754
|
-
.filter(Boolean)
|
|
755
|
-
.map((l) => l.slice(base.length + 1))
|
|
756
|
-
const readFile = (p) => git(['show', `${base}:${p}`])
|
|
826
|
+
const tree = epicTree(git, base)
|
|
827
|
+
if (!tree) return say(`the base branch ${base} could not be read`)
|
|
757
828
|
const worktrees = present
|
|
758
829
|
? provisionedSpecs(dir, config)
|
|
759
830
|
.filter((p) => !p.specless)
|
|
760
831
|
.map((p) => worktreeOverview(p.project, p.folder))
|
|
761
832
|
.filter(Boolean)
|
|
762
833
|
: []
|
|
763
|
-
return { dir,
|
|
764
|
-
}
|
|
765
|
-
|
|
766
|
-
// A provisioned spec's own overview and bucket, read in its worktree — the
|
|
767
|
-
// copy where an in-flight spec's bucket and headers are true. null when the
|
|
768
|
-
// worktree holds no readable copy.
|
|
769
|
-
function worktreeOverview(root, folder) {
|
|
770
|
-
for (const bucket of ['in-progress', 'backlog', 'complete', 'cancelled']) {
|
|
771
|
-
const dir = path.join(root, 'specs', bucket, folder)
|
|
772
|
-
let overview
|
|
773
|
-
try {
|
|
774
|
-
overview = fs.readFileSync(path.join(dir, '00-overview.md'), 'utf8')
|
|
775
|
-
} catch {
|
|
776
|
-
continue
|
|
777
|
-
}
|
|
778
|
-
const phases = fs
|
|
779
|
-
.readdirSync(dir)
|
|
780
|
-
.filter((f) => /^\d\d-.+\.md$/.test(f) && f !== '00-overview.md')
|
|
781
|
-
.map((f) => {
|
|
782
|
-
let text = null
|
|
783
|
-
try {
|
|
784
|
-
text = fs.readFileSync(path.join(dir, f), 'utf8')
|
|
785
|
-
} catch {
|
|
786
|
-
// unreadable: a phase with nothing to say
|
|
787
|
-
}
|
|
788
|
-
return { n: Number(f.slice(0, 2)), text }
|
|
789
|
-
})
|
|
790
|
-
return { folder, bucket, overview, phases, root }
|
|
791
|
-
}
|
|
792
|
-
return null
|
|
834
|
+
return { dir, config: present ? config : null, base, ...tree, worktrees }
|
|
793
835
|
}
|
|
794
836
|
|
|
795
837
|
// Plan a provision: allocate the slot, persist the registry, and print the plan
|
package/src/env/epic.js
CHANGED
|
@@ -27,6 +27,7 @@
|
|
|
27
27
|
*/
|
|
28
28
|
|
|
29
29
|
const { phaseIsDone } = require('./resolve.js')
|
|
30
|
+
const { epicRows, actionText } = require('./nextaction.js')
|
|
30
31
|
|
|
31
32
|
const BUCKETS = ['backlog', 'in-progress', 'complete', 'cancelled']
|
|
32
33
|
|
|
@@ -379,9 +380,6 @@ function epicStatus({ epic, index, readFile, candidates = [], worktrees = [] })
|
|
|
379
380
|
}
|
|
380
381
|
}
|
|
381
382
|
|
|
382
|
-
const names = (xs) => xs.map((x) => (typeof x === 'string' ? x : x.spec)).join(', ')
|
|
383
|
-
const reasons = (xs) => xs.map((x) => `${x.spec} (${x.by.map((w) => w.why).join('; ')})`).join(', ')
|
|
384
|
-
|
|
385
383
|
// `feat-a phase 2 after feat-b phase 1 — not done`, or `feat-a starts after …`.
|
|
386
384
|
function syncLine({ spec, phase, wait }) {
|
|
387
385
|
const who = phase === null ? `${spec} starts` : `${spec} phase ${phase}`
|
|
@@ -389,28 +387,44 @@ function syncLine({ spec, phase, wait }) {
|
|
|
389
387
|
return `${who} after ${wait.raw} (${mark} — ${wait.why})`
|
|
390
388
|
}
|
|
391
389
|
|
|
390
|
+
// Columns padded to their widest cell. Plain text, never a markdown table: the
|
|
391
|
+
// answer is read raw under `watch` as often as it is rendered (spec
|
|
392
|
+
// feat-epic-next, Decision 3), and a pipe table read raw is noise.
|
|
393
|
+
function aligned(lines, indent = ' ') {
|
|
394
|
+
const widths = lines[0].map((_, i) => Math.max(...lines.map((l) => l[i].length)))
|
|
395
|
+
return lines.map((l) => (indent + l.map((c, i) => (i === l.length - 1 ? c : c.padEnd(widths[i]))).join(' ')).trimEnd())
|
|
396
|
+
}
|
|
397
|
+
|
|
392
398
|
/**
|
|
393
|
-
* The human answer,
|
|
394
|
-
*
|
|
399
|
+
* The human answer: a headline, one row per member saying what to run and in
|
|
400
|
+
* which tab, then the plan's shape — waves, sync points, clashes — wherever
|
|
401
|
+
* there is something to say. `s.rows` comes from `epicRows`; a status without
|
|
402
|
+
* them is rendered with nothing read off disk, so an in-flight member says it
|
|
403
|
+
* cannot tell rather than guessing.
|
|
395
404
|
*/
|
|
396
405
|
function formatEpicStatus(s) {
|
|
397
406
|
if (!s.found && !s.members.length) return `no epic named ${s.epic}, and no spec names it as its Epic.\n`
|
|
398
407
|
const lanes = s.lanes === null ? 'no lane cap' : `${s.lanes} lanes, ${s.freeLanes} free`
|
|
399
|
-
const head =
|
|
400
|
-
const
|
|
401
|
-
|
|
402
|
-
|
|
403
|
-
|
|
404
|
-
|
|
405
|
-
|
|
406
|
-
|
|
407
|
-
|
|
408
|
-
|
|
409
|
-
|
|
410
|
-
|
|
408
|
+
const head = `${s.epic} — ${s.members.length} member${s.members.length === 1 ? '' : 's'} · ${lanes}${s.found ? '' : ' · epic not on the base branch'}`
|
|
409
|
+
const out = [head, '']
|
|
410
|
+
if (!s.members.length) {
|
|
411
|
+
out.push(` no members — no spec carries \`> **Epic:** ${s.epic}\``)
|
|
412
|
+
} else {
|
|
413
|
+
const { rows, next } = s.rows ? { rows: s.rows, next: s.next } : epicRows(s)
|
|
414
|
+
const state = (r) => (r.bucket === 'in-progress' ? r.next.state : r.next.state || r.bucket || 'unknown')
|
|
415
|
+
out.push(
|
|
416
|
+
...aligned([['member', 'state', 'next', 'tab'], ...rows.map((r) => [r.spec, state(r), actionText(r.next), r.tab || '—'])]),
|
|
417
|
+
)
|
|
418
|
+
if (next) out.push('', ` ${s.epic}: ${actionText(next)}`)
|
|
419
|
+
}
|
|
420
|
+
const shape = [
|
|
421
|
+
['waves', s.waves.map((w, i) => `${i + 1}: ${w.join(', ')}`).join(' · ')],
|
|
422
|
+
['sync points', s.syncPoints.map(syncLine).join(' · ')],
|
|
423
|
+
['never together', s.clashes.map((c) => `${c.specs.join(' ‖ ')} (${c.paths.join(', ')})`).join(' · ')],
|
|
424
|
+
['cycle', s.cycles.map((c) => c.join(' → ')).join(' · ')],
|
|
411
425
|
].filter(([, v]) => v)
|
|
412
|
-
if (
|
|
413
|
-
return
|
|
426
|
+
if (shape.length) out.push('', ...aligned(shape))
|
|
427
|
+
return out.join('\n') + '\n'
|
|
414
428
|
}
|
|
415
429
|
|
|
416
430
|
/**
|
|
@@ -0,0 +1,128 @@
|
|
|
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 } = {}) {
|
|
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>${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
|
+
.sub { color:var(--dim); margin:0 0 1.25rem }
|
|
98
|
+
.wrap { overflow-x:auto }
|
|
99
|
+
table { border-collapse:collapse; width:100% }
|
|
100
|
+
th { text-align:left; color:var(--dim); font-weight:500; font-size:.85em }
|
|
101
|
+
th, td { padding:.55rem .6rem .55rem 0; border-top:1px solid var(--line); vertical-align:top }
|
|
102
|
+
a { color:var(--link); text-decoration:none; font-weight:600 }
|
|
103
|
+
a:hover { text-decoration:underline }
|
|
104
|
+
code { font-family:ui-monospace,SFMono-Regular,Menlo,monospace; font-size:.9em }
|
|
105
|
+
.why, .s, .t { color:var(--dim) }
|
|
106
|
+
.v-verdict .x, .v-claim .x { color:var(--hot) }
|
|
107
|
+
.own { margin:1rem 0 0 }
|
|
108
|
+
dl { margin:1.5rem 0 0; display:grid; grid-template-columns:max-content 1fr; gap:.3rem 1rem }
|
|
109
|
+
dt { color:var(--dim) } dd { margin:0 }
|
|
110
|
+
.empty, .foot { color:var(--dim) }
|
|
111
|
+
.foot { margin-top:1.5rem; font-size:.85em }
|
|
112
|
+
</style>
|
|
113
|
+
</head>
|
|
114
|
+
<body>
|
|
115
|
+
<main>
|
|
116
|
+
<h1>${escapeHtml(answer.epic)}</h1>
|
|
117
|
+
<p class="sub">${count} · ${escapeHtml(lanes)}</p>
|
|
118
|
+
<div class="wrap">${table}</div>
|
|
119
|
+
${own}
|
|
120
|
+
${shape ? `<dl>\n${shape}\n</dl>` : ''}
|
|
121
|
+
<p class="foot">Refreshes every ${Number(refreshSeconds)} s. Type commands in the member's own tab.</p>
|
|
122
|
+
</main>
|
|
123
|
+
</body>
|
|
124
|
+
</html>
|
|
125
|
+
`
|
|
126
|
+
}
|
|
127
|
+
|
|
128
|
+
module.exports = { renderEpicPage, REFRESH_SECONDS }
|
|
@@ -0,0 +1,109 @@
|
|
|
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
|
+
// A provisioned spec's own overview and bucket, read in its worktree — the
|
|
40
|
+
// copy where an in-flight spec's bucket and headers are true. null when the
|
|
41
|
+
// worktree holds no readable copy.
|
|
42
|
+
function worktreeOverview(root, folder) {
|
|
43
|
+
for (const bucket of ['in-progress', 'backlog', 'complete', 'cancelled']) {
|
|
44
|
+
const dir = path.join(root, 'specs', bucket, folder)
|
|
45
|
+
let overview
|
|
46
|
+
try {
|
|
47
|
+
overview = fs.readFileSync(path.join(dir, '00-overview.md'), 'utf8')
|
|
48
|
+
} catch {
|
|
49
|
+
continue
|
|
50
|
+
}
|
|
51
|
+
const phases = fs
|
|
52
|
+
.readdirSync(dir)
|
|
53
|
+
.filter((f) => /^\d\d-.+\.md$/.test(f) && f !== '00-overview.md')
|
|
54
|
+
.map((f) => {
|
|
55
|
+
let text = null
|
|
56
|
+
try {
|
|
57
|
+
text = fs.readFileSync(path.join(dir, f), 'utf8')
|
|
58
|
+
} catch {
|
|
59
|
+
// unreadable: a phase with nothing to say
|
|
60
|
+
}
|
|
61
|
+
return { n: Number(f.slice(0, 2)), text }
|
|
62
|
+
})
|
|
63
|
+
return { folder, bucket, overview, phases, root }
|
|
64
|
+
}
|
|
65
|
+
return null
|
|
66
|
+
}
|
|
67
|
+
|
|
68
|
+
// Epics with a member, or themselves, in flight on this machine — what a bare
|
|
69
|
+
// `epic status` offers when it cannot tell which one was meant, and what the
|
|
70
|
+
// review server's index lists.
|
|
71
|
+
function epicsInFlight(worktrees) {
|
|
72
|
+
const open = worktrees.filter((w) => w.bucket !== 'complete' && w.bucket !== 'cancelled')
|
|
73
|
+
const names = open.map((w) => (isEpic(w.folder) ? w.folder : epicHeaders(w.overview).epic)).filter(Boolean)
|
|
74
|
+
return [...new Set(names)].sort()
|
|
75
|
+
}
|
|
76
|
+
|
|
77
|
+
/**
|
|
78
|
+
* The callbacks `epicRows` reads each member through: its own worktree, the
|
|
79
|
+
* review sidecars beside its page in the primary checkout, and a link to that
|
|
80
|
+
* page from `linkFor` — absolute for a terminal, relative for the served page.
|
|
81
|
+
*/
|
|
82
|
+
function memberReaders({ dir, config, worktrees, linkFor = () => null, git }) {
|
|
83
|
+
const own = new Map(worktrees.map((w) => [w.folder, w]))
|
|
84
|
+
return {
|
|
85
|
+
inputsFor: (spec) => {
|
|
86
|
+
const w = own.get(spec)
|
|
87
|
+
if (!w) return null
|
|
88
|
+
return readNextInputs({
|
|
89
|
+
folder: spec,
|
|
90
|
+
bucket: w.bucket,
|
|
91
|
+
worktree: w.root,
|
|
92
|
+
outPath: reviewOutPath(dir, spec),
|
|
93
|
+
required: config ? config.review.required : true,
|
|
94
|
+
git: git(w.root),
|
|
95
|
+
})
|
|
96
|
+
},
|
|
97
|
+
tabFor: (spec) => (own.has(spec) ? path.relative(path.dirname(dir), own.get(spec).root) : null),
|
|
98
|
+
linkFor,
|
|
99
|
+
}
|
|
100
|
+
}
|
|
101
|
+
|
|
102
|
+
/** The whole answer for one epic: `epicStatus` plus a row per member. */
|
|
103
|
+
function epicAnswer(epic, inputs, readers) {
|
|
104
|
+
const status = epicStatus({ epic, ...inputs })
|
|
105
|
+
const { rows, next } = epicRows(status, readers)
|
|
106
|
+
return { ...status, rows, next }
|
|
107
|
+
}
|
|
108
|
+
|
|
109
|
+
module.exports = { epicTree, 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.
|
|
@@ -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/serve.js
CHANGED
|
@@ -35,7 +35,10 @@ const {
|
|
|
35
35
|
allSpecs,
|
|
36
36
|
resolveSpec,
|
|
37
37
|
resolveBaseBranch,
|
|
38
|
+
isEpic,
|
|
38
39
|
} = require('./resolve.js')
|
|
40
|
+
const { epicTree, worktreeOverview, epicsInFlight, memberReaders, epicAnswer } = require('./epicread.js')
|
|
41
|
+
const { renderEpicPage } = require('./epicpage.js')
|
|
39
42
|
const { readRegistry } = require('./registry.js')
|
|
40
43
|
const { loadEnvConfig } = require('./config.js')
|
|
41
44
|
const { primaryAnchor, attachProject, repoRootOf, prefixOf, fromRepoPath, toRepoPath } = require('./project.js')
|
|
@@ -124,8 +127,16 @@ function escapeHtml(s) {
|
|
|
124
127
|
* palette on bare `:root`, redefined under `prefers-color-scheme`) so the two
|
|
125
128
|
* do not disagree when opened side by side.
|
|
126
129
|
*/
|
|
127
|
-
function renderIndex(entries, { token = null } = {}) {
|
|
130
|
+
function renderIndex(entries, { token = null, epics = [] } = {}) {
|
|
128
131
|
const prefix = token ? `/${token}` : ''
|
|
132
|
+
// Epics with a member in flight, each a doorway to its epic page. Listed
|
|
133
|
+
// above the diffs because an epic page is where a reader running several
|
|
134
|
+
// members starts; absent entirely on a repo with no epic in flight.
|
|
135
|
+
const epicList = epics.length
|
|
136
|
+
? `<h2>epics</h2>\n<ul>\n${epics
|
|
137
|
+
.map((e) => `<li><a href="${prefix}/${encodeURIComponent(e)}">${escapeHtml(e)}</a><span class="b">what to run next, per member</span></li>`)
|
|
138
|
+
.join('\n')}\n</ul>\n<h2>diffs</h2>`
|
|
139
|
+
: ''
|
|
129
140
|
const rows = entries
|
|
130
141
|
.map((e) => {
|
|
131
142
|
const t = e.totals || { files: 0, additions: 0, deletions: 0 }
|
|
@@ -161,6 +172,7 @@ body { margin:0; padding:2rem 1.25rem; background:var(--bg); color:var(--fg);
|
|
|
161
172
|
font:15px/1.5 ui-sans-serif,system-ui,-apple-system,Segoe UI,Roboto,sans-serif }
|
|
162
173
|
main { max-width:52rem; margin:0 auto }
|
|
163
174
|
h1 { font-size:1.1rem; margin:0 0 1.25rem; font-weight:600 }
|
|
175
|
+
h2 { font-size:.9rem; margin:1.25rem 0 .25rem; font-weight:600; color:var(--dim) }
|
|
164
176
|
ul { list-style:none; margin:0; padding:0 }
|
|
165
177
|
li { display:flex; flex-wrap:wrap; gap:.75rem; align-items:baseline;
|
|
166
178
|
padding:.7rem 0; border-top:1px solid var(--line) }
|
|
@@ -177,6 +189,7 @@ code { font-family:ui-monospace,SFMono-Regular,Menlo,monospace }
|
|
|
177
189
|
<body>
|
|
178
190
|
<main>
|
|
179
191
|
<h1>spec diffs</h1>
|
|
192
|
+
${epicList}
|
|
180
193
|
${body}
|
|
181
194
|
</main>
|
|
182
195
|
</body>
|
|
@@ -792,7 +805,7 @@ function readBody(req, limit = MAX_PASS_BYTES) {
|
|
|
792
805
|
})
|
|
793
806
|
}
|
|
794
807
|
|
|
795
|
-
function createReviewServer({ resolveEntries, render, receive = null, passState = null, token = null }) {
|
|
808
|
+
function createReviewServer({ resolveEntries, resolveEpics = () => [], render, receive = null, passState = null, token = null }) {
|
|
796
809
|
return http.createServer((req, res) => {
|
|
797
810
|
const send = (code, body, type = 'text/html; charset=utf-8') => {
|
|
798
811
|
res.writeHead(code, { 'content-type': type, 'cache-control': 'no-store' })
|
|
@@ -846,7 +859,7 @@ function createReviewServer({ resolveEntries, render, receive = null, passState
|
|
|
846
859
|
}
|
|
847
860
|
|
|
848
861
|
try {
|
|
849
|
-
if (route.kind === 'index') return send(200, renderIndex(resolveEntries(), { token }))
|
|
862
|
+
if (route.kind === 'index') return send(200, renderIndex(resolveEntries(), { token, epics: resolveEpics() }))
|
|
850
863
|
const out = render(route.spec, { branch: route.branch })
|
|
851
864
|
if (!out) return send(404, 'not found', 'text/plain; charset=utf-8')
|
|
852
865
|
if (out.error) return send(409, out.error, 'text/plain; charset=utf-8')
|
|
@@ -995,9 +1008,53 @@ function serverHooks(dir, config) {
|
|
|
995
1008
|
}
|
|
996
1009
|
})
|
|
997
1010
|
|
|
1011
|
+
// Every provisioned spec's own copy — what an epic's members are read off.
|
|
1012
|
+
const worktrees = () =>
|
|
1013
|
+
allSpecs(dir, config, liveWorktreePaths(trimmedGit), specless())
|
|
1014
|
+
.filter((s) => !s.specless && s.worktreePath && s.worktreePath !== dir && fs.existsSync(s.worktreePath))
|
|
1015
|
+
.map((s) => worktreeOverview(s.projectPath || s.worktreePath, s.folder))
|
|
1016
|
+
.filter(Boolean)
|
|
1017
|
+
|
|
1018
|
+
// The epic page, read per request like every other page. null — a 404 — when
|
|
1019
|
+
// no such epic exists and no spec names it; an unreadable base branch is a
|
|
1020
|
+
// 409 saying so, never an empty plan.
|
|
1021
|
+
const epicPage = (folder) => {
|
|
1022
|
+
let base
|
|
1023
|
+
try {
|
|
1024
|
+
base = resolveBaseBranch(config, trimmedGit)
|
|
1025
|
+
} catch (err) {
|
|
1026
|
+
return { error: `cannot tell — ${err.message}` }
|
|
1027
|
+
}
|
|
1028
|
+
const tree = epicTree(trimmedGit, base)
|
|
1029
|
+
if (!tree) return { error: `cannot tell — the base branch ${base} could not be read` }
|
|
1030
|
+
const inputs = { dir, config, base, ...tree, worktrees: worktrees() }
|
|
1031
|
+
const answer = epicAnswer(folder, inputs, memberReaders({ ...inputs, git: trimmedGitReader, linkFor: (s) => encodeURIComponent(s) }))
|
|
1032
|
+
if (!answer.found && !answer.members.length) return null
|
|
1033
|
+
return { html: renderEpicPage(answer) }
|
|
1034
|
+
}
|
|
1035
|
+
|
|
998
1036
|
return {
|
|
999
1037
|
resolveEntries,
|
|
1000
|
-
|
|
1038
|
+
resolveEpics: () => {
|
|
1039
|
+
try {
|
|
1040
|
+
return epicsInFlight(worktrees())
|
|
1041
|
+
} catch {
|
|
1042
|
+
// The index is a doorway; an unreadable worktree costs a link, never the page.
|
|
1043
|
+
return []
|
|
1044
|
+
}
|
|
1045
|
+
},
|
|
1046
|
+
render: (folder, opts) => {
|
|
1047
|
+
// AN EPIC BEING WRITTEN KEEPS ITS AUTHORING PAGE. `/spec` renders a new
|
|
1048
|
+
// epic's own documents at this same address, with verdict buttons, and
|
|
1049
|
+
// that page must still be the one a reader gets while the documents are
|
|
1050
|
+
// uncommitted. Every other epic address is the epic page.
|
|
1051
|
+
if (isEpic(folder)) {
|
|
1052
|
+
const one = resolveOne(folder)
|
|
1053
|
+
const view = one ? viewFor(dir, config, one, trimmedGit) : null
|
|
1054
|
+
if (!view || view.kind !== 'docs') return epicPage(folder)
|
|
1055
|
+
}
|
|
1056
|
+
return renderSpecPage(dir, config, resolveOne(folder), opts)
|
|
1057
|
+
},
|
|
1001
1058
|
receive: (folder, blob) => receivePass(dir, config, resolveOne(folder), blob),
|
|
1002
1059
|
// A spec this daemon cannot resolve is not a pass that was claimed — it is
|
|
1003
1060
|
// a lookup that could not see, so it says nothing rather than reporting the
|