@skitterbyte/skitterspec-jira 2.14.0 → 2.16.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.
Files changed (43) hide show
  1. package/assets/claude-md-section.md +12 -0
  2. package/assets/core/SETUP.md +12 -12
  3. package/assets/core/env.config.md +25 -3
  4. package/assets/hooks/main-guard.cjs +73 -6
  5. package/assets/hooks/project-guard.cjs +80 -6
  6. package/assets/hooks/review-gate.cjs +73 -6
  7. package/assets/review/page.html +2 -1
  8. package/assets/rules/commit-trailers.md +2 -2
  9. package/assets/rules/offered-unblocks.md +22 -0
  10. package/assets/rules/spec-planning.md +12 -1
  11. package/assets/skills/no-spec/SKILL.md +5 -0
  12. package/assets/skills/spec/SKILL.md +20 -3
  13. package/assets/skills/spec-bug/SKILL.md +8 -2
  14. package/assets/skills/spec-complete/SKILL.md +28 -2
  15. package/assets/skills/spec-diff/SKILL.md +5 -0
  16. package/assets/skills/spec-hotfix/SKILL.md +8 -2
  17. package/assets/skills/spec-idea/SKILL.md +5 -0
  18. package/assets/skills/spec-init/SKILL.md +4 -2
  19. package/assets/skills/spec-next/SKILL.md +18 -0
  20. package/assets/skills/spec-park/SKILL.md +92 -0
  21. package/assets/skills/spec-resume/SKILL.md +153 -0
  22. package/assets/skills/spec-start/SKILL.md +6 -2
  23. package/assets/skills/spec-sync/SKILL.md +10 -10
  24. package/assets/skills/spec-to-main/SKILL.md +5 -1
  25. package/assets/skills/spec-todo/SKILL.md +5 -2
  26. package/package.json +1 -1
  27. package/src/cli.js +311 -15
  28. package/src/env/base.js +21 -5
  29. package/src/env/basepin.js +62 -0
  30. package/src/env/bootstrap.js +3 -1
  31. package/src/env/checks.js +49 -0
  32. package/src/env/config.js +48 -1
  33. package/src/env/hooks.js +53 -4
  34. package/src/env/provision.js +10 -2
  35. package/src/env/resolve.js +66 -13
  36. package/src/env/resume.js +234 -0
  37. package/src/env/review.js +4 -1
  38. package/src/env/serve.js +3 -0
  39. package/src/ideacmd.js +11 -1
  40. package/src/init.js +287 -49
  41. package/src/tada/todo.js +19 -4
  42. package/src/vendor/provider-kit/src/specs.js +46 -1
  43. package/src/vendor/sync-core/src/summary.js +10 -1
@@ -0,0 +1,62 @@
1
+ 'use strict'
2
+
3
+ /**
4
+ * The gap pin: a local record that someone accepted "use <fallback> as the base
5
+ * for now" while `baseBranchPattern` matched nothing — the gap between one
6
+ * release branch merging and the next being cut.
7
+ *
8
+ * It lives in `.spec-env/base-pin.json` in the primary checkout, gitignored, so
9
+ * accepting the offer changes nobody else's config. It records the pattern it
10
+ * was made under, and the resolver honours it only while that pattern has no
11
+ * match (`describeBaseBranch`), so cutting the next release branch is all it
12
+ * takes to retire it. Callers that see a match override it delete the file.
13
+ *
14
+ * Pure file I/O, no git: the resolver decides what a pin means.
15
+ */
16
+
17
+ const fs = require('node:fs')
18
+ const path = require('node:path')
19
+
20
+ // The state dir sits beside the registry file, e.g. `.spec-env` — the same
21
+ // convention `building.js` and `dev.js` use.
22
+ function pinPath(dir, config) {
23
+ const stateDir = path.posix.dirname((config && config.registry) || '.spec-env/registry.json') || '.spec-env'
24
+ return path.join(dir, stateDir, 'base-pin.json')
25
+ }
26
+
27
+ /**
28
+ * The pin as `{ base, pattern, pinnedAt }`, or null. An unreadable or malformed
29
+ * file is no pin: the resolver then refuses and offers again, which is the
30
+ * harmless direction — a pin read wrongly would decide a base nobody chose.
31
+ */
32
+ function readBasePin(dir, config) {
33
+ let parsed
34
+ try {
35
+ parsed = JSON.parse(fs.readFileSync(pinPath(dir, config), 'utf8'))
36
+ } catch {
37
+ return null
38
+ }
39
+ if (!parsed || typeof parsed.base !== 'string' || typeof parsed.pattern !== 'string') return null
40
+ if (!parsed.base.trim() || !parsed.pattern.trim()) return null
41
+ return { base: parsed.base, pattern: parsed.pattern, pinnedAt: typeof parsed.pinnedAt === 'string' ? parsed.pinnedAt : null }
42
+ }
43
+
44
+ function writeBasePin(dir, config, { base, pattern, pinnedAt = new Date().toISOString() }) {
45
+ const file = pinPath(dir, config)
46
+ fs.mkdirSync(path.dirname(file), { recursive: true })
47
+ const pin = { base, pattern, pinnedAt }
48
+ fs.writeFileSync(file, JSON.stringify(pin, null, 2) + '\n')
49
+ return pin
50
+ }
51
+
52
+ /** Remove the pin. True when there was one to remove. */
53
+ function clearBasePin(dir, config) {
54
+ try {
55
+ fs.unlinkSync(pinPath(dir, config))
56
+ return true
57
+ } catch {
58
+ return false
59
+ }
60
+ }
61
+
62
+ module.exports = { pinPath, readBasePin, writeBasePin, clearBasePin }
@@ -72,7 +72,9 @@ function runSeed(step, { cwd, mainRoot, fs, platform = process.platform }) {
72
72
  }
73
73
  fs.mkdirSync(path.dirname(dst), { recursive: true })
74
74
  if (step.mode === 'copy') {
75
- fs.copyFileSync(src, dst)
75
+ // A seed may be a directory (a local install seeds whole skill folders).
76
+ if (fs.statSync(src).isDirectory()) fs.cpSync(src, dst, { recursive: true })
77
+ else fs.copyFileSync(src, dst)
76
78
  return { outcome: 'seeded', line: `seeded ${step.file} → ${src}` }
77
79
  }
78
80
  // WINDOWS WITHOUT DEVELOPER MODE CANNOT CREATE A SYMLINK (EPERM), and a
@@ -0,0 +1,49 @@
1
+ 'use strict'
2
+
3
+ /**
4
+ * Completion checks — the project's own end-of-spec questions, run by
5
+ * `spec-env checks` for `/spec-complete` before it lands (`complete.checks`).
6
+ *
7
+ * ADVISORY, ALWAYS. A check reports and never refuses: a command that exits
8
+ * non-zero is `failed`, the next still runs, and the verb exits 0. A check that
9
+ * stopped a land would be the counting gate this workflow rejects, and what a
10
+ * check prints is a reason to look again, not proof of a fault.
11
+ *
12
+ * Every side effect goes through `io`, so the tests drive it with a fake spawn.
13
+ */
14
+
15
+ const { spawnSync } = require('node:child_process')
16
+
17
+ /**
18
+ * Run each command in `cwd`, in order, capturing its output.
19
+ * Returns `[{ command, status: 'ok' | 'failed', exit, output }]`.
20
+ */
21
+ function runChecks(commands, { cwd, spawn = spawnSync } = {}) {
22
+ const results = []
23
+ for (const command of commands) {
24
+ const res = spawn(command, { cwd, shell: true, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] })
25
+ const output = [res.stdout, res.stderr].filter(Boolean).join('').replace(/\s+$/, '')
26
+ if (res.error) {
27
+ results.push({ command, status: 'failed', exit: null, output: res.error.message })
28
+ continue
29
+ }
30
+ const exit = res.status === null ? null : res.status
31
+ results.push({ command, status: exit === 0 ? 'ok' : 'failed', exit, output })
32
+ }
33
+ return results
34
+ }
35
+
36
+ /** The text report: one block per command, its output indented beneath. */
37
+ function formatChecks(spec, results) {
38
+ if (!results.length) return `spec-env checks: ${spec} — no completion checks configured`
39
+ const failed = results.filter((r) => r.status === 'failed').length
40
+ const lines = [`spec-env checks: ${spec} — ${results.length} check(s), ${failed} failed (advisory — never blocks a land)`]
41
+ for (const r of results) {
42
+ const state = r.status === 'ok' ? 'ok' : `failed (${r.exit === null ? 'did not run' : `exit ${r.exit}`})`
43
+ lines.push('', ` ${state} · ${r.command}`)
44
+ for (const l of (r.output || '').split('\n')) if (l) lines.push(` ${l}`)
45
+ }
46
+ return lines.join('\n')
47
+ }
48
+
49
+ module.exports = { runChecks, formatChecks }
package/src/env/config.js CHANGED
@@ -44,6 +44,8 @@
44
44
  * baseBranch: "", // "" = auto-detect (origin/HEAD → main → master)
45
45
  * baseBranchPattern: "", // glob over remote branch names; newest match
46
46
  * // by commit date is the base (rolling release-candidate)
47
+ * baseBranchFallback: "", // offered as the base while the pattern matches
48
+ * // nothing; "" = the remote's default branch
47
49
  * land: { strategy, remote, draft, specDocs }, // how a branch lands:
48
50
  * // "ff" (default, trunk-based local fast-forward) or "pr"
49
51
  * // (push + pull request; base moves when the host merges)
@@ -65,6 +67,7 @@
65
67
  const { createHash } = require('node:crypto')
66
68
  const { existsSync, readFileSync, realpathSync } = require('node:fs')
67
69
  const { join, resolve, sep } = require('node:path')
70
+ const { readBasePin } = require('./basepin.js')
68
71
 
69
72
  const CONFIG_FILE = join('specs', '.core', 'env.config.json')
70
73
 
@@ -201,6 +204,11 @@ const DEFAULT_CONFIG = Object.freeze({
201
204
  // branch where a spec's tokens mean nothing. Normalised to `{ run, when }`,
202
205
  // `when` null for an always-run entry. Default: none.
203
206
  afterLand: Object.freeze([]),
207
+ // `/spec-complete` runs each `checks` command in the spec's worktree before it
208
+ // lands (`spec-env checks`) and relays the output. Advisory: a failed check is
209
+ // reported and never stops the land. Shell strings, run as written. Default:
210
+ // none.
211
+ complete: Object.freeze({ checks: Object.freeze([]) }),
204
212
  // Host dev servers started on the spec's port block by `spec-env dev up`.
205
213
  // Each: { name, command, portVar, health?, frontPort? }. Default: none.
206
214
  dev: Object.freeze([]),
@@ -227,6 +235,12 @@ const DEFAULT_CONFIG = Object.freeze({
227
235
  // candidate is all it takes to move every spec onto it. An explicit
228
236
  // `baseBranch` still wins. Empty = off, and resolution is exactly as before.
229
237
  baseBranchPattern: '',
238
+ // The base to offer while `baseBranchPattern` matches nothing — the gap
239
+ // between one release branch merging and the next being cut. Empty = the
240
+ // remote's default branch. Only ever used once someone accepts the offer,
241
+ // which writes a local pin (`env/basepin.js`); never consulted without a
242
+ // pattern.
243
+ baseBranchFallback: '',
230
244
  // How a finished branch reaches the base branch. `strategy: "ff"` (the
231
245
  // default) is trunk-based landing exactly as it has always been: rebase, then
232
246
  // a local `merge --ff-only` — nothing changes for an installed repo on
@@ -421,6 +435,7 @@ function defaults() {
421
435
  setup: [],
422
436
  setupTriggers: [],
423
437
  afterLand: [],
438
+ complete: { checks: [] },
424
439
  dev: [],
425
440
  proxy: { ...DEFAULT_CONFIG.proxy },
426
441
  registry: DEFAULT_CONFIG.registry,
@@ -428,6 +443,7 @@ function defaults() {
428
443
  spec: { companionPaths: [] },
429
444
  baseBranch: DEFAULT_CONFIG.baseBranch,
430
445
  baseBranchPattern: DEFAULT_CONFIG.baseBranchPattern,
446
+ baseBranchFallback: DEFAULT_CONFIG.baseBranchFallback,
431
447
  land: { ...DEFAULT_CONFIG.land },
432
448
  guards: { ...DEFAULT_CONFIG.guards },
433
449
  teardown: { ...DEFAULT_CONFIG.teardown },
@@ -687,6 +703,11 @@ function mergeConfig(base, parsed) {
687
703
  base.afterLand = normalizeAfterLand(parsed.afterLand, base.setupTriggers)
688
704
  }
689
705
 
706
+ // Same rule as `setup`: a stray entry is dropped, never thrown on.
707
+ if (isObject(parsed.complete) && Array.isArray(parsed.complete.checks)) {
708
+ base.complete.checks = parsed.complete.checks.filter((c) => typeof c === 'string' && c.trim())
709
+ }
710
+
690
711
  if (Array.isArray(parsed.dev)) {
691
712
  base.dev = normalizeDev(parsed.dev)
692
713
  }
@@ -712,6 +733,11 @@ function mergeConfig(base, parsed) {
712
733
  const pattern = parsed.baseBranchPattern.trim()
713
734
  if (pattern && !/\s/.test(pattern) && !pattern.includes('..')) base.baseBranchPattern = pattern
714
735
  }
736
+ // A branch name, so the same two characters can never be in it.
737
+ if (typeof parsed.baseBranchFallback === 'string') {
738
+ const fallback = parsed.baseBranchFallback.trim()
739
+ if (fallback && !/\s/.test(fallback) && !fallback.includes('..')) base.baseBranchFallback = fallback
740
+ }
715
741
 
716
742
  // Same treatment as `teardown.deleteRemoteBranch` below, for the same reason:
717
743
  // an unrecognised value falls through to the default rather than erroring or
@@ -944,6 +970,27 @@ function applyProviderSpecDocs(config, parsed, dir) {
944
970
  return config
945
971
  }
946
972
 
973
+ /**
974
+ * Attach the gap pin (`env/basepin.js`) to a loaded config as `gapPin`, so every
975
+ * caller that resolves the base from this config honours it with nothing passed
976
+ * — the main guard, the served pages and the dashboard included. Without a
977
+ * pattern there is no gap and nothing is read.
978
+ *
979
+ * Non-enumerable, because it is local state rather than configuration: it must
980
+ * not appear in a config dump, a deep-equal, or anything written back to disk.
981
+ * `dir` is the folder the config was read from — the primary checkout for
982
+ * every caller that anchors there first. One that does not finds no pin, which
983
+ * is the harmless direction: it refuses and offers again.
984
+ */
985
+ function withGapPin(config, dir) {
986
+ if (config.baseBranchPattern) {
987
+ // A getter, read on every resolve: the review server loads its config once
988
+ // and lives for days, and a pin taken after it started must still count.
989
+ Object.defineProperty(config, 'gapPin', { get: () => readBasePin(dir, config), enumerable: false })
990
+ }
991
+ return config
992
+ }
993
+
947
994
  function loadEnvConfig(dir = process.cwd()) {
948
995
  const base = defaults()
949
996
  const file = join(dir, CONFIG_FILE)
@@ -971,7 +1018,7 @@ function loadEnvConfig(dir = process.cwd()) {
971
1018
  }
972
1019
 
973
1020
  return {
974
- config: applyProviderSpecDocs(applyProviderEnvDefaults(mergeConfig(base, parsed), parsed), parsed, dir),
1021
+ config: withGapPin(applyProviderSpecDocs(applyProviderEnvDefaults(mergeConfig(base, parsed), parsed), parsed, dir), dir),
975
1022
  present: true,
976
1023
  unknown: collectUnknownKeys(parsed),
977
1024
  badReviewers: collectBadReviewers(parsed),
package/src/env/hooks.js CHANGED
@@ -88,8 +88,11 @@ function isObject(value) {
88
88
  return value !== null && typeof value === 'object' && !Array.isArray(value)
89
89
  }
90
90
 
91
- function settingsPath(dir) {
92
- return path.join(dir, '.claude', 'settings.json')
91
+ // A local install registers its hooks in the per-machine file, so a repo
92
+ // shared with people who do not use skitterspec gains nothing in its committed
93
+ // settings (`init --local`).
94
+ function settingsPath(dir, { local = false } = {}) {
95
+ return path.join(dir, '.claude', local ? 'settings.local.json' : 'settings.json')
93
96
  }
94
97
 
95
98
  function writeSettings(file, settings) {
@@ -181,8 +184,8 @@ function ensureOneHook(parsed, hook) {
181
184
  * already there did change the file, and reporting `present` for it would tell
182
185
  * an operator nothing happened when something did.
183
186
  */
184
- function ensureHooks(dir) {
185
- const file = settingsPath(dir)
187
+ function ensureHooks(dir, { local = false } = {}) {
188
+ const file = settingsPath(dir, { local })
186
189
 
187
190
  let raw
188
191
  try {
@@ -215,6 +218,51 @@ function ensureHooks(dir) {
215
218
  return { changed, reason: 'present' }
216
219
  }
217
220
 
221
+ /**
222
+ * Take OUR hooks out of the committed settings, for `init --local` converting a
223
+ * team install. Per hook OBJECT, never per matcher group: a group can hold ours
224
+ * beside the project's own (a secrets guard, a typecheck), and those stay. A
225
+ * group left with no hooks is dropped, then an empty `PreToolUse`, then an empty
226
+ * `hooks`. Every other key — and every other event — is untouched.
227
+ *
228
+ * Returns `{ removed, emptied, reason }`. `emptied` is true when nothing is left
229
+ * but `{}`: the caller deletes the file then, since a committed `{}` is noise.
230
+ * A missing file is `absent`; an unparseable one is `malformed` and untouched.
231
+ */
232
+ function removeHooks(dir) {
233
+ const file = settingsPath(dir)
234
+ let parsed
235
+ try {
236
+ parsed = JSON.parse(fs.readFileSync(file, 'utf-8'))
237
+ } catch (error) {
238
+ return { removed: 0, emptied: false, reason: error.code === 'ENOENT' ? 'absent' : 'malformed' }
239
+ }
240
+ if (!isObject(parsed)) return { removed: 0, emptied: false, reason: 'malformed' }
241
+ const pre = isObject(parsed.hooks) && Array.isArray(parsed.hooks.PreToolUse) ? parsed.hooks.PreToolUse : null
242
+ if (!pre) return { removed: 0, emptied: false, reason: 'none' }
243
+
244
+ let removed = 0
245
+ const ours = (h) => isObject(h) && typeof h.command === 'string' && HOOKS.some((k) => k.re.test(h.command))
246
+ const kept = []
247
+ for (const group of pre) {
248
+ if (!isObject(group) || !Array.isArray(group.hooks)) {
249
+ kept.push(group)
250
+ continue
251
+ }
252
+ const rest = group.hooks.filter((h) => !ours(h))
253
+ removed += group.hooks.length - rest.length
254
+ if (rest.length) kept.push(rest.length === group.hooks.length ? group : { ...group, hooks: rest })
255
+ }
256
+ if (!removed) return { removed: 0, emptied: false, reason: 'none' }
257
+
258
+ if (kept.length) parsed.hooks.PreToolUse = kept
259
+ else delete parsed.hooks.PreToolUse
260
+ if (!Object.keys(parsed.hooks).length) delete parsed.hooks
261
+ const emptied = !Object.keys(parsed).length
262
+ if (!emptied) writeSettings(file, parsed)
263
+ return { removed, emptied, reason: 'removed' }
264
+ }
265
+
218
266
  // The name this shipped under when there was one hook. Kept as an alias rather
219
267
  // than renamed away, because it is what an installed `init.js` from an older
220
268
  // version calls — and a rename that breaks an upgrade path is not a rename, it
@@ -223,6 +271,7 @@ const ensureReviewGateHook = ensureHooks
223
271
 
224
272
  module.exports = {
225
273
  ensureHooks,
274
+ removeHooks,
226
275
  ensureReviewGateHook,
227
276
  alreadyRegistered,
228
277
  registeredHooks,
@@ -255,7 +255,7 @@ function resolveStack(spec, config, { docs = false, composeFilePresent } = {}) {
255
255
  * filesystem fact arrives in `opts`.
256
256
  */
257
257
  function worktreeSteps(spec, offset, config, opts = {}) {
258
- const { docs = false, wantsDocker = false, composeFilePresent: compose } = opts
258
+ const { docs = false, wantsDocker = false, composeFilePresent: compose, localSeeds = [] } = opts
259
259
  const seed = config.seedFiles || { mode: 'symlink', files: [] }
260
260
  const mode = seed.mode === 'copy' ? 'copy' : 'symlink'
261
261
  const tokens = {
@@ -268,7 +268,15 @@ function worktreeSteps(spec, offset, config, opts = {}) {
268
268
  portOffset: offset === null || offset === undefined ? '' : String(offset),
269
269
  }
270
270
  const envFile = (config.docker && config.docker.envFile) || '.env'
271
- const steps = (seed.files || []).map((file) => ({ kind: 'seed', file, mode }))
271
+ // A local install (`init --local`) keeps skitterspec's own files out of git,
272
+ // so a fresh worktree has none of them; they are seeded first, implicitly from
273
+ // the manifest's scope — nothing in the committed config names them.
274
+ const seeded = new Set(seed.files || [])
275
+ const steps = [...localSeeds.filter((f) => !seeded.has(f)), ...(seed.files || [])].map((file) => ({
276
+ kind: 'seed',
277
+ file,
278
+ mode,
279
+ }))
272
280
  if (wantsDocker) {
273
281
  steps.push({ kind: 'envFile', file: envFile, projectName: spec.projectName, offset })
274
282
  }
@@ -439,15 +439,22 @@ function branchFor(spec, config) {
439
439
  /**
440
440
  * Thrown when `baseBranchPattern` is set and no remote branch matches it. A
441
441
  * refusal, never a fall-through: the default branch is exactly where a rolling
442
- * base must not land. `refused` carries the one-line reason; `pattern` the glob.
442
+ * base must not land unasked. `refused` carries the one-line reason; `pattern`
443
+ * the glob. `offer` is the way out the engine declares
444
+ * (`.claude/rules/offered-unblocks.md`) — pin the fallback for the gap — and is
445
+ * null when no fallback resolves, because guessing a base is worse than asking.
443
446
  */
444
447
  class BaseUnresolvedError extends Error {
445
- constructor(pattern) {
448
+ constructor(pattern, fallback = null) {
446
449
  const refused = `no branch matches ${pattern} — run spec-env base to fetch`
447
450
  super(refused)
448
451
  this.name = 'BaseUnresolvedError'
449
452
  this.refused = refused
450
453
  this.pattern = pattern
454
+ this.fallback = fallback
455
+ this.offer = fallback
456
+ ? { kind: 'satisfy', label: `Use ${fallback} as the base for now`, command: 'skitterspec spec-env base --use-fallback' }
457
+ : null
451
458
  }
452
459
  }
453
460
 
@@ -456,7 +463,8 @@ class BaseUnresolvedError extends Error {
456
463
  * onto). Precedence:
457
464
  * 1. `config.baseBranch` — explicit override
458
465
  * 2. `config.baseBranchPattern` — the newest remote branch matching it, by
459
- * committer date; no match throws `BaseUnresolvedError`
466
+ * committer date; no match takes a gap pin made under that same pattern
467
+ * (`env/basepin.js`), else throws `BaseUnresolvedError`
460
468
  * 3. `origin/HEAD` — the remote's default branch
461
469
  * 4. `main` if it exists locally
462
470
  * 5. `master` if it exists locally
@@ -471,30 +479,40 @@ class BaseUnresolvedError extends Error {
471
479
  * synchronous for every caller, the main-guard hook included. Fetching is left
472
480
  * to the commands that already talk to the remote.
473
481
  */
474
- function resolveBaseBranch(config, git) {
475
- const { base, refused } = describeBaseBranch(config, git)
482
+ function resolveBaseBranch(config, git, pin = (config && config.gapPin) || null) {
483
+ const { base, refused } = describeBaseBranch(config, git, pin)
476
484
  if (refused) throw refused
477
485
  return base
478
486
  }
479
487
 
480
488
  /**
481
489
  * The same resolution as `resolveBaseBranch`, returned as data with HOW it was
482
- * found — `pin` · `pattern` · `origin-head` · `local` · `fallback` — for the
483
- * one surface that reports it (`spec-env base`). A pattern with no match comes
484
- * back as `{ base: null, how: 'pattern', refused }` rather than thrown, so a
485
- * listing can still say what it saw.
490
+ * found — `pin` · `pattern` · `gap-pin` · `origin-head` · `local` · `fallback`
491
+ * — for the surfaces that report it. A pattern with no match comes back as
492
+ * `{ base: null, how: 'pattern', refused }` rather than thrown, so a listing
493
+ * can still say what it saw.
494
+ *
495
+ * `pin` is the gap pin as `readBasePin` returns it, or null. It defaults to
496
+ * the one `loadEnvConfig` attached as `config.gapPin`, so callers need not
497
+ * pass it; it is never read from disk here, so this stays pure. It is honoured only while the
498
+ * pattern has NO match and only when it was made under this same pattern: a
499
+ * match always wins, which is what makes the pin clear itself the moment the
500
+ * next release branch is cut. `stalePin` says a pin was passed and a match
501
+ * overrode it, so the caller can delete the file.
486
502
  */
487
- function describeBaseBranch(config, git) {
503
+ function describeBaseBranch(config, git, pin = (config && config.gapPin) || null) {
488
504
  const explicit = config && typeof config.baseBranch === 'string' && config.baseBranch.trim()
489
505
  if (explicit) return { base: explicit, how: 'pin' }
490
506
 
491
507
  const pattern = config && typeof config.baseBranchPattern === 'string' && config.baseBranchPattern.trim()
492
508
  if (pattern) {
493
509
  try {
494
- return { base: newestMatch(config, git, pattern), how: 'pattern' }
510
+ const base = newestMatch(config, git, pattern)
511
+ return pin ? { base, how: 'pattern', stalePin: true } : { base, how: 'pattern' }
495
512
  } catch (error) {
496
- if (error instanceof BaseUnresolvedError) return { base: null, how: 'pattern', refused: error }
497
- throw error
513
+ if (!(error instanceof BaseUnresolvedError)) throw error
514
+ if (pin && pin.pattern === pattern && pin.base) return { base: pin.base, how: 'gap-pin', pin }
515
+ return { base: null, how: 'pattern', refused: new BaseUnresolvedError(pattern, gapFallback(config, git)) }
498
516
  }
499
517
  }
500
518
 
@@ -518,6 +536,39 @@ function baseRemote(config) {
518
536
  return (config && config.land && typeof config.land.remote === 'string' && config.land.remote.trim()) || 'origin'
519
537
  }
520
538
 
539
+ /**
540
+ * The words that go beside the base wherever one is shown, when a gap pin
541
+ * chose it — `no 20??/Q? branch on origin — pinned for the gap` — else null.
542
+ * One function so the page, the review text and the plans cannot disagree.
543
+ */
544
+ function gapNote(config, git) {
545
+ const { how } = describeBaseBranch(config, git)
546
+ if (how !== 'gap-pin') return null
547
+ return `no ${config.baseBranchPattern.trim()} branch on ${baseRemote(config)} — pinned for the gap`
548
+ }
549
+
550
+ // The branch a gap pin would name: `baseBranchFallback`, else the remote's
551
+ // default branch. Null when neither can be read — and then no offer is made,
552
+ // because a guessed base is worse than a refusal.
553
+ //
554
+ // WHAT WOULD FOOL THIS: an unset `<remote>/HEAD`. A clone made with
555
+ // `git clone` has one, but a repo that added its remote by hand does not until
556
+ // `git remote set-head` runs, so a healthy repo can land here with no offer.
557
+ // That costs a plain refusal, never a wrong base.
558
+ function gapFallback(config, git) {
559
+ const remote = baseRemote(config)
560
+ const named = config && typeof config.baseBranchFallback === 'string' && config.baseBranchFallback.trim()
561
+ if (named) {
562
+ const exists =
563
+ git(['show-ref', '--verify', '--quiet', `refs/remotes/${remote}/${named}`]) !== null ||
564
+ git(['show-ref', '--verify', '--quiet', `refs/heads/${named}`]) !== null
565
+ return exists ? named : null
566
+ }
567
+ const head = git(['symbolic-ref', '--short', `refs/remotes/${remote}/HEAD`])
568
+ if (!head) return null
569
+ return head.startsWith(`${remote}/`) ? head.slice(remote.length + 1) : head
570
+ }
571
+
521
572
  function newestMatch(config, git, pattern) {
522
573
  const remote = baseRemote(config)
523
574
  const prefix = `refs/remotes/${remote}/`
@@ -834,6 +885,8 @@ module.exports = {
834
885
  allSpecs,
835
886
  resolveBaseBranch,
836
887
  describeBaseBranch,
888
+ gapFallback,
889
+ gapNote,
837
890
  baseRemote,
838
891
  BaseUnresolvedError,
839
892
  resolvePrimaryCheckout,