@skitterbyte/skitterspec-jira 2.5.1 → 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/src/cli.js CHANGED
@@ -72,6 +72,7 @@ const {
72
72
  repoInfo,
73
73
  expandTokens,
74
74
  splitPrefix,
75
+ isEpic,
75
76
  parseBaseVersion,
76
77
  BUCKETS,
77
78
  } = require('./env/resolve.js')
@@ -187,6 +188,18 @@ const { parseRemote, prFor, prPlanCommand, prAbandonCommand, preferRemoteBase }
187
188
  const { collectDisposition } = require('./env/disposition.js')
188
189
  const { planHandoff } = require('./env/handoff.js')
189
190
  const { collectInFlight, detailOf, formatInFlight, isInFlight } = require('./env/inflight.js')
191
+ const {
192
+ epicStatus,
193
+ formatEpicStatus,
194
+ indexSpecTree,
195
+ epicHeaders,
196
+ memberCheck,
197
+ bypassLine,
198
+ appendChangelog,
199
+ waitsMetByRebase,
200
+ } = require('./env/epic.js')
201
+ const { nextAction, readNextInputs } = require('./env/nextaction.js')
202
+ const { epicTree, worktreeOverview, epicsInFlight, memberReaders, epicAnswer } = require('./env/epicread.js')
190
203
  const { planHotfixLand, planBranchHotfixLand, planBranchHotfixFinish, planHotfixFinish } = require('./env/hotfix.js')
191
204
  const { runHotfixLand, describeStep: describeHotfixStep } = require('./env/hotfixland.js')
192
205
  const { planDev } = require('./env/dev.js')
@@ -296,6 +309,20 @@ Usage:
296
309
  skitterspec status What is in flight here: every spec with a worktree,
297
310
  its bucket and phase progress read from that
298
311
  worktree (--json). Offline; always exits 0.
312
+ skitterspec epic status <epic>
313
+ An epic's members, from their Epic: and Waits on:
314
+ headers: ready now, blocked and on what, cannot
315
+ tell, waves, sync points, never-together pairs
316
+ and free lanes (--json). Waits are met only on
317
+ the base branch. Always exits 0.
318
+ skitterspec epic check <spec> [--phase N]
319
+ What starting a member (or building phase N)
320
+ should hear: unmet waits, with a bypass offer the
321
+ first time, and members on the same files in
322
+ flight. Silent when nothing; never refuses.
323
+ skitterspec epic bypass <spec> [--phase N]
324
+ Build past an unmet wait, recorded as a dated
325
+ line in the member's Changelog.
299
326
  skitterspec gating <cmd> Release-gating check (opt-in; needs
300
327
  specs/.core/gating.config.json). Subcommands:
301
328
  check [spec] report specs with no recorded gating
@@ -540,7 +567,26 @@ function inFlightStatus(argv) {
540
567
  const dir = anchor.dir
541
568
  const { config, present } = loadEnvConfig(dir)
542
569
  attachProject(config, anchor)
543
- 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
+ )
544
590
  if (json) {
545
591
  const specs = rows.map((r) => ({ ...r, inFlight: isInFlight(r) }))
546
592
  process.stdout.write(JSON.stringify({ isolation: present, specs }, null, 2) + '\n')
@@ -553,6 +599,241 @@ function inFlightStatus(argv) {
553
599
  process.stdout.write(projectLine(anchor) + formatInFlight(rows, { dir }))
554
600
  }
555
601
 
602
+ /**
603
+ * `skitterspec epic status <epic>` — the members' own headers turned into an
604
+ * order. Waits are read off the BASE BRANCH by git, never off whatever the
605
+ * primary checkout has checked out, because that is the one place every
606
+ * session agrees on (`env/epic.js`). Advisory: always exits 0.
607
+ */
608
+ function epicStatusCommand(argv) {
609
+ const json = argv.includes('--json')
610
+ const named = epicPositional(argv)
611
+ const inputs = epicInputs(argv, json, named || null)
612
+ if (!inputs) return
613
+ const epic = named || epicFromHere(inputs)
614
+ if (!epic) {
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
+ )
622
+ return
623
+ }
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
677
+ }
678
+
679
+ /**
680
+ * `skitterspec epic check <spec> [--phase N]` — what starting or building one
681
+ * member should hear about its epic, asked by `/spec-start` (the start) and
682
+ * `/spec-next` (`--phase N`). Prints nothing when there is nothing to say: a
683
+ * spec in no epic, or one with nothing in its way.
684
+ *
685
+ * An unmet wait is `blocked`, with a `bypass` offer the first time it is asked
686
+ * (`.claude/rules/offered-unblocks.md`); `--offered` spends that offer. It
687
+ * never refuses anything itself and always exits 0 — the skill relays it and
688
+ * the operator answers (spec feat-epics, Decision 8).
689
+ */
690
+ function epicCheckCommand(argv) {
691
+ const json = argv.includes('--json')
692
+ const spec = epicPositional(argv)
693
+ const phase = phaseFlag(argv)
694
+ if (!spec || phase === undefined) {
695
+ process.stdout.write('Usage: skitterspec epic check <spec> [--phase N] [--offered] [--json] [--dir <path>]\n')
696
+ return
697
+ }
698
+ const ctx = memberContext(argv, json, spec)
699
+ if (!ctx) return
700
+ const { result, recordFile, record } = ctx.check(phase)
701
+ if (argv.includes('--offered')) {
702
+ const key = phase === null ? 'start' : `phase ${phase}`
703
+ if (result.offer) writeEpicRecord(recordFile, { ...record, offered: [...new Set([...(record.offered || []), key])] })
704
+ process.stdout.write(json ? JSON.stringify({ spec, offered: key }, null, 2) + '\n' : '')
705
+ return
706
+ }
707
+ if (json) {
708
+ process.stdout.write(JSON.stringify(result, null, 2) + '\n')
709
+ return
710
+ }
711
+ for (const w of result.warnings) process.stdout.write(`epic check: ${spec} (${result.epic}) — ${w.message}\n`)
712
+ if (result.blocked) process.stdout.write(`epic check: ${result.reason}\n`)
713
+ }
714
+
715
+ /**
716
+ * `skitterspec epic bypass <spec> [--phase N]` — build past an unmet wait, on
717
+ * the record. Writes a dated line into the member's own Changelog, in its
718
+ * worktree, and remembers the scope so the same wait is not asked again. A
719
+ * wait already met has nothing to bypass and writes nothing.
720
+ */
721
+ function epicBypassCommand(argv) {
722
+ const spec = epicPositional(argv)
723
+ const phase = phaseFlag(argv)
724
+ if (!spec || phase === undefined) {
725
+ process.stdout.write('Usage: skitterspec epic bypass <spec> [--phase N] [--dir <path>]\n')
726
+ return
727
+ }
728
+ const ctx = memberContext(argv, false, spec)
729
+ if (!ctx) return
730
+ const { result, recordFile, record } = ctx.check(phase)
731
+ if (!result.blocked) {
732
+ process.stdout.write(`epic bypass: ${spec} has no unmet wait${phase === null ? '' : ` for phase ${phase}`} — nothing recorded.\n`)
733
+ return
734
+ }
735
+ // Written where the spec is being built — its own worktree — and nowhere
736
+ // else: on the base branch the line would be a change nobody reviews.
737
+ const file = ctx.worktreeFile
738
+ if (!file) {
739
+ process.stdout.write(`epic bypass: ${spec} has no worktree to record it in — /spec-start it first. Nothing recorded.\n`)
740
+ process.exitCode = 1
741
+ return
742
+ }
743
+ const line = bypassLine(result, new Date().toISOString().slice(0, 10))
744
+ fs.writeFileSync(file, appendChangelog(fs.readFileSync(file, 'utf8'), line))
745
+ writeEpicRecord(recordFile, { ...record, bypassed: [...new Set([...(record.bypassed || []), ...result.scopes])] })
746
+ process.stdout.write(`epic bypass: recorded in ${path.relative(process.cwd(), file) || file}\n ${line}\n`)
747
+ }
748
+
749
+ // `--phase N` → N; absent → null (the start); present but not a number →
750
+ // undefined, which the callers refuse as usage.
751
+ function phaseFlag(argv) {
752
+ const at = argv.indexOf('--phase')
753
+ if (at === -1) return null
754
+ const n = Number(argv[at + 1])
755
+ return Number.isInteger(n) && n > 0 ? n : undefined
756
+ }
757
+
758
+ // One member, read for `check` and `bypass`: its epic (off its own copy — the
759
+ // worktree's where it has one, else the base branch's), the record of offers
760
+ // and bypasses, and where its worktree overview lives. null, having said why,
761
+ // when the base branch cannot be read.
762
+ function memberContext(argv, json, spec) {
763
+ const inputs = epicInputs(argv, json, spec)
764
+ if (!inputs) return null
765
+ const own = inputs.worktrees.find((w) => w.folder === spec)
766
+ const entry = inputs.index.get(spec)
767
+ const text = own ? own.overview : entry ? inputs.readFile(`specs/${entry.bucket}/${spec}/00-overview.md`) : null
768
+ const epic = text ? epicHeaders(text).epic : null
769
+ const recordFile = path.join(inputs.dir, '.spec-env', 'epics', `${spec}.json`)
770
+ const record = readEpicRecord(recordFile)
771
+ return {
772
+ worktreeFile: own ? path.join(own.root, 'specs', own.bucket, spec, '00-overview.md') : null,
773
+ check: (phase) => ({
774
+ recordFile,
775
+ record,
776
+ result: epic
777
+ ? memberCheck(epicStatus({ epic, ...inputs }), spec, { phase, record })
778
+ : { spec, epic: null, phase, warnings: [], blocked: false },
779
+ }),
780
+ }
781
+ }
782
+
783
+ // The per-spec record of offers raised and waits bypassed. Machine-local and
784
+ // gitignored, like the review sidecars; the Changelog line is the durable half.
785
+ // An unreadable record is an empty one: the cost is an offer asked again.
786
+ function readEpicRecord(file) {
787
+ try {
788
+ return JSON.parse(fs.readFileSync(file, 'utf8'))
789
+ } catch {
790
+ return {}
791
+ }
792
+ }
793
+
794
+ function writeEpicRecord(file, record) {
795
+ fs.mkdirSync(path.dirname(file), { recursive: true })
796
+ fs.writeFileSync(file, JSON.stringify(record, null, 2) + '\n')
797
+ }
798
+
799
+ function epicPositional(argv) {
800
+ return argv.find((a, i) => !a.startsWith('--') && argv[i - 1] !== '--dir')
801
+ }
802
+
803
+ // The base branch's spec tree and the provisioned worktrees' own copies — what
804
+ // both `epic` verbs read. Waits are read off the BASE BRANCH by git, never off
805
+ // whatever the primary checkout has checked out (`env/epic.js`). null, having
806
+ // said why, when the base branch cannot be read.
807
+ function epicInputs(argv, json, subject) {
808
+ const at = argv.indexOf('--dir')
809
+ const from = path.resolve(at !== -1 && argv[at + 1] ? argv[at + 1] : process.cwd())
810
+ const anchor = primaryAnchor(from, gitReader(from))
811
+ const dir = anchor.dir
812
+ const { config, present } = loadEnvConfig(dir)
813
+ attachProject(config, anchor)
814
+ const git = gitReader(dir)
815
+ const say = (line) => {
816
+ process.stdout.write(json ? JSON.stringify({ subject, cannotTell: line }, null, 2) + '\n' : `epic: cannot tell — ${line}\n`)
817
+ return null
818
+ }
819
+
820
+ let base
821
+ try {
822
+ base = resolveBaseBranch(config, git)
823
+ } catch (err) {
824
+ return say(err.message)
825
+ }
826
+ const tree = epicTree(git, base)
827
+ if (!tree) return say(`the base branch ${base} could not be read`)
828
+ const worktrees = present
829
+ ? provisionedSpecs(dir, config)
830
+ .filter((p) => !p.specless)
831
+ .map((p) => worktreeOverview(p.project, p.folder))
832
+ .filter(Boolean)
833
+ : []
834
+ return { dir, config: present ? config : null, base, ...tree, worktrees }
835
+ }
836
+
556
837
  // Plan a provision: allocate the slot, persist the registry, and print the plan
557
838
  // the /spec-env skill executes (git worktree add, docker compose up, .env).
558
839
  // This creates no worktree and starts no stack — the caller runs the
@@ -981,7 +1262,9 @@ function specEnvNospec(dir, config, name, flags = {}) {
981
1262
  }
982
1263
 
983
1264
  function specEnvUp(dir, config, specArg, flags = {}) {
984
- const docs = flags.docs === true
1265
+ // An epic holds no code — its work is its members' — so its tree is always a
1266
+ // documents-only one, with or without the flag (spec feat-epics).
1267
+ const docs = flags.docs === true || isEpic(String(specArg || ''))
985
1268
 
986
1269
  // THE AUTHORING LANE — `up <name> --docs` for a spec that is not written yet.
987
1270
  // `/spec` provisions BEFORE it writes a line (feat-main-is-a-landing-zone
@@ -999,7 +1282,7 @@ function specEnvUp(dir, config, specArg, flags = {}) {
999
1282
  try {
1000
1283
  spec = resolveSpecWithWorktree(dir, config, specArg)
1001
1284
  } catch (err) {
1002
- const specShaped = typeof specArg === 'string' && /^(feat|bug|hotfix|chore|issue|incident)-./.test(specArg)
1285
+ const specShaped = typeof specArg === 'string' && /^(feat|bug|hotfix|chore|issue|incident|epic)-./.test(specArg)
1003
1286
  if (err.code !== 'SPEC_NOT_FOUND' || !docs || !specShaped || config.mode === 'checkout') {
1004
1287
  throw err
1005
1288
  }
@@ -1367,7 +1650,7 @@ function specEnvUp(dir, config, specArg, flags = {}) {
1367
1650
  * primary checkout already has its dependencies.
1368
1651
  */
1369
1652
  function specEnvBootstrap(dir, config, specArg, flags = {}) {
1370
- const docs = flags.docs === true
1653
+ const docs = flags.docs === true || isEpic(String(specArg || ''))
1371
1654
  const json = flags.json === true
1372
1655
  const say = (line) => process.stdout.write(line + '\n')
1373
1656
  const refuse = (msg) => {
@@ -2243,7 +2526,8 @@ function specEnvIntegrate(dir, config, specArg, flags = {}) {
2243
2526
  }
2244
2527
  const cout = [`spec-env integrate: ${spec.folder}`, '', ' mode: checkout',
2245
2528
  ` base: ${base}`, ` branch: ${cplan.branch}`,
2246
- ...retargetLines(retarget), '',
2529
+ ...retargetLines(retarget),
2530
+ ...reverifyLines(dir, spec, base, dir), '',
2247
2531
  ' run these (abort the rebase on conflict):']
2248
2532
  for (const cmd of cplan.commands) cout.push(` ${cmd}`)
2249
2533
  process.stdout.write(cout.join('\n') + '\n' + afterLandSection(cplan.afterLand))
@@ -2359,12 +2643,51 @@ function specEnvIntegrate(dir, config, specArg, flags = {}) {
2359
2643
  out.push(` worktree: ${spec.worktreePath}`)
2360
2644
  out.push(...retargetLines(retarget))
2361
2645
  if (primarySwitch) out.push(` primary: on ${primarySwitch.from} — switched to ${base} before the land`)
2646
+ out.push(...reverifyLines(dir, spec, baseRef, spec.projectPath || spec.worktreePath))
2362
2647
  out.push('')
2363
2648
  out.push(' run these (abort the rebase on conflict):')
2364
2649
  for (const cmd of plan.commands) out.push(` ${cmd}`)
2365
2650
  process.stdout.write(out.join('\n') + '\n' + afterLandSection(plan.afterLand))
2366
2651
  }
2367
2652
 
2653
+ // What this land's rebase will bring in that the spec's BUILT phases waited
2654
+ // on (spec feat-epics, Decision 9) — each listed phase was built without its
2655
+ // dependency underneath, so the landing skill runs the tests after the rebase
2656
+ // and before the fast-forward. Read off the fork point and the base by git,
2657
+ // against the spec's own copy in `tree`. Silent when nothing arrives, which is
2658
+ // every spec with no `Waits on:` at all.
2659
+ function reverifyLines(dir, spec, baseRef, tree) {
2660
+ const own = worktreeOverview(tree, spec.folder)
2661
+ if (!own) return []
2662
+ const git = gitReader(dir)
2663
+ const read = (ref) => {
2664
+ const listing = ref ? git(['ls-tree', '-r', '--name-only', ref, '--', 'specs']) : null
2665
+ // An unreadable side reads as nothing at all, so every wait on it is a
2666
+ // cannot-tell — never a "met by this rebase" that nobody could check.
2667
+ return listing === null
2668
+ ? { index: new Map(), readFile: () => null }
2669
+ : { index: indexSpecTree(listing), readFile: (p) => git(['show', `${ref}:${p}`]) }
2670
+ }
2671
+ const fork = git(['merge-base', baseRef, spec.branch])
2672
+ const { met, cannotTell } = waitsMetByRebase({
2673
+ overview: own.overview,
2674
+ phases: own.phases,
2675
+ before: read(fork),
2676
+ after: read(baseRef),
2677
+ })
2678
+ const what = (phase) => (phase === null ? 'start' : `phase ${phase}`)
2679
+ const lines = []
2680
+ if (met.length) {
2681
+ lines.push(' re-verify: this rebase brings in what built phases waited on — run the tests')
2682
+ lines.push(' after the rebase and before the fast-forward:')
2683
+ for (const { phase, wait } of met) lines.push(` ${what(phase)} waited on ${wait.raw} — ${wait.why}`)
2684
+ }
2685
+ for (const { phase, wait } of cannotTell) {
2686
+ lines.push(` re-verify: cannot tell for ${what(phase)} — ${wait.raw}: ${wait.why}`)
2687
+ }
2688
+ return lines
2689
+ }
2690
+
2368
2691
  // The line a plan carries when the rc rolled while the spec was in flight. The
2369
2692
  // rebase onto the newer rc is the land working, not a mistake — but it should
2370
2693
  // never happen without the reader seeing it.
@@ -7091,6 +7414,15 @@ async function run(argv) {
7091
7414
  return
7092
7415
  }
7093
7416
 
7417
+ if (cmd === 'epic') {
7418
+ const [sub, ...eArgs] = rest
7419
+ if (sub === 'status') epicStatusCommand(eArgs)
7420
+ else if (sub === 'check') epicCheckCommand(eArgs)
7421
+ else if (sub === 'bypass') epicBypassCommand(eArgs)
7422
+ else process.stdout.write('Usage: skitterspec epic <status <epic> | check <spec> | bypass <spec>> [--phase N] [--json] [--dir <path>]\n')
7423
+ return
7424
+ }
7425
+
7094
7426
  const { opts, positional } = parse(rest)
7095
7427
  const dir = path.resolve(opts.dir || positional[0] || process.cwd())
7096
7428