@skitterbyte/skitterspec-jira 2.3.0 → 2.5.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/assets/claude-md-section.md +20 -1
- package/assets/core/SETUP.md +5 -0
- package/assets/core/env.config.json.example +1 -0
- package/assets/core/env.config.md +143 -8
- package/assets/core/jira.config.md +4 -2
- package/assets/hooks/main-guard.cjs +40 -6
- package/assets/hooks/review-gate.cjs +42 -7
- package/assets/rules/commit-trailers.md +24 -1
- package/assets/rules/spec-planning.md +81 -18
- package/assets/rules/spec-reports.md +1 -1
- package/assets/skills/spec/SKILL.md +55 -2
- package/assets/skills/spec-bug/SKILL.md +25 -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 +40 -2
- package/assets/skills/spec-incident/SKILL.md +22 -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 +1188 -79
- package/src/env/base.js +104 -0
- package/src/env/bootstrap.js +22 -3
- package/src/env/classify.js +12 -4
- package/src/env/config.js +77 -5
- package/src/env/disposition.js +62 -0
- package/src/env/handoff.js +81 -0
- package/src/env/host.js +262 -0
- package/src/env/hotfix.js +237 -9
- package/src/env/hotfixland.js +105 -10
- package/src/env/inflight.js +98 -0
- package/src/env/integrate.js +136 -9
- package/src/env/live.js +8 -7
- package/src/env/mainguard.js +20 -5
- package/src/env/phases.js +28 -0
- package/src/env/project.js +223 -0
- package/src/env/provision.js +30 -8
- package/src/env/resolve.js +147 -25
- package/src/env/review.js +21 -7
- package/src/env/reviewers.js +7 -10
- package/src/env/serve.js +27 -11
- package/src/env/specstate.js +101 -0
- package/src/env/supervise.js +15 -2
- package/src/env/teardown.js +46 -3
- package/src/init.js +49 -9
- package/src/vendor/jira/cli-sync.js +48 -4
- 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 +58 -6
- package/src/vendor/provider-kit/src/assignment.js +78 -1
- package/src/vendor/provider-kit/src/config.js +34 -1
- package/src/vendor/provider-kit/src/credentials.js +7 -2
- package/src/vendor/provider-kit/src/list-rows.js +35 -11
- package/src/vendor/provider-kit/src/released.js +48 -4
- package/src/vendor/provider-kit/src/specs.js +18 -7
- package/src/vendor/provider-kit/src/splice.js +64 -0
- package/src/vendor/provider-kit/src/status.js +137 -0
- package/src/vendor/sync-core/index.js +14 -1
- package/src/vendor/sync-core/src/compare.js +81 -6
- package/src/vendor/sync-core/src/normalize.js +50 -7
- package/src/vendor/sync-core/src/push.js +65 -5
- package/src/vendor/sync-core/src/summary.js +257 -0
|
@@ -0,0 +1,223 @@
|
|
|
1
|
+
'use strict'
|
|
2
|
+
|
|
3
|
+
/**
|
|
4
|
+
* Where the skitterspec project sits inside its git repo.
|
|
5
|
+
*
|
|
6
|
+
* Most projects ARE the repo: `specs/` and `.claude/` live at the git root and
|
|
7
|
+
* the prefix is `''`. Some live in a subfolder — a .NET solution folder beside
|
|
8
|
+
* `Sql/` and a prototype or two, where sessions start in the solution folder and
|
|
9
|
+
* that is where `specs/` has to be. This module is the one place that knows the
|
|
10
|
+
* difference, so every other site asks it rather than assuming `specs/` is at
|
|
11
|
+
* the root.
|
|
12
|
+
*
|
|
13
|
+
* Two kinds of path, kept apart on purpose:
|
|
14
|
+
*
|
|
15
|
+
* - a **repo path** is what git prints: relative to the git root, `/`-separated
|
|
16
|
+
* on every platform (git emits forward slashes on Windows too).
|
|
17
|
+
* - an **OS path** is what `fs` and `spawn` take, built with `path`.
|
|
18
|
+
*
|
|
19
|
+
* `fromRepoPath` / `toRepoPath` convert between a repo path and a
|
|
20
|
+
* project-relative one; `projectIn` turns a checkout root into the project's OS
|
|
21
|
+
* folder within it.
|
|
22
|
+
*/
|
|
23
|
+
|
|
24
|
+
const fs = require('node:fs')
|
|
25
|
+
const path = require('node:path')
|
|
26
|
+
|
|
27
|
+
// What marks a project folder: the config folder the installer always writes
|
|
28
|
+
// into. A positive signal (`.claude/rules/negative-checks.md` rule 1) — not
|
|
29
|
+
// "the lifecycle folders are there", which git drops whenever one empties.
|
|
30
|
+
const MARKER = path.join('specs', '.core')
|
|
31
|
+
|
|
32
|
+
function isDir(p) {
|
|
33
|
+
try {
|
|
34
|
+
return fs.statSync(p).isDirectory()
|
|
35
|
+
} catch {
|
|
36
|
+
return false
|
|
37
|
+
}
|
|
38
|
+
}
|
|
39
|
+
|
|
40
|
+
// `.native`, never the JS `realpathSync`: on Windows only the native call
|
|
41
|
+
// expands an 8.3 short name (`C:\Users\RUNNER~1\…`), and git always reports the
|
|
42
|
+
// long one. Compared un-expanded, every folder under a short-named temp dir
|
|
43
|
+
// looked outside its own repo, and the project was never found.
|
|
44
|
+
function real(p) {
|
|
45
|
+
try {
|
|
46
|
+
return fs.realpathSync.native(p)
|
|
47
|
+
} catch {
|
|
48
|
+
return path.resolve(p)
|
|
49
|
+
}
|
|
50
|
+
}
|
|
51
|
+
|
|
52
|
+
/** An OS-relative path as a repo path: `/`-separated, no leading `./`. */
|
|
53
|
+
function toPosix(p) {
|
|
54
|
+
return String(p).split(path.sep).join('/').replace(/^\.\/?/, '')
|
|
55
|
+
}
|
|
56
|
+
|
|
57
|
+
/**
|
|
58
|
+
* The project's prefix within `toplevel`, found by walking up from `from` to the
|
|
59
|
+
* nearest folder holding `specs/.core/`, stopping at `toplevel`. `''` when the
|
|
60
|
+
* project is the root, and `''` when nothing is found — today's behaviour.
|
|
61
|
+
*
|
|
62
|
+
* WHAT WOULD FOOL THIS: a `specs/.core/` that is not a project's — a fixture
|
|
63
|
+
* folder checked into the repo, say — between `from` and the real project. The
|
|
64
|
+
* walk takes the nearest, so a command run from inside such a folder anchors
|
|
65
|
+
* there. Several projects in one repo are out of scope, and nothing here
|
|
66
|
+
* arbitrates between two. Run from the root's own subfolders (the ordinary
|
|
67
|
+
* case for a root-layout repo) the walk reaches the root and answers `''`.
|
|
68
|
+
*
|
|
69
|
+
* Paths are compared as REAL paths: git reports the toplevel resolved through
|
|
70
|
+
* symlinks (macOS `/var` → `/private/var`) where a caller's cwd may not be.
|
|
71
|
+
*/
|
|
72
|
+
function findPrefix(from, toplevel) {
|
|
73
|
+
const top = real(toplevel)
|
|
74
|
+
let at = real(from)
|
|
75
|
+
const rel = path.relative(top, at)
|
|
76
|
+
// `from` outside the toplevel is cannot-tell, and cannot-tell is `''`.
|
|
77
|
+
if (rel.startsWith('..') || path.isAbsolute(rel)) return ''
|
|
78
|
+
for (;;) {
|
|
79
|
+
if (isDir(path.join(at, MARKER))) return toPosix(path.relative(top, at))
|
|
80
|
+
if (at === top) return ''
|
|
81
|
+
const up = path.dirname(at)
|
|
82
|
+
if (up === at) return ''
|
|
83
|
+
at = up
|
|
84
|
+
}
|
|
85
|
+
}
|
|
86
|
+
|
|
87
|
+
/**
|
|
88
|
+
* Locate the project from `from` in the primary checkout.
|
|
89
|
+
*
|
|
90
|
+
* `git(args)` is a reader bound to `from`, returning trimmed stdout or `null`
|
|
91
|
+
* (not a repo) — injected, as everywhere in `env/`. Returns
|
|
92
|
+
* `{ root, prefix, dir }`: the primary checkout's root, the project's prefix
|
|
93
|
+
* within it, and the project folder there (`root` itself when the prefix is
|
|
94
|
+
* `''`). Not a repo → `{ root: from, prefix: '', dir: from }`.
|
|
95
|
+
*
|
|
96
|
+
* The primary root is the parent of the shared git dir — `.git` relative from
|
|
97
|
+
* the primary checkout, `../../.git` from a subfolder of it, an absolute
|
|
98
|
+
* `<main>/.git` from a linked worktree. The prefix is found in the tree you are
|
|
99
|
+
* standing in and applied to the primary, which holds because a worktree is a
|
|
100
|
+
* checkout of the same repo: the project is at the same place in both.
|
|
101
|
+
*/
|
|
102
|
+
function primaryAnchor(from, git) {
|
|
103
|
+
const common = git(['rev-parse', '--git-common-dir'])
|
|
104
|
+
if (!common) return { root: from, prefix: '', dir: from }
|
|
105
|
+
// Canonical, so one folder prints one way wherever the command was run from.
|
|
106
|
+
// From the primary checkout `common` is relative (`.git`) and the root came
|
|
107
|
+
// out spelled as `from` was; from a worktree git hands back an absolute,
|
|
108
|
+
// long-form path — on Windows `RUNNER~1` against `runneradmin` for the same
|
|
109
|
+
// folder, and `integrate` printed two different plans (chore-windows-ci).
|
|
110
|
+
const root = real(path.dirname(path.resolve(from, common)))
|
|
111
|
+
const toplevel = git(['rev-parse', '--show-toplevel'])
|
|
112
|
+
const prefix = toplevel ? findPrefix(from, toplevel) : ''
|
|
113
|
+
return { root, prefix, dir: projectIn(root, prefix) }
|
|
114
|
+
}
|
|
115
|
+
|
|
116
|
+
/** The project's OS folder within a checkout root (the root when prefix is `''`). */
|
|
117
|
+
function projectIn(root, prefix) {
|
|
118
|
+
return prefix ? path.join(root, ...prefix.split('/')) : root
|
|
119
|
+
}
|
|
120
|
+
|
|
121
|
+
/**
|
|
122
|
+
* A repo path as a project-relative path, or `null` when it is outside the
|
|
123
|
+
* project. Prefix `''` returns the path unchanged.
|
|
124
|
+
*/
|
|
125
|
+
function fromRepoPath(rel, prefix) {
|
|
126
|
+
if (!prefix) return rel
|
|
127
|
+
if (rel === prefix) return ''
|
|
128
|
+
return rel.startsWith(`${prefix}/`) ? rel.slice(prefix.length + 1) : null
|
|
129
|
+
}
|
|
130
|
+
|
|
131
|
+
/**
|
|
132
|
+
* A repo path as seen from the project folder: `fromRepoPath` inside the
|
|
133
|
+
* project, `../…` outside it — the form a pathspec takes when it is run from the
|
|
134
|
+
* project folder, which is where a session stands. Prefix `''` returns it
|
|
135
|
+
* unchanged.
|
|
136
|
+
*/
|
|
137
|
+
function projectRelative(rel, prefix) {
|
|
138
|
+
if (!prefix) return rel
|
|
139
|
+
const inside = fromRepoPath(rel, prefix)
|
|
140
|
+
return inside !== null ? inside : path.posix.relative(prefix, rel)
|
|
141
|
+
}
|
|
142
|
+
|
|
143
|
+
/** A project-relative path as a repo path. Prefix `''` returns it unchanged. */
|
|
144
|
+
function toRepoPath(rel, prefix) {
|
|
145
|
+
if (!prefix) return rel
|
|
146
|
+
return rel ? `${prefix}/${rel}` : prefix
|
|
147
|
+
}
|
|
148
|
+
|
|
149
|
+
/**
|
|
150
|
+
* Record where the project sits on a loaded config, for the code that needs the
|
|
151
|
+
* repo's root rather than the project folder — the worktree layout and `{repo}`
|
|
152
|
+
* resolve against the root, so worktrees land beside the repo rather than
|
|
153
|
+
* inside it. Non-enumerable, so it never reaches a JSON dump or a hash of the
|
|
154
|
+
* config.
|
|
155
|
+
*/
|
|
156
|
+
function attachProject(config, anchor) {
|
|
157
|
+
Object.defineProperty(config, 'project', {
|
|
158
|
+
value: Object.freeze({ root: anchor.root, prefix: anchor.prefix }),
|
|
159
|
+
enumerable: false,
|
|
160
|
+
configurable: true,
|
|
161
|
+
})
|
|
162
|
+
return config
|
|
163
|
+
}
|
|
164
|
+
|
|
165
|
+
/**
|
|
166
|
+
* A path as one shell word, for the commands the engine PRINTS for a person or
|
|
167
|
+
* a skill to run. Quoted only when it has to be, so a path without spaces or
|
|
168
|
+
* shell characters prints byte-identically to before. Double quotes, because
|
|
169
|
+
* they mean the same in bash, zsh, Git Bash and cmd for an ordinary path; the
|
|
170
|
+
* three characters bash still expands inside them are escaped.
|
|
171
|
+
*
|
|
172
|
+
* A WINDOWS DRIVE PATH PRINTS WITH FORWARD SLASHES (`C:/Users/x/wt`): git, Git
|
|
173
|
+
* Bash, cmd and PowerShell all take that form unquoted, where `C:\Users` loses
|
|
174
|
+
* its backslashes in Git Bash (`C:Users`) unless quoted (chore-windows-ci).
|
|
175
|
+
*
|
|
176
|
+
* WHY QUOTING AT ALL: a repo at `C:\Code\LSC App` lays its worktrees out at
|
|
177
|
+
* `LSC App-wt`, and `git worktree add C:/Code/LSC App-wt/x -b …` is two
|
|
178
|
+
* arguments.
|
|
179
|
+
*/
|
|
180
|
+
function shellPath(p, platform = process.platform) {
|
|
181
|
+
let s = String(p)
|
|
182
|
+
// A drive path anywhere; on Windows every backslash, which is always a
|
|
183
|
+
// separator there — `\\wt\\x` from a rooted path is no different.
|
|
184
|
+
if (platform === 'win32' || /^[A-Za-z]:[\\/]/.test(s)) s = s.replace(/\\/g, '/')
|
|
185
|
+
// `~` only where bash expands it — at the start; `RUNNER~1` needs no quotes.
|
|
186
|
+
if (!/[\s"'$`!&|;<>()*?[\]{}#\\]/.test(s) && !s.startsWith('~')) return s
|
|
187
|
+
return `"${s.replace(/(["$`])/g, '\\$1')}"`
|
|
188
|
+
}
|
|
189
|
+
|
|
190
|
+
/** The repo root a config was loaded for, else `dir` — today's behaviour. */
|
|
191
|
+
function repoRootOf(dir, config) {
|
|
192
|
+
return (config && config.project && config.project.root) || dir
|
|
193
|
+
}
|
|
194
|
+
|
|
195
|
+
/** The project prefix a config was loaded for, else `''`. */
|
|
196
|
+
function prefixOf(config) {
|
|
197
|
+
return (config && config.project && config.project.prefix) || ''
|
|
198
|
+
}
|
|
199
|
+
|
|
200
|
+
/**
|
|
201
|
+
* The one line that says where the project is, or `''` at the root — a root
|
|
202
|
+
* layout prints nothing new.
|
|
203
|
+
*/
|
|
204
|
+
function projectLine(anchor) {
|
|
205
|
+
if (!anchor || !anchor.prefix) return ''
|
|
206
|
+
return `subfolder: ${anchor.prefix}/ (in repo ${anchor.root})\n`
|
|
207
|
+
}
|
|
208
|
+
|
|
209
|
+
module.exports = {
|
|
210
|
+
MARKER,
|
|
211
|
+
findPrefix,
|
|
212
|
+
primaryAnchor,
|
|
213
|
+
projectIn,
|
|
214
|
+
fromRepoPath,
|
|
215
|
+
projectRelative,
|
|
216
|
+
toRepoPath,
|
|
217
|
+
toPosix,
|
|
218
|
+
shellPath,
|
|
219
|
+
attachProject,
|
|
220
|
+
repoRootOf,
|
|
221
|
+
prefixOf,
|
|
222
|
+
projectLine,
|
|
223
|
+
}
|
package/src/env/provision.js
CHANGED
|
@@ -15,6 +15,7 @@ const { classifyDirtyTree } = require('./classify.js')
|
|
|
15
15
|
const { portOffset } = require('./registry.js')
|
|
16
16
|
const { renderEnvFile } = require('./render.js')
|
|
17
17
|
const { expandTokens } = require('./resolve.js')
|
|
18
|
+
const { shellPath, prefixOf, projectRelative } = require('./project.js')
|
|
18
19
|
|
|
19
20
|
// Cap a path list in a message: enough to recognise, not a wall of text.
|
|
20
21
|
function listPaths(paths) {
|
|
@@ -90,7 +91,13 @@ function planSpecCommit(spec, ctx, config, { carriesChanges = false } = {}) {
|
|
|
90
91
|
return ok
|
|
91
92
|
}
|
|
92
93
|
|
|
93
|
-
|
|
94
|
+
// Git paths in, PROJECT paths out: the planned `git add -- …` runs from the
|
|
95
|
+
// project folder, and a project in a subfolder of its repo must not name
|
|
96
|
+
// `<prefix>/specs/…` from inside `<prefix>` (feat-subfolder-project).
|
|
97
|
+
const split = classifyDirtyTree(spec, c.dirtyPaths, config)
|
|
98
|
+
const prefix = prefixOf(config)
|
|
99
|
+
const owned = split.owned.map((p) => projectRelative(p, prefix))
|
|
100
|
+
const foreign = split.foreign.map((p) => projectRelative(p, prefix))
|
|
94
101
|
|
|
95
102
|
// FOREIGN DIRT REFUSES ONLY WHERE IT CAN REACH THE BRANCH, which is checkout
|
|
96
103
|
// mode and nowhere else. `git switch -c` carries the working tree onto the new
|
|
@@ -252,7 +259,9 @@ function worktreeSteps(spec, offset, config, opts = {}) {
|
|
|
252
259
|
const seed = config.seedFiles || { mode: 'symlink', files: [] }
|
|
253
260
|
const mode = seed.mode === 'copy' ? 'copy' : 'symlink'
|
|
254
261
|
const tokens = {
|
|
255
|
-
|
|
262
|
+
// The step's own cwd — the project folder inside the worktree — so the
|
|
263
|
+
// documented "{worktreePath} is the cwd" stays true for a subfolder project.
|
|
264
|
+
worktreePath: spec.projectPath || spec.worktreePath,
|
|
256
265
|
slug: spec.slug,
|
|
257
266
|
branch: spec.branch,
|
|
258
267
|
projectName: spec.projectName,
|
|
@@ -351,12 +360,24 @@ function planUp(spec, alloc, config, ctx, opts = {}) {
|
|
|
351
360
|
// A hotfix forks its fresh branch from a release tag (`spec.baseRef`, e.g.
|
|
352
361
|
// `v33.16.4`) instead of base HEAD — so the fix is built on the exact commit
|
|
353
362
|
// line prod runs. Attaching an existing branch ignores baseRef (already forked).
|
|
354
|
-
|
|
355
|
-
|
|
356
|
-
|
|
357
|
-
|
|
358
|
-
|
|
359
|
-
|
|
363
|
+
// A rolling base sets `spec.forkFrom` when the primary checkout is not on it.
|
|
364
|
+
// A branch already published (`spec.resumeFrom` — a handed-over spec) is
|
|
365
|
+
// fetched and built from instead: the work is there, and a fresh fork would
|
|
366
|
+
// strand it. It outranks every fork point, a hotfix's tag included, because
|
|
367
|
+
// the branch already forked from wherever it was meant to.
|
|
368
|
+
const forkFrom = spec.baseRef || spec.forkFrom
|
|
369
|
+
const forkPoint = !attached && forkFrom ? ` ${forkFrom}` : ''
|
|
370
|
+
const resume = !attached && spec.resumeFrom ? spec.resumeFrom : null
|
|
371
|
+
if (resume) {
|
|
372
|
+
commands.push(`git fetch ${resume.remote} ${spec.branch}`)
|
|
373
|
+
commands.push(`git worktree add ${shellPath(spec.worktreePath)} -b ${spec.branch} --track ${resume.remote}/${spec.branch}`)
|
|
374
|
+
} else {
|
|
375
|
+
commands.push(
|
|
376
|
+
attached
|
|
377
|
+
? `git worktree add ${shellPath(spec.worktreePath)} ${spec.branch}`
|
|
378
|
+
: `git worktree add ${shellPath(spec.worktreePath)} -b ${spec.branch}${forkPoint}`,
|
|
379
|
+
)
|
|
380
|
+
}
|
|
360
381
|
// The tree gate. A worktree forks from the base branch's tree, so an
|
|
361
382
|
// uncommitted spec would produce a branch missing the spec it is for — this is
|
|
362
383
|
// where that gets committed, or refused. Worktree mode had NO clean gate before
|
|
@@ -374,6 +395,7 @@ function planUp(spec, alloc, config, ctx, opts = {}) {
|
|
|
374
395
|
// report from "provisioned", and the caller cannot reconstruct it.
|
|
375
396
|
untouched: gate.foreign || [],
|
|
376
397
|
worktreePath: spec.worktreePath,
|
|
398
|
+
projectPath: spec.projectPath || spec.worktreePath,
|
|
377
399
|
branch: spec.branch,
|
|
378
400
|
projectName: spec.projectName,
|
|
379
401
|
slot: wantsDocker ? slot : null,
|
package/src/env/resolve.js
CHANGED
|
@@ -16,6 +16,7 @@
|
|
|
16
16
|
|
|
17
17
|
const fs = require('node:fs')
|
|
18
18
|
const path = require('node:path')
|
|
19
|
+
const { primaryAnchor, repoRootOf, prefixOf, projectIn } = require('./project.js')
|
|
19
20
|
|
|
20
21
|
const BUCKETS = ['backlog', 'in-progress', 'complete', 'cancelled']
|
|
21
22
|
|
|
@@ -384,6 +385,27 @@ function readBaseVersionField(specPath) {
|
|
|
384
385
|
return m[1].trim().replace(/^["'`]|["'`]$/g, '') || null
|
|
385
386
|
}
|
|
386
387
|
|
|
388
|
+
/**
|
|
389
|
+
* Parse a `Base version` value. Two forms:
|
|
390
|
+
* - a release tag, `v33.16.4` → `{ kind: 'tag', tag, ref }`
|
|
391
|
+
* - a release BRANCH at a commit, `master@1a2b3c4d5e6f` → `{ kind: 'branch',
|
|
392
|
+
* branch, sha, ref }`, written by a branch-based hotfix (`hotfix.releaseBranch`)
|
|
393
|
+
* `ref` is what a worktree forks from: the tag, or the sha — never the branch
|
|
394
|
+
* name, which has moved on since the hotfix was cut.
|
|
395
|
+
*
|
|
396
|
+
* WHAT WOULD FOOL THIS: a tag literally shaped `<name>@<7–40 hex chars>`. Version
|
|
397
|
+
* tags carry dots (`skitterspec@1.4.0`), so they never match; a tag that did
|
|
398
|
+
* would be read as a branch form and fork from that sha, which is the commit
|
|
399
|
+
* the tag points at only if someone named it that way on purpose.
|
|
400
|
+
*/
|
|
401
|
+
function parseBaseVersion(value) {
|
|
402
|
+
if (typeof value !== 'string' || !value.trim()) return null
|
|
403
|
+
const v = value.trim()
|
|
404
|
+
const m = /^([^@\s]+)@([0-9a-f]{7,40})$/i.exec(v)
|
|
405
|
+
if (m) return { kind: 'branch', branch: m[1], sha: m[2], ref: m[2] }
|
|
406
|
+
return { kind: 'tag', tag: v, ref: v }
|
|
407
|
+
}
|
|
408
|
+
|
|
387
409
|
/**
|
|
388
410
|
* Derive the git branch for a spec from the provider-neutral `branch.pattern`
|
|
389
411
|
* (`{type}`, `{slug}`, and optionally `{identifier}`). When the pattern uses
|
|
@@ -404,45 +426,119 @@ function branchFor(spec, config) {
|
|
|
404
426
|
return expandTokens(branch, tokens)
|
|
405
427
|
}
|
|
406
428
|
|
|
429
|
+
/**
|
|
430
|
+
* Thrown when `baseBranchPattern` is set and no remote branch matches it. A
|
|
431
|
+
* refusal, never a fall-through: the default branch is exactly where a rolling
|
|
432
|
+
* base must not land. `refused` carries the one-line reason; `pattern` the glob.
|
|
433
|
+
*/
|
|
434
|
+
class BaseUnresolvedError extends Error {
|
|
435
|
+
constructor(pattern) {
|
|
436
|
+
const refused = `no branch matches ${pattern} — run spec-env base to fetch`
|
|
437
|
+
super(refused)
|
|
438
|
+
this.name = 'BaseUnresolvedError'
|
|
439
|
+
this.refused = refused
|
|
440
|
+
this.pattern = pattern
|
|
441
|
+
}
|
|
442
|
+
}
|
|
443
|
+
|
|
407
444
|
/**
|
|
408
445
|
* Resolve the integration base branch (the branch specs fork from and land back
|
|
409
446
|
* onto). Precedence:
|
|
410
447
|
* 1. `config.baseBranch` — explicit override
|
|
411
|
-
* 2. `
|
|
412
|
-
*
|
|
413
|
-
*
|
|
414
|
-
*
|
|
448
|
+
* 2. `config.baseBranchPattern` — the newest remote branch matching it, by
|
|
449
|
+
* committer date; no match throws `BaseUnresolvedError`
|
|
450
|
+
* 3. `origin/HEAD` — the remote's default branch
|
|
451
|
+
* 4. `main` if it exists locally
|
|
452
|
+
* 5. `master` if it exists locally
|
|
453
|
+
* 6. `main` — last-resort default
|
|
415
454
|
*
|
|
416
455
|
* `git(args)` runs a read-only git command and returns trimmed stdout, or `null`
|
|
417
456
|
* on a non-zero exit / failure. It's injected so this stays pure and unit-testable
|
|
418
457
|
* with no live git; the CLI supplies a real reader. (Note: `show-ref --quiet`
|
|
419
458
|
* emits no stdout on success, so a non-null `''` still means "exists".)
|
|
459
|
+
*
|
|
460
|
+
* Step 2 reads remote-tracking refs and never the network, so it stays
|
|
461
|
+
* synchronous for every caller, the main-guard hook included. Fetching is left
|
|
462
|
+
* to the commands that already talk to the remote.
|
|
420
463
|
*/
|
|
421
464
|
function resolveBaseBranch(config, git) {
|
|
465
|
+
const { base, refused } = describeBaseBranch(config, git)
|
|
466
|
+
if (refused) throw refused
|
|
467
|
+
return base
|
|
468
|
+
}
|
|
469
|
+
|
|
470
|
+
/**
|
|
471
|
+
* The same resolution as `resolveBaseBranch`, returned as data with HOW it was
|
|
472
|
+
* found — `pin` · `pattern` · `origin-head` · `local` · `fallback` — for the
|
|
473
|
+
* one surface that reports it (`spec-env base`). A pattern with no match comes
|
|
474
|
+
* back as `{ base: null, how: 'pattern', refused }` rather than thrown, so a
|
|
475
|
+
* listing can still say what it saw.
|
|
476
|
+
*/
|
|
477
|
+
function describeBaseBranch(config, git) {
|
|
422
478
|
const explicit = config && typeof config.baseBranch === 'string' && config.baseBranch.trim()
|
|
423
|
-
if (explicit) return explicit
|
|
479
|
+
if (explicit) return { base: explicit, how: 'pin' }
|
|
480
|
+
|
|
481
|
+
const pattern = config && typeof config.baseBranchPattern === 'string' && config.baseBranchPattern.trim()
|
|
482
|
+
if (pattern) {
|
|
483
|
+
try {
|
|
484
|
+
return { base: newestMatch(config, git, pattern), how: 'pattern' }
|
|
485
|
+
} catch (error) {
|
|
486
|
+
if (error instanceof BaseUnresolvedError) return { base: null, how: 'pattern', refused: error }
|
|
487
|
+
throw error
|
|
488
|
+
}
|
|
489
|
+
}
|
|
424
490
|
|
|
425
491
|
const originHead = git(['symbolic-ref', '--short', 'refs/remotes/origin/HEAD'])
|
|
426
|
-
if (originHead) return originHead.replace(/^origin\//, '')
|
|
492
|
+
if (originHead) return { base: originHead.replace(/^origin\//, ''), how: 'origin-head' }
|
|
427
493
|
|
|
428
494
|
for (const name of ['main', 'master']) {
|
|
429
|
-
if (git(['show-ref', '--verify', '--quiet', `refs/heads/${name}`]) !== null) return name
|
|
495
|
+
if (git(['show-ref', '--verify', '--quiet', `refs/heads/${name}`]) !== null) return { base: name, how: 'local' }
|
|
430
496
|
}
|
|
431
|
-
return 'main'
|
|
497
|
+
return { base: 'main', how: 'fallback' }
|
|
498
|
+
}
|
|
499
|
+
|
|
500
|
+
// The newest remote-tracking branch matching `pattern`, prefix stripped.
|
|
501
|
+
//
|
|
502
|
+
// WHAT WOULD FOOL THIS: an unfetched remote. A release candidate cut since the
|
|
503
|
+
// last fetch is invisible here, and no rc at all looks identical to "never
|
|
504
|
+
// fetched" — so an empty answer refuses rather than concluding anything, and
|
|
505
|
+
// names the verb that fetches. A stale-but-present answer is the older rc;
|
|
506
|
+
// `up` and `integrate` fetch before resolving so they never act on one.
|
|
507
|
+
function baseRemote(config) {
|
|
508
|
+
return (config && config.land && typeof config.land.remote === 'string' && config.land.remote.trim()) || 'origin'
|
|
509
|
+
}
|
|
510
|
+
|
|
511
|
+
function newestMatch(config, git, pattern) {
|
|
512
|
+
const remote = baseRemote(config)
|
|
513
|
+
const prefix = `refs/remotes/${remote}/`
|
|
514
|
+
const out = git(['for-each-ref', '--sort=-committerdate', '--format=%(refname)', `${prefix}${pattern}`])
|
|
515
|
+
const names = (out || '')
|
|
516
|
+
.split('\n')
|
|
517
|
+
.map((line) => line.trim())
|
|
518
|
+
.filter((ref) => ref.startsWith(prefix))
|
|
519
|
+
.map((ref) => ref.slice(prefix.length))
|
|
520
|
+
// `origin/HEAD` is a symref to the default branch, and a broad pattern
|
|
521
|
+
// (`*`) would otherwise match it.
|
|
522
|
+
.filter((name) => name && name !== 'HEAD')
|
|
523
|
+
if (names.length === 0) throw new BaseUnresolvedError(pattern)
|
|
524
|
+
return names[0]
|
|
432
525
|
}
|
|
433
526
|
|
|
434
527
|
/**
|
|
435
|
-
* Resolve `dir` to the
|
|
436
|
-
*
|
|
437
|
-
*
|
|
438
|
-
*
|
|
439
|
-
*
|
|
440
|
-
*
|
|
441
|
-
*
|
|
528
|
+
* Resolve `dir` to the PROJECT FOLDER in the primary checkout — the primary root
|
|
529
|
+
* (the parent of the shared git dir) joined with the project's prefix, which is
|
|
530
|
+
* `''` when the project is the repo. From the primary checkout
|
|
531
|
+
* `git rev-parse --git-common-dir` is `.git` (relative), so the root is `dir`;
|
|
532
|
+
* from a linked worktree it's the absolute `<main>/.git`, so the root is
|
|
533
|
+
* `<main>`. Anchoring every `spec-env` command here means they read the config
|
|
534
|
+
* and registry identically whether run from `main` or a worktree.
|
|
535
|
+
* `git(args)` returns trimmed stdout or `null` (not a repo) — injected for
|
|
536
|
+
* testability; a `null` degrades to `dir` (today's behaviour). `env/project.js`
|
|
537
|
+
* carries how the prefix is found; `{repo}` and the worktree layout resolve
|
|
538
|
+
* against the root, which a loaded config carries (`attachProject`).
|
|
442
539
|
*/
|
|
443
540
|
function resolvePrimaryCheckout(dir, git) {
|
|
444
|
-
|
|
445
|
-
return common ? path.dirname(path.resolve(dir, common)) : dir
|
|
541
|
+
return primaryAnchor(dir, git).dir
|
|
446
542
|
}
|
|
447
543
|
|
|
448
544
|
/**
|
|
@@ -509,7 +605,8 @@ function assertPrimaryOnMain(config, git) {
|
|
|
509
605
|
* Pure but for `repoInfo`, like `resolveSpec`.
|
|
510
606
|
*/
|
|
511
607
|
function resolveSpecless(name, dir, config, entry = {}) {
|
|
512
|
-
const
|
|
608
|
+
const root = repoRootOf(dir, config)
|
|
609
|
+
const { repo, repoSlug } = repoInfo(root)
|
|
513
610
|
// AN AUTHORING RECORD RESOLVES AS THE SPEC IT WILL BE. `spec: true` marks a
|
|
514
611
|
// record written by `up --docs` for a spec not written yet (the `/spec`
|
|
515
612
|
// authoring lane), so type and slug come from the name's own prefix — the
|
|
@@ -528,6 +625,7 @@ function resolveSpecless(name, dir, config, entry = {}) {
|
|
|
528
625
|
slug,
|
|
529
626
|
stack: 'worktree',
|
|
530
627
|
baseRef: null,
|
|
628
|
+
baseVersion: null,
|
|
531
629
|
specless: true,
|
|
532
630
|
unwritten: authored,
|
|
533
631
|
}
|
|
@@ -541,14 +639,19 @@ function resolveSpecless(name, dir, config, entry = {}) {
|
|
|
541
639
|
branch,
|
|
542
640
|
worktreeRoot,
|
|
543
641
|
worktreeFolder,
|
|
544
|
-
worktreePath: path.resolve(
|
|
642
|
+
worktreePath: path.resolve(root, worktreeRoot, worktreeFolder),
|
|
643
|
+
projectPath: projectIn(path.resolve(root, worktreeRoot, worktreeFolder), prefixOf(config)),
|
|
644
|
+
prefix: prefixOf(config),
|
|
545
645
|
projectName: expandTokens(config.docker.projectNamePattern, tokens),
|
|
546
646
|
}
|
|
547
647
|
}
|
|
548
648
|
|
|
549
649
|
function resolveSpec(specArg, dir, config, opts = {}) {
|
|
550
|
-
|
|
551
|
-
|
|
650
|
+
// Both are CHECKOUT ROOTS (worktrees, from `git worktree list` or the config's
|
|
651
|
+
// layout); a spec lives in the project folder inside each one.
|
|
652
|
+
const prefix = prefixOf(config)
|
|
653
|
+
const searchDirs = (opts.searchDirs || []).map((d) => projectIn(d, prefix))
|
|
654
|
+
const preferDirs = (opts.preferDirs || []).map((d) => projectIn(d, prefix))
|
|
552
655
|
const found = findSpecFolder(specArg, dir, searchDirs, preferDirs)
|
|
553
656
|
if (!found) {
|
|
554
657
|
// A SPECLESS BRANCH, but only on the registry's word. `/no-spec` work has a
|
|
@@ -574,13 +677,17 @@ function resolveSpec(specArg, dir, config, opts = {}) {
|
|
|
574
677
|
}
|
|
575
678
|
|
|
576
679
|
const { type, slug } = splitPrefix(found.folder)
|
|
577
|
-
|
|
680
|
+
// The repo's root, not the project folder: `{repo}` names the repo and the
|
|
681
|
+
// worktree layout sits beside it (spec feat-subfolder-project, decision 4).
|
|
682
|
+
const root = repoRootOf(dir, config)
|
|
683
|
+
const { repo, repoSlug } = repoInfo(root)
|
|
578
684
|
const tokens = { repo, repoSlug, slug }
|
|
579
685
|
|
|
580
686
|
const stack = readStackField(found.path, config)
|
|
581
687
|
// A hotfix forks its worktree from a release tag (its `Base version`) instead
|
|
582
688
|
// of base HEAD; every other type resolves to baseRef:null (fork from HEAD).
|
|
583
|
-
const
|
|
689
|
+
const baseVersion = type === 'hotfix' ? parseBaseVersion(readBaseVersionField(found.path)) : null
|
|
690
|
+
const baseRef = baseVersion ? baseVersion.ref : null
|
|
584
691
|
// `specless: false` is written out rather than left off, so every consumer
|
|
585
692
|
// reads the same field on every resolution instead of treating `undefined` as
|
|
586
693
|
// an answer.
|
|
@@ -592,13 +699,17 @@ function resolveSpec(specArg, dir, config, opts = {}) {
|
|
|
592
699
|
slug,
|
|
593
700
|
stack,
|
|
594
701
|
baseRef,
|
|
702
|
+
baseVersion,
|
|
595
703
|
specless: false,
|
|
596
704
|
}
|
|
597
705
|
const branch = branchFor(spec, config)
|
|
598
706
|
|
|
599
707
|
const worktreeRoot = expandTokens(config.worktree.root, tokens)
|
|
600
708
|
const worktreeFolder = expandTokens(config.worktree.folderPattern, tokens)
|
|
601
|
-
const worktreePath = path.resolve(
|
|
709
|
+
const worktreePath = path.resolve(root, worktreeRoot, worktreeFolder)
|
|
710
|
+
// Where the project sits inside the worktree — what a session stands in and
|
|
711
|
+
// what project-scoped steps run in. The worktree itself when the prefix is ''.
|
|
712
|
+
const projectPath = projectIn(worktreePath, prefixOf(config))
|
|
602
713
|
const projectName = expandTokens(config.docker.projectNamePattern, tokens)
|
|
603
714
|
|
|
604
715
|
return {
|
|
@@ -609,6 +720,10 @@ function resolveSpec(specArg, dir, config, opts = {}) {
|
|
|
609
720
|
worktreeRoot,
|
|
610
721
|
worktreeFolder,
|
|
611
722
|
worktreePath,
|
|
723
|
+
projectPath,
|
|
724
|
+
// The project's folder within the repo, as a repo path ('' at the root) —
|
|
725
|
+
// what turns a git path into a project path (env/project.js).
|
|
726
|
+
prefix: prefixOf(config),
|
|
612
727
|
projectName,
|
|
613
728
|
}
|
|
614
729
|
}
|
|
@@ -660,13 +775,15 @@ function collectSpecFolders(roots) {
|
|
|
660
775
|
function allSpecs(dir, config, worktreePaths, specless = {}) {
|
|
661
776
|
const searchDirs = [...worktreePaths]
|
|
662
777
|
const specs = []
|
|
663
|
-
|
|
778
|
+
const projects = searchDirs.map((d) => projectIn(d, prefixOf(config)))
|
|
779
|
+
for (const folder of collectSpecFolders([dir, ...projects])) {
|
|
664
780
|
try {
|
|
665
781
|
const spec = resolveSpec(folder, dir, config, { searchDirs })
|
|
666
782
|
specs.push({
|
|
667
783
|
folder: spec.folder,
|
|
668
784
|
slug: spec.slug,
|
|
669
785
|
worktreePath: spec.worktreePath,
|
|
786
|
+
projectPath: spec.projectPath,
|
|
670
787
|
specless: false,
|
|
671
788
|
})
|
|
672
789
|
} catch {
|
|
@@ -691,6 +808,7 @@ function allSpecs(dir, config, worktreePaths, specless = {}) {
|
|
|
691
808
|
folder: spec.folder,
|
|
692
809
|
slug: spec.slug,
|
|
693
810
|
worktreePath: spec.worktreePath,
|
|
811
|
+
projectPath: spec.projectPath,
|
|
694
812
|
specless: true,
|
|
695
813
|
})
|
|
696
814
|
}
|
|
@@ -705,6 +823,9 @@ module.exports = {
|
|
|
705
823
|
collectSpecFolders,
|
|
706
824
|
allSpecs,
|
|
707
825
|
resolveBaseBranch,
|
|
826
|
+
describeBaseBranch,
|
|
827
|
+
baseRemote,
|
|
828
|
+
BaseUnresolvedError,
|
|
708
829
|
resolvePrimaryCheckout,
|
|
709
830
|
currentBranch,
|
|
710
831
|
assertPrimaryOnMain,
|
|
@@ -721,4 +842,5 @@ module.exports = {
|
|
|
721
842
|
readFrontmatterField,
|
|
722
843
|
readStackField,
|
|
723
844
|
readBaseVersionField,
|
|
845
|
+
parseBaseVersion,
|
|
724
846
|
}
|
package/src/env/review.js
CHANGED
|
@@ -19,6 +19,7 @@ const fs = require('node:fs')
|
|
|
19
19
|
const path = require('node:path')
|
|
20
20
|
const crypto = require('node:crypto')
|
|
21
21
|
const { readPhases, readOverview } = require('./resolve.js')
|
|
22
|
+
const { fromRepoPath, projectIn } = require('./project.js')
|
|
22
23
|
const { execFileSync } = require('node:child_process')
|
|
23
24
|
|
|
24
25
|
// `-U` large enough that a file's patch IS the file. Reviewing a changed line
|
|
@@ -40,8 +41,13 @@ const REVIEW_DIR = path.join('.spec-env', 'reviews')
|
|
|
40
41
|
// push snapshot that lives among them. The ENGINE decides this, because it knows
|
|
41
42
|
// the spec's own paths — a viewer guessing from regexes would get it wrong the
|
|
42
43
|
// first time someone's product code lived under a folder called `specs`.
|
|
43
|
-
|
|
44
|
-
|
|
44
|
+
//
|
|
45
|
+
// `relPath` is a REPO path, and only the project's own `specs/` and `.spec-env/`
|
|
46
|
+
// are bookkeeping: a project in a subfolder of its repo (`prefix`) owns neither
|
|
47
|
+
// folder at the root, and a change beside it — `Sql/` — is code.
|
|
48
|
+
function isNoise(relPath, prefix = '') {
|
|
49
|
+
const rel = fromRepoPath(relPath, prefix)
|
|
50
|
+
return rel !== null && (rel.startsWith('specs/') || rel.startsWith('.spec-env/'))
|
|
45
51
|
}
|
|
46
52
|
|
|
47
53
|
/**
|
|
@@ -57,8 +63,10 @@ function isNoise(relPath) {
|
|
|
57
63
|
* On a page whose SUBJECT is the spec, applying it folds away every file and
|
|
58
64
|
* renders a page with nothing open on it.
|
|
59
65
|
*/
|
|
60
|
-
function isSpecDocOf(relPath, folder) {
|
|
61
|
-
const
|
|
66
|
+
function isSpecDocOf(relPath, folder, prefix = '') {
|
|
67
|
+
const rel = fromRepoPath(String(relPath), prefix)
|
|
68
|
+
if (rel === null) return false
|
|
69
|
+
const parts = rel.split('/')
|
|
62
70
|
return parts.length > 3 && parts[0] === 'specs' && parts[2] === folder
|
|
63
71
|
}
|
|
64
72
|
|
|
@@ -266,7 +274,10 @@ function collectReview({ spec, git, mode = 'working', ref, base = null, now, not
|
|
|
266
274
|
// reads the spec's worktree, and for those the two are the same path — so
|
|
267
275
|
// `treePath` left null keeps the existing behaviour exactly. The `docs` mode
|
|
268
276
|
// has no worktree to read, which is the whole reason it exists.
|
|
269
|
-
|
|
277
|
+
//
|
|
278
|
+
// `treePath` is a git ROOT, like every tree the readers are bound to — the
|
|
279
|
+
// spec's documents are in the project folder inside it.
|
|
280
|
+
const root = treePath ? projectIn(treePath, spec.prefix || '') : spec.projectPath || spec.worktreePath
|
|
270
281
|
|
|
271
282
|
// AN EXPLICIT FILE SET, or every changed file. `only` is a whitelist of
|
|
272
283
|
// repo-relative paths, and it exists because the `docs` mode reads a tree
|
|
@@ -280,7 +291,8 @@ function collectReview({ spec, git, mode = 'working', ref, base = null, now, not
|
|
|
280
291
|
// else the spec's own documents are the bookkeeping beside the code; on a
|
|
281
292
|
// docs page they are the code, and the companions the project declared (a
|
|
282
293
|
// tracker snapshot, say) are what belongs folded away.
|
|
283
|
-
const
|
|
294
|
+
const prefix = spec.prefix || ''
|
|
295
|
+
const noiseOf = (p) => (mode === 'docs' ? !isSpecDocOf(p, spec.folder, prefix) : isNoise(p, prefix))
|
|
284
296
|
|
|
285
297
|
// THE SURFACES BLOCK, built here so the page never has to know which tiers
|
|
286
298
|
// exist or which of them can be turned on. `null` when the caller passed
|
|
@@ -2579,7 +2591,9 @@ function reviewFileUrl(outPath) {
|
|
|
2579
2591
|
const encoded = path
|
|
2580
2592
|
.resolve(outPath)
|
|
2581
2593
|
.split(path.sep)
|
|
2582
|
-
|
|
2594
|
+
// A Windows drive (`C:`) stays as it is: encoded, `file:///C%3A/…` is a
|
|
2595
|
+
// link no browser opens (chore-windows-ci).
|
|
2596
|
+
.map((seg, i) => (i === 0 && /^[A-Za-z]:$/.test(seg) ? seg : encodeURIComponent(seg)))
|
|
2583
2597
|
.join('/')
|
|
2584
2598
|
return `file://${encoded.startsWith('/') ? '' : '/'}${encoded}`
|
|
2585
2599
|
}
|