@skitterbyte/skitterspec-jira 2.7.0 → 2.9.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/assets/claude-md-section.md +6 -0
- package/assets/core/env.config.json.example +5 -0
- package/assets/core/env.config.md +26 -5
- package/assets/review/page.html +9 -0
- package/assets/rules/spec-planning.md +65 -12
- package/assets/rules/spec-reports.md +8 -1
- package/assets/skills/spec/SKILL.md +31 -14
- package/assets/skills/spec-cancel/SKILL.md +7 -0
- package/assets/skills/spec-complete/SKILL.md +6 -0
- package/assets/skills/spec-epic-next/SKILL.md +83 -0
- package/assets/skills/spec-init/SKILL.md +35 -3
- package/assets/skills/spec-next/SKILL.md +38 -1
- package/assets/skills/spec-start/SKILL.md +2 -2
- package/assets/skills/spec-tada/SKILL.md +153 -0
- package/bin/skitterspec-jira.js +5 -0
- package/package.json +1 -1
- package/src/cli.js +473 -25
- package/src/env/config.js +57 -6
- package/src/env/epic.js +69 -19
- package/src/env/epicpage.js +87 -39
- package/src/env/epicread.js +41 -3
- package/src/env/integrate.js +48 -1
- package/src/env/nextaction.js +78 -1
- package/src/env/project.js +54 -3
- package/src/env/projectedit.js +148 -0
- package/src/env/resolve.js +1 -0
- package/src/env/review.js +21 -3
- package/src/env/serve.js +44 -8
- package/src/env/specbranches.js +120 -0
- package/src/env/teardown.js +18 -3
- package/src/gating.js +16 -4
- package/src/init.js +11 -3
- package/src/tada/commits.js +145 -0
- package/src/tada/digest.js +260 -0
- package/src/tada/format.js +37 -0
- package/src/tada/page.js +213 -0
- package/src/tada/repo.js +102 -0
- package/src/tada/serve.js +127 -0
- package/src/tada/specs.js +146 -0
- package/src/tada/transcripts.js +258 -0
- package/src/tada/window.js +156 -0
- 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
- /package/assets/commands/{epic.md → spec-epic.md} +0 -0
package/src/env/config.js
CHANGED
|
@@ -60,7 +60,7 @@
|
|
|
60
60
|
*/
|
|
61
61
|
|
|
62
62
|
const { createHash } = require('node:crypto')
|
|
63
|
-
const { readFileSync, realpathSync } = require('node:fs')
|
|
63
|
+
const { existsSync, readFileSync, realpathSync } = require('node:fs')
|
|
64
64
|
const { join, resolve, sep } = require('node:path')
|
|
65
65
|
|
|
66
66
|
const CONFIG_FILE = join('specs', '.core', 'env.config.json')
|
|
@@ -162,6 +162,11 @@ const DEFAULT_CONFIG = Object.freeze({
|
|
|
162
162
|
// dev servers may still want parallel specs, and absence of configuration is
|
|
163
163
|
// not evidence of intent (see .claude/rules/negative-checks.md).
|
|
164
164
|
mode: 'worktree',
|
|
165
|
+
// What this project is called and which group it belongs to — facts about
|
|
166
|
+
// the project, not about any one feature. `name` heads every generated page
|
|
167
|
+
// (empty: the folder's name); `category` is a free label (`work`, a client's
|
|
168
|
+
// name) that `skitterspec tada` scopes a report by.
|
|
169
|
+
project: Object.freeze({ name: '', category: '' }),
|
|
165
170
|
worktree: Object.freeze({ root: '../{repo}-wt', folderPattern: '{slug}' }),
|
|
166
171
|
docker: Object.freeze({
|
|
167
172
|
enabled: true,
|
|
@@ -230,9 +235,11 @@ const DEFAULT_CONFIG = Object.freeze({
|
|
|
230
235
|
// follows the merge. `remote` names where the branch is pushed. `draft`
|
|
231
236
|
// opens mid-spec PRs as drafts (a draft cannot be merged, so nothing
|
|
232
237
|
// downstream can close a ticket early). `specDocs` decides where a spec
|
|
233
|
-
// DOCUMENT lands
|
|
234
|
-
//
|
|
235
|
-
//
|
|
238
|
+
// DOCUMENT lands: "trunk" keeps the authoring land (needs direct push for
|
|
239
|
+
// docs under "pr"), "branch" has the spec ride its feature branch and land
|
|
240
|
+
// with the work. The "trunk" here is only the base's default — with a
|
|
241
|
+
// ticketing provider configured and the key unset, `applyProviderSpecDocs`
|
|
242
|
+
// makes it "branch", whatever the strategy.
|
|
236
243
|
land: Object.freeze({ strategy: 'ff', remote: 'origin', draft: true, specDocs: 'trunk' }),
|
|
237
244
|
// `mainIsLandingZone` defaults ON wherever isolation is configured, matching
|
|
238
245
|
// the review gate's precedent: the push toward not working on the base branch
|
|
@@ -307,6 +314,9 @@ const DEFAULT_CONFIG = Object.freeze({
|
|
|
307
314
|
allowRemote: false,
|
|
308
315
|
commitWith: '/commit',
|
|
309
316
|
required: true,
|
|
317
|
+
// SUPERSEDED by `project.name`, and still read beneath it so a config that
|
|
318
|
+
// set it keeps its name. The name was never the review page's alone.
|
|
319
|
+
projectName: '',
|
|
310
320
|
// External code reviewers whose findings render as CHECKS on the page.
|
|
311
321
|
// Empty by default and never written by `init`: configuring one sends the
|
|
312
322
|
// worktree's diff to whatever the command talks to, which is a decision
|
|
@@ -394,6 +404,7 @@ function collectUnknownKeys(parsed, known = DEFAULT_CONFIG, prefix = '') {
|
|
|
394
404
|
function defaults() {
|
|
395
405
|
return {
|
|
396
406
|
mode: DEFAULT_CONFIG.mode,
|
|
407
|
+
project: { ...DEFAULT_CONFIG.project },
|
|
397
408
|
worktree: { ...DEFAULT_CONFIG.worktree },
|
|
398
409
|
docker: { ...DEFAULT_CONFIG.docker },
|
|
399
410
|
seedFiles: { mode: DEFAULT_CONFIG.seedFiles.mode, files: [] },
|
|
@@ -627,6 +638,11 @@ function normalizeAfterLand(parsed, setupTriggers) {
|
|
|
627
638
|
function mergeConfig(base, parsed) {
|
|
628
639
|
if (!isObject(parsed)) return base
|
|
629
640
|
|
|
641
|
+
if (isObject(parsed.project)) {
|
|
642
|
+
assign(base.project, parsed.project, 'name', 'string')
|
|
643
|
+
assign(base.project, parsed.project, 'category', 'string')
|
|
644
|
+
}
|
|
645
|
+
|
|
630
646
|
if (isObject(parsed.worktree)) {
|
|
631
647
|
assign(base.worktree, parsed.worktree, 'root', 'string')
|
|
632
648
|
assign(base.worktree, parsed.worktree, 'folderPattern', 'string')
|
|
@@ -772,6 +788,8 @@ function mergeConfig(base, parsed) {
|
|
|
772
788
|
// here. There is nothing it could mean instead: the hand-off has no off
|
|
773
789
|
// switch, so a blank value is a typo rather than an instruction.
|
|
774
790
|
assign(base.review, parsed.review, 'commitWith', 'string')
|
|
791
|
+
// A blank name falls back to the folder's, like `commitWith` above.
|
|
792
|
+
assign(base.review, parsed.review, 'projectName', 'string')
|
|
775
793
|
// Same shape as `serveOnRemote`, and for a sharper reason: a non-boolean
|
|
776
794
|
// leaves the gate ON. Turning off a check that refuses must be something
|
|
777
795
|
// someone WROTE, never something a typo achieved on their behalf.
|
|
@@ -873,6 +891,33 @@ function applyProviderEnvDefaults(config, parsed) {
|
|
|
873
891
|
return config
|
|
874
892
|
}
|
|
875
893
|
|
|
894
|
+
// The provider's own config file, relative to the project root — set once per
|
|
895
|
+
// process by a provider superset's bin, like the defaults above. A registered
|
|
896
|
+
// file that EXISTS is the positive signal that a ticketing provider is attached
|
|
897
|
+
// to this project, and only then does `land.specDocs` default to "branch": the
|
|
898
|
+
// tracker is the backlog, so landing a spec document on the base branch just to
|
|
899
|
+
// make it findable buys nothing (feat-tracker-spec-branches).
|
|
900
|
+
//
|
|
901
|
+
// WHAT WOULD FOOL THIS: an installed superset whose project never ran its setup
|
|
902
|
+
// has no config file, and reads as no provider — which is the safe reading,
|
|
903
|
+
// since "trunk" is today's behaviour. An unregistered base distribution never
|
|
904
|
+
// asks at all.
|
|
905
|
+
let providerConfigFile = null
|
|
906
|
+
function setProviderConfigFile(rel) {
|
|
907
|
+
providerConfigFile = rel || null
|
|
908
|
+
}
|
|
909
|
+
|
|
910
|
+
// An explicit `specDocs` in the file — any value, even one the merge rejected —
|
|
911
|
+
// is the project's decision; a rejected typo stays on the conservative "trunk"
|
|
912
|
+
// rather than being promoted to the provider default.
|
|
913
|
+
function applyProviderSpecDocs(config, parsed, dir) {
|
|
914
|
+
if (!providerConfigFile) return config
|
|
915
|
+
const pLand = parsed && typeof parsed.land === 'object' && parsed.land !== null ? parsed.land : null
|
|
916
|
+
if (pLand && 'specDocs' in pLand) return config
|
|
917
|
+
if (existsSync(join(dir, providerConfigFile))) config.land.specDocs = 'branch'
|
|
918
|
+
return config
|
|
919
|
+
}
|
|
920
|
+
|
|
876
921
|
function loadEnvConfig(dir = process.cwd()) {
|
|
877
922
|
const base = defaults()
|
|
878
923
|
const file = join(dir, CONFIG_FILE)
|
|
@@ -882,7 +927,12 @@ function loadEnvConfig(dir = process.cwd()) {
|
|
|
882
927
|
raw = readFileSync(file, 'utf-8')
|
|
883
928
|
} catch (error) {
|
|
884
929
|
if (error.code === 'ENOENT') {
|
|
885
|
-
return {
|
|
930
|
+
return {
|
|
931
|
+
config: applyProviderSpecDocs(applyProviderEnvDefaults(base, null), null, dir),
|
|
932
|
+
present: false,
|
|
933
|
+
unknown: [],
|
|
934
|
+
badReviewers: [],
|
|
935
|
+
}
|
|
886
936
|
}
|
|
887
937
|
throw error
|
|
888
938
|
}
|
|
@@ -895,7 +945,7 @@ function loadEnvConfig(dir = process.cwd()) {
|
|
|
895
945
|
}
|
|
896
946
|
|
|
897
947
|
return {
|
|
898
|
-
config: applyProviderEnvDefaults(mergeConfig(base, parsed), parsed),
|
|
948
|
+
config: applyProviderSpecDocs(applyProviderEnvDefaults(mergeConfig(base, parsed), parsed), parsed, dir),
|
|
899
949
|
present: true,
|
|
900
950
|
unknown: collectUnknownKeys(parsed),
|
|
901
951
|
badReviewers: collectBadReviewers(parsed),
|
|
@@ -905,6 +955,7 @@ function loadEnvConfig(dir = process.cwd()) {
|
|
|
905
955
|
module.exports = {
|
|
906
956
|
loadEnvConfig,
|
|
907
957
|
setProviderEnvDefaults,
|
|
958
|
+
setProviderConfigFile,
|
|
908
959
|
resolveServePort,
|
|
909
960
|
derivedServePort,
|
|
910
961
|
servePortRoot,
|
package/src/env/epic.js
CHANGED
|
@@ -27,7 +27,7 @@
|
|
|
27
27
|
*/
|
|
28
28
|
|
|
29
29
|
const { phaseIsDone } = require('./resolve.js')
|
|
30
|
-
const { epicRows, actionText } = require('./nextaction.js')
|
|
30
|
+
const { epicRows, epicPlan, actionText } = require('./nextaction.js')
|
|
31
31
|
|
|
32
32
|
const BUCKETS = ['backlog', 'in-progress', 'complete', 'cancelled']
|
|
33
33
|
|
|
@@ -292,12 +292,21 @@ function layer(members) {
|
|
|
292
292
|
* - `index` `indexSpecTree` of the base branch
|
|
293
293
|
* - `readFile` base-branch path → text, or null
|
|
294
294
|
* - `candidates` base-branch overview paths that may carry an `Epic:` header
|
|
295
|
+
* - `waitIndex`/`waitRead` where a wait is resolved, when that is not where
|
|
296
|
+
* members are read — `epic status --here` reads members off a
|
|
297
|
+
* working tree and still meets a wait only on the base branch
|
|
295
298
|
* - `worktrees` `[{ folder, bucket, overview, phases: [{ n, text }] }]` —
|
|
296
299
|
* each provisioned spec's own copy, which is where an
|
|
297
300
|
* in-flight spec's bucket and phase progress are true
|
|
301
|
+
* - `branches` the same shape, read off spec branches this machine has no
|
|
302
|
+
* worktree for (`env/specbranches.js`) — how a member that
|
|
303
|
+
* rides its own branch is seen at all. It can make a member
|
|
304
|
+
* VISIBLE and give it a bucket; it never meets a wait, which
|
|
305
|
+
* is still read only off the base branch.
|
|
298
306
|
*/
|
|
299
|
-
function epicStatus({ epic, index, readFile, candidates = [], worktrees = [] }) {
|
|
307
|
+
function epicStatus({ epic, index, readFile, candidates = [], worktrees = [], branches = [], waitIndex = index, waitRead = readFile }) {
|
|
300
308
|
const own = new Map(worktrees.map((w) => [w.folder, w]))
|
|
309
|
+
const onBranch = new Map(branches.filter((b) => !own.has(b.folder)).map((b) => [b.folder, b]))
|
|
301
310
|
const members = new Map()
|
|
302
311
|
|
|
303
312
|
for (const file of candidates) {
|
|
@@ -312,8 +321,10 @@ function epicStatus({ epic, index, readFile, candidates = [], worktrees = [] })
|
|
|
312
321
|
members.set(m[2], { spec: m[2], waits: h.waitsOn, area: h.area, phases })
|
|
313
322
|
}
|
|
314
323
|
// A member authored on its own branch and not landed yet is invisible on the
|
|
315
|
-
// base branch; its worktree copy is what knows it belongs here
|
|
316
|
-
|
|
324
|
+
// base branch; its worktree copy is what knows it belongs here — or, with no
|
|
325
|
+
// worktree on this machine, its branch's copy. The worktree is read last, so
|
|
326
|
+
// it wins.
|
|
327
|
+
for (const w of [...onBranch.values(), ...worktrees]) {
|
|
317
328
|
const h = epicHeaders(w.overview)
|
|
318
329
|
// The worktree's copy is the newer word on a spec being built: it may have
|
|
319
330
|
// joined, changed its waits, or moved to another epic.
|
|
@@ -327,15 +338,16 @@ function epicStatus({ epic, index, readFile, candidates = [], worktrees = [] })
|
|
|
327
338
|
const base = index.get(m.spec)
|
|
328
339
|
// In flight is the positive signal of a worktree whose own copy has not
|
|
329
340
|
// finished; otherwise the base branch's bucket.
|
|
330
|
-
|
|
331
|
-
m.
|
|
341
|
+
const br = onBranch.get(m.spec)
|
|
342
|
+
m.bucket = wt && !['complete', 'cancelled'].includes(wt.bucket) ? 'in-progress' : br ? br.bucket : base ? base.bucket : wt ? wt.bucket : null
|
|
343
|
+
m.resolved = m.waits.map((w) => ({ ...w, ...resolveWait(w, waitIndex, waitRead) }))
|
|
332
344
|
// A phase's own `Waits on:` holds that phase, not the spec's start: the
|
|
333
345
|
// sync point the field example turned on (#154 phase 2 on #159 phase 1).
|
|
334
346
|
// A phase already done has nothing left to wait for.
|
|
335
347
|
m.phaseWaits = m.phases
|
|
336
348
|
.filter((p) => p.text !== null && !phaseIsDone(p.text))
|
|
337
349
|
.flatMap((p) =>
|
|
338
|
-
epicHeaders(p.text).waitsOn.map((w) => ({ at: p.n, wait: { ...w, ...resolveWait(w,
|
|
350
|
+
epicHeaders(p.text).waitsOn.map((w) => ({ at: p.n, wait: { ...w, ...resolveWait(w, waitIndex, waitRead) } })),
|
|
339
351
|
)
|
|
340
352
|
}
|
|
341
353
|
|
|
@@ -396,26 +408,42 @@ function aligned(lines, indent = ' ') {
|
|
|
396
408
|
}
|
|
397
409
|
|
|
398
410
|
/**
|
|
399
|
-
* The human answer
|
|
400
|
-
*
|
|
401
|
-
*
|
|
402
|
-
*
|
|
403
|
-
*
|
|
411
|
+
* The human answer, in the order a reader needs it (spec
|
|
412
|
+
* feat-spec-epic-commands, Decisions 9–10): how far along, every member in its
|
|
413
|
+
* group, then the numbered next steps, then the plan's shape — waves, sync
|
|
414
|
+
* points, clashes — which explains the order the steps act on. `s.rows` comes
|
|
415
|
+
* from `epicRows`; a status without them is rendered with nothing read off
|
|
416
|
+
* disk, so an in-flight member says it cannot tell rather than guessing.
|
|
404
417
|
*/
|
|
405
418
|
function formatEpicStatus(s) {
|
|
406
|
-
if (!s.found && !s.members.length)
|
|
419
|
+
if (!s.found && !s.members.length) {
|
|
420
|
+
return `no epic named ${s.epic}, and no spec names it as its Epic${s.here ? ` in ${s.here}` : ''}.\n`
|
|
421
|
+
}
|
|
407
422
|
const lanes = s.lanes === null ? 'no lane cap' : `${s.lanes} lanes, ${s.freeLanes} free`
|
|
408
|
-
const
|
|
409
|
-
const out = [
|
|
423
|
+
const where = s.here ? ` · headers from ${s.here}` : s.found ? '' : ' · epic not on the base branch'
|
|
424
|
+
const out = []
|
|
410
425
|
if (!s.members.length) {
|
|
411
|
-
out.push(` no members — no spec carries \`> **Epic:** ${s.epic}\``)
|
|
426
|
+
out.push(`${s.epic} — 0 members · ${lanes}${where}`, '', ` no members — no spec carries \`> **Epic:** ${s.epic}\``)
|
|
412
427
|
} else {
|
|
413
428
|
const { rows, next } = s.rows ? { rows: s.rows, next: s.next } : epicRows(s)
|
|
414
|
-
const
|
|
429
|
+
const plan = s.steps ? s : epicPlan(s, { rows, next })
|
|
430
|
+
const { progress, groups, steps } = plan
|
|
431
|
+
const byName = new Map(rows.map((r) => [r.spec, r]))
|
|
415
432
|
out.push(
|
|
416
|
-
|
|
433
|
+
`${s.epic} — ${progress.done} of ${progress.total} done · ${progress.inFlight} in flight · ${lanes}${where}`,
|
|
434
|
+
` ${progressBar(progress)}`,
|
|
417
435
|
)
|
|
418
|
-
|
|
436
|
+
const group = (title, names, cells) => {
|
|
437
|
+
if (!names.length) return
|
|
438
|
+
out.push('', ` ${title}`, ...aligned(names.map((n) => cells(byName.get(n))), ' '))
|
|
439
|
+
}
|
|
440
|
+
group('in flight', groups.inFlight, (r) => [r.spec, r.next.state || 'in-progress', r.tab || '—'])
|
|
441
|
+
group('ready to start', groups.ready, (r) => [r.spec, r.next.why || 'ready'])
|
|
442
|
+
group('waiting', groups.waiting, (r) => [r.spec, r.next.why || actionText(r.next)])
|
|
443
|
+
if (groups.done.length) out.push('', ` done (${groups.done.length})`, ` ${groups.done.join(', ')}`)
|
|
444
|
+
out.push('', ' next steps')
|
|
445
|
+
if (steps.length) out.push(...steps.flatMap((st, i) => stepLines(st, i + 1, s.freeLanes)))
|
|
446
|
+
else out.push(' nothing to type — every open member is building, held or waiting')
|
|
419
447
|
}
|
|
420
448
|
const shape = [
|
|
421
449
|
['waves', s.waves.map((w, i) => `${i + 1}: ${w.join(', ')}`).join(' · ')],
|
|
@@ -427,6 +455,28 @@ function formatEpicStatus(s) {
|
|
|
427
455
|
return out.join('\n') + '\n'
|
|
428
456
|
}
|
|
429
457
|
|
|
458
|
+
// `[█████░░░░]` — one cell per member, so it reads as a count, not a percent.
|
|
459
|
+
function progressBar({ done, total }) {
|
|
460
|
+
return `[${'█'.repeat(done)}${'░'.repeat(Math.max(0, total - done))}]`
|
|
461
|
+
}
|
|
462
|
+
|
|
463
|
+
// One numbered step: where, then what to type, then what it unblocks and any
|
|
464
|
+
// caution, each on its own line so a phone-width terminal does not wrap them
|
|
465
|
+
// into one another.
|
|
466
|
+
function stepLines(st, n, freeLanes) {
|
|
467
|
+
const where =
|
|
468
|
+
st.where === 'epic'
|
|
469
|
+
? "in the epic's tab"
|
|
470
|
+
: st.where === 'new-tab'
|
|
471
|
+
? `in a new tab${freeLanes === null || freeLanes === undefined ? '' : ` (${freeLanes} lane${freeLanes === 1 ? '' : 's'} free)`}`
|
|
472
|
+
: `in ${st.tab || `${st.spec}'s tab`}`
|
|
473
|
+
const what = st.verb === 'verdict' ? (st.link ? `press a verdict → ${st.link}` : 'press a verdict on its page') : st.command
|
|
474
|
+
const lines = [` ${n}. ${where}: ${what}`]
|
|
475
|
+
if (st.unblocks.length) lines.push(` → unblocks ${st.unblocks.join(', ')}`)
|
|
476
|
+
if (st.caution) lines.push(` ⚠ ${st.caution}`)
|
|
477
|
+
return lines
|
|
478
|
+
}
|
|
479
|
+
|
|
430
480
|
/**
|
|
431
481
|
* What starting or building one member should hear about — the half of
|
|
432
482
|
* `epic check` that is about other members in flight. Each warning names the
|
package/src/env/epicpage.js
CHANGED
|
@@ -18,7 +18,7 @@
|
|
|
18
18
|
* no cell ever has to list tiers.
|
|
19
19
|
*/
|
|
20
20
|
|
|
21
|
-
const { actionText } = require('./nextaction.js')
|
|
21
|
+
const { actionText, epicRows, epicPlan } = require('./nextaction.js')
|
|
22
22
|
|
|
23
23
|
const REFRESH_SECONDS = 30
|
|
24
24
|
|
|
@@ -28,18 +28,6 @@ function escapeHtml(s) {
|
|
|
28
28
|
|
|
29
29
|
const href = (spec) => escapeHtml(encodeURIComponent(spec))
|
|
30
30
|
|
|
31
|
-
// The `next` cell. Each verb that names a code or a page is handled here; the
|
|
32
|
-
// rest are `actionText`, the same words the terminal prints.
|
|
33
|
-
function nextCell(row) {
|
|
34
|
-
const a = row.next
|
|
35
|
-
if (a.verb === 'claim') return 'verdict waiting — <code>/spec-reviewed</code> in its tab'
|
|
36
|
-
if (a.verb === 'verdict') return `<a href="${href(row.spec)}">press a verdict on its page →</a>`
|
|
37
|
-
if (a.command) {
|
|
38
|
-
return `<code>${escapeHtml(a.command)}</code>${a.why ? ` <span class="why">${escapeHtml(a.why)}</span>` : ''}`
|
|
39
|
-
}
|
|
40
|
-
return escapeHtml(actionText(a))
|
|
41
|
-
}
|
|
42
|
-
|
|
43
31
|
function memberCell(row) {
|
|
44
32
|
// An in-flight member with a tab has a page of its own on this server.
|
|
45
33
|
return row.tab ? `<a href="${href(row.spec)}">${escapeHtml(row.spec)}</a>` : escapeHtml(row.spec)
|
|
@@ -51,22 +39,66 @@ function syncLine({ spec, phase, wait }) {
|
|
|
51
39
|
return `${who} after ${wait.raw} (${mark})`
|
|
52
40
|
}
|
|
53
41
|
|
|
54
|
-
|
|
42
|
+
// One numbered step. A pass is named by what to type and never its code, like
|
|
43
|
+
// the `next` cell; a verdict links to the member's page.
|
|
44
|
+
function stepItem(st, freeLanes) {
|
|
45
|
+
const where =
|
|
46
|
+
st.where === 'epic'
|
|
47
|
+
? "In the epic's tab"
|
|
48
|
+
: st.where === 'new-tab'
|
|
49
|
+
? `In a new tab${freeLanes === null || freeLanes === undefined ? '' : ` (${freeLanes} lane${freeLanes === 1 ? '' : 's'} free)`}`
|
|
50
|
+
: `In <code>${escapeHtml(st.tab || `${st.spec}'s tab`)}</code>`
|
|
51
|
+
const what =
|
|
52
|
+
st.verb === 'claim'
|
|
53
|
+
? 'verdict waiting — <code>/spec-reviewed</code>'
|
|
54
|
+
: st.verb === 'verdict'
|
|
55
|
+
? `<a href="${href(st.spec)}">press a verdict on ${escapeHtml(st.spec)}'s page →</a>`
|
|
56
|
+
: `<code>${escapeHtml(st.command)}</code>`
|
|
57
|
+
const notes = [
|
|
58
|
+
st.unblocks.length ? `<div class="un">→ unblocks ${escapeHtml(st.unblocks.join(', '))}</div>` : '',
|
|
59
|
+
st.caution ? `<div class="warn">⚠ ${escapeHtml(st.caution)}</div>` : '',
|
|
60
|
+
].join('')
|
|
61
|
+
return `<li><div class="where">${where}</div><div class="what">${what}</div>${notes}</li>`
|
|
62
|
+
}
|
|
63
|
+
|
|
64
|
+
function renderEpicPage(answer, { refreshSeconds = REFRESH_SECONDS, project = null } = {}) {
|
|
55
65
|
const lanes = answer.lanes === null ? 'no lane cap' : `${answer.lanes} lanes, ${answer.freeLanes} free`
|
|
56
|
-
const
|
|
57
|
-
const
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
66
|
+
const { rows, next } = answer.rows ? { rows: answer.rows, next: answer.next } : epicRows(answer)
|
|
67
|
+
const { progress, groups, steps } = answer.steps ? answer : epicPlan(answer, { rows, next })
|
|
68
|
+
const byName = new Map(rows.map((r) => [r.spec, r]))
|
|
69
|
+
|
|
70
|
+
const section = (title, cls, names, cell) =>
|
|
71
|
+
names.length
|
|
72
|
+
? `<section class="${cls}"><h2>${title} <span class="n">${names.length}</span></h2>\n<table><tbody>\n${names
|
|
73
|
+
.map((n) => {
|
|
74
|
+
const r = byName.get(n)
|
|
75
|
+
return `<tr class="v-${escapeHtml(r.next.verb)}"><td class="m">${memberCell(r)}</td>${cell(r)}</tr>`
|
|
76
|
+
})
|
|
77
|
+
.join('\n')}\n</tbody></table></section>`
|
|
78
|
+
: ''
|
|
79
|
+
const groupsHtml = answer.members.length
|
|
80
|
+
? [
|
|
81
|
+
section('In flight', 'g-flight', groups.inFlight, (r) =>
|
|
82
|
+
`<td class="s">${escapeHtml(r.next.state || 'in-progress')}</td><td class="t">${r.tab ? `<code>${escapeHtml(r.tab)}</code>` : '—'}</td>`),
|
|
83
|
+
section('Ready to start', 'g-ready', groups.ready, (r) =>
|
|
84
|
+
`<td class="s">${r.next.why ? `<span class="warn">⚠ ${escapeHtml(r.next.why)}</span>` : 'ready'}</td>`),
|
|
85
|
+
section('Waiting', 'g-wait', groups.waiting, (r) => `<td class="s">${escapeHtml(r.next.why || actionText(r.next))}</td>`),
|
|
86
|
+
groups.done.length
|
|
87
|
+
? `<details class="g-done"><summary><h2>Done <span class="n">${groups.done.length}</span></h2></summary><p class="dim">${escapeHtml(groups.done.join(' · '))}</p></details>`
|
|
88
|
+
: '',
|
|
89
|
+
]
|
|
90
|
+
.filter(Boolean)
|
|
91
|
+
.join('\n')
|
|
68
92
|
: `<p class="empty">No member yet — no spec carries <code>> **Epic:** ${escapeHtml(answer.epic)}</code>.</p>`
|
|
69
|
-
|
|
93
|
+
|
|
94
|
+
const stepsHtml = answer.members.length
|
|
95
|
+
? `<section class="steps"><h2>Next steps</h2>\n${
|
|
96
|
+
steps.length
|
|
97
|
+
? `<ol>\n${steps.map((st) => stepItem(st, answer.freeLanes)).join('\n')}\n</ol>`
|
|
98
|
+
: '<p class="dim">Nothing to type — every open member is building, held or waiting.</p>'
|
|
99
|
+
}</section>`
|
|
100
|
+
: ''
|
|
101
|
+
const pct = progress.total ? Math.round((progress.done / progress.total) * 100) : 0
|
|
70
102
|
const shape = [
|
|
71
103
|
['waves', answer.waves.map((w, i) => `${i + 1}: ${w.join(', ')}`).join(' · ')],
|
|
72
104
|
['sync points', answer.syncPoints.map(syncLine).join(' · ')],
|
|
@@ -83,17 +115,18 @@ function renderEpicPage(answer, { refreshSeconds = REFRESH_SECONDS } = {}) {
|
|
|
83
115
|
<meta charset="utf-8">
|
|
84
116
|
<meta name="viewport" content="width=device-width, initial-scale=1">
|
|
85
117
|
<meta http-equiv="refresh" content="${Number(refreshSeconds)}">
|
|
86
|
-
<title>${escapeHtml(answer.epic)}</title>
|
|
118
|
+
<title>${project ? `${escapeHtml(project)} · ` : ''}${escapeHtml(answer.epic)}</title>
|
|
87
119
|
<style>
|
|
88
|
-
:root { --bg:#fff; --fg:#1a1a1a; --dim:#6b6b6b; --line:#e3e3e3; --link:#0b5fbd; --hot:#a15c00 }
|
|
120
|
+
:root { --bg:#fff; --fg:#1a1a1a; --dim:#6b6b6b; --line:#e3e3e3; --link:#0b5fbd; --hot:#a15c00; --ok:#1f7a3a }
|
|
89
121
|
@media (prefers-color-scheme: dark) {
|
|
90
|
-
:root:not([data-theme="light"]) { --bg:#16181c; --fg:#e6e6e6; --dim:#9a9a9a; --line:#2c2f36; --link:#7cb7ff; --hot:#f0b35a }
|
|
122
|
+
:root:not([data-theme="light"]) { --bg:#16181c; --fg:#e6e6e6; --dim:#9a9a9a; --line:#2c2f36; --link:#7cb7ff; --hot:#f0b35a; --ok:#5fc27e }
|
|
91
123
|
}
|
|
92
124
|
* { box-sizing:border-box }
|
|
93
125
|
body { margin:0; padding:2rem 1rem; background:var(--bg); color:var(--fg);
|
|
94
126
|
font:15px/1.5 ui-sans-serif,system-ui,-apple-system,Segoe UI,Roboto,sans-serif }
|
|
95
127
|
main { max-width:60rem; margin:0 auto }
|
|
96
128
|
h1 { font-size:1.1rem; margin:0 0 .25rem; font-weight:600 }
|
|
129
|
+
.eyebrow { color:var(--dim); font-size:.8rem; margin:0 0 .1rem }
|
|
97
130
|
.sub { color:var(--dim); margin:0 0 1.25rem }
|
|
98
131
|
.wrap { overflow-x:auto }
|
|
99
132
|
table { border-collapse:collapse; width:100% }
|
|
@@ -102,10 +135,24 @@ th, td { padding:.55rem .6rem .55rem 0; border-top:1px solid var(--line); vertic
|
|
|
102
135
|
a { color:var(--link); text-decoration:none; font-weight:600 }
|
|
103
136
|
a:hover { text-decoration:underline }
|
|
104
137
|
code { font-family:ui-monospace,SFMono-Regular,Menlo,monospace; font-size:.9em }
|
|
105
|
-
.why, .s, .t { color:var(--dim) }
|
|
106
|
-
.
|
|
107
|
-
.
|
|
108
|
-
|
|
138
|
+
.why, .s, .t, .dim { color:var(--dim) }
|
|
139
|
+
.bar { height:.5rem; background:var(--line); border-radius:.25rem; overflow:hidden; margin:0 0 1.5rem }
|
|
140
|
+
.bar > span { display:block; height:100%; background:var(--ok) }
|
|
141
|
+
h2 { font-size:.8rem; text-transform:uppercase; letter-spacing:.06em; color:var(--dim); font-weight:600; margin:1.5rem 0 .4rem; display:inline-block }
|
|
142
|
+
h2 .n { font-weight:400 }
|
|
143
|
+
section table td.m { width:40% }
|
|
144
|
+
.warn { color:var(--hot) }
|
|
145
|
+
.v-verdict .s, .v-claim .s { color:var(--hot) }
|
|
146
|
+
details summary { cursor:pointer; list-style:none }
|
|
147
|
+
details summary::-webkit-details-marker { display:none }
|
|
148
|
+
details summary h2::after { content:' ▸' } details[open] summary h2::after { content:' ▾' }
|
|
149
|
+
.steps { border-top:2px solid var(--line); margin-top:1.75rem }
|
|
150
|
+
.steps ol { margin:.25rem 0 0; padding-left:1.5rem }
|
|
151
|
+
.steps li { margin:0 0 .9rem }
|
|
152
|
+
.steps .where { color:var(--dim); font-size:.9em }
|
|
153
|
+
.steps .what { margin:.1rem 0 }
|
|
154
|
+
.steps .un { color:var(--ok) }
|
|
155
|
+
dl { margin:.5rem 0 0; display:grid; grid-template-columns:max-content 1fr; gap:.3rem 1rem }
|
|
109
156
|
dt { color:var(--dim) } dd { margin:0 }
|
|
110
157
|
.empty, .foot { color:var(--dim) }
|
|
111
158
|
.foot { margin-top:1.5rem; font-size:.85em }
|
|
@@ -113,11 +160,12 @@ dt { color:var(--dim) } dd { margin:0 }
|
|
|
113
160
|
</head>
|
|
114
161
|
<body>
|
|
115
162
|
<main>
|
|
116
|
-
<h1>${escapeHtml(answer.epic)}</h1>
|
|
117
|
-
<p class="sub">${
|
|
118
|
-
<div class="
|
|
119
|
-
|
|
120
|
-
${
|
|
163
|
+
${project ? `<p class="eyebrow">${escapeHtml(project)}</p>\n` : ''}<h1>${escapeHtml(answer.epic)}</h1>
|
|
164
|
+
<p class="sub">${progress.done} of ${progress.total} done · ${progress.inFlight} in flight · ${escapeHtml(lanes)}</p>
|
|
165
|
+
<div class="bar" role="img" aria-label="${progress.done} of ${progress.total} done"><span style="width:${pct}%"></span></div>
|
|
166
|
+
<div class="wrap">${groupsHtml}</div>
|
|
167
|
+
${stepsHtml}
|
|
168
|
+
${shape ? `<details class="shape"><summary><h2>Waves · never together</h2></summary>\n<dl>\n${shape}\n</dl></details>` : ''}
|
|
121
169
|
<p class="foot">Refreshes every ${Number(refreshSeconds)} s. Type commands in the member's own tab.</p>
|
|
122
170
|
</main>
|
|
123
171
|
</body>
|
package/src/env/epicread.js
CHANGED
|
@@ -16,7 +16,7 @@ const path = require('node:path')
|
|
|
16
16
|
|
|
17
17
|
const { isEpic } = require('./resolve.js')
|
|
18
18
|
const { epicStatus, epicHeaders, indexSpecTree } = require('./epic.js')
|
|
19
|
-
const { epicRows, readNextInputs } = require('./nextaction.js')
|
|
19
|
+
const { epicRows, epicPlan, readNextInputs } = require('./nextaction.js')
|
|
20
20
|
const { reviewOutPath } = require('./review.js')
|
|
21
21
|
|
|
22
22
|
/**
|
|
@@ -36,6 +36,44 @@ function epicTree(git, base) {
|
|
|
36
36
|
return { index: indexSpecTree(listing), readFile: (p) => git(['show', `${base}:${p}`]), candidates }
|
|
37
37
|
}
|
|
38
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
|
+
|
|
39
77
|
// A provisioned spec's own overview and bucket, read in its worktree — the
|
|
40
78
|
// copy where an in-flight spec's bucket and headers are true. null when the
|
|
41
79
|
// worktree holds no readable copy.
|
|
@@ -103,7 +141,7 @@ function memberReaders({ dir, config, worktrees, linkFor = () => null, git }) {
|
|
|
103
141
|
function epicAnswer(epic, inputs, readers) {
|
|
104
142
|
const status = epicStatus({ epic, ...inputs })
|
|
105
143
|
const { rows, next } = epicRows(status, readers)
|
|
106
|
-
return { ...status, rows, next }
|
|
144
|
+
return { ...status, rows, next, ...epicPlan(status, { rows, next }) }
|
|
107
145
|
}
|
|
108
146
|
|
|
109
|
-
module.exports = { epicTree, worktreeOverview, epicsInFlight, memberReaders, epicAnswer }
|
|
147
|
+
module.exports = { epicTree, workingTree, worktreeOverview, epicsInFlight, memberReaders, epicAnswer }
|
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 }
|