@skitterbyte/skitterspec-linear 19.2.0 → 19.4.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/env.config.json.example +1 -0
- package/assets/core/env.config.md +90 -6
- package/assets/core/linear.config.json.example +2 -2
- package/assets/core/linear.config.md +49 -16
- package/assets/hooks/main-guard.cjs +18 -2
- package/assets/hooks/review-gate.cjs +19 -2
- package/assets/rules/commit-trailers.md +24 -1
- package/assets/rules/spec-planning.md +131 -18
- package/assets/rules/spec-reports.md +1 -1
- package/assets/skills/spec/SKILL.md +95 -6
- package/assets/skills/spec-bug/SKILL.md +68 -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 +72 -4
- package/assets/skills/spec-incident/SKILL.md +44 -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 +1091 -39
- package/src/env/base.js +104 -0
- package/src/env/config.js +75 -3
- package/src/env/disposition.js +62 -0
- package/src/env/handoff.js +80 -0
- package/src/env/host.js +262 -0
- package/src/env/hotfix.js +225 -0
- package/src/env/hotfixland.js +103 -9
- package/src/env/inflight.js +95 -0
- package/src/env/integrate.js +130 -4
- package/src/env/mainguard.js +6 -0
- package/src/env/phases.js +28 -0
- package/src/env/provision.js +18 -6
- package/src/env/resolve.js +108 -9
- package/src/env/serve.js +6 -1
- package/src/env/specstate.js +101 -0
- package/src/env/teardown.js +42 -0
- package/src/vendor/linear/cli-sync.js +55 -6
- 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 +49 -4
- 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/list-rows.js +35 -11
- package/src/vendor/provider-kit/src/released.js +14 -1
- package/src/vendor/provider-kit/src/specs.js +4 -2
- 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 +17 -5
- package/src/vendor/sync-core/src/normalize.js +50 -7
- package/src/vendor/sync-core/src/push.js +26 -2
- package/src/vendor/sync-core/src/summary.js +257 -0
package/src/env/mainguard.js
CHANGED
|
@@ -13,6 +13,12 @@
|
|
|
13
13
|
* worktree, and `/no-spec` gives mechanical work a branch of its own. So the
|
|
14
14
|
* guard is a push toward a path that exists rather than a refusal with no exit.
|
|
15
15
|
*
|
|
16
|
+
* PR MODE CHANGES THE REASON, NOT THE BEHAVIOUR. Under `land.strategy: "pr"`
|
|
17
|
+
* the base branch moves when the host merges, so "where work lands" is the
|
|
18
|
+
* remote — which makes a local write on base MORE wrong, not less: it can
|
|
19
|
+
* never reach the remote base except by a push nobody reviews. The guard fires
|
|
20
|
+
* exactly as before.
|
|
21
|
+
*
|
|
16
22
|
* THE ACCUSATION IS POSITIVE, AND ALL FOUR PARTS MUST HOLD. It is
|
|
17
23
|
* `.claude/rules/negative-checks.md` rule 1 applied to a check that stops
|
|
18
24
|
* someone working: isolation is configured, the guard is not switched off, this
|
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
'use strict'
|
|
2
|
+
|
|
3
|
+
/**
|
|
4
|
+
* Phase progress, read off the phase files' H1 emoji — the same emoji the phase
|
|
5
|
+
* index mirrors, and the one `/spec-review` names as authoritative.
|
|
6
|
+
*
|
|
7
|
+
* Shared by `spec-env handoff` (the ticket note) and the spec-state reader
|
|
8
|
+
* behind `skitterspec status`, so the two can never count one spec differently.
|
|
9
|
+
* Pure: each phase arrives as `{ file, content }`.
|
|
10
|
+
*/
|
|
11
|
+
|
|
12
|
+
// How many are ✅, how many there are, and the first 🔄 (where the next owner
|
|
13
|
+
// picks up).
|
|
14
|
+
function phaseProgress(phases) {
|
|
15
|
+
const named = (phases || []).filter((p) => p && typeof p.content === 'string')
|
|
16
|
+
const heading = (p) => (p.content.split('\n').find((l) => /^#\s/.test(l)) || '').trim()
|
|
17
|
+
const done = named.filter((p) => heading(p).endsWith('✅')).length
|
|
18
|
+
const current = named.findIndex((p) => heading(p).endsWith('🔄'))
|
|
19
|
+
return { done, total: named.length, current: current === -1 ? null : current + 1 }
|
|
20
|
+
}
|
|
21
|
+
|
|
22
|
+
function progressText({ done, total, current }) {
|
|
23
|
+
if (!total) return 'no phase files'
|
|
24
|
+
const base = `${done} of ${total} phases done`
|
|
25
|
+
return current ? `${base}, phase ${current} in progress` : base
|
|
26
|
+
}
|
|
27
|
+
|
|
28
|
+
module.exports = { phaseProgress, progressText }
|
package/src/env/provision.js
CHANGED
|
@@ -351,12 +351,24 @@ function planUp(spec, alloc, config, ctx, opts = {}) {
|
|
|
351
351
|
// A hotfix forks its fresh branch from a release tag (`spec.baseRef`, e.g.
|
|
352
352
|
// `v33.16.4`) instead of base HEAD — so the fix is built on the exact commit
|
|
353
353
|
// line prod runs. Attaching an existing branch ignores baseRef (already forked).
|
|
354
|
-
|
|
355
|
-
|
|
356
|
-
|
|
357
|
-
|
|
358
|
-
|
|
359
|
-
|
|
354
|
+
// A rolling base sets `spec.forkFrom` when the primary checkout is not on it.
|
|
355
|
+
// A branch already published (`spec.resumeFrom` — a handed-over spec) is
|
|
356
|
+
// fetched and built from instead: the work is there, and a fresh fork would
|
|
357
|
+
// strand it. It outranks every fork point, a hotfix's tag included, because
|
|
358
|
+
// the branch already forked from wherever it was meant to.
|
|
359
|
+
const forkFrom = spec.baseRef || spec.forkFrom
|
|
360
|
+
const forkPoint = !attached && forkFrom ? ` ${forkFrom}` : ''
|
|
361
|
+
const resume = !attached && spec.resumeFrom ? spec.resumeFrom : null
|
|
362
|
+
if (resume) {
|
|
363
|
+
commands.push(`git fetch ${resume.remote} ${spec.branch}`)
|
|
364
|
+
commands.push(`git worktree add ${spec.worktreePath} -b ${spec.branch} --track ${resume.remote}/${spec.branch}`)
|
|
365
|
+
} else {
|
|
366
|
+
commands.push(
|
|
367
|
+
attached
|
|
368
|
+
? `git worktree add ${spec.worktreePath} ${spec.branch}`
|
|
369
|
+
: `git worktree add ${spec.worktreePath} -b ${spec.branch}${forkPoint}`,
|
|
370
|
+
)
|
|
371
|
+
}
|
|
360
372
|
// The tree gate. A worktree forks from the base branch's tree, so an
|
|
361
373
|
// uncommitted spec would produce a branch missing the spec it is for — this is
|
|
362
374
|
// where that gets committed, or refused. Worktree mode had NO clean gate before
|
package/src/env/resolve.js
CHANGED
|
@@ -384,6 +384,27 @@ function readBaseVersionField(specPath) {
|
|
|
384
384
|
return m[1].trim().replace(/^["'`]|["'`]$/g, '') || null
|
|
385
385
|
}
|
|
386
386
|
|
|
387
|
+
/**
|
|
388
|
+
* Parse a `Base version` value. Two forms:
|
|
389
|
+
* - a release tag, `v33.16.4` → `{ kind: 'tag', tag, ref }`
|
|
390
|
+
* - a release BRANCH at a commit, `master@1a2b3c4d5e6f` → `{ kind: 'branch',
|
|
391
|
+
* branch, sha, ref }`, written by a branch-based hotfix (`hotfix.releaseBranch`)
|
|
392
|
+
* `ref` is what a worktree forks from: the tag, or the sha — never the branch
|
|
393
|
+
* name, which has moved on since the hotfix was cut.
|
|
394
|
+
*
|
|
395
|
+
* WHAT WOULD FOOL THIS: a tag literally shaped `<name>@<7–40 hex chars>`. Version
|
|
396
|
+
* tags carry dots (`skitterspec@1.4.0`), so they never match; a tag that did
|
|
397
|
+
* would be read as a branch form and fork from that sha, which is the commit
|
|
398
|
+
* the tag points at only if someone named it that way on purpose.
|
|
399
|
+
*/
|
|
400
|
+
function parseBaseVersion(value) {
|
|
401
|
+
if (typeof value !== 'string' || !value.trim()) return null
|
|
402
|
+
const v = value.trim()
|
|
403
|
+
const m = /^([^@\s]+)@([0-9a-f]{7,40})$/i.exec(v)
|
|
404
|
+
if (m) return { kind: 'branch', branch: m[1], sha: m[2], ref: m[2] }
|
|
405
|
+
return { kind: 'tag', tag: v, ref: v }
|
|
406
|
+
}
|
|
407
|
+
|
|
387
408
|
/**
|
|
388
409
|
* Derive the git branch for a spec from the provider-neutral `branch.pattern`
|
|
389
410
|
* (`{type}`, `{slug}`, and optionally `{identifier}`). When the pattern uses
|
|
@@ -404,31 +425,102 @@ function branchFor(spec, config) {
|
|
|
404
425
|
return expandTokens(branch, tokens)
|
|
405
426
|
}
|
|
406
427
|
|
|
428
|
+
/**
|
|
429
|
+
* Thrown when `baseBranchPattern` is set and no remote branch matches it. A
|
|
430
|
+
* refusal, never a fall-through: the default branch is exactly where a rolling
|
|
431
|
+
* base must not land. `refused` carries the one-line reason; `pattern` the glob.
|
|
432
|
+
*/
|
|
433
|
+
class BaseUnresolvedError extends Error {
|
|
434
|
+
constructor(pattern) {
|
|
435
|
+
const refused = `no branch matches ${pattern} — run spec-env base to fetch`
|
|
436
|
+
super(refused)
|
|
437
|
+
this.name = 'BaseUnresolvedError'
|
|
438
|
+
this.refused = refused
|
|
439
|
+
this.pattern = pattern
|
|
440
|
+
}
|
|
441
|
+
}
|
|
442
|
+
|
|
407
443
|
/**
|
|
408
444
|
* Resolve the integration base branch (the branch specs fork from and land back
|
|
409
445
|
* onto). Precedence:
|
|
410
446
|
* 1. `config.baseBranch` — explicit override
|
|
411
|
-
* 2. `
|
|
412
|
-
*
|
|
413
|
-
*
|
|
414
|
-
*
|
|
447
|
+
* 2. `config.baseBranchPattern` — the newest remote branch matching it, by
|
|
448
|
+
* committer date; no match throws `BaseUnresolvedError`
|
|
449
|
+
* 3. `origin/HEAD` — the remote's default branch
|
|
450
|
+
* 4. `main` if it exists locally
|
|
451
|
+
* 5. `master` if it exists locally
|
|
452
|
+
* 6. `main` — last-resort default
|
|
415
453
|
*
|
|
416
454
|
* `git(args)` runs a read-only git command and returns trimmed stdout, or `null`
|
|
417
455
|
* on a non-zero exit / failure. It's injected so this stays pure and unit-testable
|
|
418
456
|
* with no live git; the CLI supplies a real reader. (Note: `show-ref --quiet`
|
|
419
457
|
* emits no stdout on success, so a non-null `''` still means "exists".)
|
|
458
|
+
*
|
|
459
|
+
* Step 2 reads remote-tracking refs and never the network, so it stays
|
|
460
|
+
* synchronous for every caller, the main-guard hook included. Fetching is left
|
|
461
|
+
* to the commands that already talk to the remote.
|
|
420
462
|
*/
|
|
421
463
|
function resolveBaseBranch(config, git) {
|
|
464
|
+
const { base, refused } = describeBaseBranch(config, git)
|
|
465
|
+
if (refused) throw refused
|
|
466
|
+
return base
|
|
467
|
+
}
|
|
468
|
+
|
|
469
|
+
/**
|
|
470
|
+
* The same resolution as `resolveBaseBranch`, returned as data with HOW it was
|
|
471
|
+
* found — `pin` · `pattern` · `origin-head` · `local` · `fallback` — for the
|
|
472
|
+
* one surface that reports it (`spec-env base`). A pattern with no match comes
|
|
473
|
+
* back as `{ base: null, how: 'pattern', refused }` rather than thrown, so a
|
|
474
|
+
* listing can still say what it saw.
|
|
475
|
+
*/
|
|
476
|
+
function describeBaseBranch(config, git) {
|
|
422
477
|
const explicit = config && typeof config.baseBranch === 'string' && config.baseBranch.trim()
|
|
423
|
-
if (explicit) return explicit
|
|
478
|
+
if (explicit) return { base: explicit, how: 'pin' }
|
|
479
|
+
|
|
480
|
+
const pattern = config && typeof config.baseBranchPattern === 'string' && config.baseBranchPattern.trim()
|
|
481
|
+
if (pattern) {
|
|
482
|
+
try {
|
|
483
|
+
return { base: newestMatch(config, git, pattern), how: 'pattern' }
|
|
484
|
+
} catch (error) {
|
|
485
|
+
if (error instanceof BaseUnresolvedError) return { base: null, how: 'pattern', refused: error }
|
|
486
|
+
throw error
|
|
487
|
+
}
|
|
488
|
+
}
|
|
424
489
|
|
|
425
490
|
const originHead = git(['symbolic-ref', '--short', 'refs/remotes/origin/HEAD'])
|
|
426
|
-
if (originHead) return originHead.replace(/^origin\//, '')
|
|
491
|
+
if (originHead) return { base: originHead.replace(/^origin\//, ''), how: 'origin-head' }
|
|
427
492
|
|
|
428
493
|
for (const name of ['main', 'master']) {
|
|
429
|
-
if (git(['show-ref', '--verify', '--quiet', `refs/heads/${name}`]) !== null) return name
|
|
494
|
+
if (git(['show-ref', '--verify', '--quiet', `refs/heads/${name}`]) !== null) return { base: name, how: 'local' }
|
|
430
495
|
}
|
|
431
|
-
return 'main'
|
|
496
|
+
return { base: 'main', how: 'fallback' }
|
|
497
|
+
}
|
|
498
|
+
|
|
499
|
+
// The newest remote-tracking branch matching `pattern`, prefix stripped.
|
|
500
|
+
//
|
|
501
|
+
// WHAT WOULD FOOL THIS: an unfetched remote. A release candidate cut since the
|
|
502
|
+
// last fetch is invisible here, and no rc at all looks identical to "never
|
|
503
|
+
// fetched" — so an empty answer refuses rather than concluding anything, and
|
|
504
|
+
// names the verb that fetches. A stale-but-present answer is the older rc;
|
|
505
|
+
// `up` and `integrate` fetch before resolving so they never act on one.
|
|
506
|
+
function baseRemote(config) {
|
|
507
|
+
return (config && config.land && typeof config.land.remote === 'string' && config.land.remote.trim()) || 'origin'
|
|
508
|
+
}
|
|
509
|
+
|
|
510
|
+
function newestMatch(config, git, pattern) {
|
|
511
|
+
const remote = baseRemote(config)
|
|
512
|
+
const prefix = `refs/remotes/${remote}/`
|
|
513
|
+
const out = git(['for-each-ref', '--sort=-committerdate', '--format=%(refname)', `${prefix}${pattern}`])
|
|
514
|
+
const names = (out || '')
|
|
515
|
+
.split('\n')
|
|
516
|
+
.map((line) => line.trim())
|
|
517
|
+
.filter((ref) => ref.startsWith(prefix))
|
|
518
|
+
.map((ref) => ref.slice(prefix.length))
|
|
519
|
+
// `origin/HEAD` is a symref to the default branch, and a broad pattern
|
|
520
|
+
// (`*`) would otherwise match it.
|
|
521
|
+
.filter((name) => name && name !== 'HEAD')
|
|
522
|
+
if (names.length === 0) throw new BaseUnresolvedError(pattern)
|
|
523
|
+
return names[0]
|
|
432
524
|
}
|
|
433
525
|
|
|
434
526
|
/**
|
|
@@ -528,6 +620,7 @@ function resolveSpecless(name, dir, config, entry = {}) {
|
|
|
528
620
|
slug,
|
|
529
621
|
stack: 'worktree',
|
|
530
622
|
baseRef: null,
|
|
623
|
+
baseVersion: null,
|
|
531
624
|
specless: true,
|
|
532
625
|
unwritten: authored,
|
|
533
626
|
}
|
|
@@ -580,7 +673,8 @@ function resolveSpec(specArg, dir, config, opts = {}) {
|
|
|
580
673
|
const stack = readStackField(found.path, config)
|
|
581
674
|
// A hotfix forks its worktree from a release tag (its `Base version`) instead
|
|
582
675
|
// of base HEAD; every other type resolves to baseRef:null (fork from HEAD).
|
|
583
|
-
const
|
|
676
|
+
const baseVersion = type === 'hotfix' ? parseBaseVersion(readBaseVersionField(found.path)) : null
|
|
677
|
+
const baseRef = baseVersion ? baseVersion.ref : null
|
|
584
678
|
// `specless: false` is written out rather than left off, so every consumer
|
|
585
679
|
// reads the same field on every resolution instead of treating `undefined` as
|
|
586
680
|
// an answer.
|
|
@@ -592,6 +686,7 @@ function resolveSpec(specArg, dir, config, opts = {}) {
|
|
|
592
686
|
slug,
|
|
593
687
|
stack,
|
|
594
688
|
baseRef,
|
|
689
|
+
baseVersion,
|
|
595
690
|
specless: false,
|
|
596
691
|
}
|
|
597
692
|
const branch = branchFor(spec, config)
|
|
@@ -705,6 +800,9 @@ module.exports = {
|
|
|
705
800
|
collectSpecFolders,
|
|
706
801
|
allSpecs,
|
|
707
802
|
resolveBaseBranch,
|
|
803
|
+
describeBaseBranch,
|
|
804
|
+
baseRemote,
|
|
805
|
+
BaseUnresolvedError,
|
|
708
806
|
resolvePrimaryCheckout,
|
|
709
807
|
currentBranch,
|
|
710
808
|
assertPrimaryOnMain,
|
|
@@ -721,4 +819,5 @@ module.exports = {
|
|
|
721
819
|
readFrontmatterField,
|
|
722
820
|
readStackField,
|
|
723
821
|
readBaseVersionField,
|
|
822
|
+
parseBaseVersion,
|
|
724
823
|
}
|
package/src/env/serve.js
CHANGED
|
@@ -40,6 +40,7 @@ const { readRegistry } = require('./registry.js')
|
|
|
40
40
|
const { loadEnvConfig } = require('./config.js')
|
|
41
41
|
const { specDocsIn, classifyDirtyTree, dirtyPaths } = require('./classify.js')
|
|
42
42
|
const { liveStateFor } = require('./live.js')
|
|
43
|
+
const { preferRemoteBase } = require('./host.js')
|
|
43
44
|
const {
|
|
44
45
|
rawGitReader,
|
|
45
46
|
collectReview,
|
|
@@ -557,7 +558,11 @@ function renderSpecPage(dir, config, spec, { branch = false } = {}) {
|
|
|
557
558
|
const out = git(argv)
|
|
558
559
|
return out == null ? null : String(out).trim() || null
|
|
559
560
|
}
|
|
560
|
-
|
|
561
|
+
// PR mode measures the diff against the REMOTE image of base — local base is
|
|
562
|
+
// allowed to go stale there. `preferRemoteBase` never fetches and falls back
|
|
563
|
+
// to the local name, so the render stays offline-safe.
|
|
564
|
+
const base = () =>
|
|
565
|
+
spec.baseRef || preferRemoteBase(config, resolveBaseBranch(config, trimmed), trimmed)
|
|
561
566
|
|
|
562
567
|
const now = new Date().toISOString()
|
|
563
568
|
let mode = 'working'
|
|
@@ -0,0 +1,101 @@
|
|
|
1
|
+
'use strict'
|
|
2
|
+
|
|
3
|
+
/**
|
|
4
|
+
* What a spec's own copy says about it — the reader behind `skitterspec status`.
|
|
5
|
+
*
|
|
6
|
+
* Point it at a worktree (or any checkout) and a spec folder name, and it reports
|
|
7
|
+
* the bucket the spec sits in THERE, its phase progress, and any `Status:` /
|
|
8
|
+
* `Developer:` header it still carries. Pure but for the injected `io`, so the
|
|
9
|
+
* command layer is testable without a worktree and this without a CLI.
|
|
10
|
+
*
|
|
11
|
+
* THE BUCKET IS READ FROM THE ROOT IT IS GIVEN. On the base branch an in-flight
|
|
12
|
+
* spec still sits in `backlog/`, which is the very lie this exists to correct, so
|
|
13
|
+
* the caller hands it the worktree's root, never the checkout it is standing in.
|
|
14
|
+
*
|
|
15
|
+
* A MISSING `Status:` HEADER IS NOT UNKNOWN. Under `sync.fieldOwnership`
|
|
16
|
+
* `workflowState: "pull"` new specs carry no `Status:` or `Developer:` line —
|
|
17
|
+
* the board owns both — so `status: null` is the expected shape, and the bucket
|
|
18
|
+
* and progress still answer. Only a spec that cannot be found or read is
|
|
19
|
+
* `found: false`, and the caller renders that as `status unknown` rather than
|
|
20
|
+
* dropping it (Decision 5).
|
|
21
|
+
*/
|
|
22
|
+
|
|
23
|
+
const fs = require('node:fs')
|
|
24
|
+
const path = require('node:path')
|
|
25
|
+
|
|
26
|
+
const { phaseProgress } = require('./phases.js')
|
|
27
|
+
|
|
28
|
+
// Most live first: a spec that exists in two buckets mid-`git mv` is reported
|
|
29
|
+
// where it is going, not where it was.
|
|
30
|
+
const SEARCH = ['in-progress', 'backlog', 'complete', 'cancelled']
|
|
31
|
+
|
|
32
|
+
const defaultIo = {
|
|
33
|
+
readdir: (dir) => fs.readdirSync(dir),
|
|
34
|
+
readFile: (file) => fs.readFileSync(file, 'utf8'),
|
|
35
|
+
}
|
|
36
|
+
|
|
37
|
+
// A header line's value, or null when the line is absent, empty, or the `—`
|
|
38
|
+
// placeholder the templates write before anyone is named.
|
|
39
|
+
function header(text, field) {
|
|
40
|
+
const m = new RegExp(`^>\\s*\\*\\*${field}:\\*\\*[ \\t]*(.*)$`, 'm').exec(text)
|
|
41
|
+
if (!m) return null
|
|
42
|
+
const value = m[1].trim()
|
|
43
|
+
return value && value !== '—' && value !== '-' ? value : null
|
|
44
|
+
}
|
|
45
|
+
|
|
46
|
+
// Inline phases, for the legacy overview with no phase files: `## Phase N …`
|
|
47
|
+
// headings carrying the same emoji the phase files do. Nothing countable is
|
|
48
|
+
// null, never zero — "no phases" and "could not see the phases" differ.
|
|
49
|
+
function inlineProgress(text) {
|
|
50
|
+
const headings = text.split('\n').filter((l) => /^#{2,3}\s+Phase\s+\d+\b/.test(l))
|
|
51
|
+
if (!headings.length) return null
|
|
52
|
+
return phaseProgress(headings.map((h) => ({ content: h.replace(/^#+/, '#') })))
|
|
53
|
+
}
|
|
54
|
+
|
|
55
|
+
function tryRead(io, fn) {
|
|
56
|
+
try {
|
|
57
|
+
return fn()
|
|
58
|
+
} catch {
|
|
59
|
+
return null
|
|
60
|
+
}
|
|
61
|
+
}
|
|
62
|
+
|
|
63
|
+
/**
|
|
64
|
+
* @param {string} root the checkout to read — a spec's worktree, normally
|
|
65
|
+
* @param {string} folder the spec's folder name (`feat-x`)
|
|
66
|
+
* @param {object} [io] `{ readdir, readFile }`, each throwing on failure
|
|
67
|
+
* @returns {{ found: true, bucket, legacy, phasesDone, phasesTotal, currentPhase, status, developer }
|
|
68
|
+
* | { found: false, reason }}
|
|
69
|
+
*/
|
|
70
|
+
function readSpecState(root, folder, io = defaultIo) {
|
|
71
|
+
for (const bucket of SEARCH) {
|
|
72
|
+
const dir = path.join(root, 'specs', bucket, folder)
|
|
73
|
+
const files = tryRead(io, () => io.readdir(dir))
|
|
74
|
+
if (files) {
|
|
75
|
+
const overview = tryRead(io, () => io.readFile(path.join(dir, '00-overview.md')))
|
|
76
|
+
if (overview === null) return { found: false, reason: `${bucket}/${folder} has no readable 00-overview.md` }
|
|
77
|
+
const phaseFiles = files.filter((f) => /^(?!00-)\d{2}-.*\.md$/.test(f)).sort()
|
|
78
|
+
const phases = phaseFiles.map((f) => ({ file: f, content: tryRead(io, () => io.readFile(path.join(dir, f))) }))
|
|
79
|
+
const progress = phases.length ? phaseProgress(phases) : inlineProgress(overview)
|
|
80
|
+
return state(bucket, false, overview, progress)
|
|
81
|
+
}
|
|
82
|
+
const bare = tryRead(io, () => io.readFile(path.join(root, 'specs', bucket, `${folder}.md`)))
|
|
83
|
+
if (bare !== null) return state(bucket, true, bare, inlineProgress(bare))
|
|
84
|
+
}
|
|
85
|
+
return { found: false, reason: `no spec named ${folder} under specs/` }
|
|
86
|
+
}
|
|
87
|
+
|
|
88
|
+
function state(bucket, legacy, text, progress) {
|
|
89
|
+
return {
|
|
90
|
+
found: true,
|
|
91
|
+
bucket,
|
|
92
|
+
legacy,
|
|
93
|
+
phasesDone: progress ? progress.done : null,
|
|
94
|
+
phasesTotal: progress ? progress.total : null,
|
|
95
|
+
currentPhase: progress ? progress.current : null,
|
|
96
|
+
status: header(text, 'Status'),
|
|
97
|
+
developer: header(text, 'Developer'),
|
|
98
|
+
}
|
|
99
|
+
}
|
|
100
|
+
|
|
101
|
+
module.exports = { readSpecState, SEARCH }
|
package/src/env/teardown.js
CHANGED
|
@@ -59,6 +59,28 @@ function planDown(spec, config, flags, ctx) {
|
|
|
59
59
|
if (config.guards.refuseTeardownIfUnpushed && worktreeState.unpushed && !landed) {
|
|
60
60
|
return blocked('worktree has unpushed commits not yet merged into the base branch')
|
|
61
61
|
}
|
|
62
|
+
// PR mode: `merged` already includes the host's answer (the CLI folds a
|
|
63
|
+
// merged PR in before planning), so an UNLANDED branch here really is one
|
|
64
|
+
// the host has not merged — or one whose lookup failed, and deleting a
|
|
65
|
+
// worktree on a lookup that failed is the destructive reading of an absence
|
|
66
|
+
// (`.claude/rules/negative-checks.md` rule 4). Refused at plan time rather
|
|
67
|
+
// than left to `git branch -d`'s error, because this message can name the
|
|
68
|
+
// PR and the exit where git's cannot. `--force` bypasses, and still plans
|
|
69
|
+
// `-d` below, so a genuinely unlanded branch fails loudly rather than
|
|
70
|
+
// being -D'd.
|
|
71
|
+
if (config.land && config.land.strategy === 'pr' && !landed) {
|
|
72
|
+
const prState = worktreeState.prState
|
|
73
|
+
const at = worktreeState.prUrl ? ` — see ${worktreeState.prUrl}` : ''
|
|
74
|
+
if (prState === 'open' || prState === 'draft') {
|
|
75
|
+
return blocked(
|
|
76
|
+
`the PR for ${spec.branch} is still ${prState}${at}; it lands when the host merges`,
|
|
77
|
+
)
|
|
78
|
+
}
|
|
79
|
+
if (prState === 'none') {
|
|
80
|
+
return blocked(`${spec.branch} has no PR and is not merged into the base branch`)
|
|
81
|
+
}
|
|
82
|
+
return blocked(`cannot confirm the PR for ${spec.branch} merged${at}`)
|
|
83
|
+
}
|
|
62
84
|
}
|
|
63
85
|
|
|
64
86
|
// Docker teardown only applies to a Docker-escalated spec. A worktree-only spec
|
|
@@ -160,6 +182,11 @@ function planDown(spec, config, flags, ctx) {
|
|
|
160
182
|
// may well be on a remote this clone cannot see (pushed from another machine),
|
|
161
183
|
// and the honest answer to "is there a remote branch?" is then "cannot tell",
|
|
162
184
|
// which routes to doing nothing.
|
|
185
|
+
//
|
|
186
|
+
// A host that auto-deletes the branch on merge (common PR-mode hygiene) makes
|
|
187
|
+
// this delete a no-op: `git push --delete` errors with "remote ref does not
|
|
188
|
+
// exist", which is loud and destroys nothing. The skills report that as
|
|
189
|
+
// already-gone, never as a failed teardown.
|
|
163
190
|
const remoteCommands = []
|
|
164
191
|
const policy = (config.teardown && config.teardown.deleteRemoteBranch) || 'prompt'
|
|
165
192
|
if (spec.branch && landed && worktreeState.remoteBranch && policy !== 'never') {
|
|
@@ -184,6 +211,21 @@ function planDown(spec, config, flags, ctx) {
|
|
|
184
211
|
}
|
|
185
212
|
}
|
|
186
213
|
|
|
214
|
+
// A live PR left behind by a cancelled spec is noise with a merge button on
|
|
215
|
+
// it, so a FORCED teardown past an open/draft PR also plans the abandon —
|
|
216
|
+
// composed by the caller (the host adapter's business), quarantined with the
|
|
217
|
+
// remote delete because closing a shared PR reaches outside this machine.
|
|
218
|
+
// Unforced never gets here with an open PR (the guard above refused), and a
|
|
219
|
+
// missing command (unknown host, no id) plans nothing: the refusal/report
|
|
220
|
+
// already named the PR, and a person closes it.
|
|
221
|
+
if (
|
|
222
|
+
config.land && config.land.strategy === 'pr' &&
|
|
223
|
+
(worktreeState.prState === 'open' || worktreeState.prState === 'draft') &&
|
|
224
|
+
ctx && ctx.prAbandonCommand
|
|
225
|
+
) {
|
|
226
|
+
remoteCommands.push(ctx.prAbandonCommand)
|
|
227
|
+
}
|
|
228
|
+
|
|
187
229
|
return {
|
|
188
230
|
blocked: false,
|
|
189
231
|
reason: null,
|
|
@@ -84,7 +84,9 @@ const {
|
|
|
84
84
|
} = require('./credentials.js')
|
|
85
85
|
const { resolveIdentity, displayNameOf } = require('./identity.js')
|
|
86
86
|
const { makeAssignmentCommands } = require('../provider-kit/src/assignment.js')
|
|
87
|
+
const { specSyncOwnership, specSyncBoard: kitBoard, ownershipDoctorRow } = require('../provider-kit/src/status.js')
|
|
87
88
|
const { resolveTransport } = require('../provider-kit/src/transport.js')
|
|
89
|
+
const { specSyncSplice } = require('../provider-kit/src/splice.js')
|
|
88
90
|
|
|
89
91
|
// `assign`, `whoami` and `users` are the kit's (`provider-kit/src/assignment.js`),
|
|
90
92
|
// hoisted when the GitHub provider became their second consumer. What is
|
|
@@ -115,6 +117,24 @@ const assignment = makeAssignmentCommands({
|
|
|
115
117
|
usersOverMcp: 'search the workspace over MCP with the user-list tool',
|
|
116
118
|
})
|
|
117
119
|
const specSyncAssign = (dir, config, specArg, flags, out) => assignment.assign(dir, config, specArg, flags, out)
|
|
120
|
+
|
|
121
|
+
// `board <spec>` — has Linear finished what this repo has not? The kit's
|
|
122
|
+
// (`provider-kit/src/status.js`): one line on a disagreement, silent otherwise.
|
|
123
|
+
async function specSyncBoard(dir, config, specArg, flags, out) {
|
|
124
|
+
const snapshotDir = resolveOrExit(specArg, dir, out)
|
|
125
|
+
if (!snapshotDir) return 1
|
|
126
|
+
const key = resolveApiKey(config, flags.env || process.env)
|
|
127
|
+
const transport = resolveTransport(flags, config, key.ok || !!flags.adapter)
|
|
128
|
+
const credential =
|
|
129
|
+
transport === 'mcp'
|
|
130
|
+
? { ok: false, error: 'transport = mcp — no API read' }
|
|
131
|
+
: flags.adapter
|
|
132
|
+
? { ok: true, adapter: flags.adapter }
|
|
133
|
+
: key.ok
|
|
134
|
+
? { ok: true, adapter: makeApiAdapter({ apiKey: key.key, fetch: flags.fetch }) }
|
|
135
|
+
: { ok: false, error: key.error }
|
|
136
|
+
return kitBoard({ snapshotDir, config, credential, flags, out, tracker: 'Linear', program: 'spec-sync' })
|
|
137
|
+
}
|
|
118
138
|
const specSyncWhoami = (dir, config, flags, out) => assignment.whoami(dir, config, flags, out)
|
|
119
139
|
const specSyncUsers = (dir, config, query, flags, out) => assignment.users(dir, config, query, flags, out)
|
|
120
140
|
const { readAllStdin, promptHidden } = require('../provider-kit/src/prompt.js')
|
|
@@ -883,6 +903,7 @@ function gatherState(dir, flags) {
|
|
|
883
903
|
}
|
|
884
904
|
|
|
885
905
|
state._config = config
|
|
906
|
+
if (config) state.ownership = ownershipDoctorRow(config)
|
|
886
907
|
state.retired = retiredKeysRow(path.join(dir, CONFIG_FILE), CONFIG_FILE, doctorRow)
|
|
887
908
|
return state
|
|
888
909
|
}
|
|
@@ -1027,7 +1048,10 @@ function readCommitRange(dir, rangeArg, verb) {
|
|
|
1027
1048
|
|
|
1028
1049
|
// NUL-delimited so a subject or body containing the separator cannot split a
|
|
1029
1050
|
// record; RS between commits for the same reason.
|
|
1030
|
-
|
|
1051
|
+
// %P rides with the sha so a merge commit can be told apart: its trailers
|
|
1052
|
+
// are READ (a hand merge is where a ticket's only trailer sometimes lives),
|
|
1053
|
+
// but a trailer-less merge counts as transport rather than a gap.
|
|
1054
|
+
const raw = git(['log', '--format=%H %P%x00%s%x00%b%x1e', range])
|
|
1031
1055
|
if (raw === null) {
|
|
1032
1056
|
return { error: [`spec-sync ${verb}: git could not resolve the range "${range}".`] }
|
|
1033
1057
|
}
|
|
@@ -1037,8 +1061,9 @@ function readCommitRange(dir, rangeArg, verb) {
|
|
|
1037
1061
|
.map((r) => r.replace(/^\n/, ''))
|
|
1038
1062
|
.filter((r) => r.trim())
|
|
1039
1063
|
.map((record) => {
|
|
1040
|
-
const [
|
|
1041
|
-
|
|
1064
|
+
const [idLine, subject, ...rest] = record.split('\x00')
|
|
1065
|
+
const [sha, ...parents] = String(idLine).trim().split(/\s+/).filter(Boolean)
|
|
1066
|
+
return { sha, isMerge: parents.length > 1, subject, body: rest.join('\x00') }
|
|
1042
1067
|
})
|
|
1043
1068
|
|
|
1044
1069
|
// What each commit CHANGED, so bookkeeping can be told from shipped work. A
|
|
@@ -1104,6 +1129,7 @@ async function specSyncReleased(dir, config, rangeArg, flags, out) {
|
|
|
1104
1129
|
// MISSED trailer looks identical, so silence here would read as "everything is
|
|
1105
1130
|
// accounted for".
|
|
1106
1131
|
lines.push(` ${report.unreferenced} commit(s) carry no ref`)
|
|
1132
|
+
if (report.merges) lines.push(` ${report.merges} merge commit(s) — transport, not counted as gaps`)
|
|
1107
1133
|
// A filter that removes commits without saying so reads as "there was nothing
|
|
1108
1134
|
// there". Named only when it actually fired — on a project with no paperwork
|
|
1109
1135
|
// in the range there is nothing to disclose.
|
|
@@ -1994,6 +2020,7 @@ async function specSyncList(dir, config, flags, out) {
|
|
|
1994
2020
|
|
|
1995
2021
|
const rows = ordered.map((issue) => {
|
|
1996
2022
|
const local = byIdentifier.get(issue.identifier) || null
|
|
2023
|
+
const column = specColumn((issue.state && issue.state.name) || null, local, config)
|
|
1997
2024
|
return {
|
|
1998
2025
|
identifier: issue.identifier || '',
|
|
1999
2026
|
title: issue.title || '',
|
|
@@ -2004,7 +2031,9 @@ async function specSyncList(dir, config, flags, out) {
|
|
|
2004
2031
|
// close, so hiding it would defeat the command.
|
|
2005
2032
|
spec: local ? local.spec : null,
|
|
2006
2033
|
bucket: local ? local.bucket : null,
|
|
2007
|
-
disagrees:
|
|
2034
|
+
disagrees: column.disagrees,
|
|
2035
|
+
// The command that closes it — present only on a disagreeing row.
|
|
2036
|
+
...(column.cleanup ? { cleanup: column.cleanup } : {}),
|
|
2008
2037
|
assignee: (issue.assignee && issue.assignee.name) || null,
|
|
2009
2038
|
// Filled in below for in-progress rows only; `null` on every row that was
|
|
2010
2039
|
// never looked up, so the shape does not vary by state.
|
|
@@ -2140,7 +2169,7 @@ async function specSyncList(dir, config, flags, out) {
|
|
|
2140
2169
|
} else {
|
|
2141
2170
|
const idW = Math.max(...shown.map((r) => r.identifier.length))
|
|
2142
2171
|
const stW = Math.max(...shown.map((r) => r.state.length))
|
|
2143
|
-
const cell = (r) => specCell({ specStatus: r.bucket, disagrees: r.disagrees })
|
|
2172
|
+
const cell = (r) => specCell({ specStatus: r.bucket, disagrees: r.disagrees, cleanup: r.cleanup })
|
|
2144
2173
|
const bkW = Math.max(...shown.map((r) => cell(r).length))
|
|
2145
2174
|
const pad = ' '.repeat(idW + stW + bkW + 6)
|
|
2146
2175
|
const specW = Math.max(...shown.map((r) => (r.spec || UNLINKED).length))
|
|
@@ -2656,6 +2685,10 @@ function specSyncInitConfig(dir, flags, out) {
|
|
|
2656
2685
|
if (flags.teamKey) linear.teamKey = flags.teamKey
|
|
2657
2686
|
if (flags.projectId) linear.projectId = flags.projectId
|
|
2658
2687
|
draft.linear = linear
|
|
2688
|
+
// A NEW config carries a summary, not the spec: written explicitly, so the
|
|
2689
|
+
// file says what the ticket gets. A config that predates the key keeps
|
|
2690
|
+
// pushing the spec (the loader's default), so an upgrade rewrites nothing.
|
|
2691
|
+
draft.mapping = { description: flags.description || 'summary' }
|
|
2659
2692
|
const intake = {}
|
|
2660
2693
|
if (flags.intakeLabel) intake.label = flags.intakeLabel
|
|
2661
2694
|
if (flags.bugLabels.length) intake.bugLabels = flags.bugLabels
|
|
@@ -3317,6 +3350,9 @@ async function specSync(rest, io = {}) {
|
|
|
3317
3350
|
else if (args[i] === '--apply') flags.apply = true
|
|
3318
3351
|
else if (args[i] === '--remote') flags.remote = path.resolve(args[++i])
|
|
3319
3352
|
else if (args[i] === '--stored') flags.stored = path.resolve(args[++i])
|
|
3353
|
+
else if (args[i] === '--live') flags.live = path.resolve(args[++i])
|
|
3354
|
+
else if (args[i] === '--description') flags.description = args[++i]
|
|
3355
|
+
else if (args[i] === '--phase') flags.phase = args[++i]
|
|
3320
3356
|
// `preserve --text <file>`: the description to keep, when the caller read it
|
|
3321
3357
|
// over MCP and the engine cannot.
|
|
3322
3358
|
else if (args[i] === '--text') flags.text = path.resolve(args[++i])
|
|
@@ -3355,6 +3391,7 @@ async function specSync(rest, io = {}) {
|
|
|
3355
3391
|
else if (args[i] === '--unset') flags.unset = true
|
|
3356
3392
|
else if (args[i] === '--to') flags.to = String(args[++i] || '').trim()
|
|
3357
3393
|
else if (args[i] === '--release') flags.release = true
|
|
3394
|
+
else if (args[i] === '--if-unassigned') flags.ifUnassigned = true
|
|
3358
3395
|
else if (args[i] === '--no-assign') flags.noAssign = true
|
|
3359
3396
|
else if (args[i] === '--limit') flags.limit = Number(args[++i]) || 0
|
|
3360
3397
|
else if (args[i] === '--cursor') flags.cursor = String(args[++i] || '').trim()
|
|
@@ -3490,6 +3527,11 @@ async function specSync(rest, io = {}) {
|
|
|
3490
3527
|
return (await specSyncRetarget(dir, config, flags, out)) || 0
|
|
3491
3528
|
case 'apply':
|
|
3492
3529
|
return (await specSyncApply(dir, config, positional[0], flags, out)) || 0
|
|
3530
|
+
case 'splice': {
|
|
3531
|
+
const snapshotDir = resolveOrExit(positional[0], dir, err)
|
|
3532
|
+
if (!snapshotDir) return 1
|
|
3533
|
+
return specSyncSplice({ snapshotDir, config, flags, out, err, program: 'spec-sync' })
|
|
3534
|
+
}
|
|
3493
3535
|
case 'verify':
|
|
3494
3536
|
return specSyncVerify(dir, config, positional[0], flags, out) || 0
|
|
3495
3537
|
case 'preserve':
|
|
@@ -3499,6 +3541,10 @@ async function specSync(rest, io = {}) {
|
|
|
3499
3541
|
case 'linked':
|
|
3500
3542
|
specSyncLinked(dir, config, flags, out)
|
|
3501
3543
|
return 0
|
|
3544
|
+
case 'ownership':
|
|
3545
|
+
return specSyncOwnership(config, flags, out, 'spec-sync')
|
|
3546
|
+
case 'board':
|
|
3547
|
+
return specSyncBoard(dir, config, positional[0], flags, out)
|
|
3502
3548
|
case 'credentials':
|
|
3503
3549
|
return await specSyncCredentials(dir, config, positional[0], flags, out)
|
|
3504
3550
|
default:
|
|
@@ -3510,14 +3556,17 @@ async function specSync(rest, io = {}) {
|
|
|
3510
3556
|
' skitterspec spec-sync projects [--via api|mcp] [--json]\n' +
|
|
3511
3557
|
' skitterspec spec-sync whoami [--set <id> [--name N]] [--unset] [--json]\n' +
|
|
3512
3558
|
' skitterspec spec-sync users [<name-or-email>] [--limit N] [--cursor C] [--json]\n' +
|
|
3513
|
-
' skitterspec spec-sync assign <spec> --to <id> [--name N] | --release [--json]\n' +
|
|
3559
|
+
' skitterspec spec-sync assign <spec> --to <id> [--name N] [--if-unassigned] | --release [--json]\n' +
|
|
3514
3560
|
' skitterspec spec-sync apply <spec> --plan <file> [--via api|mcp] [--project id] [--json]\n' +
|
|
3515
3561
|
' skitterspec spec-sync apply --all <bucket> [--via api|mcp] [--json]\n' +
|
|
3516
3562
|
' skitterspec spec-sync verify <spec> --stored <file>\n' +
|
|
3563
|
+
' skitterspec spec-sync splice <spec> --live <file> [--phase <ref>]\n' +
|
|
3517
3564
|
' skitterspec spec-sync preserve <spec> [--text <file>] [--via api|mcp] [--json]\n' +
|
|
3518
3565
|
' skitterspec spec-sync comment <spec> --file <file> [--via api|mcp]\n' +
|
|
3519
3566
|
' skitterspec spec-sync list [--state <name> …|--all|--in-progress] [--next N] [--mine|--by <user>] [--limit N] [--archived] [--json]\n' +
|
|
3520
3567
|
' skitterspec spec-sync linked [--json]\n' +
|
|
3568
|
+
' skitterspec spec-sync ownership [--json]\n' +
|
|
3569
|
+
' skitterspec spec-sync board <spec> [--json]\n' +
|
|
3521
3570
|
' skitterspec spec-sync ref [<spec>] [--json]\n' +
|
|
3522
3571
|
' skitterspec spec-sync released [<range>] [--json]\n' +
|
|
3523
3572
|
' skitterspec spec-sync reattach <spec> [--to <ISSUE-REF>] [--json]\n' +
|