@skitterbyte/skitterspec-linear 19.3.0 → 19.5.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 (71) hide show
  1. package/assets/claude-md-section.md +20 -1
  2. package/assets/core/SETUP.md +5 -0
  3. package/assets/core/env.config.json.example +1 -0
  4. package/assets/core/env.config.md +143 -8
  5. package/assets/core/linear.config.json.example +2 -2
  6. package/assets/core/linear.config.md +49 -16
  7. package/assets/hooks/main-guard.cjs +40 -6
  8. package/assets/hooks/review-gate.cjs +42 -7
  9. package/assets/rules/commit-trailers.md +24 -1
  10. package/assets/rules/spec-planning.md +81 -18
  11. package/assets/rules/spec-reports.md +1 -1
  12. package/assets/skills/spec/SKILL.md +55 -2
  13. package/assets/skills/spec-bug/SKILL.md +36 -3
  14. package/assets/skills/spec-cancel/SKILL.md +37 -0
  15. package/assets/skills/spec-claim/SKILL.md +41 -2
  16. package/assets/skills/spec-complete/SKILL.md +115 -0
  17. package/assets/skills/spec-hotfix/SKILL.md +51 -4
  18. package/assets/skills/spec-incident/SKILL.md +22 -0
  19. package/assets/skills/spec-linear-setup/SKILL.md +23 -1
  20. package/assets/skills/spec-next/SKILL.md +12 -5
  21. package/assets/skills/spec-push/SKILL.md +22 -0
  22. package/assets/skills/spec-review/SKILL.md +34 -0
  23. package/assets/skills/spec-start/SKILL.md +50 -3
  24. package/assets/skills/spec-status/SKILL.md +18 -3
  25. package/assets/skills/spec-sync/SKILL.md +1 -0
  26. package/assets/skills/spec-to-main/SKILL.md +47 -1
  27. package/package.json +1 -1
  28. package/src/cli.js +1188 -79
  29. package/src/env/base.js +104 -0
  30. package/src/env/bootstrap.js +22 -3
  31. package/src/env/classify.js +12 -4
  32. package/src/env/config.js +77 -5
  33. package/src/env/disposition.js +62 -0
  34. package/src/env/handoff.js +81 -0
  35. package/src/env/host.js +262 -0
  36. package/src/env/hotfix.js +237 -9
  37. package/src/env/hotfixland.js +105 -10
  38. package/src/env/inflight.js +98 -0
  39. package/src/env/integrate.js +136 -9
  40. package/src/env/live.js +8 -7
  41. package/src/env/mainguard.js +20 -5
  42. package/src/env/phases.js +28 -0
  43. package/src/env/project.js +223 -0
  44. package/src/env/provision.js +30 -8
  45. package/src/env/resolve.js +147 -25
  46. package/src/env/review.js +21 -7
  47. package/src/env/reviewers.js +7 -10
  48. package/src/env/serve.js +27 -11
  49. package/src/env/specstate.js +101 -0
  50. package/src/env/supervise.js +15 -2
  51. package/src/env/teardown.js +46 -3
  52. package/src/init.js +49 -9
  53. package/src/vendor/linear/cli-sanitise.js +8 -3
  54. package/src/vendor/linear/cli-sync.js +64 -10
  55. package/src/vendor/linear/config.js +27 -21
  56. package/src/vendor/linear/doctor.js +2 -0
  57. package/src/vendor/provider-kit/index.js +4 -0
  58. package/src/vendor/provider-kit/src/apply.js +58 -6
  59. package/src/vendor/provider-kit/src/assignment.js +78 -1
  60. package/src/vendor/provider-kit/src/config.js +34 -1
  61. package/src/vendor/provider-kit/src/credentials.js +7 -2
  62. package/src/vendor/provider-kit/src/list-rows.js +35 -11
  63. package/src/vendor/provider-kit/src/released.js +48 -4
  64. package/src/vendor/provider-kit/src/specs.js +18 -7
  65. package/src/vendor/provider-kit/src/splice.js +64 -0
  66. package/src/vendor/provider-kit/src/status.js +137 -0
  67. package/src/vendor/sync-core/index.js +14 -1
  68. package/src/vendor/sync-core/src/compare.js +81 -6
  69. package/src/vendor/sync-core/src/normalize.js +50 -7
  70. package/src/vendor/sync-core/src/push.js +65 -5
  71. package/src/vendor/sync-core/src/summary.js +257 -0
@@ -0,0 +1,262 @@
1
+ 'use strict'
2
+
3
+ /**
4
+ * Host adapter — the one place skitterspec talks to a PR host.
5
+ *
6
+ * PR mode (`land.strategy: "pr"`) needs two things git alone cannot answer once
7
+ * a host merges by squash or rebase: *is the PR for this branch merged?* (the
8
+ * ancestry test goes false forever under a rewritten merge) and *what command
9
+ * opens / readies / abandons a PR here?* Both are answered from the remote URL
10
+ * — `dev.azure.com` / `visualstudio.com` → the `az` CLI, `github.com` → `gh` —
11
+ * and never from extra config: the URL is the one place the host is already
12
+ * written down.
13
+ *
14
+ * Everything here is pure except `prFor`, which takes an injected `exec` so the
15
+ * CLI supplies a real subprocess and tests supply a fake. Every failure shape —
16
+ * unknown host, missing CLI, non-zero exit, no network, unparseable output —
17
+ * returns `state: "cannot-tell"` and says nothing: an absence is not evidence,
18
+ * and the callers route cannot-tell to inaction
19
+ * (`.claude/rules/negative-checks.md` rule 4).
20
+ */
21
+
22
+ /**
23
+ * Parse a git remote URL into { host, org, project, repo, orgUrl }.
24
+ *
25
+ * host: 'github' | 'azure' | null (null = no adapter; callers degrade to
26
+ * ancestry + cannot-tell). `project` is Azure-only. `orgUrl` is the
27
+ * `--organization` value the az CLI wants, composed as dev.azure.com even for
28
+ * a legacy visualstudio.com remote — Azure serves both.
29
+ *
30
+ * WHAT WOULD FOOL THIS: a GitHub Enterprise or Azure DevOps Server install on
31
+ * its own domain parses to host null. That is the degrade-to-ancestry path by
32
+ * design — guessing a host from an unrecognised domain risks running the wrong
33
+ * CLI against someone's internal URL.
34
+ */
35
+ function parseRemote(url) {
36
+ const none = { host: null, org: null, project: null, repo: null, orgUrl: null }
37
+ if (typeof url !== 'string' || !url.trim()) return none
38
+ const u = url.trim()
39
+
40
+ // github: https://github.com/owner/repo(.git) · git@github.com:owner/repo(.git)
41
+ // · ssh://git@github.com/owner/repo(.git)
42
+ let m = u.match(/^(?:https:\/\/|ssh:\/\/git@|git@)github\.com[/:]([^/]+)\/([^/]+?)(?:\.git)?\/?$/)
43
+ if (m) return { host: 'github', org: m[1], project: null, repo: m[2], orgUrl: null }
44
+
45
+ // azure, modern: https://[org@]dev.azure.com/org/project/_git/repo
46
+ m = u.match(/^https:\/\/(?:[^@/]+@)?dev\.azure\.com\/([^/]+)\/([^/]+)\/_git\/([^/]+?)\/?$/)
47
+ if (m) {
48
+ return azure(m[1], m[2], m[3])
49
+ }
50
+ // azure, ssh: git@ssh.dev.azure.com:v3/org/project/repo
51
+ m = u.match(/^git@ssh\.dev\.azure\.com:v3\/([^/]+)\/([^/]+)\/([^/]+?)\/?$/)
52
+ if (m) return azure(m[1], m[2], m[3])
53
+ // azure, legacy: https://org.visualstudio.com/[DefaultCollection/]project/_git/repo
54
+ m = u.match(/^https:\/\/([^.@/]+)\.visualstudio\.com\/(?:DefaultCollection\/)?([^/]+)\/_git\/([^/]+?)\/?$/)
55
+ if (m) return azure(m[1], m[2], m[3])
56
+
57
+ return none
58
+ }
59
+
60
+ function azure(org, project, repo) {
61
+ return {
62
+ host: 'azure',
63
+ org: decode(org),
64
+ project: decode(project),
65
+ repo: decode(repo),
66
+ orgUrl: `https://dev.azure.com/${org}`,
67
+ }
68
+ }
69
+
70
+ // Azure project/repo names may carry spaces, which arrive %20-encoded in the
71
+ // remote URL and must be literal in the az flags.
72
+ function decode(part) {
73
+ try {
74
+ return decodeURIComponent(part)
75
+ } catch {
76
+ return part
77
+ }
78
+ }
79
+
80
+ // Shell-quote one az/gh flag value. Values come from a remote URL, so spaces
81
+ // (Azure project names) are the realistic case; a quote inside one is not a
82
+ // name Azure or GitHub accepts, but escape it anyway rather than truncate.
83
+ function q(value) {
84
+ return /[^A-Za-z0-9_\-./]/.test(value) ? `"${String(value).replace(/"/g, '\\"')}"` : value
85
+ }
86
+
87
+ /**
88
+ * Ask the host for the PR whose source is `branch`.
89
+ *
90
+ * `exec(file, args, opts)` must return `{ ok, stdout, stderr }` and never
91
+ * throw. Returns `{ state, id, url }` with state one of:
92
+ * merged · open · draft · none · cannot-tell
93
+ *
94
+ * "none" is a POSITIVE answer — the host replied and no (live) PR exists —
95
+ * where "cannot-tell" is the lookup itself failing. The two route differently
96
+ * (none can offer a create command; cannot-tell must not conclude anything),
97
+ * so a failure is never softened into none.
98
+ */
99
+ function prFor(remoteInfo, branch, exec, cwd) {
100
+ const cannot = { state: 'cannot-tell', id: null, url: null }
101
+ if (!remoteInfo || !remoteInfo.host) return cannot
102
+
103
+ if (remoteInfo.host === 'github') {
104
+ // Run in the repo (gh resolves owner/repo from the git remotes there).
105
+ const r = exec('gh', ['pr', 'view', branch, '--json', 'state,isDraft,number,url'], { cwd })
106
+ if (!r.ok) {
107
+ // gh exits 1 both for "no PR" and for real failures; only the former is
108
+ // an answer.
109
+ return /no pull requests? found/i.test(r.stderr || '') ? { state: 'none', id: null, url: null } : cannot
110
+ }
111
+ return githubPrState(r.stdout)
112
+ }
113
+
114
+ // azure
115
+ const r = exec(
116
+ 'az',
117
+ [
118
+ 'repos', 'pr', 'list',
119
+ '--organization', remoteInfo.orgUrl,
120
+ '--project', remoteInfo.project,
121
+ '--repository', remoteInfo.repo,
122
+ '--source-branch', branch,
123
+ '--status', 'all',
124
+ '--output', 'json',
125
+ ],
126
+ { cwd },
127
+ )
128
+ if (!r.ok) return cannot
129
+ return azurePrState(r.stdout)
130
+ }
131
+
132
+ // Map `gh pr view --json state,isDraft,number,url` output. Unparseable JSON is
133
+ // a cannot-tell, never a guess.
134
+ function githubPrState(stdout) {
135
+ let pr
136
+ try {
137
+ pr = JSON.parse(stdout)
138
+ } catch {
139
+ return { state: 'cannot-tell', id: null, url: null }
140
+ }
141
+ const id = pr.number != null ? String(pr.number) : null
142
+ const url = pr.url || null
143
+ if (pr.state === 'MERGED') return { state: 'merged', id, url }
144
+ if (pr.state === 'OPEN') return { state: pr.isDraft ? 'draft' : 'open', id, url }
145
+ if (pr.state === 'CLOSED') return { state: 'none', id, url }
146
+ return { state: 'cannot-tell', id, url }
147
+ }
148
+
149
+ // Map `az repos pr list --status all` output: the newest PR for the branch is
150
+ // the one whose state matters (an abandoned early attempt must not shadow the
151
+ // live PR). An empty list is a positive "none".
152
+ function azurePrState(stdout) {
153
+ let list
154
+ try {
155
+ list = JSON.parse(stdout)
156
+ } catch {
157
+ return { state: 'cannot-tell', id: null, url: null }
158
+ }
159
+ if (!Array.isArray(list)) return { state: 'cannot-tell', id: null, url: null }
160
+ if (list.length === 0) return { state: 'none', id: null, url: null }
161
+ const pr = list.reduce((a, b) => ((a.pullRequestId || 0) >= (b.pullRequestId || 0) ? a : b))
162
+ const id = pr.pullRequestId != null ? String(pr.pullRequestId) : null
163
+ const url = null // az's list payload carries no stable web URL; callers compose nothing
164
+ if (pr.status === 'completed') return { state: 'merged', id, url }
165
+ if (pr.status === 'active') return { state: pr.isDraft ? 'draft' : 'open', id, url }
166
+ if (pr.status === 'abandoned') return { state: 'none', id, url }
167
+ return { state: 'cannot-tell', id, url }
168
+ }
169
+
170
+ /**
171
+ * The command that opens a PR for `branch` → `base`. Null for an unknown host —
172
+ * the caller keeps its placeholder comment rather than inventing a CLI.
173
+ */
174
+ function prCreateCommand(remoteInfo, { branch, base, draft }) {
175
+ if (!remoteInfo || !remoteInfo.host) return null
176
+ if (remoteInfo.host === 'github') {
177
+ return `gh pr create --head ${branch} --base ${base} --fill${draft ? ' --draft' : ''}`
178
+ }
179
+ return (
180
+ `az repos pr create --organization ${remoteInfo.orgUrl} --project ${q(remoteInfo.project)} ` +
181
+ `--repository ${q(remoteInfo.repo)} --source-branch ${branch} --target-branch ${base}` +
182
+ (draft ? ' --draft true' : '')
183
+ )
184
+ }
185
+
186
+ // Flip a draft PR to ready. Azure addresses a PR by id, so without one there is
187
+ // no command to print — null, and the caller says nothing.
188
+ function prReadyCommand(remoteInfo, { branch, id }) {
189
+ if (!remoteInfo || !remoteInfo.host) return null
190
+ if (remoteInfo.host === 'github') return `gh pr ready ${branch}`
191
+ if (!id) return null
192
+ return `az repos pr update --organization ${remoteInfo.orgUrl} --id ${id} --draft false`
193
+ }
194
+
195
+ // Close/abandon the PR without merging (the /spec-cancel path).
196
+ function prAbandonCommand(remoteInfo, { branch, id }) {
197
+ if (!remoteInfo || !remoteInfo.host) return null
198
+ if (remoteInfo.host === 'github') return `gh pr close ${branch}`
199
+ if (!id) return null
200
+ return `az repos pr update --organization ${remoteInfo.orgUrl} --id ${id} --status abandoned`
201
+ }
202
+
203
+ /**
204
+ * The PR step of an integrate plan, selected from the host's answer about the
205
+ * branch. One function so the CLI and its tests cannot disagree with each
206
+ * other about what each state means:
207
+ *
208
+ * none / merged → the real create command (merged = that PR is history and
209
+ * new commits need a new one)
210
+ * open → a comment: the push updates it, a create would only error
211
+ * draft, wanted draft → the same comment (mid-spec re-push)
212
+ * draft, wanted ready → the ready command — or, where the host needs an id
213
+ * nobody has (Azure without one), a comment naming the manual
214
+ * step rather than nothing
215
+ * cannot-tell → null; the caller keeps its degraded placeholder
216
+ */
217
+ function prPlanCommand(remoteInfo, pr, { branch, base, draft }) {
218
+ if (!pr || pr.state === 'cannot-tell') return null
219
+ if (pr.state === 'none' || pr.state === 'merged') {
220
+ return prCreateCommand(remoteInfo, { branch, base, draft })
221
+ }
222
+ if (pr.state === 'open' || (pr.state === 'draft' && draft)) {
223
+ return `# PR ${pr.id ? `#${pr.id} ` : ''}already ${pr.state} — the push updates it`
224
+ }
225
+ // draft, and the caller wants it ready
226
+ return (
227
+ prReadyCommand(remoteInfo, { branch, id: pr.id })
228
+ || `# PR ${pr.id ? `#${pr.id} ` : ''}is a draft — mark it ready on the host`
229
+ )
230
+ }
231
+
232
+ /**
233
+ * The base a PR-mode view measures from: the REMOTE image of base when its
234
+ * remote-tracking ref exists in this clone, else the local name unchanged.
235
+ * Trunk configs pass through untouched, and nothing here fetches — a render
236
+ * must stay offline-safe, so a missing ref is the local fallback, never an
237
+ * error. `trimmed(argv)` is the caller's git reader (string | null).
238
+ *
239
+ * One helper because two copies of this selection (the server's render and the
240
+ * CLI's) must not disagree about which range one spec's page shows.
241
+ */
242
+ function preferRemoteBase(config, name, trimmed) {
243
+ if (!name) return name
244
+ if (!config || !config.land || config.land.strategy !== 'pr') return name
245
+ const remoteRef = `${config.land.remote || 'origin'}/${name}`
246
+ if (trimmed(['rev-parse', '--verify', '--quiet', `refs/remotes/${remoteRef}`])) {
247
+ return remoteRef
248
+ }
249
+ return name
250
+ }
251
+
252
+ module.exports = {
253
+ parseRemote,
254
+ preferRemoteBase,
255
+ prFor,
256
+ githubPrState,
257
+ azurePrState,
258
+ prCreateCommand,
259
+ prReadyCommand,
260
+ prAbandonCommand,
261
+ prPlanCommand,
262
+ }
package/src/env/hotfix.js CHANGED
@@ -22,6 +22,7 @@
22
22
 
23
23
  const path = require('node:path')
24
24
  const { afterLandFor, rangeOf } = require('./integrate.js')
25
+ const { shellPath } = require('./project.js')
25
26
 
26
27
  /**
27
28
  * Parse a semver-ish tag and return it with its PATCH bumped by one. Preserves any
@@ -227,15 +228,17 @@ function planHotfixLand(spec, config, ctx) {
227
228
  // The tag is the command's to choose and is unknown until it has run, so
228
229
  // there is nothing to check a collision against here — the command refuses
229
230
  // a tag that exists, and the runner refuses one a target also planned.
230
- commands.push(`(cd ${spec.worktreePath} && ${releaseWith})`)
231
- steps.push({ kind: 'release', via: 'command', command: releaseWith, cwd: spec.worktreePath })
231
+ // The release command is the project's, so it runs in the project folder.
232
+ const releaseCwd = spec.projectPath || spec.worktreePath
233
+ commands.push(`(cd ${shellPath(releaseCwd)} && ${releaseWith})`)
234
+ steps.push({ kind: 'release', via: 'command', command: releaseWith, cwd: releaseCwd })
232
235
  } else {
233
236
  prodTag = nextTag(baseRef, c.existingTags, bump)
234
237
  if (taken.has(prodTag)) {
235
238
  return block(`tag ${prodTag} already exists${freeTagHint(baseRef, c.existingTags, bump)}`)
236
239
  }
237
240
  taken.add(prodTag)
238
- commands.push(`git -C ${spec.worktreePath} tag ${prodTag}`)
241
+ commands.push(`git -C ${shellPath(spec.worktreePath)} tag ${prodTag}`)
239
242
  steps.push({
240
243
  kind: 'release',
241
244
  via: 'tag',
@@ -281,10 +284,10 @@ function planHotfixLand(spec, config, ctx) {
281
284
  const tmpBranch = `hotfix/${slug}`
282
285
  const tmpPath = path.join(wtRoot, slug)
283
286
  commands.push(
284
- `git worktree add ${tmpPath} -b ${tmpBranch} ${t}`,
285
- `git -C ${tmpPath} cherry-pick ${fixPick.join(' ')}`,
286
- `git -C ${tmpPath} tag ${tag}`,
287
- `git worktree remove ${tmpPath}`,
287
+ `git worktree add ${shellPath(tmpPath)} -b ${tmpBranch} ${t}`,
288
+ `git -C ${shellPath(tmpPath)} cherry-pick ${fixPick.join(' ')}`,
289
+ `git -C ${shellPath(tmpPath)} tag ${tag}`,
290
+ `git worktree remove ${shellPath(tmpPath)}`,
288
291
  `git branch -D ${tmpBranch}`,
289
292
  )
290
293
  const root = c.mainRepoPath
@@ -320,8 +323,8 @@ function planHotfixLand(spec, config, ctx) {
320
323
  const picks = carry.commits || [fixRange]
321
324
  commands.push(
322
325
  carry.strategy === 'worktree'
323
- ? `git worktree add ${carry.tmpPath} ${c.base} && git -C ${carry.tmpPath} cherry-pick ${picks.join(' ')}`
324
- : `git -C ${carry.path} cherry-pick ${picks.join(' ')}`,
326
+ ? `git worktree add ${shellPath(carry.tmpPath)} ${c.base} && git -C ${shellPath(carry.tmpPath)} cherry-pick ${picks.join(' ')}`
327
+ : `git -C ${shellPath(carry.path)} cherry-pick ${picks.join(' ')}`,
325
328
  )
326
329
  steps.push({
327
330
  kind: 'carry',
@@ -341,6 +344,229 @@ function planHotfixLand(spec, config, ctx) {
341
344
  return { ...result, commands, steps, afterLand, prodTag, targets, fixRange }
342
345
  }
343
346
 
347
+ /**
348
+ * Plan a BRANCH-BASED hotfix land (`Base version: <branch>@<sha>`, from
349
+ * `hotfix.releaseBranch`): the release line is a branch, so the fix lands ON it —
350
+ * by the project's `land.strategy` — rather than being tagged off a fork.
351
+ *
352
+ * ff rebase onto <remote>/<branch> → release (optional tag) → push the hotfix
353
+ * head to <branch>, then the tag. The push is the land, so it waits on
354
+ * consent exactly as the tag push does today.
355
+ * pr rebase → push the hotfix branch → open a READY pull request into
356
+ * <branch> → hold until the host merges it. The run that sees it merged
357
+ * tags <remote>/<branch> and pushes the tag. A hotfix PR is finished work,
358
+ * which is why it is never a draft.
359
+ *
360
+ * Every "already done" is a positive signal from git or the host, so a re-run
361
+ * picks up where the last one stopped: HEAD already on the remote branch is a
362
+ * landed ff, a host-reported merge is a landed PR, a recorded release still at
363
+ * HEAD is reused rather than re-cut.
364
+ *
365
+ * Once the land is confirmed the fix is CARRIED to the resolved base — the
366
+ * current rc under a rolling base — the same carry a tag-based hotfix makes to
367
+ * `main` under `ff`, and under `pr` a `carry/<slug>` branch with its own ready
368
+ * PR, because the rc may be protected too. `ctx.carry` describes it; null means
369
+ * there is nothing to carry (`cherryPickMain: false`, or the base IS the release
370
+ * branch).
371
+ *
372
+ * ctx: { dirty, remote, strategy, push, behind, onRelease, ahead,
373
+ * headOnRemote, pr: { state, id, url } | null, prCommand,
374
+ * lastTag, existingTags, released, tagPushed,
375
+ * carry: { base, strategy, path, tmpPath, commits, startRef?,
376
+ * carryBranch?, prCommand?, prState?, files? } | null }
377
+ * behind <remote>/<branch> is not an ancestor of HEAD — rebase first
378
+ * onRelease HEAD is an ancestor of <remote>/<branch> — an ff land is done
379
+ * lastTag the newest tag reachable from <remote>/<branch> (bump base)
380
+ */
381
+ function planBranchHotfixLand(spec, config, ctx) {
382
+ const c = ctx || {}
383
+ const v = spec.baseVersion || {}
384
+ const releaseBranch = v.branch
385
+ const remote = c.remote || 'origin'
386
+ const releaseRef = `${remote}/${releaseBranch}`
387
+ const branch = spec.branch
388
+ const hotfixCfg = (config && config.hotfix) || {}
389
+ const tagging = hotfixCfg.tag !== false
390
+ const releaseWith = String(hotfixCfg.releaseWith || '').trim()
391
+ const bump = hotfixCfg.bump || 'patch'
392
+ const strategy = c.strategy === 'pr' ? 'pr' : 'ff'
393
+ const cwd = spec.worktreePath
394
+ const result = {
395
+ blocked: false,
396
+ noop: false,
397
+ reason: null,
398
+ steps: [],
399
+ strategy,
400
+ releaseBranch,
401
+ releaseRef,
402
+ branch,
403
+ afterLand: afterLandFor(null),
404
+ }
405
+ const block = (reason) => ({ ...result, blocked: true, reason })
406
+
407
+ if (!releaseBranch) return block('spec has no branch-based Base version (<branch>@<sha>)')
408
+ if (c.dirty) return block('worktree has uncommitted changes — commit the completion first')
409
+ // A project's release command cuts its version commit and tag on the hotfix
410
+ // branch. Under a PR the commit rides the PR but the host's merge (squash,
411
+ // rebase) leaves the tag on a commit the release branch never has.
412
+ if (strategy === 'pr' && tagging && releaseWith) {
413
+ return block(
414
+ 'hotfix.releaseWith cannot release a branch-based hotfix landed by PR — the tag would ' +
415
+ 'point at a commit the merge rewrites; use the built-in tag, or set hotfix.tag false',
416
+ )
417
+ }
418
+
419
+ // The tag the built-in tagger cuts, bumped from the newest one the release
420
+ // branch already has. Computed lazily: only a run that cuts one needs it.
421
+ const builtInTag = () => {
422
+ if (!c.lastTag) return { refused: `no release tag on ${releaseBranch} to bump from — set hotfix.tag false, or hotfix.releaseWith` }
423
+ const tag = nextTag(c.lastTag, c.existingTags, bump)
424
+ if ((c.existingTags || []).includes(tag)) {
425
+ return { refused: `tag ${tag} already exists${freeTagHint(c.lastTag, c.existingTags, bump)}` }
426
+ }
427
+ return { tag }
428
+ }
429
+ const pushVia = (done) => (done ? 'remote' : c.push ? 'push' : 'hold')
430
+
431
+ // The carry, appended once the land is confirmed. Nothing left to pick — the
432
+ // base already has every fix commit — is no step at all, so a finished land
433
+ // reads as a no-op on re-run rather than as a carry that did nothing.
434
+ const carryStep = () => {
435
+ const k = c.carry
436
+ if (!k || !Array.isArray(k.commits) || !k.commits.length) return null
437
+ return {
438
+ kind: 'carry',
439
+ base: k.base,
440
+ strategy: k.strategy,
441
+ cwd: k.path,
442
+ root: k.root || k.path,
443
+ tmpPath: k.tmpPath || null,
444
+ commits: k.commits,
445
+ startRef: k.startRef || null,
446
+ carryBranch: k.carryBranch || null,
447
+ remote,
448
+ push: Boolean(c.push),
449
+ prCommand: k.prCommand || null,
450
+ prState: k.prState || null,
451
+ }
452
+ }
453
+ const withCarry = (steps) => {
454
+ const k = carryStep()
455
+ if (!k) return steps
456
+ result.afterLand = k.strategy === 'pr' ? afterLandFor(null) : afterLandFor(config, k.root, rangeOf({ changedFiles: c.carry.files }))
457
+ return [...steps, k]
458
+ }
459
+
460
+ if (strategy === 'ff') {
461
+ const landed = Boolean(c.onRelease)
462
+ // A recorded release is only good while it is still at HEAD; a rebase
463
+ // moves HEAD, so a run that must rebase cuts afresh.
464
+ const released = c.behind ? null : c.released || null
465
+ if (landed && (!tagging || (released && c.tagPushed))) {
466
+ const steps = withCarry([])
467
+ if (!steps.length) {
468
+ return { ...result, noop: true, reason: `${branch} is already on ${releaseRef} — nothing to land` }
469
+ }
470
+ return { ...result, steps }
471
+ }
472
+ const steps = []
473
+ if (c.behind && !landed) steps.push({ kind: 'rebase', onto: releaseRef, cwd })
474
+ if (tagging) {
475
+ if (released && released.tag) {
476
+ steps.push({ kind: 'release', via: 'recorded', tag: released.tag, release: released })
477
+ } else if (releaseWith) {
478
+ steps.push({ kind: 'release', via: 'command', command: releaseWith, cwd })
479
+ } else {
480
+ const t = builtInTag()
481
+ if (t.refused) return block(t.refused)
482
+ steps.push({ kind: 'release', via: 'tag', tag: t.tag, cwd, baseTag: c.lastTag, branch })
483
+ }
484
+ }
485
+ steps.push({
486
+ kind: 'push',
487
+ via: pushVia(landed && (!tagging || c.tagPushed)),
488
+ remote,
489
+ branch,
490
+ refs: landed ? [] : [`${branch}:${releaseBranch}`],
491
+ withTag: tagging,
492
+ cwd,
493
+ })
494
+ const all = withCarry(steps)
495
+ return { ...result, steps: all }
496
+ }
497
+
498
+ // pr
499
+ const merged = c.pr && c.pr.state === 'merged'
500
+ if (!merged) {
501
+ const steps = []
502
+ if (c.behind) steps.push({ kind: 'rebase', onto: releaseRef, cwd })
503
+ // --force-with-lease because the rebase rewrites a branch that may
504
+ // already be on the remote; -u so the first push sets the upstream.
505
+ steps.push({ kind: 'push', via: pushVia(c.headOnRemote && !c.behind), remote, branch, refs: [branch], withTag: false, force: true, cwd })
506
+ steps.push({ kind: 'pr', command: c.prCommand || null, state: c.pr ? c.pr.state : 'cannot-tell', id: c.pr ? c.pr.id : null, base: releaseBranch, cwd })
507
+ steps.push({ kind: 'wait', base: releaseBranch, pr: c.pr || null })
508
+ return { ...result, steps }
509
+ }
510
+ if (!tagging || (c.released && c.tagPushed)) {
511
+ const steps = withCarry([])
512
+ if (!steps.length) {
513
+ return { ...result, noop: true, reason: `the PR into ${releaseBranch} is merged — nothing to land` }
514
+ }
515
+ return { ...result, steps }
516
+ }
517
+ const steps = []
518
+ if (c.released && c.released.tag) {
519
+ steps.push({ kind: 'release', via: 'recorded', tag: c.released.tag, release: c.released })
520
+ } else {
521
+ const t = builtInTag()
522
+ if (t.refused) return block(t.refused)
523
+ // Tagged at the release branch as the host left it — the merge, whatever
524
+ // style made it — not at the hotfix branch, which a squash never reaches.
525
+ steps.push({ kind: 'release', via: 'tag', tag: t.tag, at: releaseRef, cwd, baseTag: c.lastTag, branch })
526
+ }
527
+ steps.push({ kind: 'push', via: pushVia(c.tagPushed), remote, branch, refs: [], withTag: true, cwd })
528
+ const all = withCarry(steps)
529
+ return { ...result, steps: all }
530
+ }
531
+
532
+ /**
533
+ * Plan `spec-env hotfix finish` for a BRANCH-BASED hotfix. The fix lives on the
534
+ * release branch once landed, so the tag-based guards (a tag at HEAD, the branch
535
+ * on the remote) are the wrong question; these ask whether the work reached
536
+ * both places it was going:
537
+ * - a clean tree;
538
+ * - the land confirmed — HEAD on the release branch (ff) or the host saying
539
+ * the PR merged (pr). Cannot-tell refuses: the branch may be the only copy;
540
+ * - the carry done — the base has every fix commit, its carry PR merged, or
541
+ * there was nothing to carry. Cannot-tell refuses for the same reason.
542
+ * Every failing one is named, and there is no `--force`.
543
+ *
544
+ * state: { dirty, landed: true|false|undefined, carried: true|false|undefined|'not-needed',
545
+ * releaseBranch, base, hasSlot, mainRepoPath }
546
+ */
547
+ function planBranchHotfixFinish(spec, state) {
548
+ const s = state || {}
549
+ const reasons = []
550
+ if (s.dirty) reasons.push('the worktree has uncommitted changes')
551
+ if (s.landed === undefined) reasons.push(`cannot tell whether the fix is on ${s.releaseBranch} — the host or remote did not answer`)
552
+ else if (!s.landed) reasons.push(`the fix is not on ${s.releaseBranch} yet — run \`spec-env hotfix land\` (and merge its PR)`)
553
+ if (s.carried === undefined) reasons.push(`cannot tell whether ${s.base} has the fix — the host or remote did not answer`)
554
+ else if (s.carried === false) reasons.push(`${s.base} does not have the fix yet — re-run \`spec-env hotfix land\` to carry it (and merge the carry PR)`)
555
+ if (s.hasSlot) reasons.push(`${spec.folder} holds a Docker stack — tear it down with \`spec-env down\``)
556
+ if (reasons.length) return { blocked: true, reasons, argvs: [] }
557
+ const root = s.mainRepoPath
558
+ return {
559
+ blocked: false,
560
+ reasons: [],
561
+ argvs: [
562
+ ['-C', root, 'worktree', 'remove', spec.worktreePath],
563
+ // -D: under a squash or rebase merge the branch is never an ancestor of
564
+ // anything, and the land above is what proved its commits are kept.
565
+ ['-C', root, 'branch', '-D', spec.branch],
566
+ ],
567
+ }
568
+ }
569
+
344
570
  /**
345
571
  * Plan `spec-env hotfix finish`: the teardown a hotfix waits for until its
346
572
  * deploy is out.
@@ -409,5 +635,7 @@ module.exports = {
409
635
  BUMPS,
410
636
  tagSlug,
411
637
  planHotfixLand,
638
+ planBranchHotfixLand,
639
+ planBranchHotfixFinish,
412
640
  planHotfixFinish,
413
641
  }