@skitterbyte/skitterspec-linear 19.6.0 → 19.8.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +1 -0
- package/assets/commands/epic.md +21 -0
- package/assets/core/env.config.json.example +1 -0
- package/assets/core/env.config.md +16 -5
- package/assets/review/page.html +9 -0
- package/assets/rules/spec-planning.md +48 -11
- package/assets/rules/spec-reports.md +8 -1
- package/assets/skills/spec/SKILL.md +30 -13
- package/assets/skills/spec-cancel/SKILL.md +7 -0
- package/assets/skills/spec-next/SKILL.md +38 -1
- package/assets/skills/spec-start/SKILL.md +30 -3
- package/bin/skitterspec-linear.js +5 -0
- package/package.json +1 -1
- package/src/cli.js +216 -57
- package/src/env/config.js +47 -6
- package/src/env/epic.js +55 -26
- package/src/env/epicpage.js +129 -0
- package/src/env/epicread.js +147 -0
- package/src/env/inflight.js +2 -0
- package/src/env/integrate.js +48 -1
- package/src/env/nextaction.js +262 -0
- package/src/env/project.js +18 -0
- package/src/env/review.js +21 -3
- package/src/env/serve.js +73 -7
- package/src/env/specbranches.js +120 -0
- package/src/env/teardown.js +18 -3
- package/src/gating.js +16 -4
- package/src/vendor/provider-kit/src/apply.js +25 -1
- package/src/vendor/sync-core/src/compare.js +10 -2
- package/src/vendor/sync-core/src/push.js +14 -3
package/src/cli.js
CHANGED
|
@@ -79,6 +79,7 @@ const {
|
|
|
79
79
|
const {
|
|
80
80
|
primaryAnchor,
|
|
81
81
|
attachProject,
|
|
82
|
+
projectName,
|
|
82
83
|
repoRootOf,
|
|
83
84
|
prefixOf,
|
|
84
85
|
toRepoPath,
|
|
@@ -183,7 +184,8 @@ const {
|
|
|
183
184
|
mainGuardStatus,
|
|
184
185
|
} = require('./env/mainguard.js')
|
|
185
186
|
const { planPrune, liveSlugsForSpecs, reconcileRegistry } = require('./env/prune.js')
|
|
186
|
-
const { planIntegrate, planIntegrateCheckout, planIntegratePr } = require('./env/integrate.js')
|
|
187
|
+
const { planIntegrate, planIntegrateCheckout, planIntegratePr, planIntegrateDocs } = require('./env/integrate.js')
|
|
188
|
+
const { specBranchDocs, preferBranches } = require('./env/specbranches.js')
|
|
187
189
|
const { parseRemote, prFor, prPlanCommand, prAbandonCommand, preferRemoteBase } = require('./env/host.js')
|
|
188
190
|
const { collectDisposition } = require('./env/disposition.js')
|
|
189
191
|
const { planHandoff } = require('./env/handoff.js')
|
|
@@ -198,6 +200,8 @@ const {
|
|
|
198
200
|
appendChangelog,
|
|
199
201
|
waitsMetByRebase,
|
|
200
202
|
} = require('./env/epic.js')
|
|
203
|
+
const { nextAction, readNextInputs } = require('./env/nextaction.js')
|
|
204
|
+
const { epicTree, workingTree, worktreeOverview, epicsInFlight, memberReaders, epicAnswer } = require('./env/epicread.js')
|
|
201
205
|
const { planHotfixLand, planBranchHotfixLand, planBranchHotfixFinish, planHotfixFinish } = require('./env/hotfix.js')
|
|
202
206
|
const { runHotfixLand, describeStep: describeHotfixStep } = require('./env/hotfixland.js')
|
|
203
207
|
const { planDev } = require('./env/dev.js')
|
|
@@ -278,7 +282,8 @@ Usage:
|
|
|
278
282
|
dev down <spec> stop the spec's host dev servers
|
|
279
283
|
connect <spec> expose a spec on the canonical ports (main = off)
|
|
280
284
|
integrate <spec> plan the land: rebase + fast-forward, or in PR
|
|
281
|
-
mode push + PR (--push, --draft, --strategy)
|
|
285
|
+
mode push + PR (--push, --draft, --strategy);
|
|
286
|
+
--docs: under specDocs "branch", publish only
|
|
282
287
|
disposition <spec>
|
|
283
288
|
list unticked tasks, open phases and surfaced
|
|
284
289
|
follow-ups to dispose before a PR goes ready
|
|
@@ -565,7 +570,26 @@ function inFlightStatus(argv) {
|
|
|
565
570
|
const dir = anchor.dir
|
|
566
571
|
const { config, present } = loadEnvConfig(dir)
|
|
567
572
|
attachProject(config, anchor)
|
|
568
|
-
const rows = present ? collectInFlight({ dir, provisioned: provisionedSpecs(dir, config) }) : []
|
|
573
|
+
const rows = (present ? collectInFlight({ dir, provisioned: provisionedSpecs(dir, config) }) : []).map((r) =>
|
|
574
|
+
// Only a spec whose own copy was read, and which is still in flight, gets
|
|
575
|
+
// a next action — a finished or unreadable one has nothing true to offer.
|
|
576
|
+
isInFlight(r) && r.found
|
|
577
|
+
? {
|
|
578
|
+
...r,
|
|
579
|
+
next: nextAction({
|
|
580
|
+
spec: r.spec,
|
|
581
|
+
...readNextInputs({
|
|
582
|
+
folder: r.spec,
|
|
583
|
+
bucket: r.bucket,
|
|
584
|
+
worktree: r.worktree,
|
|
585
|
+
outPath: reviewOutPath(dir, r.spec),
|
|
586
|
+
required: config.review.required,
|
|
587
|
+
git: gitReader(r.worktree),
|
|
588
|
+
}),
|
|
589
|
+
}),
|
|
590
|
+
}
|
|
591
|
+
: r,
|
|
592
|
+
)
|
|
569
593
|
if (json) {
|
|
570
594
|
const specs = rows.map((r) => ({ ...r, inFlight: isInFlight(r) }))
|
|
571
595
|
process.stdout.write(JSON.stringify({ isolation: present, specs }, null, 2) + '\n')
|
|
@@ -586,15 +610,105 @@ function inFlightStatus(argv) {
|
|
|
586
610
|
*/
|
|
587
611
|
function epicStatusCommand(argv) {
|
|
588
612
|
const json = argv.includes('--json')
|
|
589
|
-
const
|
|
613
|
+
const named = epicPositional(argv)
|
|
614
|
+
const based = epicInputs(argv, json, named || null)
|
|
615
|
+
if (!based) return
|
|
616
|
+
const here = argv.includes('--here') ? hereTree(based) : null
|
|
617
|
+
if (argv.includes('--here') && !here) {
|
|
618
|
+
process.stdout.write(json ? JSON.stringify({ epic: named || null, cannotTell: 'not in a git checkout' }, null, 2) + '\n' : 'epic: cannot tell — --here needs a git checkout to read\n')
|
|
619
|
+
return
|
|
620
|
+
}
|
|
621
|
+
// --here: members and headers from this tree, uncommitted edits included;
|
|
622
|
+
// a wait is still met only on the base branch.
|
|
623
|
+
const inputs = here
|
|
624
|
+
? { ...based, ...here.tree, waitIndex: based.index, waitRead: based.readFile }
|
|
625
|
+
: based
|
|
626
|
+
const epic = named || epicFromHere(inputs)
|
|
590
627
|
if (!epic) {
|
|
591
|
-
|
|
628
|
+
const flying = epicsInFlight(inputs.worktrees)
|
|
629
|
+
const line = flying.length
|
|
630
|
+
? `name an epic — in flight here: ${flying.join(', ')}`
|
|
631
|
+
: 'name an epic — none has a member in flight here'
|
|
632
|
+
process.stdout.write(
|
|
633
|
+
json ? JSON.stringify({ epic: null, inFlight: flying }, null, 2) + '\n' : `Usage: skitterspec epic status [<epic>] [--here] [--json] [--dir <path>]\n${line}\n`,
|
|
634
|
+
)
|
|
635
|
+
return
|
|
636
|
+
}
|
|
637
|
+
const up = inputs.config ? readRunningReviewServer(inputs.dir, inputs.config) : null
|
|
638
|
+
const readers = memberReaders({
|
|
639
|
+
...inputs,
|
|
640
|
+
git: gitReader,
|
|
641
|
+
// A link only where a server is already serving: this reads the server and
|
|
642
|
+
// never starts one, so a status asked from a phone never restarts the
|
|
643
|
+
// server whose link that phone has open.
|
|
644
|
+
//
|
|
645
|
+
// The NETWORK address where the server is bound wide, so a row read on a
|
|
646
|
+
// phone opens there too; loopback where it is not, or where this machine
|
|
647
|
+
// has no address to offer. A tailnet reader has the epic page, whose member
|
|
648
|
+
// links are relative.
|
|
649
|
+
linkFor: (spec) => memberPageLink(up, offerableLanAddresses(), spec),
|
|
650
|
+
})
|
|
651
|
+
const answer = { ...epicAnswer(epic, inputs, readers), ...(here ? { here: here.label } : {}) }
|
|
652
|
+
const page = epicPageTiers(inputs, up, epic)
|
|
653
|
+
if (json) {
|
|
654
|
+
process.stdout.write(JSON.stringify({ base: inputs.base, ...answer, page }, null, 2) + '\n')
|
|
592
655
|
return
|
|
593
656
|
}
|
|
594
|
-
|
|
595
|
-
|
|
596
|
-
|
|
597
|
-
|
|
657
|
+
// No such epic is a plain answer; a page link for it would be a link to nothing.
|
|
658
|
+
const found = answer.found || answer.members.length
|
|
659
|
+
process.stdout.write(formatEpicStatus(answer) + (found ? '\n' + epicPageLines(page) : ''))
|
|
660
|
+
}
|
|
661
|
+
|
|
662
|
+
// A member's review page as `epic status` prints it: the network URL where the
|
|
663
|
+
// server is bound wide, else loopback; null with nothing serving.
|
|
664
|
+
function memberPageLink(up, addrs, spec) {
|
|
665
|
+
if (!up) return null
|
|
666
|
+
const served = reviewServedUrls(up, addrs, spec)
|
|
667
|
+
return served.url || served.loopbackUrl
|
|
668
|
+
}
|
|
669
|
+
|
|
670
|
+
/**
|
|
671
|
+
* Where the epic page can be read: the same tiers a review render prints, for
|
|
672
|
+
* the epic's own route — or, with no server running, the one command that
|
|
673
|
+
* starts it. Never null where isolation is configured, because the page is the
|
|
674
|
+
* thing a phone reader comes back to (Decision 8).
|
|
675
|
+
*/
|
|
676
|
+
function epicPageTiers(inputs, up, epic) {
|
|
677
|
+
if (!inputs.config) return null
|
|
678
|
+
if (!up) return { off: true, start: 'skitterspec spec-env review serve --host 0.0.0.0' }
|
|
679
|
+
const served = reviewServedUrls(up, offerableLanAddresses(), epic)
|
|
680
|
+
return { tiers: reviewTierStack({ served, fileUrl: null, publishedUrl: null, config: inputs.config }) }
|
|
681
|
+
}
|
|
682
|
+
|
|
683
|
+
function epicPageLines(page) {
|
|
684
|
+
if (!page) return ''
|
|
685
|
+
if (page.off) return `epic page: no review server running — start it with: ${page.start}\n`
|
|
686
|
+
return `epic page:\n${page.tiers.map(reviewTierLine).join('\n')}\n`
|
|
687
|
+
}
|
|
688
|
+
|
|
689
|
+
// The working tree `--here` reads: the project folder of the checkout this
|
|
690
|
+
// command runs in. null when there is no checkout to read.
|
|
691
|
+
function hereTree(inputs) {
|
|
692
|
+
const top = gitReader(process.cwd())(['rev-parse', '--show-toplevel'])
|
|
693
|
+
if (!top) return null
|
|
694
|
+
const root = path.join(path.resolve(top), (inputs.config && prefixOf(inputs.config)) || '')
|
|
695
|
+
return { tree: workingTree(root), label: path.relative(path.dirname(inputs.dir), root) || root }
|
|
696
|
+
}
|
|
697
|
+
|
|
698
|
+
/**
|
|
699
|
+
* The epic a bare `epic status` means: the one whose worktree this command runs
|
|
700
|
+
* in, or the epic named by the member whose worktree it runs in. A positive
|
|
701
|
+
* signal or nothing — standing anywhere else names no epic, and the caller says
|
|
702
|
+
* so rather than picking one.
|
|
703
|
+
*/
|
|
704
|
+
function epicFromHere(inputs) {
|
|
705
|
+
const top = gitReader(process.cwd())(['rev-parse', '--show-toplevel'])
|
|
706
|
+
if (!top) return null
|
|
707
|
+
const here = path.resolve(top)
|
|
708
|
+
const own = inputs.worktrees.find((w) => here === path.resolve(w.root) || here.startsWith(path.resolve(w.root) + path.sep))
|
|
709
|
+
if (!own) return null
|
|
710
|
+
if (isEpic(own.folder)) return own.folder
|
|
711
|
+
return epicHeaders(own.overview).epic
|
|
598
712
|
}
|
|
599
713
|
|
|
600
714
|
/**
|
|
@@ -744,52 +858,15 @@ function epicInputs(argv, json, subject) {
|
|
|
744
858
|
} catch (err) {
|
|
745
859
|
return say(err.message)
|
|
746
860
|
}
|
|
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}`])
|
|
861
|
+
const tree = epicTree(git, base)
|
|
862
|
+
if (!tree) return say(`the base branch ${base} could not be read`)
|
|
757
863
|
const worktrees = present
|
|
758
864
|
? provisionedSpecs(dir, config)
|
|
759
865
|
.filter((p) => !p.specless)
|
|
760
866
|
.map((p) => worktreeOverview(p.project, p.folder))
|
|
761
867
|
.filter(Boolean)
|
|
762
868
|
: []
|
|
763
|
-
return { dir, base,
|
|
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
|
|
869
|
+
return { dir, config: present ? config : null, base, ...tree, worktrees, branches: specBranchDocs(git, config, base) }
|
|
793
870
|
}
|
|
794
871
|
|
|
795
872
|
// Plan a provision: allocate the slot, persist the registry, and print the plan
|
|
@@ -902,14 +979,28 @@ function untouchedLines(plan) {
|
|
|
902
979
|
* yet is not broken, and a check that stopped someone's work over a missing
|
|
903
980
|
* header would be a worse failure than the omission it names.
|
|
904
981
|
*/
|
|
982
|
+
// Specs that live only on their own branch, for the checks that read the
|
|
983
|
+
// backlog. Every cannot-tell — no git, an unresolvable base — is an empty list,
|
|
984
|
+
// which leaves the disk scan exactly as it was.
|
|
985
|
+
function branchSpecDocs(dir) {
|
|
986
|
+
try {
|
|
987
|
+
const { config } = loadEnvConfig(dir)
|
|
988
|
+
const git = gitReader(dir)
|
|
989
|
+
return specBranchDocs(git, config, resolveBaseBranch(config, git))
|
|
990
|
+
} catch {
|
|
991
|
+
return []
|
|
992
|
+
}
|
|
993
|
+
}
|
|
994
|
+
|
|
905
995
|
function gatingCheck(dir, argv) {
|
|
906
996
|
const { opts, positional } = parse(argv)
|
|
907
|
-
const { checkGating, activeSpecs } = require('./gating.js')
|
|
997
|
+
const { checkGating, activeSpecs, ACTIVE_BUCKETS } = require('./gating.js')
|
|
998
|
+
const branches = branchSpecDocs(dir).filter((b) => ACTIVE_BUCKETS.includes(b.bucket))
|
|
908
999
|
|
|
909
1000
|
let specs = null
|
|
910
1001
|
if (positional.length && !opts.all) {
|
|
911
1002
|
const name = path.basename(positional[0])
|
|
912
|
-
const found = activeSpecs(dir).filter((s) => s.folder === name)
|
|
1003
|
+
const found = preferBranches(activeSpecs(dir), branches).filter((s) => s.folder === name)
|
|
913
1004
|
if (!found.length) {
|
|
914
1005
|
// Not an accusation: a name that matches no ACTIVE spec is usually a
|
|
915
1006
|
// finished one, which gating never covers anyway.
|
|
@@ -919,7 +1010,7 @@ function gatingCheck(dir, argv) {
|
|
|
919
1010
|
specs = found
|
|
920
1011
|
}
|
|
921
1012
|
|
|
922
|
-
const result = checkGating(dir, specs)
|
|
1013
|
+
const result = checkGating(dir, specs, { branches })
|
|
923
1014
|
|
|
924
1015
|
if (opts.json) {
|
|
925
1016
|
process.stdout.write(JSON.stringify(result, null, 2) + '\n')
|
|
@@ -939,8 +1030,8 @@ function gatingCheck(dir, argv) {
|
|
|
939
1030
|
for (const f of result.findings) {
|
|
940
1031
|
lines.push(
|
|
941
1032
|
f.kind === 'missing'
|
|
942
|
-
? ` ${f.folder} (${f.bucket}): no Gating: header`
|
|
943
|
-
: ` ${f.folder} (${f.bucket}): Gating: "${f.raw}" says nothing — a bare "none" is not a reason`,
|
|
1033
|
+
? ` ${f.folder} (${f.bucket}${f.from ? `, ${f.from}` : ''}): no Gating: header`
|
|
1034
|
+
: ` ${f.folder} (${f.bucket}${f.from ? `, ${f.from}` : ''}): Gating: "${f.raw}" says nothing — a bare "none" is not a reason`,
|
|
944
1035
|
)
|
|
945
1036
|
}
|
|
946
1037
|
lines.push('')
|
|
@@ -2054,6 +2145,16 @@ function specEnvDown(dir, config, specArg, flags) {
|
|
|
2054
2145
|
prAbandon = prAbandonCommand(info, { branch: spec.branch, id: pr.id })
|
|
2055
2146
|
}
|
|
2056
2147
|
}
|
|
2148
|
+
// Under the docs lane, a branch whose whole range is this spec's own
|
|
2149
|
+
// documents (its folder, its companions) is a never-started spec: the
|
|
2150
|
+
// planner may offer its remote delete. Asked only in that lane, and an
|
|
2151
|
+
// unreadable or empty range is not docs-only — it stays false.
|
|
2152
|
+
if (config.land && config.land.specDocs === 'branch' && !worktreeState.merged) {
|
|
2153
|
+
const range = landRange(gitReader(dir), base, spec.branch)
|
|
2154
|
+
if (Array.isArray(range) && range.length) {
|
|
2155
|
+
worktreeState = { ...worktreeState, docsOnly: classifyDirtyTree(spec, range, config).foreign.length === 0 }
|
|
2156
|
+
}
|
|
2157
|
+
}
|
|
2057
2158
|
const plan = planDown(spec, config, flags, {
|
|
2058
2159
|
worktreeState,
|
|
2059
2160
|
prAbandonCommand: prAbandon,
|
|
@@ -2426,6 +2527,15 @@ function specEnvIntegrate(dir, config, specArg, flags = {}) {
|
|
|
2426
2527
|
// entirely on its branch may not exist in the primary checkout's specs/** —
|
|
2427
2528
|
// resolveSpecWithWorktree offers its worktree as a fallback search location.
|
|
2428
2529
|
const spec = resolveSpecWithWorktree(dir, config, specArg)
|
|
2530
|
+
// `--docs` is /spec's authoring land. Under the "branch" lane the document
|
|
2531
|
+
// rides its own branch, so there is nothing to land — only a branch to
|
|
2532
|
+
// publish. Under "trunk" it falls through to the ordinary land unchanged.
|
|
2533
|
+
// Keyed on the FLAG, never on `specDocs` alone: /spec-complete lands CODE
|
|
2534
|
+
// through this same verb, and that land must not turn into a push.
|
|
2535
|
+
if (flags.docs === true && config.land && config.land.specDocs === 'branch') {
|
|
2536
|
+
specEnvIntegrateDocs(dir, config, spec, flags)
|
|
2537
|
+
return
|
|
2538
|
+
}
|
|
2429
2539
|
// Fetch before resolving under a rolling base, so a spec that outlived a
|
|
2430
2540
|
// release roll lands on the rc that exists now rather than the one the last
|
|
2431
2541
|
// fetch saw. No pattern → no fetch, and the plan below is unchanged.
|
|
@@ -2811,6 +2921,55 @@ function specEnvIntegratePr(dir, config, spec, base, flags, retarget = null) {
|
|
|
2811
2921
|
process.stdout.write(out.join('\n') + '\n')
|
|
2812
2922
|
}
|
|
2813
2923
|
|
|
2924
|
+
// The authoring land under `land.specDocs: "branch"`: publish the spec's branch,
|
|
2925
|
+
// consent-gated, and touch nothing else. /spec runs what is printed.
|
|
2926
|
+
function specEnvIntegrateDocs(dir, config, spec, flags) {
|
|
2927
|
+
const checkout = config.mode === 'checkout'
|
|
2928
|
+
const treePath = checkout ? dir : spec.worktreePath
|
|
2929
|
+
if (!checkout && !fs.existsSync(spec.worktreePath)) {
|
|
2930
|
+
process.stdout.write(`spec-env integrate: ${spec.folder} has no worktree — nothing to publish.\n`)
|
|
2931
|
+
return
|
|
2932
|
+
}
|
|
2933
|
+
const remote = (config.land && config.land.remote) || 'origin'
|
|
2934
|
+
const git = gitReader(treePath)
|
|
2935
|
+
const status = git(['status', '--porcelain'])
|
|
2936
|
+
const remoteConfigured = git(['remote', 'get-url', remote]) !== null
|
|
2937
|
+
const headSha = git(['rev-parse', 'HEAD'])
|
|
2938
|
+
const lsRemote = remoteConfigured ? git(['ls-remote', remote, `refs/heads/${spec.branch}`]) : null
|
|
2939
|
+
const plan = planIntegrateDocs(spec, config, {
|
|
2940
|
+
worktreeState: { dirty: status !== null && status.length > 0 },
|
|
2941
|
+
remote,
|
|
2942
|
+
treePath,
|
|
2943
|
+
remoteConfigured,
|
|
2944
|
+
pushedAtHead: Boolean(headSha && lsRemote && lsRemote.split(/\s/)[0] === headSha),
|
|
2945
|
+
push: flags.push === true,
|
|
2946
|
+
})
|
|
2947
|
+
|
|
2948
|
+
if (plan.blocked) {
|
|
2949
|
+
process.stdout.write(`spec-env integrate: blocked — ${plan.reason}.\n`)
|
|
2950
|
+
return
|
|
2951
|
+
}
|
|
2952
|
+
const out = [`spec-env integrate: ${spec.folder} (spec docs ride the branch)`, '']
|
|
2953
|
+
out.push(' lane: branch — land.specDocs; the base branch is not touched')
|
|
2954
|
+
out.push(` branch: ${plan.branch}`)
|
|
2955
|
+
out.push(checkout ? ` checkout: ${treePath}` : ` worktree: ${treePath}`)
|
|
2956
|
+
if (plan.noRemote) {
|
|
2957
|
+
out.push(` remote: no "${remote}" configured — the branch stays local`)
|
|
2958
|
+
} else if (plan.push.via === 'remote') {
|
|
2959
|
+
out.push(` pushed: already on ${remote} at HEAD — nothing to run`)
|
|
2960
|
+
} else if (plan.push.via === 'push') {
|
|
2961
|
+
out.push('')
|
|
2962
|
+
out.push(' run these:')
|
|
2963
|
+
for (const cmd of plan.commands) out.push(` ${cmd}`)
|
|
2964
|
+
} else {
|
|
2965
|
+
out.push('')
|
|
2966
|
+
out.push(' then, to publish the branch — with your consent')
|
|
2967
|
+
out.push(' (or re-run with --push to plan it as one list):')
|
|
2968
|
+
for (const cmd of plan.holdCommands) out.push(` ${cmd}`)
|
|
2969
|
+
}
|
|
2970
|
+
process.stdout.write(out.join('\n') + '\n')
|
|
2971
|
+
}
|
|
2972
|
+
|
|
2814
2973
|
// `spec-env disposition [<spec>] [--json]` — enumerate the loose ends a
|
|
2815
2974
|
// completion must dispose before a PR goes ready: unticked tasks, phase-index
|
|
2816
2975
|
// rows not ✅, surfaced follow-ups. Information only — it never refuses and
|
|
@@ -5362,6 +5521,7 @@ async function specEnvReview(dir, config, specArg, flags, invokedFrom = dir) {
|
|
|
5362
5521
|
notes,
|
|
5363
5522
|
gate,
|
|
5364
5523
|
buttons,
|
|
5524
|
+
project: projectName(config),
|
|
5365
5525
|
...surfaceArgs,
|
|
5366
5526
|
...(docs ? { only: docs.owned, treePath: docs.tree } : {}),
|
|
5367
5527
|
})
|
|
@@ -5404,6 +5564,7 @@ async function specEnvReview(dir, config, specArg, flags, invokedFrom = dir) {
|
|
|
5404
5564
|
notes,
|
|
5405
5565
|
gate,
|
|
5406
5566
|
buttons,
|
|
5567
|
+
project: projectName(config),
|
|
5407
5568
|
...surfaceArgs,
|
|
5408
5569
|
fellBack: true,
|
|
5409
5570
|
})
|
|
@@ -5753,9 +5914,6 @@ async function specEnvReview(dir, config, specArg, flags, invokedFrom = dir) {
|
|
|
5753
5914
|
// The reason there is no served URL, when there is none. A `file://` link
|
|
5754
5915
|
// with nothing said about it reads as the ordinary outcome, and it is not.
|
|
5755
5916
|
(!served && noServeBecause ? ` not served: ${noServeBecause}\n` : '') +
|
|
5756
|
-
(served && served.loopback && config.review.allowNetwork
|
|
5757
|
-
? ` network permitted but the running server is loopback-bound — ${served.widen}\n`
|
|
5758
|
-
: '') +
|
|
5759
5917
|
(served && served.started && !served.loopback
|
|
5760
5918
|
? ' serving: every provisioned spec, to anyone with a URL on your network.\n' +
|
|
5761
5919
|
' stop: skitterspec spec-env review serve --stop\n'
|
|
@@ -7473,5 +7631,6 @@ module.exports = {
|
|
|
7473
7631
|
serverScriptOk,
|
|
7474
7632
|
daemonScript,
|
|
7475
7633
|
reviewServedUrls,
|
|
7634
|
+
memberPageLink,
|
|
7476
7635
|
restartHost,
|
|
7477
7636
|
}
|
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')
|
|
@@ -230,9 +230,11 @@ const DEFAULT_CONFIG = Object.freeze({
|
|
|
230
230
|
// follows the merge. `remote` names where the branch is pushed. `draft`
|
|
231
231
|
// opens mid-spec PRs as drafts (a draft cannot be merged, so nothing
|
|
232
232
|
// downstream can close a ticket early). `specDocs` decides where a spec
|
|
233
|
-
// DOCUMENT lands
|
|
234
|
-
//
|
|
235
|
-
//
|
|
233
|
+
// DOCUMENT lands: "trunk" keeps the authoring land (needs direct push for
|
|
234
|
+
// docs under "pr"), "branch" has the spec ride its feature branch and land
|
|
235
|
+
// with the work. The "trunk" here is only the base's default — with a
|
|
236
|
+
// ticketing provider configured and the key unset, `applyProviderSpecDocs`
|
|
237
|
+
// makes it "branch", whatever the strategy.
|
|
236
238
|
land: Object.freeze({ strategy: 'ff', remote: 'origin', draft: true, specDocs: 'trunk' }),
|
|
237
239
|
// `mainIsLandingZone` defaults ON wherever isolation is configured, matching
|
|
238
240
|
// the review gate's precedent: the push toward not working on the base branch
|
|
@@ -307,6 +309,10 @@ const DEFAULT_CONFIG = Object.freeze({
|
|
|
307
309
|
allowRemote: false,
|
|
308
310
|
commitWith: '/commit',
|
|
309
311
|
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`.
|
|
315
|
+
projectName: '',
|
|
310
316
|
// External code reviewers whose findings render as CHECKS on the page.
|
|
311
317
|
// Empty by default and never written by `init`: configuring one sends the
|
|
312
318
|
// worktree's diff to whatever the command talks to, which is a decision
|
|
@@ -772,6 +778,8 @@ function mergeConfig(base, parsed) {
|
|
|
772
778
|
// here. There is nothing it could mean instead: the hand-off has no off
|
|
773
779
|
// switch, so a blank value is a typo rather than an instruction.
|
|
774
780
|
assign(base.review, parsed.review, 'commitWith', 'string')
|
|
781
|
+
// A blank name falls back to the folder's, like `commitWith` above.
|
|
782
|
+
assign(base.review, parsed.review, 'projectName', 'string')
|
|
775
783
|
// Same shape as `serveOnRemote`, and for a sharper reason: a non-boolean
|
|
776
784
|
// leaves the gate ON. Turning off a check that refuses must be something
|
|
777
785
|
// someone WROTE, never something a typo achieved on their behalf.
|
|
@@ -873,6 +881,33 @@ function applyProviderEnvDefaults(config, parsed) {
|
|
|
873
881
|
return config
|
|
874
882
|
}
|
|
875
883
|
|
|
884
|
+
// The provider's own config file, relative to the project root — set once per
|
|
885
|
+
// process by a provider superset's bin, like the defaults above. A registered
|
|
886
|
+
// file that EXISTS is the positive signal that a ticketing provider is attached
|
|
887
|
+
// to this project, and only then does `land.specDocs` default to "branch": the
|
|
888
|
+
// tracker is the backlog, so landing a spec document on the base branch just to
|
|
889
|
+
// make it findable buys nothing (feat-tracker-spec-branches).
|
|
890
|
+
//
|
|
891
|
+
// WHAT WOULD FOOL THIS: an installed superset whose project never ran its setup
|
|
892
|
+
// has no config file, and reads as no provider — which is the safe reading,
|
|
893
|
+
// since "trunk" is today's behaviour. An unregistered base distribution never
|
|
894
|
+
// asks at all.
|
|
895
|
+
let providerConfigFile = null
|
|
896
|
+
function setProviderConfigFile(rel) {
|
|
897
|
+
providerConfigFile = rel || null
|
|
898
|
+
}
|
|
899
|
+
|
|
900
|
+
// An explicit `specDocs` in the file — any value, even one the merge rejected —
|
|
901
|
+
// is the project's decision; a rejected typo stays on the conservative "trunk"
|
|
902
|
+
// rather than being promoted to the provider default.
|
|
903
|
+
function applyProviderSpecDocs(config, parsed, dir) {
|
|
904
|
+
if (!providerConfigFile) return config
|
|
905
|
+
const pLand = parsed && typeof parsed.land === 'object' && parsed.land !== null ? parsed.land : null
|
|
906
|
+
if (pLand && 'specDocs' in pLand) return config
|
|
907
|
+
if (existsSync(join(dir, providerConfigFile))) config.land.specDocs = 'branch'
|
|
908
|
+
return config
|
|
909
|
+
}
|
|
910
|
+
|
|
876
911
|
function loadEnvConfig(dir = process.cwd()) {
|
|
877
912
|
const base = defaults()
|
|
878
913
|
const file = join(dir, CONFIG_FILE)
|
|
@@ -882,7 +917,12 @@ function loadEnvConfig(dir = process.cwd()) {
|
|
|
882
917
|
raw = readFileSync(file, 'utf-8')
|
|
883
918
|
} catch (error) {
|
|
884
919
|
if (error.code === 'ENOENT') {
|
|
885
|
-
return {
|
|
920
|
+
return {
|
|
921
|
+
config: applyProviderSpecDocs(applyProviderEnvDefaults(base, null), null, dir),
|
|
922
|
+
present: false,
|
|
923
|
+
unknown: [],
|
|
924
|
+
badReviewers: [],
|
|
925
|
+
}
|
|
886
926
|
}
|
|
887
927
|
throw error
|
|
888
928
|
}
|
|
@@ -895,7 +935,7 @@ function loadEnvConfig(dir = process.cwd()) {
|
|
|
895
935
|
}
|
|
896
936
|
|
|
897
937
|
return {
|
|
898
|
-
config: applyProviderEnvDefaults(mergeConfig(base, parsed), parsed),
|
|
938
|
+
config: applyProviderSpecDocs(applyProviderEnvDefaults(mergeConfig(base, parsed), parsed), parsed, dir),
|
|
899
939
|
present: true,
|
|
900
940
|
unknown: collectUnknownKeys(parsed),
|
|
901
941
|
badReviewers: collectBadReviewers(parsed),
|
|
@@ -905,6 +945,7 @@ function loadEnvConfig(dir = process.cwd()) {
|
|
|
905
945
|
module.exports = {
|
|
906
946
|
loadEnvConfig,
|
|
907
947
|
setProviderEnvDefaults,
|
|
948
|
+
setProviderConfigFile,
|
|
908
949
|
resolveServePort,
|
|
909
950
|
derivedServePort,
|
|
910
951
|
servePortRoot,
|
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
|
|
|
@@ -291,12 +292,21 @@ function layer(members) {
|
|
|
291
292
|
* - `index` `indexSpecTree` of the base branch
|
|
292
293
|
* - `readFile` base-branch path → text, or null
|
|
293
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
|
|
294
298
|
* - `worktrees` `[{ folder, bucket, overview, phases: [{ n, text }] }]` —
|
|
295
299
|
* each provisioned spec's own copy, which is where an
|
|
296
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.
|
|
297
306
|
*/
|
|
298
|
-
function epicStatus({ epic, index, readFile, candidates = [], worktrees = [] }) {
|
|
307
|
+
function epicStatus({ epic, index, readFile, candidates = [], worktrees = [], branches = [], waitIndex = index, waitRead = readFile }) {
|
|
299
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]))
|
|
300
310
|
const members = new Map()
|
|
301
311
|
|
|
302
312
|
for (const file of candidates) {
|
|
@@ -311,8 +321,10 @@ function epicStatus({ epic, index, readFile, candidates = [], worktrees = [] })
|
|
|
311
321
|
members.set(m[2], { spec: m[2], waits: h.waitsOn, area: h.area, phases })
|
|
312
322
|
}
|
|
313
323
|
// A member authored on its own branch and not landed yet is invisible on the
|
|
314
|
-
// base branch; its worktree copy is what knows it belongs here
|
|
315
|
-
|
|
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]) {
|
|
316
328
|
const h = epicHeaders(w.overview)
|
|
317
329
|
// The worktree's copy is the newer word on a spec being built: it may have
|
|
318
330
|
// joined, changed its waits, or moved to another epic.
|
|
@@ -326,15 +338,16 @@ function epicStatus({ epic, index, readFile, candidates = [], worktrees = [] })
|
|
|
326
338
|
const base = index.get(m.spec)
|
|
327
339
|
// In flight is the positive signal of a worktree whose own copy has not
|
|
328
340
|
// finished; otherwise the base branch's bucket.
|
|
329
|
-
|
|
330
|
-
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) }))
|
|
331
344
|
// A phase's own `Waits on:` holds that phase, not the spec's start: the
|
|
332
345
|
// sync point the field example turned on (#154 phase 2 on #159 phase 1).
|
|
333
346
|
// A phase already done has nothing left to wait for.
|
|
334
347
|
m.phaseWaits = m.phases
|
|
335
348
|
.filter((p) => p.text !== null && !phaseIsDone(p.text))
|
|
336
349
|
.flatMap((p) =>
|
|
337
|
-
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) } })),
|
|
338
351
|
)
|
|
339
352
|
}
|
|
340
353
|
|
|
@@ -379,9 +392,6 @@ function epicStatus({ epic, index, readFile, candidates = [], worktrees = [] })
|
|
|
379
392
|
}
|
|
380
393
|
}
|
|
381
394
|
|
|
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
395
|
// `feat-a phase 2 after feat-b phase 1 — not done`, or `feat-a starts after …`.
|
|
386
396
|
function syncLine({ spec, phase, wait }) {
|
|
387
397
|
const who = phase === null ? `${spec} starts` : `${spec} phase ${phase}`
|
|
@@ -389,28 +399,47 @@ function syncLine({ spec, phase, wait }) {
|
|
|
389
399
|
return `${who} after ${wait.raw} (${mark} — ${wait.why})`
|
|
390
400
|
}
|
|
391
401
|
|
|
402
|
+
// Columns padded to their widest cell. Plain text, never a markdown table: the
|
|
403
|
+
// answer is read raw under `watch` as often as it is rendered (spec
|
|
404
|
+
// feat-epic-next, Decision 3), and a pipe table read raw is noise.
|
|
405
|
+
function aligned(lines, indent = ' ') {
|
|
406
|
+
const widths = lines[0].map((_, i) => Math.max(...lines.map((l) => l[i].length)))
|
|
407
|
+
return lines.map((l) => (indent + l.map((c, i) => (i === l.length - 1 ? c : c.padEnd(widths[i]))).join(' ')).trimEnd())
|
|
408
|
+
}
|
|
409
|
+
|
|
392
410
|
/**
|
|
393
|
-
* The human answer,
|
|
394
|
-
*
|
|
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.
|
|
395
416
|
*/
|
|
396
417
|
function formatEpicStatus(s) {
|
|
397
|
-
if (!s.found && !s.members.length)
|
|
418
|
+
if (!s.found && !s.members.length) {
|
|
419
|
+
return `no epic named ${s.epic}, and no spec names it as its Epic${s.here ? ` in ${s.here}` : ''}.\n`
|
|
420
|
+
}
|
|
398
421
|
const lanes = s.lanes === null ? 'no lane cap' : `${s.lanes} lanes, ${s.freeLanes} free`
|
|
399
|
-
const
|
|
400
|
-
const
|
|
401
|
-
|
|
402
|
-
|
|
403
|
-
|
|
404
|
-
|
|
405
|
-
|
|
406
|
-
|
|
407
|
-
|
|
408
|
-
|
|
409
|
-
|
|
410
|
-
|
|
422
|
+
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, '']
|
|
425
|
+
if (!s.members.length) {
|
|
426
|
+
out.push(` no members — no spec carries \`> **Epic:** ${s.epic}\``)
|
|
427
|
+
} else {
|
|
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')
|
|
430
|
+
out.push(
|
|
431
|
+
...aligned([['member', 'state', 'next', 'tab'], ...rows.map((r) => [r.spec, state(r), actionText(r.next), r.tab || '—'])]),
|
|
432
|
+
)
|
|
433
|
+
if (next) out.push('', ` ${s.epic}: ${actionText(next)}`)
|
|
434
|
+
}
|
|
435
|
+
const shape = [
|
|
436
|
+
['waves', s.waves.map((w, i) => `${i + 1}: ${w.join(', ')}`).join(' · ')],
|
|
437
|
+
['sync points', s.syncPoints.map(syncLine).join(' · ')],
|
|
438
|
+
['never together', s.clashes.map((c) => `${c.specs.join(' ‖ ')} (${c.paths.join(', ')})`).join(' · ')],
|
|
439
|
+
['cycle', s.cycles.map((c) => c.join(' → ')).join(' · ')],
|
|
411
440
|
].filter(([, v]) => v)
|
|
412
|
-
if (
|
|
413
|
-
return
|
|
441
|
+
if (shape.length) out.push('', ...aligned(shape))
|
|
442
|
+
return out.join('\n') + '\n'
|
|
414
443
|
}
|
|
415
444
|
|
|
416
445
|
/**
|