@skitterbyte/skitterspec-linear 19.14.0 → 19.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/README.md +2 -0
- package/assets/claude-md-section.md +12 -0
- 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-status/SKILL.md +1 -1
- package/assets/skills/spec-sync/SKILL.md +12 -12
- 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/linear/cli-sync.js +3 -3
- package/src/vendor/provider-kit/src/specs.js +46 -1
- package/src/vendor/sync-core/src/summary.js +10 -1
package/src/cli.js
CHANGED
|
@@ -5,7 +5,7 @@ const path = require('path')
|
|
|
5
5
|
const os = require('os')
|
|
6
6
|
const { pathToFileURL } = require('url')
|
|
7
7
|
const { execFileSync } = require('child_process')
|
|
8
|
-
const { init, resync, reset, checkSync, isExistingSetup } = require('./init.js')
|
|
8
|
+
const { init, resync, reset, checkSync, isExistingSetup, localSeedFiles } = require('./init.js')
|
|
9
9
|
const {
|
|
10
10
|
detectReleaseTooling,
|
|
11
11
|
removeReleaseTooling,
|
|
@@ -43,14 +43,17 @@ const SPEC_ENV_VERBS = Object.freeze([
|
|
|
43
43
|
'live',
|
|
44
44
|
'review',
|
|
45
45
|
'stage',
|
|
46
|
+
'checks',
|
|
46
47
|
'status',
|
|
47
48
|
'resolve',
|
|
49
|
+
'resume',
|
|
48
50
|
'base',
|
|
49
51
|
'nospec',
|
|
50
52
|
'main',
|
|
51
53
|
'project',
|
|
52
54
|
])
|
|
53
55
|
const { forkMatch, planBaseReport } = require('./env/base.js')
|
|
56
|
+
const { readBasePin, writeBasePin, clearBasePin } = require('./env/basepin.js')
|
|
54
57
|
const {
|
|
55
58
|
readRegistry,
|
|
56
59
|
writeRegistry,
|
|
@@ -66,6 +69,8 @@ const {
|
|
|
66
69
|
resolveSpecless,
|
|
67
70
|
resolveBaseBranch,
|
|
68
71
|
describeBaseBranch,
|
|
72
|
+
BaseUnresolvedError,
|
|
73
|
+
gapNote,
|
|
69
74
|
baseRemote,
|
|
70
75
|
liveWorktreePaths,
|
|
71
76
|
collectSpecFolders,
|
|
@@ -195,6 +200,7 @@ const {
|
|
|
195
200
|
const { planPrune, liveSlugsForSpecs, reconcileRegistry } = require('./env/prune.js')
|
|
196
201
|
const { planIntegrate, planIntegrateCheckout, planIntegratePr, planIntegrateDocs } = require('./env/integrate.js')
|
|
197
202
|
const { specBranchDocs, preferBranches } = require('./env/specbranches.js')
|
|
203
|
+
const { findTarget, planResume, resumeLines, blockingNext } = require('./env/resume.js')
|
|
198
204
|
const { parseRemote, prFor, prPlanCommand, prAbandonCommand, preferRemoteBase } = require('./env/host.js')
|
|
199
205
|
const { collectDisposition } = require('./env/disposition.js')
|
|
200
206
|
const { planHandoff } = require('./env/handoff.js')
|
|
@@ -333,11 +339,18 @@ Usage:
|
|
|
333
339
|
--run-reviewers runs review.reviewers)
|
|
334
340
|
stage [spec] split the uncommitted tree into this spec's
|
|
335
341
|
documents and everything else
|
|
342
|
+
checks [spec] run complete.checks in the spec's worktree
|
|
343
|
+
(advisory — always exits 0)
|
|
336
344
|
status list provisioned specs + port blocks
|
|
337
345
|
resolve <spec> print resolved slug/type/branch/paths
|
|
346
|
+
resume [spec|#N] an in-flight spec: its blockers, and the plan
|
|
347
|
+
to rebuild its worktree from its branch
|
|
348
|
+
(prints commands; creates nothing)
|
|
338
349
|
base fetch, list baseBranchPattern matches
|
|
339
350
|
newest-first, mark the base, and name
|
|
340
351
|
specs forked from an older match
|
|
352
|
+
(--use-fallback pins the fallback
|
|
353
|
+
while nothing matches; --unpin)
|
|
341
354
|
skitterspec status What is in flight here: every spec with a worktree,
|
|
342
355
|
its bucket and phase progress read from that
|
|
343
356
|
worktree (--json). Offline; always exits 0.
|
|
@@ -404,8 +417,12 @@ Options (init / update):
|
|
|
404
417
|
--dir <path> Target project dir (default: positional arg or cwd)
|
|
405
418
|
--gating (init) Adopt release gating: each spec records whether
|
|
406
419
|
it ships behind a feature flag
|
|
420
|
+
--local (init) Keep the install on this machine: managed
|
|
421
|
+
files excluded from git, hooks in
|
|
422
|
+
settings.local.json, the block in CLAUDE.local.md.
|
|
423
|
+
For one developer on a shared repo — never a team
|
|
407
424
|
--no-claude-md Skip creating/patching CLAUDE.md
|
|
408
|
-
--yes, -y
|
|
425
|
+
--yes, -y Accept defaults; skip the interactive setup prompts
|
|
409
426
|
--isolation / --no-isolation Enable/skip per-spec isolation (a git
|
|
410
427
|
worktree per spec; writes env.config.json)
|
|
411
428
|
--name <name> / --category <c> (init --isolation) Write project.name /
|
|
@@ -439,6 +456,7 @@ function parse(argv) {
|
|
|
439
456
|
if (a === '--force') opts.force = true
|
|
440
457
|
else if (a === '--no-claude-md') opts.claudeMd = false
|
|
441
458
|
else if (a === '--yes' || a === '-y') opts.yes = true
|
|
459
|
+
else if (a === '--local') opts.local = true
|
|
442
460
|
else if (a === '--isolation') opts.isolation = true
|
|
443
461
|
else if (a === '--no-isolation') opts.isolation = false
|
|
444
462
|
else if (a === '--gating') opts.gating = true
|
|
@@ -590,6 +608,10 @@ function provisionedSpecs(dir, config) {
|
|
|
590
608
|
|
|
591
609
|
function specEnvStatus(dir, config) {
|
|
592
610
|
const provisioned = provisionedSpecs(dir, config)
|
|
611
|
+
// A base held on the fallback is worth one line wherever work is listed: it
|
|
612
|
+
// is the state every fork and land is in until the next release branch.
|
|
613
|
+
const gap = gapNote(config, gitReader(dir))
|
|
614
|
+
if (gap) process.stdout.write(`spec-env: base ${config.gapPin.base} — ${gap}\n`)
|
|
593
615
|
|
|
594
616
|
// REACHED EITHER WAY. This used to return here, so a repo with nothing in
|
|
595
617
|
// flight could say nothing about a waiting pass — and a repo with nothing in
|
|
@@ -911,7 +933,20 @@ function repoBlockers(repo, specs) {
|
|
|
911
933
|
} catch {
|
|
912
934
|
return []
|
|
913
935
|
}
|
|
914
|
-
|
|
936
|
+
// Each spec's own copy — its worktree where it has one, since base reads
|
|
937
|
+
// `backlog` for the life of a spec and holds none of its Blocked on: edits.
|
|
938
|
+
// A spec that cannot be resolved or read is not parked, it is unknown.
|
|
939
|
+
const parked = {}
|
|
940
|
+
for (const spec of specs) {
|
|
941
|
+
try {
|
|
942
|
+
const copy = readSpecCopy(resolveSpecWithWorktree(repo, config, spec).path)
|
|
943
|
+
const b = copy && blockingNext(copy)
|
|
944
|
+
if (b) parked[spec] = b
|
|
945
|
+
} catch {
|
|
946
|
+
// cannot tell — say nothing
|
|
947
|
+
}
|
|
948
|
+
}
|
|
949
|
+
return readBlockers(reviewsDirFor(repo, config), specs, config.review && config.review.required, parked)
|
|
915
950
|
}
|
|
916
951
|
|
|
917
952
|
/**
|
|
@@ -2281,7 +2316,7 @@ function specEnvBootstrap(dir, config, specArg, flags = {}) {
|
|
|
2281
2316
|
// `setup` exactly as a spec does, since a `setup` that reads a seeded `.env`
|
|
2282
2317
|
// fails without it; what it never has is a stack, so no slot is consulted.
|
|
2283
2318
|
if (spec.specless && !spec.unwritten) {
|
|
2284
|
-
steps = worktreeSteps(spec, null, config, { docs, wantsDocker: false })
|
|
2319
|
+
steps = worktreeSteps(spec, null, config, { docs, wantsDocker: false, localSeeds: localSeedFiles(dir) })
|
|
2285
2320
|
} else {
|
|
2286
2321
|
const compose = composeFilePresent(dir, config)
|
|
2287
2322
|
const { wantsDocker } = resolveStack(spec, config, { docs, composeFilePresent: compose })
|
|
@@ -2301,6 +2336,7 @@ function specEnvBootstrap(dir, config, specArg, flags = {}) {
|
|
|
2301
2336
|
docs,
|
|
2302
2337
|
wantsDocker,
|
|
2303
2338
|
composeFilePresent: compose,
|
|
2339
|
+
localSeeds: localSeedFiles(dir),
|
|
2304
2340
|
})
|
|
2305
2341
|
}
|
|
2306
2342
|
|
|
@@ -3135,7 +3171,7 @@ function specEnvIntegrate(dir, config, specArg, flags = {}) {
|
|
|
3135
3171
|
}
|
|
3136
3172
|
const cout = [`spec-env integrate: ${spec.folder}`, '', ' mode: checkout',
|
|
3137
3173
|
` base: ${base}`, ` branch: ${cplan.branch}`,
|
|
3138
|
-
...retargetLines(retarget),
|
|
3174
|
+
...retargetLines(retarget), ...gapLines(config, gitReader(dir)),
|
|
3139
3175
|
...reverifyLines(dir, spec, base, dir), '',
|
|
3140
3176
|
' run these (abort the rebase on conflict):']
|
|
3141
3177
|
for (const cmd of cplan.commands) cout.push(` ${cmd}`)
|
|
@@ -3250,7 +3286,7 @@ function specEnvIntegrate(dir, config, specArg, flags = {}) {
|
|
|
3250
3286
|
out.push(` base: ${plan.base}`)
|
|
3251
3287
|
out.push(` branch: ${plan.branch}`)
|
|
3252
3288
|
out.push(` worktree: ${spec.worktreePath}`)
|
|
3253
|
-
out.push(...retargetLines(retarget))
|
|
3289
|
+
out.push(...retargetLines(retarget), ...gapLines(config, gitReader(dir)))
|
|
3254
3290
|
if (primarySwitch) out.push(` primary: on ${primarySwitch.from} — switched to ${base} before the land`)
|
|
3255
3291
|
out.push(...reverifyLines(dir, spec, baseRef, spec.projectPath || spec.worktreePath))
|
|
3256
3292
|
out.push('')
|
|
@@ -3304,6 +3340,13 @@ function retargetLines(retarget) {
|
|
|
3304
3340
|
return retarget ? [` retarget: forked from ${retarget.from} · landing onto ${retarget.to}`] : []
|
|
3305
3341
|
}
|
|
3306
3342
|
|
|
3343
|
+
// Said under `base:` when a gap pin chose it, so a land onto the fallback is
|
|
3344
|
+
// never mistaken for a land onto a release branch. Nothing otherwise.
|
|
3345
|
+
function gapLines(config, git) {
|
|
3346
|
+
const note = gapNote(config, git)
|
|
3347
|
+
return note ? [` gap: ${note}`] : []
|
|
3348
|
+
}
|
|
3349
|
+
|
|
3307
3350
|
// Is the primary checkout sitting on an older rolling-base match? Positive
|
|
3308
3351
|
// signal only: the branch it has out must itself match `baseBranchPattern`
|
|
3309
3352
|
// (locally or on the remote). Anything else — a live spec, a detached HEAD, no
|
|
@@ -3438,7 +3481,7 @@ function specEnvIntegratePr(dir, config, spec, base, flags, retarget = null) {
|
|
|
3438
3481
|
out.push(` base: ${remote}/${base}`)
|
|
3439
3482
|
out.push(` branch: ${plan.branch}`)
|
|
3440
3483
|
out.push(checkout ? ` checkout: ${treePath}` : ` worktree: ${treePath}`)
|
|
3441
|
-
out.push(...retargetLines(retarget))
|
|
3484
|
+
out.push(...retargetLines(retarget), ...gapLines(config, gitReader(dir)))
|
|
3442
3485
|
// Silent on cannot-tell: a line about a lookup that failed accuses nothing
|
|
3443
3486
|
// and helps nobody — the placeholder in the commands already degrades.
|
|
3444
3487
|
if (pr.state === 'none') out.push(' pr: none yet')
|
|
@@ -4470,18 +4513,141 @@ function specEnvResolve(dir, config, specArg, flags = {}) {
|
|
|
4470
4513
|
}
|
|
4471
4514
|
|
|
4472
4515
|
/**
|
|
4473
|
-
* `skitterspec spec-env
|
|
4516
|
+
* `skitterspec spec-env resume <name|#N> [--json]` (feat-spec-resume)
|
|
4517
|
+
*
|
|
4518
|
+
* Which in-flight spec the argument means, what it is blocked on, and — where
|
|
4519
|
+
* this machine has no worktree for it — the commands that rebuild one from its
|
|
4520
|
+
* branch. Plans and prints; creates nothing, moves nothing, asks no tracker.
|
|
4521
|
+
* A refusal exits 1.
|
|
4522
|
+
*
|
|
4523
|
+
* Every copy of the spec this clone can see is read — the checkout it runs
|
|
4524
|
+
* from, each live worktree, and each spec branch (local, then remote-tracking,
|
|
4525
|
+
* never fetched) — because under `land.specDocs: "branch"` an in-flight spec
|
|
4526
|
+
* may exist nowhere else than its branch, and on the base branch its bucket
|
|
4527
|
+
* reads `backlog` whatever it really is. `env/resume.js` picks which copy
|
|
4528
|
+
* speaks.
|
|
4529
|
+
*/
|
|
4530
|
+
function specEnvResume(dir, config, arg, flags = {}) {
|
|
4531
|
+
const git = gitReader(dir)
|
|
4532
|
+
const prefix = prefixOf(config)
|
|
4533
|
+
const ownTree = (folder) => resolveSpecless(folder, dir, config, { spec: true }).worktreePath
|
|
4534
|
+
const copies = []
|
|
4535
|
+
const roots = [dir, ...[...liveWorktreePaths(git)].filter((p) => !sameDir(p, dir))]
|
|
4536
|
+
for (const root of roots) {
|
|
4537
|
+
const project = sameDir(root, dir) ? dir : projectIn(root, prefix)
|
|
4538
|
+
for (const bucket of BUCKETS) {
|
|
4539
|
+
let folders
|
|
4540
|
+
try {
|
|
4541
|
+
folders = fs.readdirSync(path.join(project, 'specs', bucket), { withFileTypes: true })
|
|
4542
|
+
} catch {
|
|
4543
|
+
continue
|
|
4544
|
+
}
|
|
4545
|
+
for (const entry of folders) {
|
|
4546
|
+
if (!entry.isDirectory()) continue
|
|
4547
|
+
const folder = entry.name
|
|
4548
|
+
// Another spec's worktree carries every base spec too; only a spec's
|
|
4549
|
+
// OWN tree speaks for it, and the checkout this ran from speaks last.
|
|
4550
|
+
const own = sameDir(ownTree(folder), root)
|
|
4551
|
+
if (!own && !sameDir(root, dir)) continue
|
|
4552
|
+
const copy = readSpecCopy(path.join(project, 'specs', bucket, folder))
|
|
4553
|
+
if (copy) copies.push({ folder, bucket, origin: own ? 'worktree' : 'here', ...copy })
|
|
4554
|
+
}
|
|
4555
|
+
}
|
|
4556
|
+
}
|
|
4557
|
+
let base = null
|
|
4558
|
+
try {
|
|
4559
|
+
base = resolveBaseBranch(config, git)
|
|
4560
|
+
} catch {
|
|
4561
|
+
// An unresolvable base hides branch-only specs; the disk copies still answer.
|
|
4562
|
+
}
|
|
4563
|
+
for (const b of specBranchDocs(git, config, base)) {
|
|
4564
|
+
copies.push({ folder: b.folder, bucket: b.bucket, origin: 'branch', local: b.local, ref: b.ref, overview: b.overview, phases: b.phases })
|
|
4565
|
+
}
|
|
4566
|
+
|
|
4567
|
+
// Bare means what every bare spec-env verb means: the worktree you are
|
|
4568
|
+
// standing in, else the sole provisioned spec. Neither answering leaves the
|
|
4569
|
+
// argument empty, and findTarget refuses that rather than guessing.
|
|
4570
|
+
if (!arg) {
|
|
4571
|
+
try {
|
|
4572
|
+
arg = resolveSpecWithWorktree(dir, config).folder
|
|
4573
|
+
} catch {
|
|
4574
|
+
arg = ''
|
|
4575
|
+
}
|
|
4576
|
+
}
|
|
4577
|
+
const identifierField = config.branch && config.branch.identifierField
|
|
4578
|
+
const found = findTarget(arg, copies, identifierField)
|
|
4579
|
+
if (found.refused) {
|
|
4580
|
+
process.exitCode = 1
|
|
4581
|
+
const r = { ok: false, refused: found.refused, refusedOnly: true }
|
|
4582
|
+
process.stdout.write(flags.json ? JSON.stringify({ ok: false, refused: found.refused }, null, 2) + '\n' : resumeLines(r).join('\n') + '\n')
|
|
4583
|
+
return
|
|
4584
|
+
}
|
|
4585
|
+
const target = found.target
|
|
4586
|
+
const remote = baseRemote(config)
|
|
4587
|
+
let branch
|
|
4588
|
+
if (target.origin === 'branch') {
|
|
4589
|
+
branch = target.ref.replace(/^refs\/heads\//, '').replace(new RegExp(`^refs/remotes/${remote}/`), '')
|
|
4590
|
+
} else {
|
|
4591
|
+
try {
|
|
4592
|
+
branch = resolveSpecWithWorktree(dir, config, target.folder).branch
|
|
4593
|
+
} catch {
|
|
4594
|
+
branch = resolveSpecless(target.folder, dir, config, { spec: true }).branch
|
|
4595
|
+
}
|
|
4596
|
+
}
|
|
4597
|
+
const worktreePath = ownTree(target.folder)
|
|
4598
|
+
const r = planResume(target, {
|
|
4599
|
+
branch,
|
|
4600
|
+
worktreePath,
|
|
4601
|
+
worktreeExists: fs.existsSync(worktreePath),
|
|
4602
|
+
localBranch: git(['show-ref', '--verify', '--quiet', `refs/heads/${branch}`]) !== null,
|
|
4603
|
+
remoteBranch: git(['show-ref', '--verify', '--quiet', `refs/remotes/${remote}/${branch}`]) !== null,
|
|
4604
|
+
remote,
|
|
4605
|
+
identifierField,
|
|
4606
|
+
})
|
|
4607
|
+
if (!r.ok) process.exitCode = 1
|
|
4608
|
+
process.stdout.write(flags.json ? JSON.stringify(r, null, 2) + '\n' : resumeLines(r).join('\n') + '\n')
|
|
4609
|
+
}
|
|
4610
|
+
|
|
4611
|
+
// A spec folder's overview and phase files, or null when it has no overview.
|
|
4612
|
+
function readSpecCopy(specDir) {
|
|
4613
|
+
let overview
|
|
4614
|
+
try {
|
|
4615
|
+
overview = fs.readFileSync(path.join(specDir, '00-overview.md'), 'utf8')
|
|
4616
|
+
} catch {
|
|
4617
|
+
return null
|
|
4618
|
+
}
|
|
4619
|
+
const phases = []
|
|
4620
|
+
for (const f of fs.readdirSync(specDir).filter((n) => /^(?!00-)\d{2}-.*\.md$/.test(n)).sort()) {
|
|
4621
|
+
try {
|
|
4622
|
+
phases.push({ n: Number(f.slice(0, 2)), text: fs.readFileSync(path.join(specDir, f), 'utf8') })
|
|
4623
|
+
} catch {
|
|
4624
|
+
// An unreadable phase file is left out, never counted as done or blocked.
|
|
4625
|
+
}
|
|
4626
|
+
}
|
|
4627
|
+
return { overview, phases }
|
|
4628
|
+
}
|
|
4629
|
+
|
|
4630
|
+
/**
|
|
4631
|
+
* `skitterspec spec-env base [--json] [--use-fallback | --unpin]`
|
|
4474
4632
|
*
|
|
4475
4633
|
* Which branch is the base, how it was found, and — under `baseBranchPattern` —
|
|
4476
4634
|
* every match newest-first plus the provisioned specs that forked from an older
|
|
4477
4635
|
* one. It fetches first, because the resolver itself never does: a release
|
|
4478
4636
|
* candidate cut since the last fetch is invisible to it.
|
|
4479
4637
|
*
|
|
4480
|
-
*
|
|
4481
|
-
*
|
|
4482
|
-
*
|
|
4638
|
+
* Bare, it lists only and always exits 0; the one thing it writes is deleting a
|
|
4639
|
+
* gap pin a match has retired. A failed fetch is reported and the listing
|
|
4640
|
+
* carries on from the refs already here.
|
|
4641
|
+
*
|
|
4642
|
+
* `--use-fallback` is the offer's command: it writes the gap pin
|
|
4643
|
+
* (`env/basepin.js`) when the pattern matches nothing and a fallback resolves.
|
|
4644
|
+
* `--unpin` removes it. Both exit 1 on a refusal, since a caller retries on 0.
|
|
4645
|
+
* A permanent pin stays a hand edit of `baseBranch`.
|
|
4483
4646
|
*/
|
|
4484
4647
|
function specEnvBase(dir, config, flags = {}) {
|
|
4648
|
+
if (flags.useFallback) return baseUseFallback(dir, config, flags)
|
|
4649
|
+
if (flags.unpin) return baseUnpin(dir, config, flags)
|
|
4650
|
+
|
|
4485
4651
|
const pattern = (config.baseBranchPattern || '').trim()
|
|
4486
4652
|
const remote = baseRemote(config)
|
|
4487
4653
|
const git = gitReader(dir)
|
|
@@ -4489,7 +4655,9 @@ function specEnvBase(dir, config, flags = {}) {
|
|
|
4489
4655
|
// No pattern: the base is today's chain, and there is nothing to fetch for —
|
|
4490
4656
|
// origin/HEAD is not updated by a fetch.
|
|
4491
4657
|
const fetch = fetchForPattern(dir, config)
|
|
4492
|
-
const
|
|
4658
|
+
const pin = pattern ? readBasePin(dir, config) : null
|
|
4659
|
+
const { base, how, stalePin, refused } = describeBaseBranch(config, git, pin)
|
|
4660
|
+
const pinCleared = Boolean(flags.pinRetired) || (Boolean(stalePin) && clearBasePin(dir, config))
|
|
4493
4661
|
|
|
4494
4662
|
let matches = []
|
|
4495
4663
|
let forks = []
|
|
@@ -4502,10 +4670,74 @@ function specEnvBase(dir, config, flags = {}) {
|
|
|
4502
4670
|
}))
|
|
4503
4671
|
}
|
|
4504
4672
|
|
|
4505
|
-
const { json, lines } = planBaseReport({
|
|
4673
|
+
const { json, lines } = planBaseReport({
|
|
4674
|
+
pattern,
|
|
4675
|
+
remote,
|
|
4676
|
+
base,
|
|
4677
|
+
how,
|
|
4678
|
+
fetch,
|
|
4679
|
+
matches,
|
|
4680
|
+
forks,
|
|
4681
|
+
pin,
|
|
4682
|
+
pinCleared,
|
|
4683
|
+
offer: refused ? refused.offer : null,
|
|
4684
|
+
})
|
|
4506
4685
|
process.stdout.write(flags.json ? JSON.stringify(json, null, 2) + '\n' : lines.join('\n') + '\n')
|
|
4507
4686
|
}
|
|
4508
4687
|
|
|
4688
|
+
// One answer for both pin verbs: a line of text, or `{ ok, ... }` as JSON.
|
|
4689
|
+
function basePinAnswer(flags, ok, line, extra = {}) {
|
|
4690
|
+
if (!ok) process.exitCode = 1
|
|
4691
|
+
process.stdout.write(flags.json ? JSON.stringify({ ok, ...extra, message: line }, null, 2) + '\n' : line + '\n')
|
|
4692
|
+
}
|
|
4693
|
+
|
|
4694
|
+
// WHAT WOULD FOOL THIS: an unfetched remote looks exactly like the gap — no
|
|
4695
|
+
// branch matches in either case. So it fetches first and will not pin on a
|
|
4696
|
+
// failed fetch: a pin made then could hold the base on the fallback while the
|
|
4697
|
+
// next release branch already exists on the remote.
|
|
4698
|
+
function baseUseFallback(dir, config, flags) {
|
|
4699
|
+
const pattern = (config.baseBranchPattern || '').trim()
|
|
4700
|
+
if (!pattern) {
|
|
4701
|
+
return basePinAnswer(flags, false, 'spec-env base: no baseBranchPattern is set — there is no gap to pin.')
|
|
4702
|
+
}
|
|
4703
|
+
const fetch = fetchForPattern(dir, config)
|
|
4704
|
+
if (fetch && !fetch.ok) {
|
|
4705
|
+
return basePinAnswer(
|
|
4706
|
+
flags,
|
|
4707
|
+
false,
|
|
4708
|
+
`spec-env base: fetch from ${baseRemote(config)} failed${fetch.reason ? ` (${fetch.reason})` : ''} — ` +
|
|
4709
|
+
`cannot tell whether a ${pattern} branch exists, so nothing was pinned.`,
|
|
4710
|
+
)
|
|
4711
|
+
}
|
|
4712
|
+
// null, not the attached pin: the question is whether the PATTERN matches.
|
|
4713
|
+
const { base, refused } = describeBaseBranch(config, gitReader(dir), null)
|
|
4714
|
+
if (base) {
|
|
4715
|
+
clearBasePin(dir, config)
|
|
4716
|
+
return basePinAnswer(flags, false, `spec-env base: ${base} matches ${pattern} — no gap to pin; it is the base.`, { base })
|
|
4717
|
+
}
|
|
4718
|
+
if (!refused || !refused.fallback) {
|
|
4719
|
+
return basePinAnswer(
|
|
4720
|
+
flags,
|
|
4721
|
+
false,
|
|
4722
|
+
`spec-env base: no branch matches ${pattern}, and no fallback resolves — set baseBranchFallback, ` +
|
|
4723
|
+
`or run git remote set-head ${baseRemote(config)} --auto.`,
|
|
4724
|
+
)
|
|
4725
|
+
}
|
|
4726
|
+
const pin = writeBasePin(dir, config, { base: refused.fallback, pattern })
|
|
4727
|
+
basePinAnswer(
|
|
4728
|
+
flags,
|
|
4729
|
+
true,
|
|
4730
|
+
`spec-env base: pinned ${pin.base} for the gap — no ${pattern} branch on ${baseRemote(config)}. ` +
|
|
4731
|
+
`It clears itself when one appears.`,
|
|
4732
|
+
{ base: pin.base, pin },
|
|
4733
|
+
)
|
|
4734
|
+
}
|
|
4735
|
+
|
|
4736
|
+
function baseUnpin(dir, config, flags) {
|
|
4737
|
+
const removed = clearBasePin(dir, config)
|
|
4738
|
+
basePinAnswer(flags, true, removed ? 'spec-env base: gap pin removed.' : 'spec-env base: no gap pin to remove.', { removed })
|
|
4739
|
+
}
|
|
4740
|
+
|
|
4509
4741
|
// Fetch the base's remote, but only where `baseBranchPattern` decides the base:
|
|
4510
4742
|
// the resolver reads remote-tracking refs and never the network, so a release
|
|
4511
4743
|
// candidate cut since the last fetch is invisible until something fetches. With
|
|
@@ -4623,6 +4855,20 @@ function provisionedBranches(dir, config) {
|
|
|
4623
4855
|
* Re-anchoring would silently answer about the wrong checkout, so the tree read
|
|
4624
4856
|
* is printed rather than assumed.
|
|
4625
4857
|
*/
|
|
4858
|
+
// `spec-env checks [spec]` — run the project's `complete.checks` in the spec's
|
|
4859
|
+
// worktree, for `/spec-complete` to relay before it lands. Always exits 0: the
|
|
4860
|
+
// checks inform the completion and never stop it (`env/checks.js`).
|
|
4861
|
+
function specEnvChecks(dir, config, specArg, flags = {}) {
|
|
4862
|
+
const spec = resolveSpecWithWorktree(dir, config, specArg)
|
|
4863
|
+
const { runChecks, formatChecks } = require('./env/checks.js')
|
|
4864
|
+
const results = runChecks(config.complete.checks, { cwd: spec.projectPath || spec.worktreePath })
|
|
4865
|
+
if (flags.json) {
|
|
4866
|
+
process.stdout.write(JSON.stringify({ spec: spec.folder, checks: results }, null, 2) + '\n')
|
|
4867
|
+
return
|
|
4868
|
+
}
|
|
4869
|
+
process.stdout.write(formatChecks(spec.folder, results) + '\n')
|
|
4870
|
+
}
|
|
4871
|
+
|
|
4626
4872
|
function specEnvStage(dir, config, specArg, flags = {}, invokedFrom = dir) {
|
|
4627
4873
|
const spec = resolveSpecWithWorktree(dir, config, specArg)
|
|
4628
4874
|
|
|
@@ -6053,12 +6299,16 @@ async function specEnvReview(dir, config, specArg, flags, invokedFrom = dir) {
|
|
|
6053
6299
|
// spec with no branch to put live (decision 6), so it carries neither key and
|
|
6054
6300
|
// renders exactly as it did before this existed.
|
|
6055
6301
|
const surfaceArgs = docs ? {} : { live, tiers: pageTiers(config) }
|
|
6302
|
+
// The words beside the base when a gap pin chose it; asked only where a base
|
|
6303
|
+
// is shown, which is the branch range.
|
|
6304
|
+
const baseGap = () => gapNote(config, trimmed)
|
|
6056
6305
|
let data = collectReview({
|
|
6057
6306
|
spec,
|
|
6058
6307
|
git,
|
|
6059
6308
|
mode,
|
|
6060
6309
|
ref,
|
|
6061
6310
|
base,
|
|
6311
|
+
baseGap: base ? baseGap() : null,
|
|
6062
6312
|
now,
|
|
6063
6313
|
notes,
|
|
6064
6314
|
gate,
|
|
@@ -6102,6 +6352,7 @@ async function specEnvReview(dir, config, specArg, flags, invokedFrom = dir) {
|
|
|
6102
6352
|
mode: 'branch',
|
|
6103
6353
|
ref: mergeBase,
|
|
6104
6354
|
base: fallbackBase,
|
|
6355
|
+
baseGap: baseGap(),
|
|
6105
6356
|
now,
|
|
6106
6357
|
notes,
|
|
6107
6358
|
gate,
|
|
@@ -6300,6 +6551,7 @@ async function specEnvReview(dir, config, specArg, flags, invokedFrom = dir) {
|
|
|
6300
6551
|
mode,
|
|
6301
6552
|
base,
|
|
6302
6553
|
fellBack,
|
|
6554
|
+
baseGap: data.baseGap,
|
|
6303
6555
|
// The paths a committing verdict on this page must commit, so the
|
|
6304
6556
|
// skill that routes on it never recomputes the set the reader saw.
|
|
6305
6557
|
// Absent for every other mode, which keeps their output identical.
|
|
@@ -6376,6 +6628,7 @@ async function specEnvReview(dir, config, specArg, flags, invokedFrom = dir) {
|
|
|
6376
6628
|
`spec-env review: ${spec.folder} (${
|
|
6377
6629
|
fellBack ? `working tree clean — since ${base}` : mode === 'branch' ? `since ${base}` : 'uncommitted'
|
|
6378
6630
|
})\n` +
|
|
6631
|
+
(data.baseGap ? ` base: ${base} — ${data.baseGap}\n` : '') +
|
|
6379
6632
|
` ${t.files} file${t.files === 1 ? '' : 's'}, +${t.additions} -${t.deletions}\n` +
|
|
6380
6633
|
(merged
|
|
6381
6634
|
? ` merged: ${merged.accepted} accept${merged.accepted === 1 ? '' : 's'}, ` +
|
|
@@ -7916,6 +8169,8 @@ async function specEnv(rest) {
|
|
|
7916
8169
|
else if (args[i] === '--cwd') flags.cwd = args[++i]
|
|
7917
8170
|
else if (args[i] === '--command') flags.command = args[++i] ?? ''
|
|
7918
8171
|
else if (args[i] === '--assert-primary-clean') flags.assertPrimaryClean = true
|
|
8172
|
+
else if (args[i] === '--use-fallback') flags.useFallback = true
|
|
8173
|
+
else if (args[i] === '--unpin') flags.unpin = true
|
|
7919
8174
|
else positional.push(args[i])
|
|
7920
8175
|
}
|
|
7921
8176
|
dir = path.resolve(dir)
|
|
@@ -7987,6 +8242,40 @@ async function specEnv(rest) {
|
|
|
7987
8242
|
}
|
|
7988
8243
|
}
|
|
7989
8244
|
|
|
8245
|
+
// A gap pin a match has retired is deleted here, the one point every
|
|
8246
|
+
// subcommand passes, so it cannot outlive the gap even when nobody runs
|
|
8247
|
+
// `spec-env base`. Only asked when a pin exists, so the common path pays
|
|
8248
|
+
// nothing. The resolver already ignores it; this just tidies the file.
|
|
8249
|
+
if (config.gapPin && describeBaseBranch(config, gitReader(dir)).stalePin) {
|
|
8250
|
+
clearBasePin(dir, config)
|
|
8251
|
+
flags.pinRetired = true
|
|
8252
|
+
}
|
|
8253
|
+
|
|
8254
|
+
try {
|
|
8255
|
+
await specEnvDispatch(sub, dir, config, positional, flags, present, invokedFrom)
|
|
8256
|
+
} catch (error) {
|
|
8257
|
+
if (!(error instanceof BaseUnresolvedError)) throw error
|
|
8258
|
+
baseRefusal(sub, error, flags)
|
|
8259
|
+
}
|
|
8260
|
+
}
|
|
8261
|
+
|
|
8262
|
+
// A base that will not resolve, said with the way out where the engine has one
|
|
8263
|
+
// (`.claude/rules/offered-unblocks.md`): the refusal first, then the offer.
|
|
8264
|
+
// stdout and exit 1, so a skill reads it whether or not it asked for --json.
|
|
8265
|
+
function baseRefusal(sub, error, flags) {
|
|
8266
|
+
process.exitCode = 1
|
|
8267
|
+
if (flags.json) {
|
|
8268
|
+
const out = { blocked: true, reason: error.refused }
|
|
8269
|
+
if (error.offer) out.offer = error.offer
|
|
8270
|
+
process.stdout.write(JSON.stringify(out, null, 2) + '\n')
|
|
8271
|
+
return
|
|
8272
|
+
}
|
|
8273
|
+
const lines = [`spec-env ${sub}: ${error.refused}`]
|
|
8274
|
+
if (error.offer) lines.push(` offer: ${error.offer.label} — ${error.offer.command}`)
|
|
8275
|
+
process.stdout.write(lines.join('\n') + '\n')
|
|
8276
|
+
}
|
|
8277
|
+
|
|
8278
|
+
async function specEnvDispatch(sub, dir, config, positional, flags, present, invokedFrom) {
|
|
7990
8279
|
switch (sub) {
|
|
7991
8280
|
case 'up':
|
|
7992
8281
|
specEnvUp(dir, config, positional[0], flags)
|
|
@@ -8033,12 +8322,18 @@ async function specEnv(rest) {
|
|
|
8033
8322
|
case 'resolve':
|
|
8034
8323
|
specEnvResolve(dir, config, positional[0], flags)
|
|
8035
8324
|
break
|
|
8325
|
+
case 'resume':
|
|
8326
|
+
specEnvResume(dir, config, positional[0], flags)
|
|
8327
|
+
break
|
|
8036
8328
|
case 'base':
|
|
8037
8329
|
specEnvBase(dir, config, flags)
|
|
8038
8330
|
break
|
|
8039
8331
|
case 'stage':
|
|
8040
8332
|
specEnvStage(dir, config, positional[0], flags, invokedFrom)
|
|
8041
8333
|
break
|
|
8334
|
+
case 'checks':
|
|
8335
|
+
specEnvChecks(dir, config, positional[0], flags)
|
|
8336
|
+
break
|
|
8042
8337
|
case 'review':
|
|
8043
8338
|
// `serve` is the one review sub-action rather than a verb of its own: it
|
|
8044
8339
|
// answers the same question ("show me this diff") from the same engine,
|
|
@@ -8203,7 +8498,7 @@ async function run(argv) {
|
|
|
8203
8498
|
break
|
|
8204
8499
|
}
|
|
8205
8500
|
if (action === 'resync') {
|
|
8206
|
-
resync(dir, { claudeMd: opts.claudeMd, force: opts.force, diff: opts.diff })
|
|
8501
|
+
resync(dir, { claudeMd: opts.claudeMd, force: opts.force, diff: opts.diff, local: opts.local })
|
|
8207
8502
|
break
|
|
8208
8503
|
}
|
|
8209
8504
|
// action === 'create-missing' → fall through to a normal (skip-existing) init.
|
|
@@ -8230,6 +8525,7 @@ async function run(argv) {
|
|
|
8230
8525
|
workspaceMode,
|
|
8231
8526
|
gating,
|
|
8232
8527
|
project: opts.project,
|
|
8528
|
+
local: opts.local,
|
|
8233
8529
|
})
|
|
8234
8530
|
break
|
|
8235
8531
|
}
|
|
@@ -8241,7 +8537,7 @@ async function run(argv) {
|
|
|
8241
8537
|
checkSync(dir, { claudeMd: opts.claudeMd })
|
|
8242
8538
|
break
|
|
8243
8539
|
}
|
|
8244
|
-
resync(dir, { claudeMd: opts.claudeMd, force: opts.force, diff: opts.diff })
|
|
8540
|
+
resync(dir, { claudeMd: opts.claudeMd, force: opts.force, diff: opts.diff, local: opts.local })
|
|
8245
8541
|
await cleanupReleaseTooling(dir, opts)
|
|
8246
8542
|
break
|
|
8247
8543
|
default:
|
package/src/env/base.js
CHANGED
|
@@ -5,14 +5,16 @@
|
|
|
5
5
|
* which in-flight specs forked from an older one.
|
|
6
6
|
*
|
|
7
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 —
|
|
9
|
-
* is a hand edit of `baseBranch`, deliberately without a verb
|
|
10
|
-
*
|
|
8
|
+
* facts in. Nothing here touches git, and nothing here edits config — a
|
|
9
|
+
* permanent pin is a hand edit of `baseBranch`, deliberately without a verb.
|
|
10
|
+
* The gap pin is different (`env/basepin.js`): local, temporary, and retired by
|
|
11
|
+
* the next match, so `--use-fallback` and `--unpin` are its verbs.
|
|
11
12
|
*/
|
|
12
13
|
|
|
13
14
|
const HOW = Object.freeze({
|
|
14
15
|
pin: 'pinned by baseBranch',
|
|
15
16
|
pattern: 'newest match',
|
|
17
|
+
'gap-pin': 'pinned for the gap',
|
|
16
18
|
'origin-head': 'origin/HEAD',
|
|
17
19
|
local: 'local branch',
|
|
18
20
|
fallback: 'nothing detected — default',
|
|
@@ -44,7 +46,10 @@ function forkMatch(matches, mergeBase, isAncestor) {
|
|
|
44
46
|
/**
|
|
45
47
|
* Build the report. `facts`:
|
|
46
48
|
* { pattern, remote, base, how, fetch: { ok, reason } | null,
|
|
47
|
-
* matches: [{ name, date }] (newest first), forks: [{ spec, forkedFrom }]
|
|
49
|
+
* matches: [{ name, date }] (newest first), forks: [{ spec, forkedFrom }],
|
|
50
|
+
* pin: { base, pattern, pinnedAt } | null — the gap pin in force,
|
|
51
|
+
* pinCleared: bool — a match retired a pin on this run,
|
|
52
|
+
* offer: { kind, label, command } | null — no match and no pin }
|
|
48
53
|
* Returns `{ json, lines }`; the CLI prints one of them and always exits 0.
|
|
49
54
|
*/
|
|
50
55
|
function planBaseReport(facts) {
|
|
@@ -67,6 +72,9 @@ function planBaseReport(facts) {
|
|
|
67
72
|
fetch,
|
|
68
73
|
matches: matches.map((m) => ({ ...m, base: m.name === base })),
|
|
69
74
|
stale,
|
|
75
|
+
pin: how === 'gap-pin' ? facts.pin || null : null,
|
|
76
|
+
pinCleared: Boolean(facts.pinCleared),
|
|
77
|
+
offer: facts.offer || null,
|
|
70
78
|
}
|
|
71
79
|
|
|
72
80
|
const lines = []
|
|
@@ -75,7 +83,8 @@ function planBaseReport(facts) {
|
|
|
75
83
|
return { json, lines }
|
|
76
84
|
}
|
|
77
85
|
|
|
78
|
-
if (
|
|
86
|
+
if (how === 'gap-pin') lines.push(`spec-env base: ${base} — no ${pattern} branch on ${remote} (${HOW[how]})`)
|
|
87
|
+
else if (base) lines.push(`spec-env base: ${base} (${HOW[how]}${how === 'pin' ? ` — ${pattern} not used` : ` for ${pattern}`})`)
|
|
79
88
|
else lines.push(`spec-env base: none — no branch on ${remote} matches ${pattern}`)
|
|
80
89
|
|
|
81
90
|
if (fetch) {
|
|
@@ -94,6 +103,13 @@ function planBaseReport(facts) {
|
|
|
94
103
|
}
|
|
95
104
|
}
|
|
96
105
|
|
|
106
|
+
if (how === 'gap-pin') {
|
|
107
|
+
const since = facts.pin && facts.pin.pinnedAt ? ` since ${facts.pin.pinnedAt.slice(0, 10)}` : ''
|
|
108
|
+
lines.push(` pinned${since} · clears itself when a ${pattern} branch appears · --unpin removes it now`)
|
|
109
|
+
}
|
|
110
|
+
if (facts.pinCleared) lines.push(` gap pin cleared — ${base} matches ${pattern}`)
|
|
111
|
+
if (!base && facts.offer) lines.push(` offer: ${facts.offer.label} — ${facts.offer.command}`)
|
|
112
|
+
|
|
97
113
|
if (stale.length) {
|
|
98
114
|
lines.push(' forked from an older match:')
|
|
99
115
|
for (const s of stale) lines.push(` ${s.spec} · forked from ${s.forkedFrom}`)
|