@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 +37 -0
- package/assets/core/env.config.md +49 -0
- package/assets/hooks/main-guard.cjs +1 -1
- package/assets/hooks/review-gate.cjs +1 -1
- package/assets/skills/no-spec/SKILL.md +6 -3
- package/assets/skills/spec-complete/SKILL.md +6 -3
- package/assets/skills/spec-to-main/SKILL.md +5 -3
- package/package.json +1 -1
- package/src/cli.js +68 -10
- package/src/env/config.js +64 -12
- package/src/env/glob.js +34 -0
- package/src/env/hotfix.js +4 -2
- package/src/env/integrate.js +52 -11
- package/src/env/live.js +1 -26
- package/src/env/proxy.js +33 -0
- package/src/init.js +3 -3
- package/src/vendor/linear/cli-sync.js +33 -283
- package/src/vendor/provider-kit/src/apply.js +10 -0
- package/src/vendor/provider-kit/src/assignment.js +277 -0
- package/src/vendor/provider-kit/src/http.js +30 -11
- package/src/vendor/provider-kit/src/released.js +56 -13
- package/src/vendor/provider-kit/src/releases.js +380 -0
- package/src/vendor/sync-core/index.js +2 -1
- package/src/vendor/sync-core/src/compare.js +32 -0
- package/src/vendor/sync-core/src/normalize.js +10 -1
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.
|
|
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
|
|
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
|
|
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.
|
|
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
|
|
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
|
|
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.
|
|
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 {
|
|
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-
|
|
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.
|
|
2045
|
-
const
|
|
2046
|
-
|
|
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
|
|
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
|
|
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
|
|
26
|
-
* // after `git worktree add` (e.g. install
|
|
27
|
-
*
|
|
28
|
-
* //
|
|
29
|
-
*
|
|
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.
|
|
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
|
|
530
|
-
|
|
531
|
-
|
|
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
|
-
|
|
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 =
|
|
620
|
+
base.afterLand = normalizeAfterLand(parsed.afterLand, base.setupTriggers)
|
|
569
621
|
}
|
|
570
622
|
|
|
571
623
|
if (Array.isArray(parsed.dev)) {
|
package/src/env/glob.js
ADDED
|
@@ -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
|
-
|
|
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 }
|
package/src/env/integrate.js
CHANGED
|
@@ -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
|
-
|
|
118
|
-
|
|
119
|
-
|
|
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 }
|