@skitterbyte/skitterspec-linear 18.1.1 → 18.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/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
@@ -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
  }
@@ -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
@@ -171,8 +171,8 @@ the shape; this section carries only what is specific here.
171
171
  **Fields:** `Tracker` · `Spec` · `Tests` · `Notes` · `Landed` · `Worktree` ·
172
172
  `Follow-ups` · `Next`
173
173
 
174
- `Notes` carries the after-land commands step 6 ran, and where — or, on a
175
- failure, the command that failed and the ones that did not run. A project with
174
+ `Notes` carries the after-land commands step 6 ran, and where, and any it
175
+ 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
176
176
  no `afterLand` says nothing about it.
177
177
 
178
178
  **Report this spec and no other.** A completion is the moment it is most
@@ -289,7 +289,10 @@ is finished — e.g. to run a later phase in CI or a shared test env? Use
289
289
  3. **Run the after-land commands.** Where the plan ends with a
290
290
  `then, in the primary checkout (<path>), run:` section — the project's
291
291
  `afterLand`, such as a data migration — run those commands in that
292
- directory, in order, after the fast-forward succeeds. **Also on the no-op**:
292
+ directory, in order, after the fast-forward succeeds. Run only the lines under that
293
+ heading; a `skipped (nothing in the land matched):` block lists conditional
294
+ entries this land did not need, and is information, never commands.
295
+ **Also on the no-op**:
293
296
  the engine prints them there deliberately, because a land made on another
294
297
  machine leaves them pending here. **Stop at the first non-zero exit** — a
295
298
  later command may depend on it — and carry on with the rest of the skill:
@@ -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
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@skitterbyte/skitterspec-linear",
3
- "version": "18.1.1",
3
+ "version": "18.2.0",
4
4
  "description": "Spec-driven development for Claude Code, with one-way Linear sync — a superset of @skitterbyte/skitterspec: the base filesystem workflow plus /spec-status · /spec-push and the spec-sync CLI. The repo is canonical; Linear is a generated mirror. Install this OR the base, not both.",
5
5
  "keywords": [
6
6
  "claude",
package/src/cli.js CHANGED
@@ -165,7 +165,13 @@ const { planHotfixLand, planHotfixFinish } = require('./env/hotfix.js')
165
165
  const { runHotfixLand, describeStep: describeHotfixStep } = require('./env/hotfixland.js')
166
166
  const { planDev } = require('./env/dev.js')
167
167
  const { startProcess, stopProcess, waitHealthy, readPid, isAlive } = require('./env/supervise.js')
168
- const { renderRoutes, portsInUse, portsInUseOn, waitListening } = require('./env/proxy.js')
168
+ const {
169
+ renderRoutes,
170
+ portsHeld,
171
+ portsAnswering,
172
+ portsInUseOn,
173
+ waitListening,
174
+ } = require('./env/proxy.js')
169
175
  const {
170
176
  mintToken,
171
177
  servableSpecs,
@@ -185,7 +191,7 @@ const pkg = require('../package.json')
185
191
  // supersets the hand-off names both where both ship the command, and the one
186
192
  // that does where only one does.
187
193
  const PROVIDER_COMMANDS = {
188
- 'spec-sync': '@skitterbyte/skitterspec-linear or @skitterbyte/skitterspec-jira',
194
+ 'spec-sync': '@skitterbyte/skitterspec-linear, @skitterbyte/skitterspec-jira, @skitterbyte/skitterspec-github or @skitterbyte/skitterspec-azure-boards',
189
195
  'spec-sanitise': '@skitterbyte/skitterspec-linear',
190
196
  }
191
197
 
@@ -1914,6 +1920,7 @@ function specEnvIntegrate(dir, config, specArg) {
1914
1920
  aheadOfBase: cahead !== null && Number(cahead) > 0,
1915
1921
  checkoutPath: dir,
1916
1922
  onBranch: cgit(['rev-parse', '--abbrev-ref', 'HEAD']) === spec.branch,
1923
+ changedFiles: landRange(cgit, base, spec.branch),
1917
1924
  })
1918
1925
  if (cplan.blocked) {
1919
1926
  process.stdout.write(`spec-env integrate: blocked — ${cplan.reason}.\n`)
@@ -2011,6 +2018,7 @@ function specEnvIntegrate(dir, config, specArg) {
2011
2018
  base,
2012
2019
  aheadOfBase,
2013
2020
  mainRepoPath: dir,
2021
+ changedFiles: landRange(gitReader(dir), base, spec.branch),
2014
2022
  })
2015
2023
 
2016
2024
  if (plan.blocked) {
@@ -2037,13 +2045,47 @@ function specEnvIntegrate(dir, config, specArg) {
2037
2045
  process.stdout.write(out.join('\n') + '\n' + afterLandSection(plan.afterLand))
2038
2046
  }
2039
2047
 
2048
+ // The files a land brings into the base branch: `base...branch`, merge-base to
2049
+ // the branch tip. Read before the rebase runs, so it is the branch's own
2050
+ // changes — `base..branch` would also list what the base gained meanwhile and
2051
+ // over-match. A diff git would not answer is null: unknown, never empty.
2052
+ function landRange(git, base, branch) {
2053
+ const out = git(['diff', '--name-only', `${base}...${branch}`])
2054
+ if (out === null) return null
2055
+ return out.split('\n').map((l) => l.trim()).filter(Boolean)
2056
+ }
2057
+
2040
2058
  // The `afterLand` commands, as a section printed after a land plan — or after
2041
2059
  // integrate's already-landed line. Empty string when none apply, so a project
2042
- // without the key sees exactly the output it always has.
2060
+ // without the key sees exactly the output it always has, and one of plain
2061
+ // strings sees exactly what it saw before entries could be conditional.
2043
2062
  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}`)
2063
+ if (!afterLand || !afterLand.entries || afterLand.entries.length === 0) return ''
2064
+ const entries = afterLand.entries
2065
+ const ran = entries.filter((e) => e.decision !== 'skipped')
2066
+ const skipped = entries.filter((e) => e.decision === 'skipped')
2067
+ const width = Math.max(...entries.map((e) => e.run.length))
2068
+ const out = ['']
2069
+ if (ran.length) {
2070
+ out.push(` then, in the primary checkout (${afterLand.cwd}), run (stop at the first failure):`)
2071
+ for (const e of ran) {
2072
+ // The reason is a shell COMMENT, not prose after a dash: these lines are
2073
+ // run as printed, and `cmd — path changed` would hand the command two
2074
+ // stray arguments.
2075
+ if (e.decision === 'matched') out.push(` ${e.run.padEnd(width)} # ${e.matched} changed`)
2076
+ else if (e.decision === 'unknown') out.push(` ${e.run.padEnd(width)} # range unknown`)
2077
+ else out.push(` ${e.run}`)
2078
+ }
2079
+ } else {
2080
+ out.push(` after-land, in the primary checkout (${afterLand.cwd}): nothing to run.`)
2081
+ }
2082
+ if (ran.some((e) => e.decision === 'unknown')) {
2083
+ out.push(" the land's changed files are unknown here, so the conditional entries run.")
2084
+ }
2085
+ if (skipped.length) {
2086
+ out.push(' skipped (nothing in the land matched):')
2087
+ for (const e of skipped) out.push(` ${e.run.padEnd(width)} # when ${e.when.join(', ')}`)
2088
+ }
2047
2089
  return out.join('\n') + '\n'
2048
2090
  }
2049
2091
 
@@ -2105,6 +2147,12 @@ function hotfixCarry(dir, spec, base, wtGit, released) {
2105
2147
  .map((l) => l.slice(2).trim()),
2106
2148
  )
2107
2149
  const commits = fixCommits.filter((sha) => !already.has(sha))
2150
+ // What main gains from the whole fix, for afterLand's `when` — taken from
2151
+ // every fix commit rather than the remaining ones, so a carry resumed after a
2152
+ // partial run still sees what the earlier picks changed. A commit git would
2153
+ // not describe makes the range unknown (null), which runs the conditional
2154
+ // entries rather than skipping them.
2155
+ const files = carryFiles(wtGit, fixCommits)
2108
2156
 
2109
2157
  // Which checkout, if any, has the base branch checked out.
2110
2158
  const list = git(['worktree', 'list', '--porcelain']) || ''
@@ -2117,14 +2165,24 @@ function hotfixCarry(dir, spec, base, wtGit, released) {
2117
2165
  let carry
2118
2166
  if (where) {
2119
2167
  const st = gitReader(where)(['status', '--porcelain'])
2120
- carry = { strategy: st ? 'dirty' : 'inplace', path: where, commits }
2168
+ carry = { strategy: st ? 'dirty' : 'inplace', path: where, commits, files }
2121
2169
  } else {
2122
2170
  const tmpPath = path.join(path.dirname(spec.worktreePath), `${spec.slug}-carry-${base}`)
2123
- carry = { strategy: 'worktree', path: dir, tmpPath, commits }
2171
+ carry = { strategy: 'worktree', path: dir, tmpPath, commits, files }
2124
2172
  }
2125
2173
  return { fixCommits, carry }
2126
2174
  }
2127
2175
 
2176
+ function carryFiles(git, commits) {
2177
+ const files = new Set()
2178
+ for (const sha of commits) {
2179
+ const out = git(['diff-tree', '--no-commit-id', '--name-only', '-r', sha])
2180
+ if (out === null) return null
2181
+ for (const line of out.split('\n')) if (line.trim()) files.add(line.trim())
2182
+ }
2183
+ return [...files]
2184
+ }
2185
+
2128
2186
  // `hotfix finish`: tear a landed hotfix down once its deploy is out. The guards
2129
2187
  // live in `planHotfixFinish`; this gathers the facts, refuses from inside the
2130
2188
  // worktree it is about to remove, and runs the two git commands itself.
@@ -4988,7 +5046,7 @@ async function specEnvConnect(dir, config, specArg) {
4988
5046
  // Stop any proxy we already run (a previous connect), freeing the canonical
4989
5047
  // ports, then refuse if the primary checkout still holds one of them.
4990
5048
  await stopProcess(proxyProc, { rootDir: dir })
4991
- const busy = await portsInUse(routes.map((r) => r.frontPort), config.proxy.host)
5049
+ const busy = await portsHeld(routes.map((r) => r.frontPort), config.proxy.host)
4992
5050
  if (busy.length) {
4993
5051
  process.stdout.write(
4994
5052
  `spec-connect: canonical port(s) ${busy.join(', ')} are in use (your main dev server?).\n` +
@@ -5199,7 +5257,7 @@ async function specEnvLiveTake(dir, config, specArg, flags = {}) {
5199
5257
  const canonicalPorts = config.dev.map((d) => d.frontPort).filter((p) => typeof p === 'number')
5200
5258
  let serverUp = null
5201
5259
  if (canonicalPorts.length) {
5202
- const up = await portsInUse(canonicalPorts, config.proxy.host)
5260
+ const up = await portsAnswering(canonicalPorts, config.proxy.host)
5203
5261
  serverUp = up.length === canonicalPorts.length
5204
5262
  }
5205
5263
 
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)) {
@@ -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
@@ -333,7 +333,9 @@ function planHotfixLand(spec, config, ctx) {
333
333
  commits: picks,
334
334
  })
335
335
  targets.push({ kind: 'main', base: c.base })
336
- 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 }))
337
339
  }
338
340
 
339
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 }