@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.
- package/assets/claude-md-section.md +20 -1
- package/assets/core/SETUP.md +5 -0
- package/assets/core/env.config.json.example +1 -0
- package/assets/core/env.config.md +143 -8
- package/assets/core/linear.config.json.example +2 -2
- package/assets/core/linear.config.md +49 -16
- package/assets/hooks/main-guard.cjs +40 -6
- package/assets/hooks/review-gate.cjs +42 -7
- package/assets/rules/commit-trailers.md +24 -1
- package/assets/rules/spec-planning.md +81 -18
- package/assets/rules/spec-reports.md +1 -1
- package/assets/skills/spec/SKILL.md +55 -2
- package/assets/skills/spec-bug/SKILL.md +36 -3
- package/assets/skills/spec-cancel/SKILL.md +37 -0
- package/assets/skills/spec-claim/SKILL.md +41 -2
- package/assets/skills/spec-complete/SKILL.md +115 -0
- package/assets/skills/spec-hotfix/SKILL.md +51 -4
- package/assets/skills/spec-incident/SKILL.md +22 -0
- package/assets/skills/spec-linear-setup/SKILL.md +23 -1
- package/assets/skills/spec-next/SKILL.md +12 -5
- package/assets/skills/spec-push/SKILL.md +22 -0
- package/assets/skills/spec-review/SKILL.md +34 -0
- package/assets/skills/spec-start/SKILL.md +50 -3
- package/assets/skills/spec-status/SKILL.md +18 -3
- package/assets/skills/spec-sync/SKILL.md +1 -0
- package/assets/skills/spec-to-main/SKILL.md +47 -1
- package/package.json +1 -1
- package/src/cli.js +1188 -79
- package/src/env/base.js +104 -0
- package/src/env/bootstrap.js +22 -3
- package/src/env/classify.js +12 -4
- package/src/env/config.js +77 -5
- package/src/env/disposition.js +62 -0
- package/src/env/handoff.js +81 -0
- package/src/env/host.js +262 -0
- package/src/env/hotfix.js +237 -9
- package/src/env/hotfixland.js +105 -10
- package/src/env/inflight.js +98 -0
- package/src/env/integrate.js +136 -9
- package/src/env/live.js +8 -7
- package/src/env/mainguard.js +20 -5
- package/src/env/phases.js +28 -0
- package/src/env/project.js +223 -0
- package/src/env/provision.js +30 -8
- package/src/env/resolve.js +147 -25
- package/src/env/review.js +21 -7
- package/src/env/reviewers.js +7 -10
- package/src/env/serve.js +27 -11
- package/src/env/specstate.js +101 -0
- package/src/env/supervise.js +15 -2
- package/src/env/teardown.js +46 -3
- package/src/init.js +49 -9
- package/src/vendor/linear/cli-sanitise.js +8 -3
- package/src/vendor/linear/cli-sync.js +64 -10
- package/src/vendor/linear/config.js +27 -21
- package/src/vendor/linear/doctor.js +2 -0
- package/src/vendor/provider-kit/index.js +4 -0
- package/src/vendor/provider-kit/src/apply.js +58 -6
- package/src/vendor/provider-kit/src/assignment.js +78 -1
- package/src/vendor/provider-kit/src/config.js +34 -1
- package/src/vendor/provider-kit/src/credentials.js +7 -2
- package/src/vendor/provider-kit/src/list-rows.js +35 -11
- package/src/vendor/provider-kit/src/released.js +48 -4
- package/src/vendor/provider-kit/src/specs.js +18 -7
- package/src/vendor/provider-kit/src/splice.js +64 -0
- package/src/vendor/provider-kit/src/status.js +137 -0
- package/src/vendor/sync-core/index.js +14 -1
- package/src/vendor/sync-core/src/compare.js +81 -6
- package/src/vendor/sync-core/src/normalize.js +50 -7
- package/src/vendor/sync-core/src/push.js +65 -5
- package/src/vendor/sync-core/src/summary.js +257 -0
package/src/env/base.js
ADDED
|
@@ -0,0 +1,104 @@
|
|
|
1
|
+
'use strict'
|
|
2
|
+
|
|
3
|
+
/**
|
|
4
|
+
* `spec-env base` — which branch skitterspec will fork from and land onto, and
|
|
5
|
+
* which in-flight specs forked from an older one.
|
|
6
|
+
*
|
|
7
|
+
* Pure: the CLI fetches, reads refs and computes merge-bases, and hands the
|
|
8
|
+
* facts in. Nothing here touches git, and nothing here edits config — pinning
|
|
9
|
+
* is a hand edit of `baseBranch`, deliberately without a verb (the pin is the
|
|
10
|
+
* exception, so it does not get one).
|
|
11
|
+
*/
|
|
12
|
+
|
|
13
|
+
const HOW = Object.freeze({
|
|
14
|
+
pin: 'pinned by baseBranch',
|
|
15
|
+
pattern: 'newest match',
|
|
16
|
+
'origin-head': 'origin/HEAD',
|
|
17
|
+
local: 'local branch',
|
|
18
|
+
fallback: 'nothing detected — default',
|
|
19
|
+
})
|
|
20
|
+
|
|
21
|
+
/**
|
|
22
|
+
* Which match a spec branch forked from: the one whose merge-base with the
|
|
23
|
+
* branch is newest. `matches` is newest-first; `mergeBase(name)` returns a sha
|
|
24
|
+
* or null; `isAncestor(a, b)` is true when `a` is an ancestor of (or equal to) `b`.
|
|
25
|
+
*
|
|
26
|
+
* WHAT WOULD FOOL THIS: a release candidate cut from a base that already holds
|
|
27
|
+
* the old rc's tip. Both merge-bases are then the same commit and nothing in
|
|
28
|
+
* the history says which one the spec was forked from — so a tie goes to the
|
|
29
|
+
* NEWER match, and the spec is not reported as behind. Being wrong that way
|
|
30
|
+
* costs a row that should have printed; the rebase onto the newer match is a
|
|
31
|
+
* no-op for exactly the commits the two share, so nothing lands wrong.
|
|
32
|
+
*/
|
|
33
|
+
function forkMatch(matches, mergeBase, isAncestor) {
|
|
34
|
+
let best = null
|
|
35
|
+
for (const name of matches) {
|
|
36
|
+
const sha = mergeBase(name)
|
|
37
|
+
if (!sha) continue
|
|
38
|
+
// Strictly newer only: an equal merge-base keeps the newer match already held.
|
|
39
|
+
if (!best || (sha !== best.sha && isAncestor(best.sha, sha))) best = { name, sha }
|
|
40
|
+
}
|
|
41
|
+
return best ? best.name : null
|
|
42
|
+
}
|
|
43
|
+
|
|
44
|
+
/**
|
|
45
|
+
* Build the report. `facts`:
|
|
46
|
+
* { pattern, remote, base, how, fetch: { ok, reason } | null,
|
|
47
|
+
* matches: [{ name, date }] (newest first), forks: [{ spec, forkedFrom }] }
|
|
48
|
+
* Returns `{ json, lines }`; the CLI prints one of them and always exits 0.
|
|
49
|
+
*/
|
|
50
|
+
function planBaseReport(facts) {
|
|
51
|
+
const { pattern, remote, base, how } = facts
|
|
52
|
+
const matches = facts.matches || []
|
|
53
|
+
const fetch = facts.fetch || null
|
|
54
|
+
// Behind = forked from a match that is not the base. Only meaningful when the
|
|
55
|
+
// pattern chose the base: a pin is a deliberate choice of base, and the
|
|
56
|
+
// matches beside it are not competing for the role.
|
|
57
|
+
const stale =
|
|
58
|
+
how === 'pattern' && base
|
|
59
|
+
? (facts.forks || []).filter((f) => f.forkedFrom && f.forkedFrom !== base)
|
|
60
|
+
: []
|
|
61
|
+
|
|
62
|
+
const json = {
|
|
63
|
+
base: base || null,
|
|
64
|
+
how,
|
|
65
|
+
pattern: pattern || null,
|
|
66
|
+
remote,
|
|
67
|
+
fetch,
|
|
68
|
+
matches: matches.map((m) => ({ ...m, base: m.name === base })),
|
|
69
|
+
stale,
|
|
70
|
+
}
|
|
71
|
+
|
|
72
|
+
const lines = []
|
|
73
|
+
if (!pattern) {
|
|
74
|
+
lines.push(`spec-env base: ${base} (${HOW[how]})`)
|
|
75
|
+
return { json, lines }
|
|
76
|
+
}
|
|
77
|
+
|
|
78
|
+
if (base) lines.push(`spec-env base: ${base} (${HOW[how]}${how === 'pin' ? ` — ${pattern} not used` : ` for ${pattern}`})`)
|
|
79
|
+
else lines.push(`spec-env base: none — no branch on ${remote} matches ${pattern}`)
|
|
80
|
+
|
|
81
|
+
if (fetch) {
|
|
82
|
+
lines.push(
|
|
83
|
+
fetch.ok
|
|
84
|
+
? ` fetched ${remote}`
|
|
85
|
+
: ` fetch from ${remote} failed${fetch.reason ? ` (${fetch.reason})` : ''} — listing the refs already here`,
|
|
86
|
+
)
|
|
87
|
+
}
|
|
88
|
+
|
|
89
|
+
if (matches.length) {
|
|
90
|
+
const width = Math.max(...matches.map((m) => m.name.length))
|
|
91
|
+
for (const m of matches) {
|
|
92
|
+
const mark = m.name === base ? (how === 'pin' ? ' ← base (pin)' : ' ← base') : ''
|
|
93
|
+
lines.push(` ${m.name.padEnd(width)} ${m.date || ''}${mark}`.trimEnd())
|
|
94
|
+
}
|
|
95
|
+
}
|
|
96
|
+
|
|
97
|
+
if (stale.length) {
|
|
98
|
+
lines.push(' forked from an older match:')
|
|
99
|
+
for (const s of stale) lines.push(` ${s.spec} · forked from ${s.forkedFrom}`)
|
|
100
|
+
}
|
|
101
|
+
return { json, lines }
|
|
102
|
+
}
|
|
103
|
+
|
|
104
|
+
module.exports = { forkMatch, planBaseReport }
|
package/src/env/bootstrap.js
CHANGED
|
@@ -61,7 +61,7 @@ function lstatOrNull(fs, p) {
|
|
|
61
61
|
* The target is tested with `lstat`, which does not: an existing link, even a
|
|
62
62
|
* dangling one, is somebody's deliberate state and is left alone.
|
|
63
63
|
*/
|
|
64
|
-
function runSeed(step, { cwd, mainRoot, fs }) {
|
|
64
|
+
function runSeed(step, { cwd, mainRoot, fs, platform = process.platform }) {
|
|
65
65
|
const src = path.join(mainRoot, step.file)
|
|
66
66
|
const dst = path.join(cwd, step.file)
|
|
67
67
|
if (!fs.existsSync(src)) {
|
|
@@ -71,8 +71,26 @@ function runSeed(step, { cwd, mainRoot, fs }) {
|
|
|
71
71
|
return { outcome: 'skipped', line: `seed ${step.file}: exists — skipped` }
|
|
72
72
|
}
|
|
73
73
|
fs.mkdirSync(path.dirname(dst), { recursive: true })
|
|
74
|
-
if (step.mode === 'copy')
|
|
75
|
-
|
|
74
|
+
if (step.mode === 'copy') {
|
|
75
|
+
fs.copyFileSync(src, dst)
|
|
76
|
+
return { outcome: 'seeded', line: `seeded ${step.file} → ${src}` }
|
|
77
|
+
}
|
|
78
|
+
// WINDOWS WITHOUT DEVELOPER MODE CANNOT CREATE A SYMLINK (EPERM), and a
|
|
79
|
+
// seed is what makes a fresh worktree runnable at all (chore-windows-ci). A
|
|
80
|
+
// directory takes a junction there, which needs no privilege; a file that
|
|
81
|
+
// still cannot be linked is copied — said, because a copy does not follow
|
|
82
|
+
// later edits to the primary checkout's file the way a link would.
|
|
83
|
+
const dir = fs.statSync(src).isDirectory()
|
|
84
|
+
try {
|
|
85
|
+
fs.symlinkSync(src, dst, dir && platform === 'win32' ? 'junction' : undefined)
|
|
86
|
+
} catch (err) {
|
|
87
|
+
if (dir || !(err && (err.code === 'EPERM' || err.code === 'EACCES'))) throw err
|
|
88
|
+
fs.copyFileSync(src, dst)
|
|
89
|
+
return {
|
|
90
|
+
outcome: 'seeded',
|
|
91
|
+
line: `seeded ${step.file} → ${src} (copied — this machine cannot create symlinks)`,
|
|
92
|
+
}
|
|
93
|
+
}
|
|
76
94
|
return { outcome: 'seeded', line: `seeded ${step.file} → ${src}` }
|
|
77
95
|
}
|
|
78
96
|
|
|
@@ -157,6 +175,7 @@ function runBootstrap(steps, io) {
|
|
|
157
175
|
cwd: io.cwd,
|
|
158
176
|
mainRoot: io.mainRoot,
|
|
159
177
|
fs: io.fs || realFs,
|
|
178
|
+
platform: io.platform || process.platform,
|
|
160
179
|
spawn: io.spawn || spawnSync,
|
|
161
180
|
childStdout: io.childStdout || 'inherit',
|
|
162
181
|
}
|
package/src/env/classify.js
CHANGED
|
@@ -17,6 +17,7 @@
|
|
|
17
17
|
|
|
18
18
|
const path = require('node:path')
|
|
19
19
|
const { BUCKETS, expandTokens, readFrontmatterField } = require('./resolve.js')
|
|
20
|
+
const { fromRepoPath, prefixOf } = require('./project.js')
|
|
20
21
|
|
|
21
22
|
// git reports repo-relative, forward-slashed paths; an untracked directory comes
|
|
22
23
|
// back with a trailing slash. Normalise both away so comparisons are exact.
|
|
@@ -66,7 +67,9 @@ function expandCompanion(pattern, spec, config) {
|
|
|
66
67
|
/**
|
|
67
68
|
* Split `dirtyPaths` into the ones that belong to `spec` and the ones that do
|
|
68
69
|
* not. Repo-relative paths in, repo-relative paths out; nothing is read from git
|
|
69
|
-
* and nothing is written.
|
|
70
|
+
* and nothing is written. The spec's folders and companion paths are
|
|
71
|
+
* PROJECT-relative, so each path is converted with the config's prefix before it
|
|
72
|
+
* is compared — a path outside a subfolder project is never the spec's.
|
|
70
73
|
*
|
|
71
74
|
* Owned:
|
|
72
75
|
* - anything inside `specs/<bucket>/<folder>/` for ANY bucket. Every bucket is
|
|
@@ -89,11 +92,13 @@ function classifyDirtyTree(spec, dirtyPaths, config) {
|
|
|
89
92
|
if (expanded) companions.add(expanded)
|
|
90
93
|
}
|
|
91
94
|
|
|
95
|
+
const prefix = prefixOf(config)
|
|
92
96
|
for (const raw of dirtyPaths || []) {
|
|
93
97
|
const p = normalize(raw)
|
|
94
98
|
if (!p) continue
|
|
95
|
-
const
|
|
96
|
-
|
|
99
|
+
const rel = fromRepoPath(p, prefix)
|
|
100
|
+
const inFolder = rel !== null && folders.some((f) => rel === f || rel.startsWith(`${f}/`))
|
|
101
|
+
if (inFolder || (rel !== null && companions.has(rel))) owned.push(p)
|
|
97
102
|
else foreign.push(p)
|
|
98
103
|
}
|
|
99
104
|
return { owned, foreign }
|
|
@@ -129,7 +134,10 @@ function unquotePath(p) {
|
|
|
129
134
|
function dirtyPaths(git) {
|
|
130
135
|
const lists = [
|
|
131
136
|
git(['diff', '--name-only', 'HEAD']),
|
|
132
|
-
|
|
137
|
+
// `--full-name`: `ls-files` answers relative to its cwd, `diff` from the repo
|
|
138
|
+
// root. Read from a subfolder project they disagreed, and every untracked
|
|
139
|
+
// spec document was classified as somebody else's.
|
|
140
|
+
git(['ls-files', '--others', '--exclude-standard', '--full-name']),
|
|
133
141
|
]
|
|
134
142
|
if (lists.every((l) => l === null)) return null
|
|
135
143
|
const out = []
|
package/src/env/config.js
CHANGED
|
@@ -41,19 +41,27 @@
|
|
|
41
41
|
* // spec alongside its own folder (provider-neutral; {slug} and
|
|
42
42
|
* // {identifier} expand); empty = the spec folder only
|
|
43
43
|
* baseBranch: "", // "" = auto-detect (origin/HEAD → main → master)
|
|
44
|
+
* baseBranchPattern: "", // glob over remote branch names; newest match
|
|
45
|
+
* // by commit date is the base (rolling release-candidate)
|
|
46
|
+
* land: { strategy, remote, draft, specDocs }, // how a branch lands:
|
|
47
|
+
* // "ff" (default, trunk-based local fast-forward) or "pr"
|
|
48
|
+
* // (push + pull request; base moves when the host merges)
|
|
44
49
|
* guards: { refuseTeardownIfDirty, refuseTeardownIfUnpushed },
|
|
45
50
|
* teardown: { deleteRemoteBranch },
|
|
46
51
|
* live: { migrations: [ "glob", ... ] } // migration globs → `live take`
|
|
47
52
|
* // refuses a branch that changes them (code-only v1)
|
|
48
|
-
* hotfix: { bump, cherryPickMain, targets
|
|
49
|
-
* // deploy tag, also cherry-pick
|
|
50
|
-
* // onto any extra base tags in
|
|
53
|
+
* hotfix: { bump, cherryPickMain, targets, releaseWith, releaseBranch, tag }
|
|
54
|
+
* // `hotfix land`: patch-bump the deploy tag, also cherry-pick
|
|
55
|
+
* // onto the base branch (main), and onto any extra base tags in
|
|
56
|
+
* // `targets` (test/demo lines). `releaseBranch` makes the hotfix
|
|
57
|
+
* // branch-based: it forks from <remote>/<releaseBranch> instead
|
|
58
|
+
* // of a tag; `tag` keeps (true) or drops the release-tag cut
|
|
51
59
|
* }
|
|
52
60
|
*/
|
|
53
61
|
|
|
54
62
|
const { createHash } = require('node:crypto')
|
|
55
63
|
const { readFileSync, realpathSync } = require('node:fs')
|
|
56
|
-
const { join, resolve } = require('node:path')
|
|
64
|
+
const { join, resolve, sep } = require('node:path')
|
|
57
65
|
|
|
58
66
|
const CONFIG_FILE = join('specs', '.core', 'env.config.json')
|
|
59
67
|
|
|
@@ -206,6 +214,26 @@ const DEFAULT_CONFIG = Object.freeze({
|
|
|
206
214
|
spec: Object.freeze({ companionPaths: Object.freeze([]) }),
|
|
207
215
|
// Integration base branch. Empty = auto-detect (origin/HEAD → main → master).
|
|
208
216
|
baseBranch: '',
|
|
217
|
+
// A glob over the remote's branch names (`"20??/Q?"`) for a base that rolls:
|
|
218
|
+
// the newest match by commit date is the base, so cutting the next release
|
|
219
|
+
// candidate is all it takes to move every spec onto it. An explicit
|
|
220
|
+
// `baseBranch` still wins. Empty = off, and resolution is exactly as before.
|
|
221
|
+
baseBranchPattern: '',
|
|
222
|
+
// How a finished branch reaches the base branch. `strategy: "ff"` (the
|
|
223
|
+
// default) is trunk-based landing exactly as it has always been: rebase, then
|
|
224
|
+
// a local `merge --ff-only` — nothing changes for an installed repo on
|
|
225
|
+
// upgrade. `"pr"` lands by pushing the branch and opening a pull request on
|
|
226
|
+
// the host: the base branch moves only when the host merges, so integrate's
|
|
227
|
+
// plan ends in a consent-gated push (the hotfix pattern: already-pushed is
|
|
228
|
+
// honoured, `--push` is the recorded yes, otherwise the plan holds) and the
|
|
229
|
+
// project's `afterLand` commands are deferred to the completion run that
|
|
230
|
+
// follows the merge. `remote` names where the branch is pushed. `draft`
|
|
231
|
+
// opens mid-spec PRs as drafts (a draft cannot be merged, so nothing
|
|
232
|
+
// downstream can close a ticket early). `specDocs` decides where a spec
|
|
233
|
+
// DOCUMENT lands under "pr": "trunk" keeps today's authoring land (needs
|
|
234
|
+
// direct push for docs), "branch" has the spec ride the feature branch and
|
|
235
|
+
// land with the work's PR.
|
|
236
|
+
land: Object.freeze({ strategy: 'ff', remote: 'origin', draft: true, specDocs: 'trunk' }),
|
|
209
237
|
// `mainIsLandingZone` defaults ON wherever isolation is configured, matching
|
|
210
238
|
// the review gate's precedent: the push toward not working on the base branch
|
|
211
239
|
// is the normal path, and stepping off it is the deliberate act. That does
|
|
@@ -301,11 +329,19 @@ const DEFAULT_CONFIG = Object.freeze({
|
|
|
301
329
|
// `releaseWith` is a project's own release command, run in the hotfix
|
|
302
330
|
// worktree in place of the built-in tagger — e.g. skittership's
|
|
303
331
|
// `node scripts/release-hotfix.cjs --json`. Empty (the default) = built-in.
|
|
332
|
+
// `releaseBranch` names a release LINE that is a branch rather than a tag
|
|
333
|
+
// (e.g. "master", where prod is whatever master holds): the hotfix forks from
|
|
334
|
+
// the remote's head of it and records `Base version: <branch>@<sha>`. Empty
|
|
335
|
+
// (the default) = today's tag-based hotfix, unchanged. `tag` (default true)
|
|
336
|
+
// keeps the release-tag cut; false is for a team whose deploy is driven by a
|
|
337
|
+
// branch merge rather than a tag.
|
|
304
338
|
hotfix: Object.freeze({
|
|
305
339
|
bump: 'patch',
|
|
306
340
|
cherryPickMain: true,
|
|
307
341
|
targets: Object.freeze([]),
|
|
308
342
|
releaseWith: '',
|
|
343
|
+
releaseBranch: '',
|
|
344
|
+
tag: true,
|
|
309
345
|
}),
|
|
310
346
|
})
|
|
311
347
|
|
|
@@ -370,6 +406,8 @@ function defaults() {
|
|
|
370
406
|
branch: { ...DEFAULT_CONFIG.branch },
|
|
371
407
|
spec: { companionPaths: [] },
|
|
372
408
|
baseBranch: DEFAULT_CONFIG.baseBranch,
|
|
409
|
+
baseBranchPattern: DEFAULT_CONFIG.baseBranchPattern,
|
|
410
|
+
land: { ...DEFAULT_CONFIG.land },
|
|
373
411
|
guards: { ...DEFAULT_CONFIG.guards },
|
|
374
412
|
teardown: { ...DEFAULT_CONFIG.teardown },
|
|
375
413
|
review: { ...DEFAULT_CONFIG.review, reviewers: [] },
|
|
@@ -637,6 +675,15 @@ function mergeConfig(base, parsed) {
|
|
|
637
675
|
assign(base, parsed, 'registry', 'string')
|
|
638
676
|
assign(base, parsed, 'baseBranch', 'string')
|
|
639
677
|
|
|
678
|
+
// Dropped rather than thrown on, like every field here — and dropping is the
|
|
679
|
+
// safe direction: an unusable pattern resolves the base exactly as an unset
|
|
680
|
+
// one does. Whitespace and `..` can never name a branch, so a pattern holding
|
|
681
|
+
// either is a typo, not a glob.
|
|
682
|
+
if (typeof parsed.baseBranchPattern === 'string') {
|
|
683
|
+
const pattern = parsed.baseBranchPattern.trim()
|
|
684
|
+
if (pattern && !/\s/.test(pattern) && !pattern.includes('..')) base.baseBranchPattern = pattern
|
|
685
|
+
}
|
|
686
|
+
|
|
640
687
|
// Same treatment as `teardown.deleteRemoteBranch` below, for the same reason:
|
|
641
688
|
// an unrecognised value falls through to the default rather than erroring or
|
|
642
689
|
// being taken literally. The fallback direction matters — "worktree" is the
|
|
@@ -646,6 +693,23 @@ function mergeConfig(base, parsed) {
|
|
|
646
693
|
base.mode = parsed.mode
|
|
647
694
|
}
|
|
648
695
|
|
|
696
|
+
// The enums fall through to their defaults on an unrecognised value, like
|
|
697
|
+
// `mode` above — and the fallback direction matters the same way: "ff" is the
|
|
698
|
+
// conservative strategy (nothing leaves the machine), so a typo ("PR",
|
|
699
|
+
// "pull-request") costs a local land that was meant to be a push, never a
|
|
700
|
+
// push that was meant to stay local. Same for `specDocs`: "trunk" is today's
|
|
701
|
+
// behaviour.
|
|
702
|
+
if (isObject(parsed.land)) {
|
|
703
|
+
if (parsed.land.strategy === 'ff' || parsed.land.strategy === 'pr') {
|
|
704
|
+
base.land.strategy = parsed.land.strategy
|
|
705
|
+
}
|
|
706
|
+
assign(base.land, parsed.land, 'remote', 'string')
|
|
707
|
+
assign(base.land, parsed.land, 'draft', 'boolean')
|
|
708
|
+
if (parsed.land.specDocs === 'trunk' || parsed.land.specDocs === 'branch') {
|
|
709
|
+
base.land.specDocs = parsed.land.specDocs
|
|
710
|
+
}
|
|
711
|
+
}
|
|
712
|
+
|
|
649
713
|
if (isObject(parsed.guards)) {
|
|
650
714
|
assign(base.guards, parsed.guards, 'refuseTeardownIfDirty', 'boolean')
|
|
651
715
|
assign(base.guards, parsed.guards, 'refuseTeardownIfUnpushed', 'boolean')
|
|
@@ -739,6 +803,14 @@ function mergeConfig(base, parsed) {
|
|
|
739
803
|
assign(base.hotfix, parsed.hotfix, 'bump', 'string')
|
|
740
804
|
assign(base.hotfix, parsed.hotfix, 'cherryPickMain', 'boolean')
|
|
741
805
|
assign(base.hotfix, parsed.hotfix, 'releaseWith', 'string')
|
|
806
|
+
assign(base.hotfix, parsed.hotfix, 'tag', 'boolean')
|
|
807
|
+
// Trimmed, and dropped when it could never name a branch — the same
|
|
808
|
+
// direction as `baseBranchPattern`: unusable means unset, which is the
|
|
809
|
+
// tag-based flow every hotfix had before this key existed.
|
|
810
|
+
if (typeof parsed.hotfix.releaseBranch === 'string') {
|
|
811
|
+
const name = parsed.hotfix.releaseBranch.trim()
|
|
812
|
+
if (name && !/[\s@~^:?*[\\]/.test(name) && !name.includes('..')) base.hotfix.releaseBranch = name
|
|
813
|
+
}
|
|
742
814
|
if (Array.isArray(parsed.hotfix.targets)) {
|
|
743
815
|
base.hotfix.targets = normalizeFileList(parsed.hotfix.targets)
|
|
744
816
|
}
|
|
@@ -819,7 +891,7 @@ function loadEnvConfig(dir = process.cwd()) {
|
|
|
819
891
|
try {
|
|
820
892
|
parsed = JSON.parse(raw)
|
|
821
893
|
} catch (error) {
|
|
822
|
-
throw new Error(`Invalid ${CONFIG_FILE}: ${error.message}`)
|
|
894
|
+
throw new Error(`Invalid ${CONFIG_FILE.split(sep).join('/')}: ${error.message}`)
|
|
823
895
|
}
|
|
824
896
|
|
|
825
897
|
return {
|
|
@@ -0,0 +1,62 @@
|
|
|
1
|
+
'use strict'
|
|
2
|
+
|
|
3
|
+
/**
|
|
4
|
+
* Disposition enumeration for `spec-env disposition` — the input to
|
|
5
|
+
* /spec-complete's PR-mode guard.
|
|
6
|
+
*
|
|
7
|
+
* Once a PR is ready, anyone can merge from the host's UI and the tracker
|
|
8
|
+
* closes the ticket, so readying it is the last moment skitterspec is
|
|
9
|
+
* guaranteed to be standing there. Before that happens, every loose end is
|
|
10
|
+
* ENUMERATED here and DISPOSED by the operator in the skill (tick with
|
|
11
|
+
* evidence · spin off as a linked ticket · drop with a recorded reason).
|
|
12
|
+
* Enumeration is automatic; deciding is human — the same split the review
|
|
13
|
+
* marks use, and like them this is information: nothing here refuses, counts
|
|
14
|
+
* toward a gate, or exits non-zero.
|
|
15
|
+
*
|
|
16
|
+
* Pure: the caller reads the files and hands them over, so every shape is
|
|
17
|
+
* unit-testable with no filesystem.
|
|
18
|
+
*
|
|
19
|
+
* @param {object} input { overview, phases: [{ file, content }] }
|
|
20
|
+
* @returns {object} { tasks, phases, followUps, clean }
|
|
21
|
+
* tasks — unticked `- [ ]` items, per phase file, with line numbers
|
|
22
|
+
* phases — phase-index rows whose status is not ✅
|
|
23
|
+
* followUps — Changelog `Follow-up surfaced:` lines (all of them: whether a
|
|
24
|
+
* spec was later written for one is not knowable from this file,
|
|
25
|
+
* so the operator reads the list rather than trusting a guess)
|
|
26
|
+
* clean — nothing enumerated; the guard has nothing to ask about
|
|
27
|
+
*/
|
|
28
|
+
function collectDisposition(input) {
|
|
29
|
+
const overview = (input && input.overview) || ''
|
|
30
|
+
const phaseFiles = (input && Array.isArray(input.phases)) ? input.phases : []
|
|
31
|
+
|
|
32
|
+
const tasks = []
|
|
33
|
+
for (const { file, content } of phaseFiles) {
|
|
34
|
+
const lines = String(content || '').split('\n')
|
|
35
|
+
lines.forEach((line, i) => {
|
|
36
|
+
const m = line.match(/^\s*- \[ \] (.+)$/)
|
|
37
|
+
if (m) tasks.push({ file, line: i + 1, text: m[1].trim() })
|
|
38
|
+
})
|
|
39
|
+
}
|
|
40
|
+
|
|
41
|
+
// Phase-index rows: | <n> | <title> | <status> | [<file>](<file>) | — only
|
|
42
|
+
// rows whose status cell is not ✅. The index is the overview's summary of
|
|
43
|
+
// the phase files, so a row here and no unticked tasks usually means the
|
|
44
|
+
// index lagged; both are listed and the operator reconciles.
|
|
45
|
+
const phases = []
|
|
46
|
+
for (const line of overview.split('\n')) {
|
|
47
|
+
const m = line.match(/^\|\s*(\d+)\s*\|\s*(.+?)\s*\|\s*([^|]+?)\s*\|\s*\[([^\]]+)\]/)
|
|
48
|
+
if (m && !m[3].includes('✅')) {
|
|
49
|
+
phases.push({ n: Number(m[1]), title: m[2], status: m[3].trim(), file: m[4] })
|
|
50
|
+
}
|
|
51
|
+
}
|
|
52
|
+
|
|
53
|
+
const followUps = []
|
|
54
|
+
for (const line of overview.split('\n')) {
|
|
55
|
+
const m = line.match(/Follow-up surfaced:\s*(.+)$/)
|
|
56
|
+
if (m) followUps.push({ text: m[1].trim() })
|
|
57
|
+
}
|
|
58
|
+
|
|
59
|
+
return { tasks, phases, followUps, clean: !tasks.length && !phases.length && !followUps.length }
|
|
60
|
+
}
|
|
61
|
+
|
|
62
|
+
module.exports = { collectDisposition }
|
|
@@ -0,0 +1,81 @@
|
|
|
1
|
+
'use strict'
|
|
2
|
+
|
|
3
|
+
/**
|
|
4
|
+
* `spec-env handoff <spec>` — make a spec's work reachable by its next owner.
|
|
5
|
+
*
|
|
6
|
+
* A spec branch lives in a local worktree, and nothing requires it ever to
|
|
7
|
+
* reach a remote — so a ticket handed to someone else points at code only its
|
|
8
|
+
* old owner can see. This plans the two things that close that: the branch
|
|
9
|
+
* published (a push the operator consents to, since it is outward-facing), and
|
|
10
|
+
* a note for the ticket naming where the work is. `/spec-start` on the new
|
|
11
|
+
* owner's machine then resumes from the published branch rather than forking.
|
|
12
|
+
*
|
|
13
|
+
* Pure: every fact arrives as an argument, so each answer is testable without a
|
|
14
|
+
* repo. The CLI reads git and writes the note.
|
|
15
|
+
*/
|
|
16
|
+
|
|
17
|
+
const { phaseProgress, progressText } = require('./phases.js')
|
|
18
|
+
const { shellPath } = require('./project.js')
|
|
19
|
+
|
|
20
|
+
// Uncommitted work cannot travel with a push, so a hand-over would silently
|
|
21
|
+
// leave it behind in the old worktree. The engine declares the way out rather
|
|
22
|
+
// than leaving the skill to infer one (`offered-unblocks.md`): committing is
|
|
23
|
+
// what the guard asks for, so it is a `satisfy`, and nothing is weakened.
|
|
24
|
+
const COMMIT_FIRST = Object.freeze({ kind: 'satisfy', label: 'Commit first, then hand it over', command: '/commit' })
|
|
25
|
+
|
|
26
|
+
/**
|
|
27
|
+
* @param {object} f
|
|
28
|
+
* - `spec` `{ folder, branch, worktreePath }`
|
|
29
|
+
* - `worktree` true when the worktree exists on this machine
|
|
30
|
+
* - `dirtyPaths` uncommitted paths in that worktree ([] when clean)
|
|
31
|
+
* - `remote` the remote name, and `remoteConfigured` whether it exists
|
|
32
|
+
* - `headSha` the worktree's HEAD
|
|
33
|
+
* - `remoteSha` the branch's sha on the remote, '' when unpublished,
|
|
34
|
+
* null when the remote could not be asked
|
|
35
|
+
* - `phases` `[{ file, content }]`
|
|
36
|
+
*/
|
|
37
|
+
function planHandoff(f) {
|
|
38
|
+
const { spec } = f
|
|
39
|
+
const refuse = (reason, offer) => ({ blocked: true, reason, ...(offer ? { offer } : {}) })
|
|
40
|
+
|
|
41
|
+
if (!f.worktree) {
|
|
42
|
+
return refuse(`${spec.folder} has no worktree on this machine — hand it over from wherever it is being built`)
|
|
43
|
+
}
|
|
44
|
+
if (f.dirtyPaths && f.dirtyPaths.length) {
|
|
45
|
+
return refuse(
|
|
46
|
+
`${spec.folder}'s worktree has ${f.dirtyPaths.length} uncommitted path(s) — a push carries commits, so they would stay behind`,
|
|
47
|
+
COMMIT_FIRST,
|
|
48
|
+
)
|
|
49
|
+
}
|
|
50
|
+
if (!f.remoteConfigured) {
|
|
51
|
+
return refuse(`no remote named ${f.remote} — publish ${spec.branch} somewhere the new owner can reach first`)
|
|
52
|
+
}
|
|
53
|
+
|
|
54
|
+
const progress = phaseProgress(f.phases)
|
|
55
|
+
// Published AT HEAD is the positive signal the push is already done; an
|
|
56
|
+
// unpublished branch and a stale one both need it, and a remote that could
|
|
57
|
+
// not be asked is planned as if it does (a redundant push is harmless).
|
|
58
|
+
const published = Boolean(f.headSha && f.remoteSha && f.remoteSha === f.headSha)
|
|
59
|
+
const commands = published ? [] : [`git -C ${shellPath(spec.worktreePath)} push -u ${f.remote} ${spec.branch}`]
|
|
60
|
+
const sha = (f.headSha || '').slice(0, 12)
|
|
61
|
+
const note = [
|
|
62
|
+
`**Handed over** — the work is on \`${spec.branch}\` at \`${sha}\` (${f.remote}), ${progressText(progress)}.`,
|
|
63
|
+
'',
|
|
64
|
+
`\`/spec-start ${spec.folder}\` resumes from that branch rather than forking a new one.`,
|
|
65
|
+
'',
|
|
66
|
+
].join('\n')
|
|
67
|
+
|
|
68
|
+
return {
|
|
69
|
+
blocked: false,
|
|
70
|
+
branch: spec.branch,
|
|
71
|
+
sha,
|
|
72
|
+
remote: f.remote,
|
|
73
|
+
published,
|
|
74
|
+
remoteUnknown: f.remoteSha === null,
|
|
75
|
+
progress,
|
|
76
|
+
commands,
|
|
77
|
+
note,
|
|
78
|
+
}
|
|
79
|
+
}
|
|
80
|
+
|
|
81
|
+
module.exports = { planHandoff, phaseProgress, progressText, COMMIT_FIRST }
|