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