@skitterbyte/skitterspec-jira 2.2.0 → 2.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/jira.config.md +4 -2
- 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 +57 -1
- package/assets/skills/spec-cancel/SKILL.md +35 -0
- package/assets/skills/spec-complete/SKILL.md +113 -0
- package/assets/skills/spec-hotfix/SKILL.md +61 -2
- package/assets/skills/spec-incident/SKILL.md +44 -0
- package/assets/skills/spec-jira-setup/SKILL.md +23 -1
- package/assets/skills/spec-next/SKILL.md +9 -4
- package/assets/skills/spec-push/SKILL.md +22 -0
- package/assets/skills/spec-review/SKILL.md +32 -0
- package/assets/skills/spec-start/SKILL.md +39 -1
- 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/jira/cli-sync.js +45 -3
- package/src/vendor/jira/config.js +17 -5
- 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,
|
|
@@ -34,6 +34,7 @@ const {
|
|
|
34
34
|
stampSubIssueId,
|
|
35
35
|
listPhaseFiles,
|
|
36
36
|
normalizeLocal,
|
|
37
|
+
descriptionMode,
|
|
37
38
|
} = require('../sync-core')
|
|
38
39
|
const kit = require('../provider-kit')
|
|
39
40
|
const { BUCKETS, findSpecFolder, currentBranch } = require('../../env/resolve.js')
|
|
@@ -258,6 +259,16 @@ function apiAdapterFor(config, flags) {
|
|
|
258
259
|
}
|
|
259
260
|
}
|
|
260
261
|
|
|
262
|
+
// `board <spec>` — has Jira finished what this repo has not? The kit's
|
|
263
|
+
// (`provider-kit/src/status.js`): one line on a disagreement, silent otherwise.
|
|
264
|
+
async function specSyncBoard(dir, config, specArg, flags, out) {
|
|
265
|
+
const snapshotDir = resolveOrExit(specArg, dir, out)
|
|
266
|
+
if (!snapshotDir) return 1
|
|
267
|
+
const cred = apiAdapterFor(config, flags)
|
|
268
|
+
const credential = kit.resolveTransport(flags, config, cred.ok) === 'mcp' ? { ok: false, error: 'transport = mcp — no API read' } : cred
|
|
269
|
+
return kit.specSyncBoard({ snapshotDir, config, credential, flags, out, tracker: 'Jira', program: PROGRAM })
|
|
270
|
+
}
|
|
271
|
+
|
|
261
272
|
// ---------------------------------------------------------------------------
|
|
262
273
|
// Subcommands. Each returns an exit code and writes only to the streams it is
|
|
263
274
|
// handed, so every branch is testable offline.
|
|
@@ -755,12 +766,16 @@ function specSyncRef(dir, config, specArg, flags, out, err) {
|
|
|
755
766
|
// ---------------------------------------------------------------------------
|
|
756
767
|
// `released [<range>]` — which tickets a commit range contains, off the
|
|
757
768
|
// `Refs:` trailers (kit `src/released.js` owns the parsing rules).
|
|
769
|
+
// Merge commits are READ, never skipped: a hand merge is where a ticket's only
|
|
770
|
+
// trailer sometimes lives (--no-merges was tried and dropped for exactly that
|
|
771
|
+
// loss). What changes is the counting — a trailer-less merge is transport, not
|
|
772
|
+
// a gap — and %P is what lets ticketsInRange tell the two apart.
|
|
758
773
|
function readCommitRange(dir, range) {
|
|
759
774
|
const { execFileSync } = require('node:child_process')
|
|
760
775
|
const SEP = 'SKITTERSPEC'
|
|
761
776
|
let raw
|
|
762
777
|
try {
|
|
763
|
-
raw = execFileSync('git', ['-C', dir, 'log', `--format=%x00SKITTERSPEC%x00%H%n%B%x00END%x00`, '--name-only', range], {
|
|
778
|
+
raw = execFileSync('git', ['-C', dir, 'log', `--format=%x00SKITTERSPEC%x00%H %P%n%B%x00END%x00`, '--name-only', range], {
|
|
764
779
|
encoding: 'utf-8',
|
|
765
780
|
stdio: ['ignore', 'pipe', 'pipe'],
|
|
766
781
|
maxBuffer: 64 * 1024 * 1024,
|
|
@@ -781,9 +796,10 @@ function readCommitRange(dir, range) {
|
|
|
781
796
|
.map((l) => l.trim())
|
|
782
797
|
.filter(Boolean)
|
|
783
798
|
const nl = head.indexOf('\n')
|
|
784
|
-
const
|
|
799
|
+
const idLine = head.slice(0, nl < 0 ? head.length : nl).trim()
|
|
800
|
+
const [sha, ...parents] = idLine.split(/\s+/).filter(Boolean)
|
|
785
801
|
const body = nl < 0 ? '' : head.slice(nl + 1)
|
|
786
|
-
commits.push({ sha, subject: body.split('\n')[0] || '', body, paths })
|
|
802
|
+
commits.push({ sha, isMerge: parents.length > 1, subject: body.split('\n')[0] || '', body, paths })
|
|
787
803
|
}
|
|
788
804
|
return { ok: true, commits }
|
|
789
805
|
}
|
|
@@ -807,6 +823,7 @@ function specSyncReleased(dir, config, rangeArg, flags, out) {
|
|
|
807
823
|
for (const t of report.tickets) lines.push(` ${t.ref} (${t.commits} commit(s))${t.spec ? ` ${t.spec}` : ''}`)
|
|
808
824
|
if (!report.tickets.length) lines.push(' no referenced tickets')
|
|
809
825
|
if (report.unreferenced) lines.push(` ${report.unreferenced} commit(s) carry no Refs: trailer`)
|
|
826
|
+
if (report.merges) lines.push(` ${report.merges} merge commit(s) — transport, not counted as gaps`)
|
|
810
827
|
if (report.ignored) lines.push(` ${report.ignored} bookkeeping commit(s) ignored`)
|
|
811
828
|
out.write(lines.join('\n') + '\n')
|
|
812
829
|
return 0
|
|
@@ -874,6 +891,11 @@ async function specSyncPreserve(dir, config, specArg, flags, out) {
|
|
|
874
891
|
return 0
|
|
875
892
|
}
|
|
876
893
|
if (!identifier) return done(`${path.basename(snapshotDir)} is not linked — nothing to preserve`)
|
|
894
|
+
// Summary mode splices a block in beside the reporter's text rather than
|
|
895
|
+
// replacing it, so the original is still in the description itself.
|
|
896
|
+
if (descriptionMode(config) === 'summary') {
|
|
897
|
+
return done(`${identifier} — summary mode keeps the original description in place; nothing to preserve`)
|
|
898
|
+
}
|
|
877
899
|
|
|
878
900
|
let original = null
|
|
879
901
|
if (flags.text) {
|
|
@@ -1070,6 +1092,10 @@ async function specSyncInitConfig(dir, flags, out) {
|
|
|
1070
1092
|
const parsed = { jira: { siteUrl: flags.siteUrl, projectKey: flags.projectKey } }
|
|
1071
1093
|
if (flags.issueType) parsed.jira.issueType = flags.issueType
|
|
1072
1094
|
if (flags.subtaskType) parsed.jira.subtaskType = flags.subtaskType
|
|
1095
|
+
// A NEW config carries a summary, not the spec: written explicitly, so the
|
|
1096
|
+
// file says what the ticket gets. A config that predates the key keeps
|
|
1097
|
+
// pushing the spec (the loader's default), so an upgrade rewrites nothing.
|
|
1098
|
+
parsed.mapping = { description: flags.description || 'summary' }
|
|
1073
1099
|
if (flags.stateNames && Object.keys(flags.stateNames).length) {
|
|
1074
1100
|
for (const bucket of Object.keys(flags.stateNames)) {
|
|
1075
1101
|
if (!LIFECYCLE_BUCKETS.includes(bucket)) {
|
|
@@ -1170,6 +1196,7 @@ async function specSyncDoctor(dir, flags, out) {
|
|
|
1170
1196
|
checks.push(row('tracker', 'Jira config', 'broken', 'siteUrl or projectKey is empty', `fix ${CONFIG_FILE}`))
|
|
1171
1197
|
} else {
|
|
1172
1198
|
checks.push(row('tracker', 'Jira config', 'ok', `${loaded.config.jira.projectKey} @ ${loaded.config.jira.siteUrl}`))
|
|
1199
|
+
checks.push(kit.ownershipDoctorRow(loaded.config))
|
|
1173
1200
|
// A worktree forks from a COMMIT, so a config that exists only in the
|
|
1174
1201
|
// working tree is invisible in every spec worktree — where the sync
|
|
1175
1202
|
// skills actually run — and sync there reports itself off with no clue
|
|
@@ -1266,9 +1293,12 @@ const USAGE = `Usage: skitterspec-jira spec-sync <subcommand>
|
|
|
1266
1293
|
record <spec> write the last-pushed snapshot
|
|
1267
1294
|
status <spec> [--remote <f>] read-only drift report
|
|
1268
1295
|
verify <spec> --stored <f> compare a read-back against the repo
|
|
1296
|
+
splice <spec> --live <f> [--phase <ref>] the body to write over MCP (summary mode)
|
|
1269
1297
|
states [--json] the project's status names
|
|
1270
1298
|
list [--all | --state NAME] tracker listing for the project
|
|
1271
1299
|
linked [--json] specs and their linked issues (offline)
|
|
1300
|
+
ownership [--json] who owns status and assignee (offline)
|
|
1301
|
+
board <spec> [--json] is the issue finished where the spec is not?
|
|
1272
1302
|
ref [<spec>] the Refs: trailer value for this branch
|
|
1273
1303
|
released [<range>] tickets a commit range contains
|
|
1274
1304
|
preserve <spec> [--text <f>] keep an adopted issue's original report
|
|
@@ -1337,10 +1367,19 @@ async function specSync(rest, io = {}) {
|
|
|
1337
1367
|
return specSyncRecord(dir, config, positional[0], out)
|
|
1338
1368
|
case 'status':
|
|
1339
1369
|
return specSyncStatus(dir, config, positional[0], flags, out, err)
|
|
1370
|
+
case 'splice': {
|
|
1371
|
+
const snapshotDir = resolveOrExit(positional[0], dir, err)
|
|
1372
|
+
if (!snapshotDir) return 1
|
|
1373
|
+
return kit.specSyncSplice({ snapshotDir, config, flags, out, err, program: PROGRAM })
|
|
1374
|
+
}
|
|
1340
1375
|
case 'verify':
|
|
1341
1376
|
return specSyncVerify(dir, config, positional[0], flags, out)
|
|
1342
1377
|
case 'linked':
|
|
1343
1378
|
return specSyncLinked(dir, config, flags, out)
|
|
1379
|
+
case 'ownership':
|
|
1380
|
+
return kit.specSyncOwnership(config, flags, out, PROGRAM)
|
|
1381
|
+
case 'board':
|
|
1382
|
+
return specSyncBoard(dir, config, positional[0], flags, out)
|
|
1344
1383
|
case 'states':
|
|
1345
1384
|
return specSyncStates(dir, config, flags, out)
|
|
1346
1385
|
case 'list':
|
|
@@ -1379,6 +1418,9 @@ function parseArgs(args, sub) {
|
|
|
1379
1418
|
'--dir': { kind: 'path', name: 'dirOverride' },
|
|
1380
1419
|
'--plan': { kind: 'path' },
|
|
1381
1420
|
'--stored': { kind: 'path' },
|
|
1421
|
+
'--live': { kind: 'path' },
|
|
1422
|
+
'--description': { kind: 'string' },
|
|
1423
|
+
'--phase': { kind: 'string' },
|
|
1382
1424
|
'--remote': { kind: 'path' },
|
|
1383
1425
|
'--text': { kind: 'path' },
|
|
1384
1426
|
'--file': { kind: 'path' },
|
|
@@ -21,7 +21,7 @@ const CONFIG_FILE = 'specs/.core/jira.config.json'
|
|
|
21
21
|
|
|
22
22
|
const OWNERSHIP = Object.freeze(['both', 'pull', 'push', 'none'])
|
|
23
23
|
const TASK_MAPPINGS = Object.freeze(['checklist', 'none'])
|
|
24
|
-
const PHASE_MAPPINGS = Object.freeze(['subissue', 'deferred', 'inline'])
|
|
24
|
+
const PHASE_MAPPINGS = Object.freeze(['subissue', 'deferred', 'inline', 'none'])
|
|
25
25
|
const TRANSPORTS = Object.freeze(['api', 'mcp'])
|
|
26
26
|
const DEFAULT_EMAIL_ENV = 'JIRA_EMAIL'
|
|
27
27
|
const DEFAULT_TOKEN_ENV = 'JIRA_API_TOKEN'
|
|
@@ -43,7 +43,12 @@ const DEFAULT_CONFIG = Object.freeze({
|
|
|
43
43
|
// A spec is a Jira ISSUE; each phase a SUBTASK of it. `tasks` selects how the
|
|
44
44
|
// phase's checkboxes reach that subtask's description (as an ADF task list —
|
|
45
45
|
// live checkboxes, still a read-only mirror).
|
|
46
|
-
|
|
46
|
+
// `description`: what the ticket body carries — `spec` (the whole overview)
|
|
47
|
+
// or `summary` (a delimited block beside the team's own text). `spec` is the
|
|
48
|
+
// default so a config written before the key pushes what it always pushed.
|
|
49
|
+
mapping: Object.freeze({ specFolder: 'issue', phases: DEFAULT_PHASE_MODE, tasks: 'checklist', description: 'spec' }),
|
|
50
|
+
// The summary block's delimiters (provisional until chore-delimiter-spike-providers measures this tracker).
|
|
51
|
+
summary: Object.freeze({ delimiter: 'heading' }),
|
|
47
52
|
// Jira STATUS names — the spec issue's status (from the folder bucket) and
|
|
48
53
|
// each subtask's status (from the phase emoji) both map through this table.
|
|
49
54
|
// They must match the project's workflow statuses exactly; `validateStates`
|
|
@@ -76,11 +81,16 @@ const DEFAULT_CONFIG = Object.freeze({
|
|
|
76
81
|
sync: Object.freeze({
|
|
77
82
|
baseDir: 'specs/.core/jira-base',
|
|
78
83
|
backupDir: 'specs/.core/jira-backups',
|
|
84
|
+
// The repo owns the spec's CONTENT (`push`); the tracker owns its STATUS and
|
|
85
|
+
// ASSIGNEE (`pull`) — the board is where a team assigns and moves work, so a
|
|
86
|
+
// repo copy is one somebody has to keep in step by hand. Under `pull` the
|
|
87
|
+
// state is sent only as a transition the repo made (a bucket move), and the
|
|
88
|
+
// assignee not at all. Set either back to `"push"` for the repo-owned behaviour.
|
|
79
89
|
fieldOwnership: Object.freeze({
|
|
80
90
|
description: 'push',
|
|
81
91
|
subIssues: 'push',
|
|
82
|
-
workflowState: '
|
|
83
|
-
assignee: '
|
|
92
|
+
workflowState: 'pull',
|
|
93
|
+
assignee: 'pull',
|
|
84
94
|
}),
|
|
85
95
|
localOnlySections: Object.freeze(['State log', 'Changelog', 'Open questions']),
|
|
86
96
|
keyedFields: Object.freeze({}),
|
|
@@ -105,6 +115,7 @@ function defaults() {
|
|
|
105
115
|
return {
|
|
106
116
|
jira: { ...DEFAULT_CONFIG.jira, issueTypeByKind: { ...DEFAULT_CONFIG.jira.issueTypeByKind } },
|
|
107
117
|
mapping: { ...DEFAULT_CONFIG.mapping },
|
|
118
|
+
summary: { ...DEFAULT_CONFIG.summary },
|
|
108
119
|
states: { ...DEFAULT_CONFIG.states },
|
|
109
120
|
statesByType: {},
|
|
110
121
|
stateAliases: {},
|
|
@@ -127,7 +138,7 @@ function defaults() {
|
|
|
127
138
|
}
|
|
128
139
|
|
|
129
140
|
const { isObject, stringList, assign } = kitConfig
|
|
130
|
-
const { mergeStates, mergeStateOverrides, mergeFieldOwnership, mergePhaseMapping, mergeReleaseIgnorePaths, mergeKeyedFields } =
|
|
141
|
+
const { mergeStates, mergeStateOverrides, mergeFieldOwnership, mergePhaseMapping, mergeReleaseIgnorePaths, mergeKeyedFields, mergeDescription } =
|
|
131
142
|
kitConfig.makeMergeHelpers({
|
|
132
143
|
configFile: CONFIG_FILE,
|
|
133
144
|
ownership: OWNERSHIP,
|
|
@@ -173,6 +184,7 @@ function mergeConfig(base, parsed) {
|
|
|
173
184
|
}
|
|
174
185
|
mergePhaseMapping(base.mapping, parsed.mapping)
|
|
175
186
|
}
|
|
187
|
+
mergeDescription(base, parsed)
|
|
176
188
|
|
|
177
189
|
mergeStates(base, parsed)
|
|
178
190
|
mergeStateOverrides(base, parsed, 'statesByType')
|
|
@@ -24,6 +24,8 @@ const prompt = require('./src/prompt.js')
|
|
|
24
24
|
const args = require('./src/args.js')
|
|
25
25
|
const adapter = require('./src/adapter.js')
|
|
26
26
|
const apply = require('./src/apply.js')
|
|
27
|
+
const status = require('./src/status.js')
|
|
28
|
+
const splice = require('./src/splice.js')
|
|
27
29
|
|
|
28
30
|
module.exports = {
|
|
29
31
|
...config,
|
|
@@ -38,4 +40,6 @@ module.exports = {
|
|
|
38
40
|
...args,
|
|
39
41
|
...adapter,
|
|
40
42
|
...apply,
|
|
43
|
+
...status,
|
|
44
|
+
...splice,
|
|
41
45
|
}
|