@skitterbyte/skitterspec-jira 1.0.0 → 1.2.2

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/MIGRATION.md CHANGED
@@ -100,6 +100,43 @@ Nothing in `env.config.json` changes.
100
100
  **If you added a secrets-hook exception for the printed seed commands**, you
101
101
  can remove it now. Nothing shipped prints them any more.
102
102
 
103
+ ## `@skitterbyte/skitterspec-azure-boards` v0 → v1 (first release)
104
+
105
+ Nothing to migrate: this is the distribution's first release. It is a superset
106
+ of `@skitterbyte/skitterspec` — install exactly one of the base or one
107
+ superset. Coming from the base, run `npx @skitterbyte/skitterspec-azure-boards
108
+ update` and run `/spec-azure-setup`
109
+ (or `skitterspec-azure-boards spec-sync init-config --org-url … --project …`).
110
+
111
+ **Coming from `@skitterbyte/skitterspec-linear` or `-jira`** — a repo moving
112
+ trackers: swap the distribution, configure Azure as above, set
113
+ `refs.foreignPatterns` to the old team key (e.g. `"ERQ-\\d+"`), then push each
114
+ backlog and in-progress spec (`/spec-push`, or `spec-sync apply --all
115
+ in-progress` and `--all backlog`) to link it to a new work item. Finished specs
116
+ keep their old stamps (`linear_identifier`, …) as history; nothing rewrites
117
+ them. Old `Refs: ERQ-12` trailers stay in the log, and `spec-sync released`
118
+ counts them as `historical` rather than as missing a ref. New commits carry
119
+ `Refs: AB#n`. Delete the old `linear.config.json` / `jira.config.json` once the
120
+ open specs are linked.
121
+
122
+ ## `@skitterbyte/skitterspec-github` v0 → v1 (first release)
123
+
124
+ Nothing to migrate: this is the distribution's first release. It is a superset
125
+ of `@skitterbyte/skitterspec` — install exactly one of the base or one
126
+ superset. Coming from the base, run `npx @skitterbyte/skitterspec-github
127
+ update`, make a Projects v2 board for the repo, and run `/spec-github-setup`
128
+ (or `skitterspec-github spec-sync init-config --owner … --repo … --project N`).
129
+
130
+ **Coming from `@skitterbyte/skitterspec-linear` or `-jira`** — a repo moving
131
+ trackers: swap the distribution, configure GitHub as above, then push each
132
+ backlog and in-progress spec (`/spec-push`, or `spec-sync apply --all
133
+ in-progress` and `--all backlog`) to link it to a new issue. Finished specs keep
134
+ their old stamps (`linear_identifier`, …) as history; nothing rewrites them.
135
+ Old `Refs: SKS-12` trailers stay in the log, and `spec-sync released` counts
136
+ them as `historical` rather than as missing a ref. New commits carry
137
+ `Refs: #N`. Delete the old `linear.config.json` / `jira.config.json` once the
138
+ open specs are linked.
139
+
103
140
  ## `@skitterbyte/skitterspec-jira` v0 → v1 (first release)
104
141
 
105
142
  Nothing to migrate: this is the distribution's first release. It is a superset
@@ -143,6 +143,10 @@ through to a documented conservative default; see the field notes below.
143
143
  // exits non-zero; [] = none. Each string is a shell command; {slug}/{branch}/{worktreePath}/{projectName}/{portOffset}
144
144
  // expand (the cwd is already the worktree, so {worktreePath} is usually
145
145
  // redundant). Example: ["pnpm install --frozen-lockfile"].
146
+ // An entry may also be { "run": "<cmd>", "when": ["<glob>", ...] }. `when` is
147
+ // IGNORED here — a fresh worktree always runs every setup step — and exists
148
+ // so `afterLand` can re-run that step after a land that changes its inputs
149
+ // (`{ "setup": true }`, below).
146
150
  "setup": [],
147
151
 
148
152
  // Commands to run in the PRIMARY checkout after a land — the counterpart of
@@ -160,6 +164,51 @@ through to a documented conservative default; see the field notes below.
160
164
  // failure, report it as a caveat, and never undo the land or block
161
165
  // teardown. Literal strings — tokens are NOT expanded, because they run on
162
166
  // the base branch where a spec's {slug} or {portOffset} mean nothing.
167
+ //
168
+ // CONDITIONAL ENTRIES. A plain string always runs. An entry may instead be
169
+ // { "run": "<cmd>", "when": ["<glob>", ...] } (a single string `when` is
170
+ // fine), which runs only when the land changes a file one of its globs
171
+ // matches — so a generate or an install costs nothing on a land that does
172
+ // not need it, and is not forgotten on one that does:
173
+ //
174
+ // "afterLand": [
175
+ // { "run": "pnpm install --frozen-lockfile", "when": ["pnpm-lock.yaml", "**/package.json"] },
176
+ // { "run": "pnpm run db:generate", "when": ["prisma/schema.prisma"] },
177
+ // "pnpm db:data-migration"
178
+ // ]
179
+ //
180
+ // Globs are repo-relative: `*` stays within a directory, `**` crosses them
181
+ // (`**/package.json` matches the root one too), `?` is one character. An
182
+ // entry whose `when` holds no usable glob is DROPPED, never widened to
183
+ // always-run.
184
+ // The changed files are what the land brings into the base branch:
185
+ // `base...branch` for `integrate` (read before the rebase, so it is the
186
+ // branch's own changes), and the carried fix commits — minus the release's
187
+ // version commit — for `hotfix land`.
188
+ // When that cannot be known, the conditional entries RUN. That is the
189
+ // "already landed" plan (the land happened elsewhere, so its range is not
190
+ // here) and any diff git would not answer. A redundant generate costs
191
+ // seconds; a skipped one leaves the base red with nothing pointing at why.
192
+ // A land that changed no files is known, not unknown, and skips them.
193
+ // The plan says why for every entry: a matched one ends in
194
+ // `# <path> changed`, an unknown one in `# range unknown` with a line saying
195
+ // so, and the rest are listed under `skipped (nothing in the land matched):`
196
+ // with their globs. The reason is a shell comment, so a line run as printed
197
+ // stays one command. Skipped lines are information — run only the list
198
+ // under `then, … run`.
199
+ //
200
+ // REUSING A SETUP STEP. `{ "setup": true }` expands, in place, to every
201
+ // `setup` entry that declares `when`, so the trigger lives in one list:
202
+ //
203
+ // "setup": [
204
+ // { "run": "pnpm install --frozen-lockfile", "when": ["pnpm-lock.yaml", "**/package.json"] },
205
+ // { "run": "pnpm run db:generate", "when": ["prisma/schema.prisma"] }
206
+ // ],
207
+ // "afterLand": [{ "setup": true }, "pnpm db:data-migration"]
208
+ //
209
+ // Plain setup strings carry no trigger and are never pulled in. The command
210
+ // is copied literally — afterLand expands no tokens — so a setup step that
211
+ // relies on {slug}-style tokens is a poor one to reuse.
163
212
  "afterLand": [],
164
213
 
165
214
  // Host dev servers `spec-env dev up <spec>` starts on the spec's port block
@@ -292,8 +341,11 @@ through to a documented conservative default; see the field notes below.
292
341
  // one. Empty (the default) = the built-in tagger.
293
342
  //
294
343
  // `bump` is the built-in tagger's strategy: "patch" (v33.16.4 -> v33.16.5) or
295
- // "hotfix-suffix" (v33.16.4 -> v33.16.4-hotfix.1, then -hotfix.2, ...; a base
296
- // that is already a hotfix tag continues its line). Any other value is refused
344
+ // "hotfix-suffix" (v33.16.4 -> v33.16.4-hotfix.1, then -hotfix.2, ...). Under
345
+ // either, a base that is already a hotfix tag continues its line
346
+ // (v36.2.3-hotfix.4 -> v36.2.3-hotfix.5), so "patch" never takes a number the
347
+ // mainline owns. When the patch tag already exists, the refusal names the
348
+ // free hotfix tag that "hotfix-suffix" would cut. Any other value is refused
297
349
  // when `hotfix land` runs. Tags order X.Y.Z-rc.N < X.Y.Z < X.Y.Z-hotfix.N <
298
350
  // X.Y.(Z+1), the same as skittership.
299
351
  //
@@ -85,7 +85,7 @@ function findEngine(projectDir) {
85
85
  if (process.env.SKITTERSPEC_BIN) return process.env.SKITTERSPEC_BIN
86
86
  let at = projectDir
87
87
  for (let i = 0; i < 6 && at; i++) {
88
- for (const name of ['skitterspec', 'skitterspec-linear', 'skitterspec-jira']) {
88
+ for (const name of ['skitterspec', 'skitterspec-linear', 'skitterspec-jira', 'skitterspec-github', 'skitterspec-azure-boards']) {
89
89
  const candidate = path.join(at, 'node_modules', '.bin', name)
90
90
  if (fs.existsSync(candidate)) return candidate
91
91
  }
@@ -82,7 +82,7 @@ function findEngine(projectDir) {
82
82
  if (process.env.SKITTERSPEC_BIN) return process.env.SKITTERSPEC_BIN
83
83
  let at = projectDir
84
84
  for (let i = 0; i < 6 && at; i++) {
85
- for (const name of ['skitterspec', 'skitterspec-linear', 'skitterspec-jira']) {
85
+ for (const name of ['skitterspec', 'skitterspec-linear', 'skitterspec-jira', 'skitterspec-github', 'skitterspec-azure-boards']) {
86
86
  const candidate = path.join(at, 'node_modules', '.bin', name)
87
87
  if (fs.existsSync(candidate)) return candidate
88
88
  }
@@ -36,7 +36,7 @@ A verdict sentence, a blank line, then a two-column table:
36
36
  | **Branch** | `spec/feat-foo` · 3 commits, clean |
37
37
  | **Built** | POST /orders handler, orders schema |
38
38
  | **Tests** | 128 passed · dotnet test |
39
- | **Review** | 7 files, +212 −18 · **local** [http://127.0.0.1:7760/…](http://127.0.0.1:7760/…) · **network** [http://192.168.0.136:7760/…](http://192.168.0.136:7760/…) · **remote** off |
39
+ | **Review** | 7 files, +212 −18 · **local** [http://127.0.0.1:7760/…](http://127.0.0.1:7760/…) · **network** [http://192.168.0.136:7760/…](http://192.168.0.136:7760/…) also [http://100.126.111.34:7760/…](http://100.126.111.34:7760/…) (tailnet) · **remote** off |
40
40
  | **Follow-ups** | none |
41
41
  | **Next** | `/spec-next` → phase 3 (Auth) |
42
42
 
@@ -89,6 +89,7 @@ the options may be offered after the table.
89
89
 
90
90
  - **local** — [http://127.0.0.1:7760/7e9e123e7540/feat-orders](http://127.0.0.1:7760/7e9e123e7540/feat-orders)
91
91
  - **network** — [http://192.168.0.136:7760/7e9e123e7540/feat-orders](http://192.168.0.136:7760/7e9e123e7540/feat-orders)
92
+ - also — [http://100.126.111.34:7760/7e9e123e7540/feat-orders](http://100.126.111.34:7760/7e9e123e7540/feat-orders) (tailnet)
92
93
  - **remote** — off · `/spec-remote-review` turns it on
93
94
 
94
95
  live: off — /spec-live to put it live
@@ -156,6 +157,17 @@ on. Dropping the line is what left a reader who had walked out of the house with
156
157
  nothing on screen to tell them a remote page was even possible — they could not
157
158
  ask for what they could not see.
158
159
 
160
+ **The `network` tier may carry alternates, and they are part of it — not a fourth tier.**
161
+ The engine offers the other addresses this machine has (a
162
+ tailnet one, for a reader off the wifi) as `also:` lines under `network`, each
163
+ labelled; `--json` carries them as that tier's `alternates`, labelled the same
164
+ way. Copy them as indented sub-bullets under the network bullet, verbatim,
165
+ labels included. This is not an amendment to the tier rule: the stack is the
166
+ engine's, copied rather than composed, and the engine was already printing
167
+ these — a contract that made the skill edit them out was the composing this
168
+ section forbids. A machine with no alternates renders the banner exactly as
169
+ above, minus the sub-bullet.
170
+
159
171
  **Only promise a wait the transport can deliver.** The wait itself is real in
160
172
  every case; what varies is what carries it back, not whether the run is
161
173
  stopped. Three transports, three true sentences:
@@ -298,8 +310,11 @@ behind, and they cannot.
298
310
  `fetch(location.pathname, …)`, so a page opened at `127.0.0.1:7760/…` and one
299
311
  opened at `192.168.0.136:7760/…` reach the same server process and the same
300
312
  pending store. One wait covers both, and a verdict pressed on either wakes the
301
- same run. Between those two the objection does not apply — which is why both are
302
- offered, and why offering them gives nothing up.
313
+ same run. A `network` alternate — the `also:` tailnet address — is one more
314
+ door into the same room: the same server answers on it, so the wait-coverage
315
+ line stays true with nothing added to it. Between all of those the objection
316
+ does not apply — which is why they are offered, and why offering them gives
317
+ nothing up.
303
318
 
304
319
  **So two things are required, and the second is what the old rule lacked.**
305
320
  Every link is **labelled** with its tier, and one line says
@@ -410,7 +425,7 @@ behind it — say nothing rather than reporting that there was nothing to report
410
425
  | `Landed` | A fast-forward, a tag, a cherry-pick. |
411
426
  | `Worktree` | A worktree provisioned, entered, or torn down. |
412
427
  | `Untouched` | Uncommitted work the run deliberately left alone — whose, and how much. |
413
- | `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, 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. |
428
+ | `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. |
414
429
  | `Follow-ups` | **Always.** `none`, or one line each. |
415
430
  | `Next` | **Last.** The single next action for this work — runnable from the state the run leaves behind. |
416
431
 
@@ -174,7 +174,10 @@ three, in that order — never the bare `page:` path.
174
174
  **Between the two, run the after-land commands.** Where the `integrate` plan
175
175
  ends with a `then, in the primary checkout (<path>), run:` section — the
176
176
  project's `afterLand` — run those commands there, in order, once the
177
- fast-forward has succeeded, and on an already-landed no-op too. A lockfile
177
+ fast-forward has succeeded, and on an already-landed no-op too. Run only the
178
+ lines under that heading; a `skipped (nothing in the land matched):` block
179
+ lists conditional entries this land did not need, and is information, never
180
+ commands. A lockfile
178
181
  refresh is exactly the land that needs them.
179
182
  **Stop at the first non-zero exit**: the run becomes `⚠️`, naming the command that failed and the ones that
180
183
  did not run, and it **never undoes the land and never stops the `down`**.
@@ -205,8 +208,8 @@ the shape; this section carries only what is specific here.
205
208
 
206
209
  - `✅` — the work is done, the tests are green, and the verdict was acted on.
207
210
  - `⚠️` — done and green, with something worth knowing — an after-land command
208
- that failed, for one. `Notes` carries what the after-land commands ran, or
209
- where they stopped; nothing about them when none are configured.
211
+ that failed, for one. `Notes` carries what the after-land commands ran and
212
+ skipped, or where they stopped; nothing about them when none are configured.
210
213
  - `❌` — the tests are red, or the land failed part-way. Quote the failure and
211
214
  say what is standing.
212
215
  - `⏸` — refused before acting: no name given, the name is already a spec, the
@@ -527,7 +527,9 @@ underneath a reader when detection flipped mid-session.
527
527
 
528
528
  So: **relay all three tier lines, every time.** Any `also:` lines sit under
529
529
  `network` — the other addresses this machine has, offered because the
530
- best-guess one can be wrong — so pass them on rather than editing them out.
530
+ best-guess one can be wrong — so pass them on rather than editing them out: in
531
+ the banner they are indented sub-bullets under **network**, labels
532
+ (`(tailnet)`) included, exactly as `.claude/rules/spec-reports.md` shows.
531
533
 
532
534
  **Never read an environment variable to decide anything about the offer** — not
533
535
  `SSH_CONNECTION`, not `CLAUDE_CODE_*`, not a tty check. There is nothing left
@@ -169,8 +169,8 @@ the shape; this section carries only what is specific here.
169
169
  **Fields:** `Tracker` · `Spec` · `Tests` · `Notes` · `Landed` · `Worktree` ·
170
170
  `Follow-ups` · `Next`
171
171
 
172
- `Notes` carries the after-land commands step 6 ran, and where — or, on a
173
- failure, the command that failed and the ones that did not run. A project with
172
+ `Notes` carries the after-land commands step 6 ran, and where, and any it
173
+ skipped because the land matched no `when` — or, on a failure, the command that failed and the ones that did not run. A project with
174
174
  no `afterLand` says nothing about it.
175
175
 
176
176
  **Report this spec and no other.** A completion is the moment it is most
@@ -287,7 +287,10 @@ is finished — e.g. to run a later phase in CI or a shared test env? Use
287
287
  3. **Run the after-land commands.** Where the plan ends with a
288
288
  `then, in the primary checkout (<path>), run:` section — the project's
289
289
  `afterLand`, such as a data migration — run those commands in that
290
- directory, in order, after the fast-forward succeeds. **Also on the no-op**:
290
+ directory, in order, after the fast-forward succeeds. Run only the lines under that
291
+ heading; a `skipped (nothing in the land matched):` block lists conditional
292
+ entries this land did not need, and is information, never commands.
293
+ **Also on the no-op**:
291
294
  the engine prints them there deliberately, because a land made on another
292
295
  machine leaves them pending here. **Stop at the first non-zero exit** — a
293
296
  later command may depend on it — and carry on with the rest of the skill:
@@ -538,7 +538,9 @@ underneath a reader when detection flipped mid-session.
538
538
 
539
539
  So: **relay all three tier lines, every time.** Any `also:` lines sit under
540
540
  `network` — the other addresses this machine has, offered because the
541
- best-guess one can be wrong — so pass them on rather than editing them out.
541
+ best-guess one can be wrong — so pass them on rather than editing them out: in
542
+ the banner they are indented sub-bullets under **network**, labels
543
+ (`(tailnet)`) included, exactly as `.claude/rules/spec-reports.md` shows.
542
544
 
543
545
  **Never read an environment variable to decide anything about the offer** — not
544
546
  `SSH_CONNECTION`, not `CLAUDE_CODE_*`, not a tty check. There is nothing left
@@ -574,7 +574,9 @@ underneath a reader when detection flipped mid-session.
574
574
 
575
575
  So: **relay all three tier lines, every time.** Any `also:` lines sit under
576
576
  `network` — the other addresses this machine has, offered because the
577
- best-guess one can be wrong — so pass them on rather than editing them out.
577
+ best-guess one can be wrong — so pass them on rather than editing them out: in
578
+ the banner they are indented sub-bullets under **network**, labels
579
+ (`(tailnet)`) included, exactly as `.claude/rules/spec-reports.md` shows.
578
580
 
579
581
  **Never read an environment variable to decide anything about the offer** — not
580
582
  `SSH_CONNECTION`, not `CLAUDE_CODE_*`, not a tty check. There is nothing left
@@ -91,7 +91,9 @@ and continue — the branch has no commits base doesn't already have.
91
91
  `then, in the primary checkout (<path>), run:` section — the project's
92
92
  `afterLand`, such as a data migration — run those commands in that directory,
93
93
  in order, after the fast-forward and **before** the re-test below, which may
94
- need them. Run them on the no-op too: the engine prints them there because a
94
+ need them. Run only the lines under that heading; a
95
+ `skipped (nothing in the land matched):` block lists conditional entries this
96
+ land did not need, and is information, never commands. Run them on the no-op too: the engine prints them there because a
95
97
  land made elsewhere leaves them pending here.
96
98
  **Stop at the first non-zero exit**, and carry on with §5: a failure makes the run `⚠️`, naming the command
97
99
  that failed and the ones that did not run, and it **never undoes the land**.
@@ -129,8 +131,8 @@ the shape; this section carries only what is specific here.
129
131
 
130
132
  **Fields:** `Branch` · `Tests` · `Notes` · `Landed` · `Follow-ups` · `Next`
131
133
 
132
- `Notes` carries the after-land commands §4 ran, and where — or the one that
133
- failed and the ones that did not run. Nothing about it when none are
134
+ `Notes` carries the after-land commands §4 ran, and where, and any it
135
+ skipped because the land matched no `when` — or the one that failed and the ones that did not run. Nothing about it when none are
134
136
  configured.
135
137
 
136
138
  **No `Spec` field, deliberately.** This skill changes no status and moves no
@@ -20,6 +20,13 @@ if (!existsSync(join(__dirname, '..', 'src'))) {
20
20
  }
21
21
 
22
22
  const { run, HELP } = require('../src/cli.js')
23
+
24
+ // The provider's isolation defaults, registered beneath the project's own
25
+ // env.config.json so `spec-env stage` claims this provider's snapshot sidecar
26
+ // without a hand edit (see common src/env/config.js, setProviderEnvDefaults).
27
+ require('../src/env/config.js').setProviderEnvDefaults(
28
+ require('../src/vendor/jira/config.js').ENV_CONFIG_DEFAULTS,
29
+ )
23
30
  const {
24
31
  PROVIDER_COMMANDS,
25
32
  providerHelpSection,
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@skitterbyte/skitterspec-jira",
3
- "version": "1.0.0",
3
+ "version": "1.2.2",
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
@@ -88,6 +88,8 @@ const {
88
88
  collectReview,
89
89
  reviewTierStack,
90
90
  reviewTierLine,
91
+ isTailnetAddress,
92
+ tailnetLabel,
91
93
  renderReviewPage,
92
94
  renderReviewBlock,
93
95
  reviewOutPath,
@@ -165,7 +167,13 @@ const { planHotfixLand, planHotfixFinish } = require('./env/hotfix.js')
165
167
  const { runHotfixLand, describeStep: describeHotfixStep } = require('./env/hotfixland.js')
166
168
  const { planDev } = require('./env/dev.js')
167
169
  const { startProcess, stopProcess, waitHealthy, readPid, isAlive } = require('./env/supervise.js')
168
- const { renderRoutes, portsInUse, portsInUseOn, waitListening } = require('./env/proxy.js')
170
+ const {
171
+ renderRoutes,
172
+ portsHeld,
173
+ portsAnswering,
174
+ portsInUseOn,
175
+ waitListening,
176
+ } = require('./env/proxy.js')
169
177
  const {
170
178
  mintToken,
171
179
  servableSpecs,
@@ -185,7 +193,7 @@ const pkg = require('../package.json')
185
193
  // supersets the hand-off names both where both ship the command, and the one
186
194
  // that does where only one does.
187
195
  const PROVIDER_COMMANDS = {
188
- 'spec-sync': '@skitterbyte/skitterspec-linear or @skitterbyte/skitterspec-jira',
196
+ 'spec-sync': '@skitterbyte/skitterspec-linear, @skitterbyte/skitterspec-jira, @skitterbyte/skitterspec-github or @skitterbyte/skitterspec-azure-boards',
189
197
  'spec-sanitise': '@skitterbyte/skitterspec-linear',
190
198
  }
191
199
 
@@ -1914,6 +1922,7 @@ function specEnvIntegrate(dir, config, specArg) {
1914
1922
  aheadOfBase: cahead !== null && Number(cahead) > 0,
1915
1923
  checkoutPath: dir,
1916
1924
  onBranch: cgit(['rev-parse', '--abbrev-ref', 'HEAD']) === spec.branch,
1925
+ changedFiles: landRange(cgit, base, spec.branch),
1917
1926
  })
1918
1927
  if (cplan.blocked) {
1919
1928
  process.stdout.write(`spec-env integrate: blocked — ${cplan.reason}.\n`)
@@ -2011,6 +2020,7 @@ function specEnvIntegrate(dir, config, specArg) {
2011
2020
  base,
2012
2021
  aheadOfBase,
2013
2022
  mainRepoPath: dir,
2023
+ changedFiles: landRange(gitReader(dir), base, spec.branch),
2014
2024
  })
2015
2025
 
2016
2026
  if (plan.blocked) {
@@ -2037,13 +2047,47 @@ function specEnvIntegrate(dir, config, specArg) {
2037
2047
  process.stdout.write(out.join('\n') + '\n' + afterLandSection(plan.afterLand))
2038
2048
  }
2039
2049
 
2050
+ // The files a land brings into the base branch: `base...branch`, merge-base to
2051
+ // the branch tip. Read before the rebase runs, so it is the branch's own
2052
+ // changes — `base..branch` would also list what the base gained meanwhile and
2053
+ // over-match. A diff git would not answer is null: unknown, never empty.
2054
+ function landRange(git, base, branch) {
2055
+ const out = git(['diff', '--name-only', `${base}...${branch}`])
2056
+ if (out === null) return null
2057
+ return out.split('\n').map((l) => l.trim()).filter(Boolean)
2058
+ }
2059
+
2040
2060
  // The `afterLand` commands, as a section printed after a land plan — or after
2041
2061
  // integrate's already-landed line. Empty string when none apply, so a project
2042
- // without the key sees exactly the output it always has.
2062
+ // without the key sees exactly the output it always has, and one of plain
2063
+ // strings sees exactly what it saw before entries could be conditional.
2043
2064
  function afterLandSection(afterLand) {
2044
- if (!afterLand || !afterLand.commands || afterLand.commands.length === 0) return ''
2045
- const out = ['', ` then, in the primary checkout (${afterLand.cwd}), run (stop at the first failure):`]
2046
- for (const cmd of afterLand.commands) out.push(` ${cmd}`)
2065
+ if (!afterLand || !afterLand.entries || afterLand.entries.length === 0) return ''
2066
+ const entries = afterLand.entries
2067
+ const ran = entries.filter((e) => e.decision !== 'skipped')
2068
+ const skipped = entries.filter((e) => e.decision === 'skipped')
2069
+ const width = Math.max(...entries.map((e) => e.run.length))
2070
+ const out = ['']
2071
+ if (ran.length) {
2072
+ out.push(` then, in the primary checkout (${afterLand.cwd}), run (stop at the first failure):`)
2073
+ for (const e of ran) {
2074
+ // The reason is a shell COMMENT, not prose after a dash: these lines are
2075
+ // run as printed, and `cmd — path changed` would hand the command two
2076
+ // stray arguments.
2077
+ if (e.decision === 'matched') out.push(` ${e.run.padEnd(width)} # ${e.matched} changed`)
2078
+ else if (e.decision === 'unknown') out.push(` ${e.run.padEnd(width)} # range unknown`)
2079
+ else out.push(` ${e.run}`)
2080
+ }
2081
+ } else {
2082
+ out.push(` after-land, in the primary checkout (${afterLand.cwd}): nothing to run.`)
2083
+ }
2084
+ if (ran.some((e) => e.decision === 'unknown')) {
2085
+ out.push(" the land's changed files are unknown here, so the conditional entries run.")
2086
+ }
2087
+ if (skipped.length) {
2088
+ out.push(' skipped (nothing in the land matched):')
2089
+ for (const e of skipped) out.push(` ${e.run.padEnd(width)} # when ${e.when.join(', ')}`)
2090
+ }
2047
2091
  return out.join('\n') + '\n'
2048
2092
  }
2049
2093
 
@@ -2105,6 +2149,12 @@ function hotfixCarry(dir, spec, base, wtGit, released) {
2105
2149
  .map((l) => l.slice(2).trim()),
2106
2150
  )
2107
2151
  const commits = fixCommits.filter((sha) => !already.has(sha))
2152
+ // What main gains from the whole fix, for afterLand's `when` — taken from
2153
+ // every fix commit rather than the remaining ones, so a carry resumed after a
2154
+ // partial run still sees what the earlier picks changed. A commit git would
2155
+ // not describe makes the range unknown (null), which runs the conditional
2156
+ // entries rather than skipping them.
2157
+ const files = carryFiles(wtGit, fixCommits)
2108
2158
 
2109
2159
  // Which checkout, if any, has the base branch checked out.
2110
2160
  const list = git(['worktree', 'list', '--porcelain']) || ''
@@ -2117,14 +2167,24 @@ function hotfixCarry(dir, spec, base, wtGit, released) {
2117
2167
  let carry
2118
2168
  if (where) {
2119
2169
  const st = gitReader(where)(['status', '--porcelain'])
2120
- carry = { strategy: st ? 'dirty' : 'inplace', path: where, commits }
2170
+ carry = { strategy: st ? 'dirty' : 'inplace', path: where, commits, files }
2121
2171
  } else {
2122
2172
  const tmpPath = path.join(path.dirname(spec.worktreePath), `${spec.slug}-carry-${base}`)
2123
- carry = { strategy: 'worktree', path: dir, tmpPath, commits }
2173
+ carry = { strategy: 'worktree', path: dir, tmpPath, commits, files }
2124
2174
  }
2125
2175
  return { fixCommits, carry }
2126
2176
  }
2127
2177
 
2178
+ function carryFiles(git, commits) {
2179
+ const files = new Set()
2180
+ for (const sha of commits) {
2181
+ const out = git(['diff-tree', '--no-commit-id', '--name-only', '-r', sha])
2182
+ if (out === null) return null
2183
+ for (const line of out.split('\n')) if (line.trim()) files.add(line.trim())
2184
+ }
2185
+ return [...files]
2186
+ }
2187
+
2128
2188
  // `hotfix finish`: tear a landed hotfix down once its deploy is out. The guards
2129
2189
  // live in `planHotfixFinish`; this gathers the facts, refuses from inside the
2130
2190
  // worktree it is about to remove, and runs the two git commands itself.
@@ -4200,6 +4260,10 @@ async function specEnvReview(dir, config, specArg, flags, invokedFrom = dir) {
4200
4260
  // use, and the engine cannot know — that guess failed three separate ways
4201
4261
  // in one day. Now every tier is listed, labelled, and either a URL or the
4202
4262
  // one command that turns it on.
4263
+ // The runners-up print as `also:` lines inside the network tier's own
4264
+ // rendering — `reviewTierLine` carries them, which is what puts them
4265
+ // under `network:` rather than dangling after the stack (they used to
4266
+ // print below `remote:`, against the comment that placed them).
4203
4267
  reviewTierStack({
4204
4268
  served,
4205
4269
  fileUrl: reviewFileUrl(out),
@@ -4208,11 +4272,6 @@ async function specEnvReview(dir, config, specArg, flags, invokedFrom = dir) {
4208
4272
  })
4209
4273
  .map((t) => reviewTierLine(t) + '\n')
4210
4274
  .join('') +
4211
- // The runners-up sit UNDER the network tier, because that is what they are
4212
- // alternatives to — and virtual adapters are gone from them entirely.
4213
- (served && !served.loopback && (served.alternates || []).length
4214
- ? served.alternates.map((u) => ` also: ${u}\n`).join('')
4215
- : '') +
4216
4275
  // WHICH TIERS THE WAIT COVERS, once, next to the stack. `local` and
4217
4276
  // `network` are two doors into one room — the page POSTs to
4218
4277
  // `location.pathname`, so both reach this server and this pending store.
@@ -4514,8 +4573,14 @@ function lanAddresses(nets = require('node:os').networkInterfaces()) {
4514
4573
  * where the opposite hides the only address that works.
4515
4574
  */
4516
4575
  function offerableLanAddresses(nets = require('node:os').networkInterfaces()) {
4517
- return rankLanAddresses(nets)
4576
+ const ranked = rankLanAddresses(nets)
4577
+ // A tailnet address IS reachable from a phone off the LAN, but macOS puts it
4578
+ // on `utunN`, which the virtual filter drops. It is appended after every
4579
+ // other offerable address so the wifi one stays the best guess at home.
4580
+ const tailnet = ranked.filter((e) => VIRTUAL_IFACE.test(e.iface) && isTailnetAddress(e.address))
4581
+ return ranked
4518
4582
  .filter((e) => !VIRTUAL_IFACE.test(e.iface))
4583
+ .concat(tailnet)
4519
4584
  .map((e) => e.address)
4520
4585
  }
4521
4586
 
@@ -4988,7 +5053,7 @@ async function specEnvConnect(dir, config, specArg) {
4988
5053
  // Stop any proxy we already run (a previous connect), freeing the canonical
4989
5054
  // ports, then refuse if the primary checkout still holds one of them.
4990
5055
  await stopProcess(proxyProc, { rootDir: dir })
4991
- const busy = await portsInUse(routes.map((r) => r.frontPort), config.proxy.host)
5056
+ const busy = await portsHeld(routes.map((r) => r.frontPort), config.proxy.host)
4992
5057
  if (busy.length) {
4993
5058
  process.stdout.write(
4994
5059
  `spec-connect: canonical port(s) ${busy.join(', ')} are in use (your main dev server?).\n` +
@@ -5199,7 +5264,7 @@ async function specEnvLiveTake(dir, config, specArg, flags = {}) {
5199
5264
  const canonicalPorts = config.dev.map((d) => d.frontPort).filter((p) => typeof p === 'number')
5200
5265
  let serverUp = null
5201
5266
  if (canonicalPorts.length) {
5202
- const up = await portsInUse(canonicalPorts, config.proxy.host)
5267
+ const up = await portsAnswering(canonicalPorts, config.proxy.host)
5203
5268
  serverUp = up.length === canonicalPorts.length
5204
5269
  }
5205
5270
 
@@ -5892,6 +5957,7 @@ module.exports = {
5892
5957
  unknownCommand,
5893
5958
  rankLanAddresses,
5894
5959
  offerableLanAddresses,
5960
+ tailnetLabel,
5895
5961
  reviewTierStack,
5896
5962
  serveProcFor,
5897
5963
  serverScriptOk,