@skitterbyte/skitterspec-jira 2.7.0 → 2.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/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 +40 -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/bin/skitterspec-jira.js +5 -0
- package/package.json +1 -1
- package/src/cli.js +134 -17
- package/src/env/config.js +47 -6
- package/src/env/epic.js +23 -8
- package/src/env/epicpage.js +4 -3
- package/src/env/epicread.js +39 -1
- package/src/env/integrate.js +48 -1
- package/src/env/project.js +18 -0
- package/src/env/review.js +21 -3
- package/src/env/serve.js +17 -8
- 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
|
@@ -329,11 +329,15 @@ through to a documented conservative default; see the field notes below.
|
|
|
329
329
|
// draft: mid-spec PRs open as drafts (a draft cannot be merged, so
|
|
330
330
|
// nothing downstream can close a ticket early); /spec-complete is
|
|
331
331
|
// what flips the PR to ready. Default true.
|
|
332
|
-
// specDocs: where a SPEC DOCUMENT lands
|
|
333
|
-
//
|
|
334
|
-
//
|
|
335
|
-
//
|
|
336
|
-
//
|
|
332
|
+
// specDocs: where a SPEC DOCUMENT lands. "trunk" keeps the authoring land
|
|
333
|
+
// — needs direct push for docs under "pr". "branch" has the spec
|
|
334
|
+
// ride its feature branch and land with the work; the backlog is
|
|
335
|
+
// then found via the tracker listing, and the authoring worktree
|
|
336
|
+
// stays (it is the document's only copy). Default "trunk" —
|
|
337
|
+
// unless a ticketing provider is configured (its config file in
|
|
338
|
+
// specs/.core/) and this key is unset, under either strategy:
|
|
339
|
+
// then "branch", because the tracker already is the backlog.
|
|
340
|
+
// Setting the key, to either value, always wins.
|
|
337
341
|
// The merged-check and PR commands need the host's CLI — `gh` on github.com,
|
|
338
342
|
// `az` on dev.azure.com — detected from the remote URL, never configured. An
|
|
339
343
|
// unknown host (Enterprise/Server domains included) degrades to the ancestry
|
|
@@ -564,6 +568,12 @@ through to a documented conservative default; see the field notes below.
|
|
|
564
568
|
// because a commit made under rules nobody configured must not read as one
|
|
565
569
|
// made under /commit.
|
|
566
570
|
//
|
|
571
|
+
// `projectName` is what every generated page — the review page, the served
|
|
572
|
+
// index, the epic page — calls this project, in its tab and above its
|
|
573
|
+
// heading. Empty (the default) means the project folder's name in the
|
|
574
|
+
// primary checkout, never a worktree's; set it when that folder is called
|
|
575
|
+
// something like `app`. Default: "".
|
|
576
|
+
//
|
|
567
577
|
// THERE IS NO OFF SWITCH. `"none"` existed and was removed: it produced a
|
|
568
578
|
// verdict that records itself and does nothing, which is the one thing a
|
|
569
579
|
// review page must not offer — a review is the guard in front of an action.
|
|
@@ -657,6 +667,7 @@ through to a documented conservative default; see the field notes below.
|
|
|
657
667
|
"serve": "always",
|
|
658
668
|
"commitWith": "/commit",
|
|
659
669
|
"required": true,
|
|
670
|
+
"projectName": "",
|
|
660
671
|
"reviewers": []
|
|
661
672
|
}
|
|
662
673
|
}
|
package/assets/review/page.html
CHANGED
|
@@ -120,6 +120,7 @@ body {
|
|
|
120
120
|
|
|
121
121
|
header { margin-bottom: 1rem; }
|
|
122
122
|
h1 { font-size: 1.3rem; margin: 0 0 .3rem; overflow-wrap: anywhere; }
|
|
123
|
+
.eyebrow { color: var(--muted); font-size: .8rem; margin: 0 0 .15rem; overflow-wrap: anywhere; }
|
|
123
124
|
.sub { color: var(--muted); font-size: .85rem; margin: 0; overflow-wrap: anywhere; }
|
|
124
125
|
.sub .sep { opacity: .5; padding: 0 .35rem; }
|
|
125
126
|
.a { color: var(--add-mark); }
|
|
@@ -833,6 +834,7 @@ a.ticket:hover { border-color: var(--accent); }
|
|
|
833
834
|
<body>
|
|
834
835
|
<div class="wrap" id="wrap">
|
|
835
836
|
<header>
|
|
837
|
+
<p class="eyebrow" id="project" hidden></p>
|
|
836
838
|
<h1 id="title"></h1>
|
|
837
839
|
<p class="sub" id="sub"></p>
|
|
838
840
|
<div class="controls">
|
|
@@ -3311,6 +3313,13 @@ a.ticket:hover { border-color: var(--accent); }
|
|
|
3311
3313
|
// --- header --------------------------------------------------------------
|
|
3312
3314
|
var titleEl = document.getElementById('title')
|
|
3313
3315
|
titleEl.textContent = data.title
|
|
3316
|
+
// The project this page belongs to, above the heading. textContent, never
|
|
3317
|
+
// markup: the name comes from a config file and the page is served.
|
|
3318
|
+
if (data.project) {
|
|
3319
|
+
var projectEl = document.getElementById('project')
|
|
3320
|
+
projectEl.textContent = data.project
|
|
3321
|
+
projectEl.hidden = false
|
|
3322
|
+
}
|
|
3314
3323
|
/**
|
|
3315
3324
|
* The tracker ticket, beside the title and linked where there is a url.
|
|
3316
3325
|
*
|
|
@@ -245,15 +245,18 @@ worktree: `Commit & Start` keeps it and carries into `/spec-start`, plain
|
|
|
245
245
|
`commit` tears it down, because a spec parked in the backlog should hold no
|
|
246
246
|
checkout.
|
|
247
247
|
|
|
248
|
-
**`land.specDocs: "branch"` is the exception
|
|
249
|
-
|
|
250
|
-
|
|
251
|
-
|
|
252
|
-
|
|
253
|
-
|
|
254
|
-
|
|
255
|
-
|
|
256
|
-
|
|
248
|
+
**`land.specDocs: "branch"` is the exception — and the default with a tracker.**
|
|
249
|
+
The spec rides its feature branch and lands with the work: both verdicts commit
|
|
250
|
+
and skip the integrate, plain `commit` keeps branch and worktree (they are the
|
|
251
|
+
document's only copy), and the backlog is found through the tracker listing
|
|
252
|
+
rather than `ls specs/backlog/` on base. It began as the lane for a base branch
|
|
253
|
+
that accepts no direct push even for documents. It is now also what a project
|
|
254
|
+
gets by default once a ticketing provider is configured and the key is unset,
|
|
255
|
+
under either landing strategy: the ticket already exists and the board already
|
|
256
|
+
owns status, so a land whose only purpose was findability buys nothing. Setting
|
|
257
|
+
the key, to either value, always wins. The worktree fork-point check is exempt
|
|
258
|
+
in this mode for the hotfix's reason: the spec is *supposed* to be absent from
|
|
259
|
+
the fork point.
|
|
257
260
|
|
|
258
261
|
**What this bought is the reason it changed.** The page waits for a verdict
|
|
259
262
|
without a timeout — deliberately, because a reader walking away from a diff is
|
|
@@ -729,8 +732,26 @@ its order onto its members: rename the folder to `epic-<name>` (`git mv`), set
|
|
|
729
732
|
`> **Type:** Epic`, add `> **Epic:**` and `> **Waits on:**` to each member (and
|
|
730
733
|
a phase file's own `Waits on:` for a phase-level sync point), and delete the
|
|
731
734
|
wave phase files — `epic status` derives them. Keep the plan's Decisions: they
|
|
732
|
-
are the *why* the members' headers cannot say.
|
|
733
|
-
|
|
735
|
+
are the *why* the members' headers cannot say.
|
|
736
|
+
|
|
737
|
+
**A phase that is not a wave becomes a member.** A test pass, a review, a
|
|
738
|
+
manual step the plan held as a phase is its own spec of the kind its work is —
|
|
739
|
+
usually an **Issue** (manual steps, no code) — with `> **Epic:**` and its own
|
|
740
|
+
`> **Waits on:**`; whatever waited on that phase waits on the member instead.
|
|
741
|
+
An epic holds no phases, because it holds no check it cannot observe.
|
|
742
|
+
|
|
743
|
+
**Do it off the base branch, and check it before it lands.** The conversion is
|
|
744
|
+
documents only, so it is a `/no-spec` branch. From that worktree,
|
|
745
|
+
`skitterspec epic status <epic> --here` reads the members and headers as the
|
|
746
|
+
branch has them — uncommitted edits included — while a wait still counts as met
|
|
747
|
+
only on the base branch, so you can confirm it reproduces the plan you had
|
|
748
|
+
before landing it.
|
|
749
|
+
|
|
750
|
+
**The epic's first push retires the wave sub-issues.** An epic has no phases,
|
|
751
|
+
so every phase sub-issue its snapshot still remembers is a leftover of the plan
|
|
752
|
+
it was converted from: the push closes each as not planned and unlinks it from
|
|
753
|
+
the epic's issue, leaving the members as its only sub-issues. A tracker that
|
|
754
|
+
cannot retire one names it, to close by hand.
|
|
734
755
|
|
|
735
756
|
### Kind routing — any door, the right spec
|
|
736
757
|
|
|
@@ -888,6 +909,14 @@ status also lives in the tracker when a ticketing provider is linked. (There are
|
|
|
888
909
|
no `00-index.md` summary files — the folder tree, headers, and State logs are
|
|
889
910
|
queried directly.)
|
|
890
911
|
|
|
912
|
+
Under `land.specDocs: "branch"` a spec is not on the base branch until its
|
|
913
|
+
work lands, so `specs/backlog/` there misses it. `gating check` and
|
|
914
|
+
`epic status` therefore also read the spec folders each spec branch changed —
|
|
915
|
+
local branches, then remote-tracking ones as of the last fetch, never
|
|
916
|
+
fetching — and a branch copy wins over the base copy unless the base branch
|
|
917
|
+
has already finished that spec. A branch copy can make an epic member visible;
|
|
918
|
+
it never meets a wait, which is still read only off the base branch.
|
|
919
|
+
|
|
891
920
|
## Rules
|
|
892
921
|
|
|
893
922
|
- If a spec already exists, update it — don't rewrite from scratch.
|
|
@@ -144,6 +144,13 @@ mentioning. The whole reason the stack exists is that the engine was being asked
|
|
|
144
144
|
to guess where the reader was sitting, and it guessed wrong three separate ways
|
|
145
145
|
in one day; a skill re-deciding that in prose is the same guess one layer up.
|
|
146
146
|
|
|
147
|
+
**And it holds outside a skill too.** Whenever you relay engine output that
|
|
148
|
+
carries a stack — `epic status` asked in passing, a `resolve`, an answer to a
|
|
149
|
+
question — pass on every tier, every `also:` line with its label, and the
|
|
150
|
+
`remote` line, never the one URL that looked like the answer. An agent asked
|
|
151
|
+
about an epic once replied with the member list and the loopback link alone,
|
|
152
|
+
and the reader on a phone was left with nothing they could open.
|
|
153
|
+
|
|
147
154
|
**Three tiers, always all three, in this order.**
|
|
148
155
|
|
|
149
156
|
| Tier | Is | Off when |
|
|
@@ -448,7 +455,7 @@ behind it — say nothing rather than reporting that there was nothing to report
|
|
|
448
455
|
| `Built` | What the run produced — the code, the edits, the spec written. |
|
|
449
456
|
| `Tests` | The result and the command that produced it. |
|
|
450
457
|
| `Notes` | What this run hit and handled — one short paragraph. Named `Snags` once, which announced a problem before the reader had read one; most of what belongs here is neither good nor bad, just worth knowing. A wrong turn, a guard that fired, a check of yours that turned out to be a false negative. Not a caveat on the outcome (`⚠️` and `Why` carry those) and not future work (`Follow-ups` carries that): this is what happened on the way. |
|
|
451
|
-
| `Landed` | A fast-forward, a tag, a cherry-pick — or in PR mode the PR itself: `PR #14 (draft) updated` · `PR #14 opened — finish after merge` · `PR #14 merged` · `held — not pushed` (a declined consent is a true outcome, not a failure). |
|
|
458
|
+
| `Landed` | A fast-forward, a tag, a cherry-pick — or in PR mode the PR itself: `PR #14 (draft) updated` · `PR #14 opened — finish after merge` · `PR #14 merged` · `held — not pushed` (a declined consent is a true outcome, not a failure) · `not pushed · <command> publishes it` (a push suggested rather than asked, as `/spec`'s branch lane does). |
|
|
452
459
|
| `Worktree` | A worktree provisioned, entered, or torn down. |
|
|
453
460
|
| `Untouched` | Uncommitted work the run deliberately left alone — whose, and how much. |
|
|
454
461
|
| `Review` | The rendered diff page: files, `+`/`−`, and the stack — the same tiers the banner lists, labelled, run together with `·` because a row is one cell, with any `network` alternates inline after the network URL (`also <url> (tailnet)`), plus `live` where the engine reported one. **No question** — a row cannot be waited on, so a question in one is unanswerable by construction (see *asking implies waiting*). **Omitted entirely when the run is waiting on a verdict**: the banner after the block carries it instead, and a row saying the same thing beside it splits the reader's attention across two places. |
|
|
@@ -620,23 +620,40 @@ on the branch you are standing on — so a spec left on its own branch would be
|
|
|
620
620
|
invisible to everyone, including the next `/spec` run. The commit goes on the
|
|
621
621
|
branch and then the branch goes onto the base:
|
|
622
622
|
|
|
623
|
-
**Unless
|
|
624
|
-
|
|
625
|
-
|
|
626
|
-
|
|
627
|
-
|
|
628
|
-
|
|
629
|
-
|
|
630
|
-
|
|
631
|
-
|
|
632
|
-
|
|
633
|
-
|
|
623
|
+
**Unless `land.specDocs` is `"branch"`** — set so in `env.config.json`, or
|
|
624
|
+
left unset in a project with a ticketing provider configured (its config file
|
|
625
|
+
under `specs/.core/`), where it is the default because the tracker already is
|
|
626
|
+
the backlog. It is the lane where the spec document rides its feature branch
|
|
627
|
+
and lands with the work. There both verdicts commit on the branch and
|
|
628
|
+
**touch no base at all**; `commit-start` carries into `/spec-start` over the
|
|
629
|
+
same worktree exactly as ever, and plain `commit` keeps the branch AND the
|
|
630
|
+
worktree, because they are the document's working copy. What the lane does
|
|
631
|
+
instead of landing is **publish the branch**, because an unpushed spec branch
|
|
632
|
+
is on one machine and nowhere else — the ticket's summary cannot rebuild it.
|
|
633
|
+
|
|
634
|
+
**The same command answers both lanes; you do not choose between them:**
|
|
634
635
|
|
|
635
636
|
```
|
|
636
|
-
skitterspec spec-env integrate <name>
|
|
637
|
+
skitterspec spec-env integrate <name> --docs
|
|
637
638
|
```
|
|
638
639
|
|
|
639
|
-
|
|
640
|
+
Under `"trunk"` it prints the ordinary land, unchanged. Under `"branch"` it
|
|
641
|
+
says `spec docs ride the branch` and plans one push of the spec's branch,
|
|
642
|
+
consent-gated like every push in this workflow: already on the remote at HEAD
|
|
643
|
+
is honoured and runs nothing; otherwise it holds the push.
|
|
644
|
+
**Do not ask, and do not run it** — a suggestion is not a question.
|
|
645
|
+
Report `Landed` as `not pushed`, with the held command it printed beside it as
|
|
646
|
+
the way to publish, so it sits in the table for the reader to take or leave. A
|
|
647
|
+
question here interrupted the end of an authoring run for something that can
|
|
648
|
+
wait until the reader chooses to. Already on the remote reports
|
|
649
|
+
`pushed <remote>/<branch>`. A clone with no such remote prints that the branch
|
|
650
|
+
stays local; report that as the `Landed` row.
|
|
651
|
+
|
|
652
|
+
Say the trade in the report's `Notes`: the backlog is found through the
|
|
653
|
+
tracker listing (or the spec branches), not `ls specs/backlog/` on base. Under
|
|
654
|
+
`"trunk"` everything below applies unchanged.
|
|
655
|
+
|
|
656
|
+
Under `"trunk"` it plans a rebase onto the base branch in the worktree, then a
|
|
640
657
|
`merge --ff-only` in the primary checkout — run the commands it prints. It
|
|
641
658
|
refuses on a dirty tree, which is correct here: the commit ran first, so anything
|
|
642
659
|
still uncommitted at this point is not this spec's and the land must not proceed.
|
|
@@ -279,6 +279,13 @@ only ordering that survives.
|
|
|
279
279
|
a fault — and if the user wants the remote branch gone anyway, that is their
|
|
280
280
|
call to make explicitly, not something to tidy away on their behalf.
|
|
281
281
|
|
|
282
|
+
**One unlanded branch does get the section: a never-started spec under `land.specDocs: "branch"`**, whose branch holds nothing but its own
|
|
283
|
+
documents. Its remote copy backs up only the spec being cancelled — the
|
|
284
|
+
ticket keeps the record — and left there it goes on reading as backlog to
|
|
285
|
+
every check that scans spec branches. Ask exactly as above. On a no, say in
|
|
286
|
+
the report that the branch stays on the remote and will still read as
|
|
287
|
+
backlog until someone deletes it.
|
|
288
|
+
|
|
282
289
|
**In PR mode the same confirm-first section may carry the PR abandon**
|
|
283
290
|
(`gh pr close` / `az repos pr update --status abandoned`): a cancelled spec
|
|
284
291
|
must not leave a live PR behind — it is noise with a merge button on it.
|
|
@@ -297,11 +297,46 @@ Then build it, following the project rules in `.claude/rules/*.md` and `CLAUDE.m
|
|
|
297
297
|
- Never hardcode dates in tests; never run destructive commands against a real
|
|
298
298
|
database — use the project's test database only.
|
|
299
299
|
|
|
300
|
+
### Manual steps — list them, then ask
|
|
301
|
+
|
|
302
|
+
Some tasks are a person's to do: every task in an **Issue** spec, and any task
|
|
303
|
+
you cannot perform yourself — operate a UI, check a device, confirm something
|
|
304
|
+
on a board, run a manual test pass. That is a **judgment**, not a marker: there
|
|
305
|
+
is no `(manual)` tag to look for, and a spec written before this rule has none.
|
|
306
|
+
|
|
307
|
+
Build the tasks before the first manual one as usual. Then **stop at it** and
|
|
308
|
+
print **every remaining manual step of this phase, verbatim and numbered**, as a
|
|
309
|
+
plain markdown list in the conversation — never fenced, and
|
|
310
|
+
**never only the phase file's path**. A pointer to the file sends the reader
|
|
311
|
+
out of the terminal to find out what to do, which is the failure this exists to
|
|
312
|
+
fix; the steps themselves are what they act on.
|
|
313
|
+
|
|
314
|
+
Then ask one question, with three answers:
|
|
315
|
+
|
|
316
|
+
- **All done** — tick those steps and carry on to the end of the phase.
|
|
317
|
+
- **Some failed** — the picker cannot list the steps (it holds four options and
|
|
318
|
+
a phase can hold more), so ask in prose which numbers failed and what
|
|
319
|
+
happened. Write a dated note under each failed task, leave it unticked, tick
|
|
320
|
+
the rest. Where what happened is a defect, offer **`/spec-bug`** — confirm,
|
|
321
|
+
never switch.
|
|
322
|
+
- **Not yet** — tick nothing.
|
|
323
|
+
|
|
324
|
+
This is the mid-run question `.claude/rules/spec-reports.md` already allows —
|
|
325
|
+
whether a person did something is a question you cannot answer yourself — so it
|
|
326
|
+
needs no new shape in the report.
|
|
327
|
+
|
|
328
|
+
**Some failed or Not yet leaves the phase `🔄`, and stops the run there.** Code
|
|
329
|
+
tasks after an unconfirmed step are not built past it, and the phase did not
|
|
330
|
+
end: **skip §4's done-marking and §5 entirely** — no page, no arm, no wait.
|
|
331
|
+
End `⚠️` and name `/spec-next` in `Next`; it re-lists the same unticked steps.
|
|
332
|
+
|
|
300
333
|
## 4. Record progress
|
|
301
334
|
|
|
302
335
|
- In the **phase file**: tick completed tasks (`- [x]`), flip its heading to `✅`,
|
|
303
336
|
and set its `> **Status:**` to `Done`.
|
|
304
337
|
- In **`00-overview.md`**: flip the matching phase-index row to `✅`.
|
|
338
|
+
- A manual step answered **Some failed** keeps its box unticked with its note,
|
|
339
|
+
and the phase is not marked done (§3, *Manual steps*).
|
|
305
340
|
- If anything changed from the plan (a decision, a deviation, a discovered
|
|
306
341
|
constraint), add a dated **Changelog** entry in `00-overview.md`.
|
|
307
342
|
- If new work surfaced, add it as tasks to the appropriate phase file (or add a
|
|
@@ -645,7 +680,9 @@ the shape; this section carries only what is specific here.
|
|
|
645
680
|
|
|
646
681
|
- `✅` — the phase is built and its tests are green.
|
|
647
682
|
- `⚠️` — built and green, with something worth knowing (a mirror that did not
|
|
648
|
-
refresh, a deviation from the plan)
|
|
683
|
+
refresh, a deviation from the plan) — or stopped at manual steps answered
|
|
684
|
+
**Some failed** or **Not yet**: the phase stays `🔄`, `Notes` says which steps
|
|
685
|
+
are open, and `Next` is `/commit, then /spec-next` to pick them up.
|
|
649
686
|
- `❌` — the phase's tests are red, or it stopped part-way. Quote the failure.
|
|
650
687
|
- `⏸` — no spec in flight, or the name given does not match the one that is.
|
|
651
688
|
|
package/bin/skitterspec-jira.js
CHANGED
|
@@ -27,6 +27,11 @@ const { run, HELP } = require('../src/cli.js')
|
|
|
27
27
|
require('../src/env/config.js').setProviderEnvDefaults(
|
|
28
28
|
require('../src/vendor/jira/config.js').ENV_CONFIG_DEFAULTS,
|
|
29
29
|
)
|
|
30
|
+
// Its config file too: present, it is what makes `land.specDocs` default to
|
|
31
|
+
// "branch" (see common src/env/config.js, setProviderConfigFile).
|
|
32
|
+
require('../src/env/config.js').setProviderConfigFile(
|
|
33
|
+
require('../src/vendor/jira/config.js').CONFIG_FILE,
|
|
34
|
+
)
|
|
30
35
|
const {
|
|
31
36
|
PROVIDER_COMMANDS,
|
|
32
37
|
providerHelpSection,
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@skitterbyte/skitterspec-jira",
|
|
3
|
-
"version": "2.
|
|
3
|
+
"version": "2.8.0",
|
|
4
4
|
"description": "Spec-driven development for Claude Code, with one-way Jira Cloud sync — a superset of @skitterbyte/skitterspec: the base filesystem workflow plus /spec-status · /spec-push and the spec-sync CLI. The repo is canonical; Jira is a generated mirror. Install this OR the base OR the Linear superset — exactly one.",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"claude",
|
package/src/cli.js
CHANGED
|
@@ -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')
|
|
@@ -199,7 +201,7 @@ const {
|
|
|
199
201
|
waitsMetByRebase,
|
|
200
202
|
} = require('./env/epic.js')
|
|
201
203
|
const { nextAction, readNextInputs } = require('./env/nextaction.js')
|
|
202
|
-
const { epicTree, worktreeOverview, epicsInFlight, memberReaders, epicAnswer } = require('./env/epicread.js')
|
|
204
|
+
const { epicTree, workingTree, worktreeOverview, epicsInFlight, memberReaders, epicAnswer } = require('./env/epicread.js')
|
|
203
205
|
const { planHotfixLand, planBranchHotfixLand, planBranchHotfixFinish, planHotfixFinish } = require('./env/hotfix.js')
|
|
204
206
|
const { runHotfixLand, describeStep: describeHotfixStep } = require('./env/hotfixland.js')
|
|
205
207
|
const { planDev } = require('./env/dev.js')
|
|
@@ -280,7 +282,8 @@ Usage:
|
|
|
280
282
|
dev down <spec> stop the spec's host dev servers
|
|
281
283
|
connect <spec> expose a spec on the canonical ports (main = off)
|
|
282
284
|
integrate <spec> plan the land: rebase + fast-forward, or in PR
|
|
283
|
-
mode push + PR (--push, --draft, --strategy)
|
|
285
|
+
mode push + PR (--push, --draft, --strategy);
|
|
286
|
+
--docs: under specDocs "branch", publish only
|
|
284
287
|
disposition <spec>
|
|
285
288
|
list unticked tasks, open phases and surfaced
|
|
286
289
|
follow-ups to dispose before a PR goes ready
|
|
@@ -608,8 +611,18 @@ function inFlightStatus(argv) {
|
|
|
608
611
|
function epicStatusCommand(argv) {
|
|
609
612
|
const json = argv.includes('--json')
|
|
610
613
|
const named = epicPositional(argv)
|
|
611
|
-
const
|
|
612
|
-
if (!
|
|
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
|
|
613
626
|
const epic = named || epicFromHere(inputs)
|
|
614
627
|
if (!epic) {
|
|
615
628
|
const flying = epicsInFlight(inputs.worktrees)
|
|
@@ -617,7 +630,7 @@ function epicStatusCommand(argv) {
|
|
|
617
630
|
? `name an epic — in flight here: ${flying.join(', ')}`
|
|
618
631
|
: 'name an epic — none has a member in flight here'
|
|
619
632
|
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`,
|
|
633
|
+
json ? JSON.stringify({ epic: null, inFlight: flying }, null, 2) + '\n' : `Usage: skitterspec epic status [<epic>] [--here] [--json] [--dir <path>]\n${line}\n`,
|
|
621
634
|
)
|
|
622
635
|
return
|
|
623
636
|
}
|
|
@@ -628,9 +641,14 @@ function epicStatusCommand(argv) {
|
|
|
628
641
|
// A link only where a server is already serving: this reads the server and
|
|
629
642
|
// never starts one, so a status asked from a phone never restarts the
|
|
630
643
|
// server whose link that phone has open.
|
|
631
|
-
|
|
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),
|
|
632
650
|
})
|
|
633
|
-
const answer = epicAnswer(epic, inputs, readers)
|
|
651
|
+
const answer = { ...epicAnswer(epic, inputs, readers), ...(here ? { here: here.label } : {}) }
|
|
634
652
|
const page = epicPageTiers(inputs, up, epic)
|
|
635
653
|
if (json) {
|
|
636
654
|
process.stdout.write(JSON.stringify({ base: inputs.base, ...answer, page }, null, 2) + '\n')
|
|
@@ -641,6 +659,14 @@ function epicStatusCommand(argv) {
|
|
|
641
659
|
process.stdout.write(formatEpicStatus(answer) + (found ? '\n' + epicPageLines(page) : ''))
|
|
642
660
|
}
|
|
643
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
|
+
|
|
644
670
|
/**
|
|
645
671
|
* Where the epic page can be read: the same tiers a review render prints, for
|
|
646
672
|
* the epic's own route — or, with no server running, the one command that
|
|
@@ -660,6 +686,15 @@ function epicPageLines(page) {
|
|
|
660
686
|
return `epic page:\n${page.tiers.map(reviewTierLine).join('\n')}\n`
|
|
661
687
|
}
|
|
662
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
|
+
|
|
663
698
|
/**
|
|
664
699
|
* The epic a bare `epic status` means: the one whose worktree this command runs
|
|
665
700
|
* in, or the epic named by the member whose worktree it runs in. A positive
|
|
@@ -831,7 +866,7 @@ function epicInputs(argv, json, subject) {
|
|
|
831
866
|
.map((p) => worktreeOverview(p.project, p.folder))
|
|
832
867
|
.filter(Boolean)
|
|
833
868
|
: []
|
|
834
|
-
return { dir, config: present ? config : null, base, ...tree, worktrees }
|
|
869
|
+
return { dir, config: present ? config : null, base, ...tree, worktrees, branches: specBranchDocs(git, config, base) }
|
|
835
870
|
}
|
|
836
871
|
|
|
837
872
|
// Plan a provision: allocate the slot, persist the registry, and print the plan
|
|
@@ -944,14 +979,28 @@ function untouchedLines(plan) {
|
|
|
944
979
|
* yet is not broken, and a check that stopped someone's work over a missing
|
|
945
980
|
* header would be a worse failure than the omission it names.
|
|
946
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
|
+
|
|
947
995
|
function gatingCheck(dir, argv) {
|
|
948
996
|
const { opts, positional } = parse(argv)
|
|
949
|
-
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))
|
|
950
999
|
|
|
951
1000
|
let specs = null
|
|
952
1001
|
if (positional.length && !opts.all) {
|
|
953
1002
|
const name = path.basename(positional[0])
|
|
954
|
-
const found = activeSpecs(dir).filter((s) => s.folder === name)
|
|
1003
|
+
const found = preferBranches(activeSpecs(dir), branches).filter((s) => s.folder === name)
|
|
955
1004
|
if (!found.length) {
|
|
956
1005
|
// Not an accusation: a name that matches no ACTIVE spec is usually a
|
|
957
1006
|
// finished one, which gating never covers anyway.
|
|
@@ -961,7 +1010,7 @@ function gatingCheck(dir, argv) {
|
|
|
961
1010
|
specs = found
|
|
962
1011
|
}
|
|
963
1012
|
|
|
964
|
-
const result = checkGating(dir, specs)
|
|
1013
|
+
const result = checkGating(dir, specs, { branches })
|
|
965
1014
|
|
|
966
1015
|
if (opts.json) {
|
|
967
1016
|
process.stdout.write(JSON.stringify(result, null, 2) + '\n')
|
|
@@ -981,8 +1030,8 @@ function gatingCheck(dir, argv) {
|
|
|
981
1030
|
for (const f of result.findings) {
|
|
982
1031
|
lines.push(
|
|
983
1032
|
f.kind === 'missing'
|
|
984
|
-
? ` ${f.folder} (${f.bucket}): no Gating: header`
|
|
985
|
-
: ` ${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`,
|
|
986
1035
|
)
|
|
987
1036
|
}
|
|
988
1037
|
lines.push('')
|
|
@@ -2096,6 +2145,16 @@ function specEnvDown(dir, config, specArg, flags) {
|
|
|
2096
2145
|
prAbandon = prAbandonCommand(info, { branch: spec.branch, id: pr.id })
|
|
2097
2146
|
}
|
|
2098
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
|
+
}
|
|
2099
2158
|
const plan = planDown(spec, config, flags, {
|
|
2100
2159
|
worktreeState,
|
|
2101
2160
|
prAbandonCommand: prAbandon,
|
|
@@ -2468,6 +2527,15 @@ function specEnvIntegrate(dir, config, specArg, flags = {}) {
|
|
|
2468
2527
|
// entirely on its branch may not exist in the primary checkout's specs/** —
|
|
2469
2528
|
// resolveSpecWithWorktree offers its worktree as a fallback search location.
|
|
2470
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
|
+
}
|
|
2471
2539
|
// Fetch before resolving under a rolling base, so a spec that outlived a
|
|
2472
2540
|
// release roll lands on the rc that exists now rather than the one the last
|
|
2473
2541
|
// fetch saw. No pattern → no fetch, and the plan below is unchanged.
|
|
@@ -2853,6 +2921,55 @@ function specEnvIntegratePr(dir, config, spec, base, flags, retarget = null) {
|
|
|
2853
2921
|
process.stdout.write(out.join('\n') + '\n')
|
|
2854
2922
|
}
|
|
2855
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
|
+
|
|
2856
2973
|
// `spec-env disposition [<spec>] [--json]` — enumerate the loose ends a
|
|
2857
2974
|
// completion must dispose before a PR goes ready: unticked tasks, phase-index
|
|
2858
2975
|
// rows not ✅, surfaced follow-ups. Information only — it never refuses and
|
|
@@ -5404,6 +5521,7 @@ async function specEnvReview(dir, config, specArg, flags, invokedFrom = dir) {
|
|
|
5404
5521
|
notes,
|
|
5405
5522
|
gate,
|
|
5406
5523
|
buttons,
|
|
5524
|
+
project: projectName(config),
|
|
5407
5525
|
...surfaceArgs,
|
|
5408
5526
|
...(docs ? { only: docs.owned, treePath: docs.tree } : {}),
|
|
5409
5527
|
})
|
|
@@ -5446,6 +5564,7 @@ async function specEnvReview(dir, config, specArg, flags, invokedFrom = dir) {
|
|
|
5446
5564
|
notes,
|
|
5447
5565
|
gate,
|
|
5448
5566
|
buttons,
|
|
5567
|
+
project: projectName(config),
|
|
5449
5568
|
...surfaceArgs,
|
|
5450
5569
|
fellBack: true,
|
|
5451
5570
|
})
|
|
@@ -5795,9 +5914,6 @@ async function specEnvReview(dir, config, specArg, flags, invokedFrom = dir) {
|
|
|
5795
5914
|
// The reason there is no served URL, when there is none. A `file://` link
|
|
5796
5915
|
// with nothing said about it reads as the ordinary outcome, and it is not.
|
|
5797
5916
|
(!served && noServeBecause ? ` not served: ${noServeBecause}\n` : '') +
|
|
5798
|
-
(served && served.loopback && config.review.allowNetwork
|
|
5799
|
-
? ` network permitted but the running server is loopback-bound — ${served.widen}\n`
|
|
5800
|
-
: '') +
|
|
5801
5917
|
(served && served.started && !served.loopback
|
|
5802
5918
|
? ' serving: every provisioned spec, to anyone with a URL on your network.\n' +
|
|
5803
5919
|
' stop: skitterspec spec-env review serve --stop\n'
|
|
@@ -7515,5 +7631,6 @@ module.exports = {
|
|
|
7515
7631
|
serverScriptOk,
|
|
7516
7632
|
daemonScript,
|
|
7517
7633
|
reviewServedUrls,
|
|
7634
|
+
memberPageLink,
|
|
7518
7635
|
restartHost,
|
|
7519
7636
|
}
|