@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/src/env/config.js CHANGED
@@ -22,11 +22,16 @@
22
22
  * seedFiles:{ mode, files } | [ ".env", ... ], // gitignored files copied/
23
23
  * // symlinked from the main checkout into a fresh worktree before
24
24
  * // setup runs (mode: "symlink" default | "copy"); empty = none
25
- * setup: [ "cmd", ... ], // bootstrap commands run in the worktree right
26
- * // after `git worktree add` (e.g. install deps); empty = none
27
- * afterLand:[ "cmd", ... ], // commands run in the PRIMARY checkout after a
28
- * // land (integrate's ff, hotfix land's main cherry-pick), e.g. a
29
- * // data migration; literal, no token expansion; empty = none
25
+ * setup: [ "cmd" | { run, when }, ... ], // bootstrap commands run in
26
+ * // the worktree right after `git worktree add` (e.g. install
27
+ * // deps); `when` is ignored there — normalised to strings, with
28
+ * // the triggered entries also kept as `setupTriggers`
29
+ * afterLand:[ "cmd" | { run, when } | { setup: true }, ... ], // commands
30
+ * // run in the PRIMARY checkout after a land (integrate's ff,
31
+ * // hotfix land's main cherry-pick), e.g. a data migration;
32
+ * // `when` globs gate an entry on the land's changed files, and
33
+ * // `{ setup: true }` expands to `setupTriggers`; literal, no
34
+ * // token expansion; normalised to `{ run, when }`; empty = none
30
35
  * dev: [ { name, command, portVar, health?, frontPort? } ], // host dev
31
36
  * // servers started on the spec's port block (empty = none)
32
37
  * proxy: { enabled, host }, // bundled front-door proxy (spec-env connect)
@@ -169,11 +174,16 @@ const DEFAULT_CONFIG = Object.freeze({
169
174
  // `git worktree add` (before Docker/dev), on every provision. Array of shell
170
175
  // strings (e.g. "pnpm install"); {slug}/{branch}/… expand. Default: none.
171
176
  setup: Object.freeze([]),
177
+ // The `setup` entries that declared `when` globs, as `{ run, when }`. Derived
178
+ // at load, never configured directly: `afterLand`'s `{ setup: true }` expands
179
+ // to these, so a setup step can re-run after a land that changes its inputs.
180
+ setupTriggers: Object.freeze([]),
172
181
  // Commands run in the primary checkout after a land, printed by `spec-env
173
182
  // integrate` (including its already-landed no-op) and by `hotfix land` when
174
183
  // it cherry-picks onto the base branch. The skill runs them; the engine only
175
184
  // plans. Literal strings — no {slug}/{port} tokens, since they run on the base
176
- // branch where a spec's tokens mean nothing. Default: none.
185
+ // branch where a spec's tokens mean nothing. Normalised to `{ run, when }`,
186
+ // `when` null for an always-run entry. Default: none.
177
187
  afterLand: Object.freeze([]),
178
188
  // Host dev servers started on the spec's port block by `spec-env dev up`.
179
189
  // Each: { name, command, portVar, health?, frontPort? }. Default: none.
@@ -352,6 +362,7 @@ function defaults() {
352
362
  docker: { ...DEFAULT_CONFIG.docker },
353
363
  seedFiles: { mode: DEFAULT_CONFIG.seedFiles.mode, files: [] },
354
364
  setup: [],
365
+ setupTriggers: [],
355
366
  afterLand: [],
356
367
  dev: [],
357
368
  proxy: { ...DEFAULT_CONFIG.proxy },
@@ -524,11 +535,49 @@ function normalizeSeedFiles(parsed) {
524
535
  * stray entry can't crash provisioning.
525
536
  */
526
537
  function normalizeSetup(parsed) {
538
+ return normalizeCommands(parsed).map((e) => e.run)
539
+ }
540
+
541
+ /**
542
+ * Normalise a list of command entries into `{ run, when }`. A string is an
543
+ * always-run entry (`when: null`); `{ run, when }` keeps its trigger globs, with
544
+ * a string `when` coerced to a one-item list. An object whose `run` is blank, or
545
+ * whose `when` holds no usable glob, is dropped rather than demoted to
546
+ * always-run — a malformed trigger must not quietly widen into "every time".
547
+ */
548
+ function normalizeCommands(parsed) {
527
549
  const out = []
528
550
  for (const raw of parsed) {
529
- if (typeof raw !== 'string') continue
530
- const cmd = raw.trim()
531
- if (cmd) out.push(cmd)
551
+ if (typeof raw === 'string') {
552
+ const run = raw.trim()
553
+ if (run) out.push({ run, when: null })
554
+ continue
555
+ }
556
+ if (!isObject(raw) || typeof raw.run !== 'string') continue
557
+ const run = raw.run.trim()
558
+ if (!run) continue
559
+ if (raw.when === undefined) {
560
+ out.push({ run, when: null })
561
+ continue
562
+ }
563
+ const globs = typeof raw.when === 'string' ? [raw.when] : Array.isArray(raw.when) ? raw.when : []
564
+ const when = normalizeFileList(globs)
565
+ if (when.length) out.push({ run, when })
566
+ }
567
+ return out
568
+ }
569
+
570
+ // `afterLand` entries: `normalizeCommands`, plus `{ setup: true }` expanded in
571
+ // place to the triggered setup entries. With none declared it expands to
572
+ // nothing — the shorthand names a set, and an empty set is a valid one.
573
+ function normalizeAfterLand(parsed, setupTriggers) {
574
+ const out = []
575
+ for (const raw of parsed) {
576
+ if (isObject(raw) && raw.setup === true) {
577
+ for (const t of setupTriggers) out.push({ run: t.run, when: [...t.when] })
578
+ continue
579
+ }
580
+ out.push(...normalizeCommands([raw]))
532
581
  }
533
582
  return out
534
583
  }
@@ -560,12 +609,15 @@ function mergeConfig(base, parsed) {
560
609
  }
561
610
 
562
611
  if (Array.isArray(parsed.setup)) {
563
- base.setup = normalizeSetup(parsed.setup)
612
+ const entries = normalizeCommands(parsed.setup)
613
+ base.setup = entries.map((e) => e.run)
614
+ base.setupTriggers = entries.filter((e) => e.when)
564
615
  }
565
616
 
566
- // Same rule as `setup`: a stray entry is dropped, never thrown on.
617
+ // Same rule as `setup`: a stray entry is dropped, never thrown on. Read after
618
+ // `setup`, which `{ setup: true }` expands from.
567
619
  if (Array.isArray(parsed.afterLand)) {
568
- base.afterLand = normalizeSetup(parsed.afterLand)
620
+ base.afterLand = normalizeAfterLand(parsed.afterLand, base.setupTriggers)
569
621
  }
570
622
 
571
623
  if (Array.isArray(parsed.dev)) {
@@ -707,6 +759,48 @@ function mergeConfig(base, parsed) {
707
759
  * It is advisory in the strongest sense: nothing here acts on it, and a config
708
760
  * full of strays loads exactly as it always did.
709
761
  */
762
+ // The isolation keys a ticketing provider needs a project to declare — set
763
+ // once per process by a provider superset's bin, beneath whatever the
764
+ // project's own env.config.json says. They used to reach only the
765
+ // `env.config.json.example` composed at build time, which left every project
766
+ // that adopted a provider over an EXISTING isolation config (or skipped the
767
+ // example) with a `spec.companionPaths` that never claims the provider's
768
+ // snapshot sidecar — `spec-env stage` then classifies the spec's own
769
+ // `<baseDir>/<identifier>.base.json` as foreign and `/commit` leaves it
770
+ // behind. The base distribution registers nothing and behaves as before.
771
+ let providerEnvDefaults = null
772
+ function setProviderEnvDefaults(overrides) {
773
+ providerEnvDefaults = overrides || null
774
+ }
775
+
776
+ // Fill ONLY the keys the project's file does not mention: a key the file sets —
777
+ // including explicitly to '' or [] — is the project's decision and stands
778
+ // ("the two keys are one fix" in scripts/build-dist.test.js is the contract:
779
+ // blanking identifierField must keep disabling the companion expansion).
780
+ function applyProviderEnvDefaults(config, parsed) {
781
+ if (!providerEnvDefaults) return config
782
+ const d = providerEnvDefaults
783
+ const pBranch = parsed && typeof parsed.branch === 'object' && parsed.branch !== null ? parsed.branch : null
784
+ if (
785
+ d.branch &&
786
+ typeof d.branch.identifierField === 'string' &&
787
+ !(pBranch && 'identifierField' in pBranch) &&
788
+ !config.branch.identifierField
789
+ ) {
790
+ config.branch.identifierField = d.branch.identifierField
791
+ }
792
+ const pSpec = parsed && typeof parsed.spec === 'object' && parsed.spec !== null ? parsed.spec : null
793
+ if (
794
+ d.spec &&
795
+ Array.isArray(d.spec.companionPaths) &&
796
+ !(pSpec && 'companionPaths' in pSpec) &&
797
+ !config.spec.companionPaths.length
798
+ ) {
799
+ config.spec.companionPaths = [...d.spec.companionPaths]
800
+ }
801
+ return config
802
+ }
803
+
710
804
  function loadEnvConfig(dir = process.cwd()) {
711
805
  const base = defaults()
712
806
  const file = join(dir, CONFIG_FILE)
@@ -715,7 +809,9 @@ function loadEnvConfig(dir = process.cwd()) {
715
809
  try {
716
810
  raw = readFileSync(file, 'utf-8')
717
811
  } catch (error) {
718
- if (error.code === 'ENOENT') return { config: base, present: false, unknown: [], badReviewers: [] }
812
+ if (error.code === 'ENOENT') {
813
+ return { config: applyProviderEnvDefaults(base, null), present: false, unknown: [], badReviewers: [] }
814
+ }
719
815
  throw error
720
816
  }
721
817
 
@@ -727,7 +823,7 @@ function loadEnvConfig(dir = process.cwd()) {
727
823
  }
728
824
 
729
825
  return {
730
- config: mergeConfig(base, parsed),
826
+ config: applyProviderEnvDefaults(mergeConfig(base, parsed), parsed),
731
827
  present: true,
732
828
  unknown: collectUnknownKeys(parsed),
733
829
  badReviewers: collectBadReviewers(parsed),
@@ -736,6 +832,7 @@ function loadEnvConfig(dir = process.cwd()) {
736
832
 
737
833
  module.exports = {
738
834
  loadEnvConfig,
835
+ setProviderEnvDefaults,
739
836
  resolveServePort,
740
837
  derivedServePort,
741
838
  servePortRoot,
@@ -0,0 +1,34 @@
1
+ 'use strict'
2
+
3
+ /**
4
+ * Restricted glob matching for repo-relative paths, shared by the live-overlay
5
+ * migration check and the conditional `afterLand` entries. Zero-dependency.
6
+ */
7
+
8
+ // Translate a restricted glob into an anchored RegExp: `**` matches across path
9
+ // separators (with an optional trailing `/`), `*` matches within a segment, `?`
10
+ // a single non-separator char. Enough for repo-path globs, no dependency.
11
+ function globToRegExp(glob) {
12
+ let re = ''
13
+ for (let i = 0; i < glob.length; i++) {
14
+ const ch = glob[i]
15
+ if (ch === '*') {
16
+ if (glob[i + 1] === '*') {
17
+ re += '.*'
18
+ i++
19
+ if (glob[i + 1] === '/') i++ // consume the `/` in `**/`
20
+ } else {
21
+ re += '[^/]*'
22
+ }
23
+ } else if (ch === '?') {
24
+ re += '[^/]'
25
+ } else if ('.+^${}()|[]\\/'.includes(ch)) {
26
+ re += '\\' + ch
27
+ } else {
28
+ re += ch
29
+ }
30
+ }
31
+ return new RegExp('^' + re + '$')
32
+ }
33
+
34
+ module.exports = { globToRegExp }
package/src/env/hotfix.js CHANGED
@@ -21,7 +21,7 @@
21
21
  */
22
22
 
23
23
  const path = require('node:path')
24
- const { afterLandFor } = require('./integrate.js')
24
+ const { afterLandFor, rangeOf } = require('./integrate.js')
25
25
 
26
26
  /**
27
27
  * Parse a semver-ish tag and return it with its PATCH bumped by one. Preserves any
@@ -114,12 +114,38 @@ const BUMPS = ['patch', 'hotfix-suffix']
114
114
  // The tag `hotfix.bump` asks for. An unknown strategy throws rather than
115
115
  // falling back to `patch`: a typo there would otherwise cut the wrong release
116
116
  // line and say nothing.
117
+ //
118
+ // Under `patch`, a base that is ITSELF a `-hotfix.N` tag continues that line.
119
+ // Bumping its patch takes X.Y.(Z+1), a number the mainline owns: refused when
120
+ // the mainline already cut it, and minted silently when it had not. Only a
121
+ // parsed hotfix suffix routes here; an rc or any other suffix keeps the patch
122
+ // bump, so a base we cannot read as a hotfix line is never treated as one.
117
123
  function nextTag(baseTag, existingTags, bump = 'patch') {
118
- if (bump === 'patch') return bumpPatch(baseTag)
124
+ if (bump === 'patch') {
125
+ const base = parseTag(baseTag)
126
+ if (base && base.hotfix !== null) return nextHotfixTag(baseTag, existingTags)
127
+ return bumpPatch(baseTag)
128
+ }
119
129
  if (bump === 'hotfix-suffix') return nextHotfixTag(baseTag, existingTags)
120
130
  throw new Error(`unknown hotfix.bump "${bump}" — use one of: ${BUMPS.join(', ')}`)
121
131
  }
122
132
 
133
+ // What a collision refusal offers: the free tag on the same base's hotfix
134
+ // line, which is never taken by a mainline release. Never a deletion and never
135
+ // another base — the first destroys a released tag, the second forks from a
136
+ // version prod is not running. Empty where the suffix line cannot be derived
137
+ // (an rc base) or is already the strategy, so the refusal just names the tag.
138
+ function freeTagHint(baseTag, existingTags, bump) {
139
+ if (bump !== 'patch') return ''
140
+ let free
141
+ try {
142
+ free = nextHotfixTag(baseTag, existingTags)
143
+ } catch {
144
+ return ''
145
+ }
146
+ return ` — set hotfix.bump "hotfix-suffix" in env.config.json to cut ${free} instead`
147
+ }
148
+
123
149
  // A filesystem/branch-safe slug derived from a tag (`v30.2.1` → `v30-2-1`).
124
150
  function tagSlug(tag) {
125
151
  return String(tag)
@@ -206,7 +232,7 @@ function planHotfixLand(spec, config, ctx) {
206
232
  } else {
207
233
  prodTag = nextTag(baseRef, c.existingTags, bump)
208
234
  if (taken.has(prodTag)) {
209
- return block(`tag ${prodTag} already exists — bump the base version or delete the stale tag`)
235
+ return block(`tag ${prodTag} already exists${freeTagHint(baseRef, c.existingTags, bump)}`)
210
236
  }
211
237
  taken.add(prodTag)
212
238
  commands.push(`git -C ${spec.worktreePath} tag ${prodTag}`)
@@ -248,7 +274,7 @@ function planHotfixLand(spec, config, ctx) {
248
274
  // hotfix numbers rather than colliding on the same one.
249
275
  const tag = nextTag(t, [...taken], bump)
250
276
  if (taken.has(tag)) {
251
- return block(`tag ${tag} (for target ${t}) already exists — resolve it before landing`)
277
+ return block(`tag ${tag} (for target ${t}) already exists${freeTagHint(t, [...taken], bump)}`)
252
278
  }
253
279
  taken.add(tag)
254
280
  const slug = `${spec.slug}-onto-${tagSlug(t)}`
@@ -307,7 +333,9 @@ function planHotfixLand(spec, config, ctx) {
307
333
  commits: picks,
308
334
  })
309
335
  targets.push({ kind: 'main', base: c.base })
310
- afterLand = afterLandFor(config, c.mainRepoPath)
336
+ // The range is the files the carried fix touches — `carry.files`, read by
337
+ // the caller from the fix commits; absent or unreadable → unknown → run.
338
+ afterLand = afterLandFor(config, c.mainRepoPath, rangeOf({ changedFiles: carry.files }))
311
339
  }
312
340
 
313
341
  return { ...result, commands, steps, afterLand, prodTag, targets, fixRange }
@@ -1,5 +1,7 @@
1
1
  'use strict'
2
2
 
3
+ const { globToRegExp } = require('./glob.js')
4
+
3
5
  /**
4
6
  * Pure integrate planner for `spec-env integrate`.
5
7
  *
@@ -21,7 +23,9 @@
21
23
  * fast-forward. `planIntegrateCheckout` below covers that; the shape of what it
22
24
  * returns is identical so callers need no second code path.
23
25
  *
24
- * @param {object} ctx { worktreeState: { dirty }, base, aheadOfBase, mainRepoPath }
26
+ * @param {object} ctx { worktreeState: { dirty }, base, aheadOfBase, mainRepoPath,
27
+ * changedFiles } — `changedFiles` is what the land brings
28
+ * in (`base...branch`), or null when it could not be read
25
29
  * @returns {object} { blocked, noop, reason, commands, afterLand, base, branch }
26
30
  */
27
31
  function planIntegrate(spec, config, ctx) {
@@ -39,8 +43,9 @@ function planIntegrate(spec, config, ctx) {
39
43
  // Nothing on the branch that isn't already on base → already landed. The
40
44
  // after-land commands still apply: the land may have happened on another
41
45
  // machine or in an earlier session, leaving them pending in THIS checkout.
46
+ // That earlier land's range is unknown here, so the range is null.
42
47
  if (!aheadOfBase) {
43
- return { ...result, noop: true, afterLand: afterLandFor(config, mainRepoPath) }
48
+ return { ...result, noop: true, afterLand: afterLandFor(config, mainRepoPath, null) }
44
49
  }
45
50
 
46
51
  return {
@@ -49,7 +54,7 @@ function planIntegrate(spec, config, ctx) {
49
54
  `git -C ${spec.worktreePath} rebase ${base}`,
50
55
  `git -C ${mainRepoPath} merge --ff-only ${branch}`,
51
56
  ],
52
- afterLand: afterLandFor(config, mainRepoPath),
57
+ afterLand: afterLandFor(config, mainRepoPath, rangeOf(ctx)),
53
58
  }
54
59
  }
55
60
 
@@ -65,7 +70,7 @@ function planIntegrate(spec, config, ctx) {
65
70
  * another spec's branch") for a spec that is finished, and the operator would
66
71
  * have to know to switch back by hand.
67
72
  *
68
- * ctx: { dirty, base, aheadOfBase, checkoutPath, onBranch }
73
+ * ctx: { dirty, base, aheadOfBase, checkoutPath, onBranch, changedFiles }
69
74
  */
70
75
  function planIntegrateCheckout(spec, config, ctx) {
71
76
  const { dirty, base, aheadOfBase, checkoutPath, onBranch } = ctx || {}
@@ -80,7 +85,7 @@ function planIntegrateCheckout(spec, config, ctx) {
80
85
  // would refuse the very spec this just finished landing. /spec-complete calls
81
86
  // integrate again on exactly that state.
82
87
  if (!aheadOfBase) {
83
- return { ...result, noop: true, afterLand: afterLandFor(config, checkoutPath) }
88
+ return { ...result, noop: true, afterLand: afterLandFor(config, checkoutPath, null) }
84
89
  }
85
90
  if (dirty) {
86
91
  return {
@@ -107,20 +112,56 @@ function planIntegrateCheckout(spec, config, ctx) {
107
112
  `git -C ${checkoutPath} switch ${base}`,
108
113
  `git -C ${checkoutPath} merge --ff-only ${branch}`,
109
114
  ],
110
- afterLand: afterLandFor(config, checkoutPath),
115
+ afterLand: afterLandFor(config, checkoutPath, rangeOf(ctx)),
111
116
  }
112
117
  }
113
118
 
114
119
  // The after-land half of a plan: `config.afterLand`, to run in `cwd` (the
115
120
  // primary checkout, standing on base) once the land commands have succeeded.
116
121
  // A blocked plan carries the empty form — nothing landed, so nothing follows.
117
- function afterLandFor(config, cwd) {
118
- const commands = (config && Array.isArray(config.afterLand)) ? [...config.afterLand] : []
119
- return { cwd: commands.length ? cwd : null, commands }
122
+ //
123
+ // `range` is the files the land changes: a list (possibly empty) when known,
124
+ // null when it is not. Each entry gets a decision — `always` (no `when`),
125
+ // `matched` (with the first path that hit), `skipped`, or `unknown` — and
126
+ // `commands` is every entry but the skipped ones, in config order.
127
+ //
128
+ // AN UNKNOWN RANGE RUNS THE CONDITIONAL ENTRIES. A land made elsewhere, or a
129
+ // diff git would not answer, says nothing about what changed, and only one
130
+ // reading is harmless: a redundant generate costs seconds, a skipped one leaves
131
+ // the base red with nothing pointing at why (`.claude/rules/negative-checks.md`
132
+ // rule 4). An EMPTY known range is not unknown — a land whose commits touch no
133
+ // files is healthy, and it skips them.
134
+ function afterLandFor(config, cwd, range = null) {
135
+ const raw = (config && Array.isArray(config.afterLand)) ? config.afterLand : []
136
+ const entries = raw.map((e) => decide(asEntry(e), range))
137
+ const commands = entries.filter((e) => e.decision !== 'skipped').map((e) => e.run)
138
+ return { cwd: entries.length ? cwd : null, commands, entries, range }
139
+ }
140
+
141
+ function decide(entry, range) {
142
+ if (!entry.when) return { ...entry, decision: 'always', matched: null }
143
+ if (range === null) return { ...entry, decision: 'unknown', matched: null }
144
+ const res = entry.when.map(globToRegExp)
145
+ const matched = range.find((f) => res.some((r) => r.test(f)))
146
+ return matched === undefined
147
+ ? { ...entry, decision: 'skipped', matched: null }
148
+ : { ...entry, decision: 'matched', matched }
149
+ }
150
+
151
+ // Normalised config holds `{ run, when }`; a pure caller may still hand over
152
+ // the plain string an entry is written as.
153
+ function asEntry(entry) {
154
+ return typeof entry === 'string' ? { run: entry, when: null } : { run: entry.run, when: entry.when || null }
155
+ }
156
+
157
+ // `changedFiles` from a planner's ctx, with anything that is not a list read as
158
+ // unknown — a caller that did not supply it said nothing about the range.
159
+ function rangeOf(ctx) {
160
+ return Array.isArray(ctx && ctx.changedFiles) ? ctx.changedFiles : null
120
161
  }
121
162
 
122
163
  function noAfterLand() {
123
- return { cwd: null, commands: [] }
164
+ return { cwd: null, commands: [], entries: [], range: null }
124
165
  }
125
166
 
126
- module.exports = { planIntegrate, planIntegrateCheckout, afterLandFor }
167
+ module.exports = { planIntegrate, planIntegrateCheckout, afterLandFor, rangeOf }
package/src/env/live.js CHANGED
@@ -18,6 +18,7 @@
18
18
 
19
19
  const fs = require('node:fs')
20
20
  const path = require('node:path')
21
+ const { globToRegExp } = require('./glob.js')
21
22
 
22
23
  const REQUIRED = ['spec', 'branch', 'holder', 'heldSince', 'baseMainCommit']
23
24
 
@@ -179,32 +180,6 @@ function liveStateLine(live) {
179
180
 
180
181
  // --- stateful detection (glob matching) -----------------------------------
181
182
 
182
- // Translate a restricted glob into an anchored RegExp: `**` matches across path
183
- // separators (with an optional trailing `/`), `*` matches within a segment, `?`
184
- // a single non-separator char. Enough for migration-path globs, no dependency.
185
- function globToRegExp(glob) {
186
- let re = ''
187
- for (let i = 0; i < glob.length; i++) {
188
- const ch = glob[i]
189
- if (ch === '*') {
190
- if (glob[i + 1] === '*') {
191
- re += '.*'
192
- i++
193
- if (glob[i + 1] === '/') i++ // consume the `/` in `**/`
194
- } else {
195
- re += '[^/]*'
196
- }
197
- } else if (ch === '?') {
198
- re += '[^/]'
199
- } else if ('.+^${}()|[]\\/'.includes(ch)) {
200
- re += '\\' + ch
201
- } else {
202
- re += ch
203
- }
204
- }
205
- return new RegExp('^' + re + '$')
206
- }
207
-
208
183
  // True when any file path matches any of the migration globs. Empty patterns or
209
184
  // no files → false (nothing configured / nothing changed).
210
185
  function migrationsHit(files, patterns) {
package/src/env/proxy.js CHANGED
@@ -167,12 +167,45 @@ async function portsInUseOn(port, hosts, probe = portsInUse) {
167
167
  return [...new Set(busy)]
168
168
  }
169
169
 
170
+ /**
171
+ * Which of `ports` accept a connection on `host` — "is a dev server running?".
172
+ *
173
+ * CONNECTS, never binds. A bind probe on 127.0.0.1 SUCCEEDS on macOS beside a
174
+ * server listening on every address (Vite `host: true`, Fastify `0.0.0.0`),
175
+ * because BSD lets the two coexist, so it read a running phone-on-wifi dev
176
+ * server as absent. Linux refuses the second bind, which is why CI never saw
177
+ * it. A server that answers is running on any OS. What could still fool it: a
178
+ * server bound only to a non-loopback address, which `host` does not reach.
179
+ */
180
+ async function portsAnswering(ports, host = '127.0.0.1') {
181
+ const results = await Promise.all(ports.map((p) => checkListening(p, host)))
182
+ return ports.filter((_, i) => results[i])
183
+ }
184
+
185
+ /**
186
+ * Which of `ports` are taken for a new listener on `host` — "may the proxy
187
+ * have these?". Busy when the bind fails OR something already answers.
188
+ *
189
+ * The bind alone is not enough on macOS: beside a wildcard listener it
190
+ * succeeds, and the proxy would then own `localhost` while LAN clients still
191
+ * reach the old server — two apps behind one port number. The connect catches
192
+ * that. SEQUENTIAL, bind first: the bind probe's own listener is closed before
193
+ * the connect runs, so the connect can never find the probe itself.
194
+ */
195
+ async function portsHeld(ports, host = '127.0.0.1') {
196
+ const bound = await portsInUse(ports, host)
197
+ const answering = await portsAnswering(ports, host)
198
+ return ports.filter((p) => bound.includes(p) || answering.includes(p))
199
+ }
200
+
170
201
  module.exports = {
171
202
  renderRoutes,
172
203
  createRouteServer,
173
204
  startProxy,
174
205
  portsInUse,
175
206
  portsInUseOn,
207
+ portsAnswering,
208
+ portsHeld,
176
209
  waitListening,
177
210
  }
178
211
 
package/src/env/review.js CHANGED
@@ -715,7 +715,21 @@ function reviewTierStack({ served, fileUrl, publishedUrl, config }) {
715
715
  if (!config.review.allowNetwork) {
716
716
  tiers.push({ tier: 'network', off: true, enable: 'skitterspec spec-env review allow network' })
717
717
  } else if (served && !served.loopback && served.url) {
718
- tiers.push({ tier: 'network', url: served.url, alternates: served.alternates || [] })
718
+ // LABELLED HERE, not by the renderer: `--json`'s `tiers` is the stack a
719
+ // skill copies, and an unlabelled alternate made the `(tailnet)` suffix a
720
+ // fact only the text render knew — so the one link a reader off the wifi
721
+ // could open reached the JSON indistinguishable from a second LAN address.
722
+ tiers.push({
723
+ tier: 'network',
724
+ url: served.url,
725
+ alternates: (served.alternates || []).map((u) => {
726
+ let host = ''
727
+ try {
728
+ host = new URL(u).hostname
729
+ } catch {}
730
+ return isTailnetAddress(host) ? { url: u, label: 'tailnet' } : { url: u }
731
+ }),
732
+ })
719
733
  } else {
720
734
  // Permitted, but there is no address to offer — a machine with no network,
721
735
  // or a server that could not take one. Not a problem to report as an error.
@@ -738,13 +752,42 @@ function reviewTierStack({ served, fileUrl, publishedUrl, config }) {
738
752
  }
739
753
 
740
754
  // One tier as a line, padded so the labels form a column the eye can run down.
755
+ // A tier with alternates renders them as indented `also:` lines of its own —
756
+ // they are PART of the tier, which is what puts them under `network:` rather
757
+ // than dangling after the stack (they used to print below `remote:`, against
758
+ // the comment that placed them).
741
759
  function reviewTierLine(t) {
742
760
  const label = ` ${t.tier}:`.padEnd(11)
743
- if (t.url) return `${label}${t.url}${t.note ? ` (${t.note})` : ''}`
761
+ if (t.url) {
762
+ return [
763
+ `${label}${t.url}${t.note ? ` (${t.note})` : ''}`,
764
+ ...(t.alternates || []).map((a) => ` also: ${a.url}${a.label ? ` (${a.label})` : ''}`),
765
+ ].join('\n')
766
+ }
744
767
  if (t.off) return `${label}off — turn on with: ${t.enable}`
745
768
  return `${label}— (${t.note})`
746
769
  }
747
770
 
771
+ // 100.64.0.0/10 — the CGNAT range Tailscale assigns from.
772
+ //
773
+ // WHAT WOULD FOOL THIS: a carrier-grade NAT or another overlay network using
774
+ // the same range on a utun adapter is offered too. That costs one dud `also:`
775
+ // line, where filtering it hides the only link a reader off the wifi can open.
776
+ function isTailnetAddress(address) {
777
+ const m = /^100\.(\d+)\./.exec(address)
778
+ return !!m && Number(m[1]) >= 64 && Number(m[1]) <= 127
779
+ }
780
+
781
+ // The suffix on an `also:` line whose host is a tailnet address, so it reads
782
+ // apart from the LAN one — a reader off the wifi needs to know which to tap.
783
+ function tailnetLabel(url) {
784
+ let host = ''
785
+ try {
786
+ host = new URL(url).hostname
787
+ } catch {}
788
+ return isTailnetAddress(host) ? ' (tailnet)' : ''
789
+ }
790
+
748
791
 
749
792
  // The verdicts that COMMIT, and are therefore blocked by an open comment. One
750
793
  // list, so a fifth verdict cannot become a way around the single refusal this
@@ -2482,6 +2525,8 @@ module.exports = {
2482
2525
  surfacesFor,
2483
2526
  reviewTierStack,
2484
2527
  reviewTierLine,
2528
+ isTailnetAddress,
2529
+ tailnetLabel,
2485
2530
  COMMITTING,
2486
2531
  BUTTON_SETS,
2487
2532
  DEFAULT_BUTTON_SET,
package/src/init.js CHANGED
@@ -125,7 +125,7 @@ function detectPackageManager(dir) {
125
125
 
126
126
  // The bin names a distribution may expose. A provider superset ships its own
127
127
  // name alongside `skitterspec`, and either proves the engine is reachable.
128
- const ENGINE_BINS = ['skitterspec', 'skitterspec-linear', 'skitterspec-jira']
128
+ const ENGINE_BINS = ['skitterspec', 'skitterspec-linear', 'skitterspec-jira', 'skitterspec-github', 'skitterspec-azure-boards']
129
129
 
130
130
  function binNames() {
131
131
  return process.platform === 'win32'
@@ -914,8 +914,8 @@ function resync(dir, { force = false, claudeMd = true, diff = false } = {}) {
914
914
  // never delete spec content or active config (defense-in-depth — the manifest
915
915
  // never lists these, but a tampered/foreign entry must still be refused).
916
916
  const PROTECTED_SPEC_BUCKETS = ['backlog', 'in-progress', 'complete', 'cancelled']
917
- const PROTECTED_CONFIG = ['env.config.json', 'linear.config.json', 'jira.config.json']
918
- const PROTECTED_DIRS = ['linear-base', 'linear-backups', 'jira-base', 'jira-backups']
917
+ const PROTECTED_CONFIG = ['env.config.json', 'linear.config.json', 'jira.config.json', 'github.config.json', 'azure-boards.config.json']
918
+ const PROTECTED_DIRS = ['linear-base', 'linear-backups', 'jira-base', 'jira-backups', 'github-base', 'github-backups', 'azure-base', 'azure-backups']
919
919
 
920
920
  function assertSafeToDelete(relPath, managedSet) {
921
921
  const norm = relPath.split(path.sep).join('/')
@@ -49,6 +49,7 @@ const {
49
49
  stampSubIssueId,
50
50
  fieldsOf,
51
51
  remoteDescriptionEdited,
52
+ remoteSubIssueEdited,
52
53
  listPhaseFiles,
53
54
  } = require('../../sync-core')
54
55
  const { makeSpecHelpers } = require('./specs.js')
@@ -162,7 +163,16 @@ async function applyInner({ dir, config, snapshotDir, plan, adapter, ops, progre
162
163
  for (const s of projectionOf(snapshotDir, config).subIssues || []) {
163
164
  if (s.id != null) refById.set(String(s.id), s.ref)
164
165
  }
166
+ // A phase body edited on the tracker gets the same warning as the spec
167
+ // issue. The read is spent only where the snapshot recorded something to
168
+ // compare against, so an old snapshot costs no extra calls.
169
+ const base = readBase(dir, identifier, config)
165
170
  for (const sub of (plan.subIssues && plan.subIssues.update) || []) {
171
+ const streams = base && base.subIssueStreams
172
+ if (sub.goal != null && streams && streams[String(sub.id)]) {
173
+ const before = await adapter.readIssue(sub.id)
174
+ if (remoteSubIssueEdited(base, sub.id, before, config) === true) lines.push(ops.remoteEditedLine(sub.id))
175
+ }
166
176
  await ops.updateSubIssue(sub)
167
177
  result.subIssues[sub.ref || refById.get(String(sub.id)) || sub.id] = sub.id
168
178
  lines.push(` sub-issue updated: ${sub.id}`)