@skitterbyte/skitterspec-jira 2.8.0 → 2.9.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/src/cli.js CHANGED
@@ -2,6 +2,8 @@
2
2
 
3
3
  const fs = require('fs')
4
4
  const path = require('path')
5
+ const os = require('os')
6
+ const { pathToFileURL } = require('url')
5
7
  const { execFileSync } = require('child_process')
6
8
  const { init, resync, reset, checkSync, isExistingSetup } = require('./init.js')
7
9
  const {
@@ -80,6 +82,8 @@ const {
80
82
  primaryAnchor,
81
83
  attachProject,
82
84
  projectName,
85
+ projectCategory,
86
+ describeProject,
83
87
  repoRootOf,
84
88
  prefixOf,
85
89
  toRepoPath,
@@ -200,11 +204,19 @@ const {
200
204
  appendChangelog,
201
205
  waitsMetByRebase,
202
206
  } = require('./env/epic.js')
203
- const { nextAction, readNextInputs } = require('./env/nextaction.js')
207
+ const { nextAction, readNextInputs, actionText } = require('./env/nextaction.js')
204
208
  const { epicTree, workingTree, worktreeOverview, epicsInFlight, memberReaders, epicAnswer } = require('./env/epicread.js')
205
209
  const { planHotfixLand, planBranchHotfixLand, planBranchHotfixFinish, planHotfixFinish } = require('./env/hotfix.js')
206
210
  const { runHotfixLand, describeStep: describeHotfixStep } = require('./env/hotfixland.js')
207
211
  const { planDev } = require('./env/dev.js')
212
+ const { windowFor, windowLabel, humanLabel, localDay } = require('./tada/window.js')
213
+ const { ROUTE: TADA_ROUTE, tadaQuery, recapKey: tadaRecapKey, recapPath: tadaRecapPath } = require('./tada/serve.js')
214
+ const { defaultRoot, knownDirs } = require('./tada/transcripts.js')
215
+ const { setProjectKeys } = require('./env/projectedit.js')
216
+ const { buildDigest, gitRepoOf } = require('./tada/digest.js')
217
+ const { readRepoFacts } = require('./tada/repo.js')
218
+ const { formatTada } = require('./tada/format.js')
219
+ const { renderTadaPage } = require('./tada/page.js')
208
220
  const { startProcess, stopProcess, waitHealthy, readPid, isAlive } = require('./env/supervise.js')
209
221
  const {
210
222
  renderRoutes,
@@ -326,6 +338,24 @@ Usage:
326
338
  skitterspec epic bypass <spec> [--phase N]
327
339
  Build past an unmet wait, recorded as a dated
328
340
  line in the member's Changelog.
341
+ skitterspec project This project's name and category, and where each
342
+ comes from. --name <n> / --category <c> set them
343
+ in specs/.core/env.config.json ("" clears),
344
+ editing only those keys; --categories lists the
345
+ categories your other projects use (--json).
346
+ skitterspec tada What you did in Claude Code: the window's sessions,
347
+ commits and spec moves across every project,
348
+ folded into each repo and grouped by spec.
349
+ --since <when> (to now) or --on <when> (that day):
350
+ today, yesterday, last friday, 3 days ago, 2w,
351
+ 2026-11-06 or 6 Nov. Scoped to projects sharing
352
+ this one's project.category (--all-projects for
353
+ every project). Prompts on branches with no spec
354
+ are left out unless they led to one (--chat keeps
355
+ them). --here for this repo only,
356
+ --json, --page [--summary <recap.md>] for an HTML
357
+ page. Reads ~/.claude/projects; exits 0 unless the
358
+ window cannot be read.
329
359
  skitterspec gating <cmd> Release-gating check (opt-in; needs
330
360
  specs/.core/gating.config.json). Subcommands:
331
361
  check [spec] report specs with no recorded gating
@@ -348,6 +378,8 @@ Options (init / update):
348
378
  --yes, -y Accept defaults; skip the interactive setup prompts
349
379
  --isolation / --no-isolation Enable/skip per-spec isolation (a git
350
380
  worktree per spec; writes env.config.json)
381
+ --name <name> / --category <c> (init --isolation) Write project.name /
382
+ project.category into env.config.json
351
383
  --remove-release-tooling (update) Remove leftover release tooling
352
384
  non-interactively (moved to skittership)
353
385
 
@@ -389,7 +421,11 @@ function parse(argv) {
389
421
  else if (a === '--diff') opts.diff = true
390
422
  else if (a === '--check') opts.check = true
391
423
  else if (a === '--dir') opts.dir = argv[++i]
392
- else if (a.startsWith('--')) throw new Error(`unknown option: ${a}`)
424
+ else if (a === '--name' || a === '--category') {
425
+ const v = argv[++i]
426
+ if (v === undefined) throw new Error(`${a} needs a value`)
427
+ opts.project = { ...opts.project, [a.slice(2)]: v }
428
+ } else if (a.startsWith('--')) throw new Error(`unknown option: ${a}`)
393
429
  else positional.push(a)
394
430
  }
395
431
  return { opts, positional }
@@ -566,6 +602,25 @@ function inFlightStatus(argv) {
566
602
  const json = argv.includes('--json')
567
603
  const at = argv.indexOf('--dir')
568
604
  const from = path.resolve(at !== -1 && argv[at + 1] ? argv[at + 1] : process.cwd())
605
+ const { anchor, present, rows } = inFlightRows(from)
606
+ if (json) {
607
+ const specs = rows.map((r) => ({ ...r, inFlight: isInFlight(r) }))
608
+ process.stdout.write(JSON.stringify({ isolation: present, specs }, null, 2) + '\n')
609
+ return
610
+ }
611
+ if (!present) {
612
+ process.stdout.write('no specs in flight — isolation is not enabled here, so no spec has a worktree.\n')
613
+ return
614
+ }
615
+ process.stdout.write(projectLine(anchor) + formatInFlight(rows, { dir: anchor.dir }))
616
+ }
617
+
618
+ /**
619
+ * The rows behind `skitterspec status`, read from `from`'s repo — shared with
620
+ * `skitterspec tada`, whose open items are exactly these, so the two can never
621
+ * disagree about what is in flight.
622
+ */
623
+ function inFlightRows(from) {
569
624
  const anchor = primaryAnchor(from, gitReader(from))
570
625
  const dir = anchor.dir
571
626
  const { config, present } = loadEnvConfig(dir)
@@ -590,18 +645,283 @@ function inFlightStatus(argv) {
590
645
  }
591
646
  : r,
592
647
  )
648
+ return { anchor, present, rows }
649
+ }
650
+
651
+ /**
652
+ * `skitterspec project` — what this project is called and which category it is
653
+ * in, and the one way to set them. It writes the checkout it runs in (in a
654
+ * worktree, that is the branch), and leaves committing to the caller.
655
+ *
656
+ * NO env.config.json, NO WRITE. That file's presence is what turns isolation
657
+ * on, so creating it to hold a category would change how every skill behaves
658
+ * as a side effect of naming a project.
659
+ */
660
+ function projectCommand(argv) {
661
+ const json = argv.includes('--json')
662
+ if (argv.includes('--categories')) return projectCategories(json)
663
+
664
+ const cwd = process.cwd()
665
+ const anchor = primaryAnchor(cwd, gitReader(cwd))
666
+ const top = gitReader(cwd)(['rev-parse', '--show-toplevel'])
667
+ // THE TREE YOU ARE STANDING IN, never the primary checkout: a worktree's
668
+ // config is the branch's, and that is where the change is meant to land.
669
+ const dir = top ? projectIn(path.resolve(top), anchor.prefix) : cwd
670
+ const file = path.join(dir, 'specs', '.core', 'env.config.json')
671
+ const refuse = (why) => {
672
+ process.stderr.write(`skitterspec project: ${why}\n`)
673
+ process.exitCode = 1
674
+ }
675
+
676
+ const changes = {}
677
+ for (const k of ['name', 'category']) {
678
+ const at = argv.indexOf(`--${k}`)
679
+ if (at === -1) continue
680
+ const v = argv[at + 1]
681
+ if (v === undefined || (v.startsWith('--') && v !== '')) return refuse(`--${k} needs a value ("" clears it)`)
682
+ changes[k] = v.trim()
683
+ }
684
+
685
+ if (!fs.existsSync(file)) {
686
+ if (Object.keys(changes).length) {
687
+ return refuse(
688
+ `no specs/.core/env.config.json here — it is what turns isolation on, so it is not created just to hold a ` +
689
+ `${Object.keys(changes).join(' and ')}. Adopt isolation first: skitterspec init --isolation`,
690
+ )
691
+ }
692
+ } else if (Object.keys(changes).length) {
693
+ let edited
694
+ try {
695
+ edited = setProjectKeys(fs.readFileSync(file, 'utf8'), changes)
696
+ } catch (e) {
697
+ return refuse(`${path.relative(cwd, file) || file}: ${e.message}`)
698
+ }
699
+ fs.writeFileSync(file, edited)
700
+ }
701
+
702
+ let config = {}
703
+ try {
704
+ config = loadEnvConfig(dir).config
705
+ } catch (e) {
706
+ return refuse(e.message)
707
+ }
708
+ attachProject(config, anchor)
709
+ const d = describeProject(config)
710
+ const wrote = Object.keys(changes)
593
711
  if (json) {
594
- const specs = rows.map((r) => ({ ...r, inFlight: isInFlight(r) }))
595
- process.stdout.write(JSON.stringify({ isolation: present, specs }, null, 2) + '\n')
712
+ process.stdout.write(JSON.stringify({ dir, file: fs.existsSync(file) ? file : null, ...d, wrote }, null, 2) + '\n')
596
713
  return
597
714
  }
598
- if (!present) {
599
- process.stdout.write('no specs in flight — isolation is not enabled here, so no spec has a worktree.\n')
715
+ const line = (label, x) => ` ${label.padEnd(9)} ${x.value === null ? '—' : x.value} (${x.source})`
716
+ const out = [`project: ${dir}`, line('name:', d.name), line('category:', d.category)]
717
+ if (wrote.length) out.push('', `set ${wrote.join(' and ')} in specs/.core/env.config.json — commit it to keep it`)
718
+ else if (!fs.existsSync(file)) out.push('', 'no specs/.core/env.config.json — these are the defaults')
719
+ process.stdout.write(out.join('\n') + '\n')
720
+ }
721
+
722
+ // The categories the projects you work in already carry — so a new one picks
723
+ // `work` rather than inventing `Work stuff` and splitting a report in two.
724
+ // Projects are the repos your Claude Code sessions ran in; each is asked for
725
+ // its own config.
726
+ function projectCategories(json) {
727
+ const repos = new Set()
728
+ for (const d of knownDirs(defaultRoot())) {
729
+ const r = gitRepoOf(d)
730
+ if (r.repo) repos.add(r.repo)
731
+ }
732
+ const byCategory = new Map()
733
+ const none = []
734
+ for (const repo of [...repos].sort()) {
735
+ let category = null
736
+ let name = path.basename(repo)
737
+ try {
738
+ const { config } = loadEnvConfig(repo)
739
+ category = projectCategory(config)
740
+ name = (config.project && config.project.name && config.project.name.trim()) || name
741
+ } catch {
742
+ // An unreadable config is that repo's to fix; it simply has no answer.
743
+ }
744
+ if (!category) {
745
+ none.push(name)
746
+ continue
747
+ }
748
+ const key = category.toLowerCase()
749
+ if (!byCategory.has(key)) byCategory.set(key, { spellings: new Map(), projects: [] })
750
+ const row = byCategory.get(key)
751
+ row.spellings.set(category, (row.spellings.get(category) || 0) + 1)
752
+ row.projects.push(name)
753
+ }
754
+ // One category, however it was capitalised — shown as most projects spell
755
+ // it, the tie broken alphabetically so the answer does not depend on which
756
+ // repo happened to be read first.
757
+ const rows = [...byCategory.values()]
758
+ .map(({ spellings, projects }) => ({
759
+ category: [...spellings].sort((a, b) => b[1] - a[1] || (a[0] < b[0] ? -1 : 1))[0][0],
760
+ projects,
761
+ }))
762
+ .sort((a, b) => b.projects.length - a.projects.length || a.category.localeCompare(b.category))
763
+ if (json) {
764
+ process.stdout.write(JSON.stringify({ categories: rows, uncategorised: none }, null, 2) + '\n')
600
765
  return
601
766
  }
602
- process.stdout.write(projectLine(anchor) + formatInFlight(rows, { dir }))
767
+ const width = Math.max(8, ...rows.map((r) => r.category.length))
768
+ const out = rows.length ? ['categories in use:', ...rows.map((r) => ` ${r.category.padEnd(width)} ${r.projects.length} ${r.projects.join(', ')}`)] : ['no project has a category yet']
769
+ if (none.length) out.push(`uncategorised: ${none.join(', ')}`)
770
+ process.stdout.write(out.join('\n') + '\n')
603
771
  }
604
772
 
773
+ /**
774
+ * `skitterspec tada` — the ta-da list's digest: what was done in the window,
775
+ * across every project, folded into repos and grouped by branch. Advisory and
776
+ * read-only: always exits 0, a quiet day included — an empty answer is not a
777
+ * finding. Only a `--since` it cannot read refuses, because a window guessed
778
+ * from a typo would report the wrong day with total confidence.
779
+ */
780
+ async function tadaCommand(argv) {
781
+ const json = argv.includes('--json')
782
+ let window
783
+ try {
784
+ window = windowFor({ since: tadaFlag(argv, '--since'), on: tadaFlag(argv, '--on') })
785
+ } catch (e) {
786
+ process.stderr.write(`skitterspec tada: ${e.message}\n`)
787
+ process.exitCode = 1
788
+ return
789
+ }
790
+ const flags = {
791
+ on: tadaFlag(argv, '--on') ? localDay(window.since) : null,
792
+ since: tadaFlag(argv, '--since') ? localDay(window.since) : null,
793
+ all: argv.includes('--all-projects'),
794
+ chat: argv.includes('--chat'),
795
+ here: argv.includes('--here'),
796
+ }
797
+ let recap = null
798
+ if (argv.includes('--page')) {
799
+ // The recap is the model's, handed over as a file.
800
+ const from = tadaFlag(argv, '--summary')
801
+ if (from) {
802
+ try {
803
+ recap = fs.readFileSync(path.resolve(from), 'utf8')
804
+ } catch (e) {
805
+ process.stderr.write(`skitterspec tada: --summary ${from}: ${e.code || e.message}\n`)
806
+ process.exitCode = 1
807
+ return
808
+ }
809
+ }
810
+ // Served where the review server can serve it: the page is drawn per
811
+ // request there, so only the recap is kept. It prints the links and
812
+ // nothing else, because the digest it carries was already read once.
813
+ if (await serveTadaPage({ window, flags, recap })) return
814
+ }
815
+ const digest = await buildDigest({
816
+ root: defaultRoot(),
817
+ window,
818
+ here: flags.here ? process.cwd() : null,
819
+ category: flags.all ? null : runningCategory(process.cwd()),
820
+ chat: flags.chat,
821
+ facts: (repo) => {
822
+ let config = {}
823
+ try {
824
+ config = loadEnvConfig(repo).config
825
+ } catch {
826
+ // An unreadable config is the repo's to fix, not this report's — the
827
+ // defaults still read its commits; only a custom branch.pattern is lost.
828
+ }
829
+ return readRepoFacts({ repo, git: gitReader(repo), config, window })
830
+ },
831
+ openFor: (repo) => {
832
+ try {
833
+ return inFlightRows(repo)
834
+ .rows.filter(isInFlight)
835
+ .map((r) => ({ spec: r.spec, detail: detailOf(r), next: r.next ? actionText(r.next) : null }))
836
+ } catch {
837
+ return []
838
+ }
839
+ },
840
+ })
841
+ // The reader's own dates, for the text header and the page; the digest's
842
+ // own `since`/`until` stay UTC instants for a script.
843
+ digest.window.label = humanLabel(window)
844
+ if (argv.includes('--page')) {
845
+ // No server to serve it: the page is a file on this machine, as it was.
846
+ const out = path.join(os.tmpdir(), `skitterspec-tada-${windowLabel(window).replace(' → ', '_')}.html`)
847
+ fs.writeFileSync(out, renderTadaPage(digest, { recap, title: `Ta-da · ${digest.window.label}`, category: digest.category || null }))
848
+ process.stdout.write(`page: ${pathToFileURL(out).href}\n`)
849
+ return
850
+ }
851
+ if (json) {
852
+ process.stdout.write(JSON.stringify(digest, null, 2) + '\n')
853
+ return
854
+ }
855
+ process.stdout.write(formatTada(digest))
856
+ }
857
+
858
+ /**
859
+ * `--page` through the review server: save the recap where the server reads
860
+ * it, make sure the server is up, and print every tier for the window's
861
+ * address — the stack a review render prints, for the `_tada` route.
862
+ *
863
+ * Returns false — fall back to the file — where there is nothing to serve
864
+ * from: no isolation here, `review.serve: "never"`, or a server that could not
865
+ * start. Each of those is the project's or the machine's state, not a failure
866
+ * of the page, so the file is still written and nothing exits non-zero.
867
+ */
868
+ async function serveTadaPage({ window, flags, recap }) {
869
+ const cwd = process.cwd()
870
+ const anchor = primaryAnchor(cwd, gitReader(cwd))
871
+ let loaded
872
+ try {
873
+ loaded = loadEnvConfig(anchor.dir)
874
+ } catch {
875
+ return false
876
+ }
877
+ const { config, present } = loaded
878
+ if (!present || config.review.serve === 'never') return false
879
+ attachProject(config, anchor)
880
+ const dir = anchor.dir
881
+ const ask = { on: flags.on, since: flags.since, window, all: flags.all, chat: flags.chat }
882
+ if (recap !== null) {
883
+ const file = tadaRecapPath(path.join(dir, stateDirLabel(config)), tadaRecapKey(ask))
884
+ fs.mkdirSync(path.dirname(file), { recursive: true })
885
+ fs.writeFileSync(file, recap)
886
+ }
887
+ const up = await ensureReviewServer(dir, config, { host: config.review.allowNetwork ? '0.0.0.0' : '127.0.0.1' })
888
+ if (up.error) return false
889
+ const served = reviewServedUrls(up, offerableLanAddresses(), TADA_ROUTE)
890
+ // The window rides in the query, as absolute days, so the link means the
891
+ // same page tomorrow as it does now.
892
+ const q = tadaQuery({ ...flags, on: flags.on || (flags.since ? null : localDay(window.since)) })
893
+ const withQ = (u) => (u ? `${u}${q}` : u)
894
+ const page = { ...served, loopbackUrl: withQ(served.loopbackUrl), url: withQ(served.url), alternates: (served.alternates || []).map(withQ) }
895
+ const tiers = reviewTierStack({ served: page, fileUrl: null, publishedUrl: null, config })
896
+ process.stdout.write(`page: ${humanLabel(window)}\n${tiers.map(reviewTierLine).join('\n')}\n`)
897
+ return true
898
+ }
899
+
900
+ // The category of the project a report is run from — its scope. Null (report
901
+ // everything) outside a repo, in a repo with no category, or with a config that
902
+ // cannot be read: an unreadable config narrowing the report to nothing would
903
+ // be the confident wrong answer.
904
+ function runningCategory(cwd) {
905
+ const r = gitRepoOf(cwd)
906
+ if (!r.repo) return null
907
+ try {
908
+ return projectCategory(loadEnvConfig(r.repo).config)
909
+ } catch {
910
+ return null
911
+ }
912
+ }
913
+
914
+ // A flag's value, which may be several words — `--since last friday`,
915
+ // `--on 6 Nov` — running to the next flag. Quoting it works too.
916
+ function tadaFlag(argv, name) {
917
+ const at = argv.indexOf(name)
918
+ if (at === -1) return undefined
919
+ const words = []
920
+ for (let i = at + 1; i < argv.length && !argv[i].startsWith('--'); i++) words.push(argv[i])
921
+ return words.length ? words.join(' ') : undefined
922
+ }
923
+
924
+
605
925
  /**
606
926
  * `skitterspec epic status <epic>` — the members' own headers turned into an
607
927
  * order. Waits are read off the BASE BRANCH by git, never off whatever the
@@ -3924,7 +4244,7 @@ function specEnvResolve(dir, config, specArg, flags = {}) {
3924
4244
  `branch: ${r.branch}\n` +
3925
4245
  `worktree: ${r.projectPath}\n` +
3926
4246
  `project: ${r.projectName}\n` +
3927
- projectLine(config.project),
4247
+ projectLine(config.checkout),
3928
4248
  )
3929
4249
  }
3930
4250
 
@@ -7530,6 +7850,16 @@ async function run(argv) {
7530
7850
  return
7531
7851
  }
7532
7852
 
7853
+ if (cmd === 'project') {
7854
+ projectCommand(rest)
7855
+ return
7856
+ }
7857
+
7858
+ if (cmd === 'tada') {
7859
+ await tadaCommand(rest)
7860
+ return
7861
+ }
7862
+
7533
7863
  if (cmd === 'epic') {
7534
7864
  const [sub, ...eArgs] = rest
7535
7865
  if (sub === 'status') epicStatusCommand(eArgs)
@@ -7598,6 +7928,7 @@ async function run(argv) {
7598
7928
  isolation,
7599
7929
  workspaceMode,
7600
7930
  gating,
7931
+ project: opts.project,
7601
7932
  })
7602
7933
  break
7603
7934
  }
package/src/env/config.js CHANGED
@@ -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,
@@ -309,9 +314,8 @@ const DEFAULT_CONFIG = Object.freeze({
309
314
  allowRemote: false,
310
315
  commitWith: '/commit',
311
316
  required: true,
312
- // The name every generated page carries in its tab and above its heading.
313
- // Empty means "the project folder's name" (`projectName` in project.js) —
314
- // the override exists for a checkout named `app` or `repo`.
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.
315
319
  projectName: '',
316
320
  // External code reviewers whose findings render as CHECKS on the page.
317
321
  // Empty by default and never written by `init`: configuring one sends the
@@ -400,6 +404,7 @@ function collectUnknownKeys(parsed, known = DEFAULT_CONFIG, prefix = '') {
400
404
  function defaults() {
401
405
  return {
402
406
  mode: DEFAULT_CONFIG.mode,
407
+ project: { ...DEFAULT_CONFIG.project },
403
408
  worktree: { ...DEFAULT_CONFIG.worktree },
404
409
  docker: { ...DEFAULT_CONFIG.docker },
405
410
  seedFiles: { mode: DEFAULT_CONFIG.seedFiles.mode, files: [] },
@@ -633,6 +638,11 @@ function normalizeAfterLand(parsed, setupTriggers) {
633
638
  function mergeConfig(base, parsed) {
634
639
  if (!isObject(parsed)) return base
635
640
 
641
+ if (isObject(parsed.project)) {
642
+ assign(base.project, parsed.project, 'name', 'string')
643
+ assign(base.project, parsed.project, 'category', 'string')
644
+ }
645
+
636
646
  if (isObject(parsed.worktree)) {
637
647
  assign(base.worktree, parsed.worktree, 'root', 'string')
638
648
  assign(base.worktree, parsed.worktree, 'folderPattern', 'string')
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
 
@@ -408,11 +408,12 @@ function aligned(lines, indent = ' ') {
408
408
  }
409
409
 
410
410
  /**
411
- * The human answer: a headline, one row per member saying what to run and in
412
- * which tab, then the plan's shape — waves, sync points, clashes — wherever
413
- * there is something to say. `s.rows` comes from `epicRows`; a status without
414
- * them is rendered with nothing read off disk, so an in-flight member says it
415
- * cannot tell rather than guessing.
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.
416
417
  */
417
418
  function formatEpicStatus(s) {
418
419
  if (!s.found && !s.members.length) {
@@ -420,17 +421,29 @@ function formatEpicStatus(s) {
420
421
  }
421
422
  const lanes = s.lanes === null ? 'no lane cap' : `${s.lanes} lanes, ${s.freeLanes} free`
422
423
  const where = s.here ? ` · headers from ${s.here}` : s.found ? '' : ' · epic not on the base branch'
423
- const head = `${s.epic} — ${s.members.length} member${s.members.length === 1 ? '' : 's'} · ${lanes}${where}`
424
- const out = [head, '']
424
+ const out = []
425
425
  if (!s.members.length) {
426
- 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}\``)
427
427
  } else {
428
428
  const { rows, next } = s.rows ? { rows: s.rows, next: s.next } : epicRows(s)
429
- const state = (r) => (r.bucket === 'in-progress' ? r.next.state : r.next.state || r.bucket || 'unknown')
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]))
430
432
  out.push(
431
- ...aligned([['member', 'state', 'next', 'tab'], ...rows.map((r) => [r.spec, state(r), actionText(r.next), r.tab || '—'])]),
433
+ `${s.epic} — ${progress.done} of ${progress.total} done · ${progress.inFlight} in flight · ${lanes}${where}`,
434
+ ` ${progressBar(progress)}`,
432
435
  )
433
- if (next) out.push('', ` ${s.epic}: ${actionText(next)}`)
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')
434
447
  }
435
448
  const shape = [
436
449
  ['waves', s.waves.map((w, i) => `${i + 1}: ${w.join(', ')}`).join(' · ')],
@@ -442,6 +455,28 @@ function formatEpicStatus(s) {
442
455
  return out.join('\n') + '\n'
443
456
  }
444
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
+
445
480
  /**
446
481
  * What starting or building one member should hear about — the half of
447
482
  * `epic check` that is about other members in flight. Each warning names the