@skitterbyte/skitterspec-jira 2.15.0 → 2.17.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/MIGRATION.md +27 -0
- package/assets/claude-md-section.md +18 -9
- package/assets/commands/allow-main.md +1 -2
- package/assets/core/SETUP.md +12 -12
- package/assets/core/env.config.json.example +0 -1
- package/assets/core/env.config.md +28 -26
- package/assets/hooks/main-guard.cjs +73 -6
- package/assets/hooks/project-guard.cjs +80 -6
- package/assets/hooks/review-gate.cjs +73 -6
- package/assets/review/page.html +10 -83
- package/assets/rules/commit-trailers.md +2 -2
- package/assets/rules/spec-planning.md +26 -22
- package/assets/rules/spec-reports.md +52 -52
- package/assets/skills/no-spec/SKILL.md +2 -2
- package/assets/skills/spec/SKILL.md +22 -5
- package/assets/skills/spec-bug/SKILL.md +18 -15
- package/assets/skills/spec-complete/SKILL.md +23 -1
- package/assets/skills/spec-diff/SKILL.md +47 -115
- package/assets/skills/spec-hotfix/SKILL.md +18 -15
- package/assets/skills/spec-init/SKILL.md +4 -2
- package/assets/skills/spec-next/SKILL.md +66 -41
- package/assets/skills/spec-park/SKILL.md +92 -0
- package/assets/skills/spec-resume/SKILL.md +153 -0
- package/assets/skills/spec-review/SKILL.md +2 -2
- package/assets/skills/spec-reviewed/SKILL.md +1 -8
- package/assets/skills/spec-sync/SKILL.md +10 -10
- package/assets/skills/spec-todo/SKILL.md +5 -2
- package/package.json +1 -1
- package/src/cli.js +361 -208
- package/src/env/bootstrap.js +3 -1
- package/src/env/checks.js +49 -0
- package/src/env/config.js +27 -7
- package/src/env/hooks.js +53 -4
- package/src/env/live.js +48 -0
- package/src/env/provision.js +10 -2
- package/src/env/resume.js +234 -0
- package/src/env/review.js +71 -173
- package/src/env/serve.js +3 -7
- package/src/init.js +383 -50
- package/src/tada/todo.js +19 -4
- package/src/vendor/provider-kit/src/specs.js +46 -1
- package/src/vendor/sync-core/src/summary.js +10 -1
- package/assets/commands/spec-remote-review.md +0 -37
package/MIGRATION.md
CHANGED
|
@@ -1,5 +1,32 @@
|
|
|
1
1
|
# Migration guide
|
|
2
2
|
|
|
3
|
+
## The tailnet is `remote`; publishing the review is retired (nothing to edit)
|
|
4
|
+
|
|
5
|
+
The review stack's `remote:` line used to be a claude.ai page the review was
|
|
6
|
+
published to. That tier is gone. `remote:` is now the review server's
|
|
7
|
+
**tailnet address**, on its own line, labelled `(tailnet)`. It is the same
|
|
8
|
+
server as `local` and `network`, so one wait covers all three, and a verdict
|
|
9
|
+
pressed there wakes the waiting session like any other.
|
|
10
|
+
|
|
11
|
+
```
|
|
12
|
+
local: http://127.0.0.1:7760/7e9e…/feat-orders
|
|
13
|
+
network: http://192.168.0.136:7760/7e9e…/feat-orders
|
|
14
|
+
remote: http://100.126.111.34:7760/7e9e…/feat-orders (tailnet)
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
- **`/spec-remote-review` is removed.** `skitterspec update` retires the command
|
|
18
|
+
file. A copy you edited is kept, with the usual warning, and you can delete
|
|
19
|
+
it.
|
|
20
|
+
- **`review.allowRemote` is ignored.** A config that still sets it loads
|
|
21
|
+
without a warning, and you can delete the key whenever you like.
|
|
22
|
+
`spec-env review allow remote` now refuses and names the tailnet line.
|
|
23
|
+
- **`remote` follows `review.allowNetwork`.** It is off whenever `network` is,
|
|
24
|
+
with the same command to turn it on. On a machine with no tailnet address it
|
|
25
|
+
reads `— (no tailnet address on this machine)`.
|
|
26
|
+
- **`--publish-copy` is gone**, along with the page's published mode and its
|
|
27
|
+
`Allow remote` button. A page published before this change still exists, and
|
|
28
|
+
`spec-env down` still names it at teardown.
|
|
29
|
+
|
|
3
30
|
## `issue` and `incident` spec kinds, per-type states, incident log (additive — nothing breaks)
|
|
4
31
|
|
|
5
32
|
Specs can now be **issues** (`issue-` prefix — non-code work done as recorded
|
|
@@ -12,8 +12,8 @@ skill that wants one will tell you to type it.
|
|
|
12
12
|
|
|
13
13
|
**Seeing the work.** A phase is built in its own worktree, so `git diff` in your
|
|
14
14
|
terminal answers about the base branch. **`/spec-diff`** renders that worktree's
|
|
15
|
-
diff as a self-contained HTML page you open locally — or
|
|
16
|
-
|
|
15
|
+
diff as a self-contained HTML page you open locally — or on a phone, over your
|
|
16
|
+
LAN or tailnet. The diff never passes through the model, so the page costs no context
|
|
17
17
|
tokens however large it is; the optional written review is the part that costs,
|
|
18
18
|
and it is offered rather than assumed. `/spec-next` writes the page at the end of
|
|
19
19
|
every phase. **`skitterspec status`** lists what is in flight across worktrees.
|
|
@@ -30,6 +30,18 @@ neither acts on one: a session works on the project it was started in, and a
|
|
|
30
30
|
hook refuses its writes and lifecycle commands anywhere else until you type
|
|
31
31
|
`/allow-project <name>`.
|
|
32
32
|
|
|
33
|
+
**Coming back to a spec** that waited on a deploy, another project or a soak
|
|
34
|
+
is **`/spec-resume <name|#N> [message]`**. It finds the spec even if it exists
|
|
35
|
+
only on its branch, rebuilds its worktree if this machine has none, moves the
|
|
36
|
+
session there and shows what it was blocked on. Then it acts on the message:
|
|
37
|
+
feedback on the shipped work becomes tasks, "the deploy is out" clears the
|
|
38
|
+
blocker, and a question gets an answer from the spec. It never starts
|
|
39
|
+
anything. `/spec #N` on a ticket that already has a spec offers it instead.
|
|
40
|
+
**`/spec-park "<reason>"`** records the wait in the first place, as a
|
|
41
|
+
`Blocked on:` line. `/spec` writes the planned ones ("phase 4 waits until
|
|
42
|
+
phase 3 has run in prod a week"), and `/spec-next` stops before building
|
|
43
|
+
past either kind.
|
|
44
|
+
|
|
33
45
|
**Handing the review back.** The page takes marks: tick `✓ accept` per file as
|
|
34
46
|
you read, note anything against a line or a whole file, answer the questions a
|
|
35
47
|
written review asked — then **end it in a decision**. At the end of a phase the
|
|
@@ -86,13 +98,10 @@ running and concluded nothing, so the phase still owes an answer.
|
|
|
86
98
|
|
|
87
99
|
**Every render lists where the page can be read**, labelled, in a fixed order —
|
|
88
100
|
`local`, `network`, `remote` — each either a URL or the one command that turns it
|
|
89
|
-
on, plus a `live:` line saying whether the change is also running.
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
**`/spec-remote-review`**, which toggles it. Publishing is permitted by that
|
|
94
|
-
command, never performed by it: a published page is one this tooling cannot
|
|
95
|
-
remove.
|
|
101
|
+
on, plus a `live:` line saying whether the change is also running. They are
|
|
102
|
+
labelled by address: `local` is this machine, `network` your LAN, `remote` your
|
|
103
|
+
tailnet. All three are doors into one room — the same server and the same
|
|
104
|
+
waiting verdict — so one wait covers every one the stack shows.
|
|
96
105
|
|
|
97
106
|
**One ending.** Every spec skill finishes with the same block — a verdict
|
|
98
107
|
(`✅` · `⚠️` · `❌` · `⏸`), then a table of the fields that skill declares,
|
|
@@ -26,8 +26,7 @@ id it degrades to a repo-wide allow that outlives the session and is cleared onl
|
|
|
26
26
|
by `/allow-main off`; the engine says which kind you got, so do not read a bare
|
|
27
27
|
"allowed" as temporary.
|
|
28
28
|
|
|
29
|
-
**It is machine-local and gitignored.**
|
|
30
|
-
nothing anyone else pulls: it is your decision about your checkout, not the
|
|
29
|
+
**It is machine-local and gitignored.** It writes nothing anyone else pulls: it is your decision about your checkout, not the
|
|
31
30
|
project's policy. The project-wide switch is `guards.mainIsLandingZone` in
|
|
32
31
|
`specs/.core/env.config.json`, and turning that off is a different, committed
|
|
33
32
|
decision.
|
package/assets/core/SETUP.md
CHANGED
|
@@ -50,7 +50,7 @@ Store the pair in the user-level credentials store (outside every repo,
|
|
|
50
50
|
`0600`), **in your own terminal — not through an assistant**:
|
|
51
51
|
|
|
52
52
|
```sh
|
|
53
|
-
|
|
53
|
+
{{exec}} skitterspec-jira spec-sync credentials set --site-url https://<site>.atlassian.net
|
|
54
54
|
# Jira account email for https://<site>.atlassian.net: you@example.com
|
|
55
55
|
# Jira API token for you@example.com (hidden): ●●●●●●●●
|
|
56
56
|
```
|
|
@@ -81,7 +81,7 @@ statuses (`spec-sync states`) — then writes `specs/.core/jira.config.json`
|
|
|
81
81
|
via `spec-sync init-config`. By hand instead:
|
|
82
82
|
|
|
83
83
|
```sh
|
|
84
|
-
|
|
84
|
+
{{exec}} skitterspec-jira spec-sync init-config \
|
|
85
85
|
--site-url https://your-site.atlassian.net \
|
|
86
86
|
--project-key PROJ \
|
|
87
87
|
--state complete=Done
|
|
@@ -106,7 +106,7 @@ anything was released. A workflow that encodes a pipeline has standard outs
|
|
|
106
106
|
## 4. Check — `spec-sync doctor`
|
|
107
107
|
|
|
108
108
|
```sh
|
|
109
|
-
|
|
109
|
+
{{exec}} skitterspec-jira spec-sync doctor --check-remote
|
|
110
110
|
```
|
|
111
111
|
|
|
112
112
|
Every row reports `ok`, or names the exact command that fixes it. `missing`
|
|
@@ -133,20 +133,20 @@ apply path. `states.json` below is the project's status names.
|
|
|
133
133
|
1. **Doctor** — every row ok:
|
|
134
134
|
|
|
135
135
|
```sh
|
|
136
|
-
|
|
136
|
+
{{exec}} skitterspec-jira spec-sync doctor --check-remote
|
|
137
137
|
```
|
|
138
138
|
|
|
139
139
|
2. **States** — the project's statuses list:
|
|
140
140
|
|
|
141
141
|
```sh
|
|
142
|
-
|
|
142
|
+
{{exec}} skitterspec-jira spec-sync states --json > states.json
|
|
143
143
|
```
|
|
144
144
|
|
|
145
145
|
3. **Mint** — on a test spec with at least one phase and a task checklist:
|
|
146
146
|
|
|
147
147
|
```sh
|
|
148
|
-
|
|
149
|
-
|
|
148
|
+
{{exec}} skitterspec-jira spec-sync plan <spec> --workspace-states states.json --json > plan.json
|
|
149
|
+
{{exec}} skitterspec-jira spec-sync apply <spec> --plan plan.json
|
|
150
150
|
```
|
|
151
151
|
|
|
152
152
|
In Jira: the issue and its subtasks exist, statuses match the buckets, and
|
|
@@ -161,8 +161,8 @@ apply path. `states.json` below is the project's status names.
|
|
|
161
161
|
onto a spec, and preserve before the linking push:
|
|
162
162
|
|
|
163
163
|
```sh
|
|
164
|
-
|
|
165
|
-
|
|
164
|
+
{{exec}} skitterspec-jira spec-sync stamp <spec> --issue PROJ-123
|
|
165
|
+
{{exec}} skitterspec-jira spec-sync preserve <spec>
|
|
166
166
|
```
|
|
167
167
|
|
|
168
168
|
The original description appears as a comment headed **Original report**;
|
|
@@ -174,7 +174,7 @@ apply path. `states.json` below is the project's status names.
|
|
|
174
174
|
every sub-issue as a stale ref) and:
|
|
175
175
|
|
|
176
176
|
```sh
|
|
177
|
-
|
|
177
|
+
{{exec}} skitterspec-jira spec-sync verify <spec> --stored readback.json
|
|
178
178
|
```
|
|
179
179
|
|
|
180
180
|
"round-tripped intact", exit 0.
|
|
@@ -182,7 +182,7 @@ apply path. `states.json` below is the project's status names.
|
|
|
182
182
|
7. **Released** — over a range with `Refs:` trailers:
|
|
183
183
|
|
|
184
184
|
```sh
|
|
185
|
-
|
|
185
|
+
{{exec}} skitterspec-jira spec-sync released <tag>..HEAD
|
|
186
186
|
```
|
|
187
187
|
|
|
188
188
|
Tickets counted, unreferenced commits reported, bookkeeping ignored.
|
|
@@ -191,7 +191,7 @@ apply path. `states.json` below is the project's status names.
|
|
|
191
191
|
and:
|
|
192
192
|
|
|
193
193
|
```sh
|
|
194
|
-
|
|
194
|
+
{{exec}} skitterspec-jira spec-sync status <spec> --remote issue.json
|
|
195
195
|
```
|
|
196
196
|
|
|
197
197
|
The edit is reported; the next apply replaces it and says so loudly.
|
|
@@ -5,7 +5,7 @@ stack + host dev servers + a front-door proxy per in-progress spec).
|
|
|
5
5
|
Provisioning is folded into `/spec-start`, teardown into `/spec-complete` ·
|
|
6
6
|
`/spec-cancel`, traffic diversion is `/spec-connect`, and reading a spec's diff
|
|
7
7
|
is `/spec-diff`; the `skitterspec spec-env
|
|
8
|
-
<up|bootstrap|nospec|main|project|down|prune|dev|connect|integrate|disposition|handoff|hotfix|live|review|stage|status|resolve|base>` CLI is
|
|
8
|
+
<up|bootstrap|nospec|main|project|down|prune|dev|connect|integrate|disposition|handoff|hotfix|live|review|stage|checks|status|resolve|resume|base>` CLI is
|
|
9
9
|
the engine beneath them.
|
|
10
10
|
|
|
11
11
|
**Once this file is present, isolation is the default policy:** `/spec-start` gives
|
|
@@ -229,6 +229,14 @@ through to a documented conservative default; see the field notes below.
|
|
|
229
229
|
// relies on {slug}-style tokens is a poor one to reuse.
|
|
230
230
|
"afterLand": [],
|
|
231
231
|
|
|
232
|
+
// The project's own end-of-spec checks. `/spec-complete` runs them with
|
|
233
|
+
// `spec-env checks <spec>` in the spec's worktree once the suite is green,
|
|
234
|
+
// before it lands, and relays each one's output in its report. Shell strings,
|
|
235
|
+
// run as written. ADVISORY: a non-zero exit is reported as `failed` and makes
|
|
236
|
+
// the run ⚠️ — it never stops the land. A non-string entry is dropped.
|
|
237
|
+
// "complete": { "checks": ["node scripts/docs-freshness.js impact"] }
|
|
238
|
+
"complete": { "checks": [] },
|
|
239
|
+
|
|
232
240
|
// Host dev servers `spec-env dev up <spec>` starts on the spec's port block
|
|
233
241
|
// (for apps that run via `pnpm dev` on the host, not inside the Docker stack).
|
|
234
242
|
// An array so UI + API (or more) are supervised independently; [] = none.
|
|
@@ -593,14 +601,13 @@ through to a documented conservative default; see the field notes below.
|
|
|
593
601
|
// It replaced `serveOnRemote`, which gated serving on the reader — and so
|
|
594
602
|
// handed a local machine a page it could read and not answer. A legacy
|
|
595
603
|
// `serveOnRemote: false` is still read as `serve: "never"`.
|
|
596
|
-
// Either way NOTHING IS PUBLISHED
|
|
597
|
-
//
|
|
598
|
-
// remove, so that half stays an explicit ask. Teardown names a server that
|
|
604
|
+
// Either way NOTHING IS PUBLISHED: a server is one process ended by one flag,
|
|
605
|
+
// and nothing in this workflow publishes the page. Teardown names a server that
|
|
599
606
|
// served the last spec, and `spec-env prune` reaps a pidfile whose process is
|
|
600
607
|
// gone. Default: true.
|
|
601
608
|
//
|
|
602
|
-
// `allowNetwork`
|
|
603
|
-
//
|
|
609
|
+
// `allowNetwork` decides WHICH TIERS a render offers beyond `local`, and it
|
|
610
|
+
// replaced the engine guessing where the reader was sitting. It guessed
|
|
604
611
|
// for a while and got it wrong three separate ways in one day: a file:// page
|
|
605
612
|
// on a session detected `unknown`, a LAN URL for a phone that had left the
|
|
606
613
|
// network, and an address that changed underneath a reader mid-session. So
|
|
@@ -608,26 +615,21 @@ through to a documented conservative default; see the field notes below.
|
|
|
608
615
|
// turns it on — and you pick the one that reaches you.
|
|
609
616
|
//
|
|
610
617
|
// `allowNetwork` — whether the review server binds EVERY INTERFACE, so the
|
|
611
|
-
// page opens on your phone
|
|
612
|
-
//
|
|
613
|
-
//
|
|
614
|
-
//
|
|
615
|
-
//
|
|
616
|
-
//
|
|
617
|
-
//
|
|
618
|
-
//
|
|
619
|
-
//
|
|
620
|
-
//
|
|
621
|
-
//
|
|
622
|
-
//
|
|
623
|
-
//
|
|
624
|
-
//
|
|
625
|
-
//
|
|
626
|
-
// pressed on a published page needs `/spec-reviewed`, because nothing pushes
|
|
627
|
-
// from an artifact's store into a conversation.
|
|
628
|
-
//
|
|
629
|
-
// Both are toggled by `spec-env review allow <tier> --set [on|off]`, where an
|
|
630
|
-
// empty value toggles — which is what `/spec-remote-review` runs. It writes
|
|
618
|
+
// page opens on your phone (`network`, the LAN URL) and
|
|
619
|
+
// over your tailnet (`remote`), or loopback only. THIS IS
|
|
620
|
+
// WHAT CHOOSES THE BIND; `reader` no longer does.
|
|
621
|
+
// Default: true, which matches what the engine already did.
|
|
622
|
+
// `allowRemote` — RETIRED, and ignored if present. It permitted publishing
|
|
623
|
+
// the page as a claude.ai artifact; that tier is gone, and
|
|
624
|
+
// `remote` now names the tailnet address on
|
|
625
|
+
// `allowNetwork`'s switch (feat-tailnet-remote-tier).
|
|
626
|
+
//
|
|
627
|
+
// `local`, `network` and `remote` are three doors into ONE ROOM — the page
|
|
628
|
+
// POSTs to `location.pathname`, so each reaches the same server and the same
|
|
629
|
+
// waiting verdict, and one wait covers them all.
|
|
630
|
+
//
|
|
631
|
+
// It is toggled by `spec-env review allow network --set [on|off]`, where an
|
|
632
|
+
// empty value toggles. It writes
|
|
631
633
|
// THIS FILE in the primary checkout, so it changes for everyone who pulls and
|
|
632
634
|
// leaves that tree dirty; the engine says so when it does.
|
|
633
635
|
//
|
|
@@ -84,8 +84,62 @@ function readPayload() {
|
|
|
84
84
|
const ENGINES = ['skitterspec', 'skitterspec-linear', 'skitterspec-jira', 'skitterspec-github', 'skitterspec-azure-boards']
|
|
85
85
|
|
|
86
86
|
function findEngine(projectDir, platform = process.platform) {
|
|
87
|
-
|
|
88
|
-
|
|
87
|
+
return locateEngine(projectDir, platform).engine
|
|
88
|
+
}
|
|
89
|
+
|
|
90
|
+
/**
|
|
91
|
+
* `findEngine`, plus the directories it walked up from — which is what a hook
|
|
92
|
+
* names when nothing answered.
|
|
93
|
+
*
|
|
94
|
+
* A GIT WORKTREE IS A SIBLING OF ITS PRIMARY CHECKOUT, not a child of it
|
|
95
|
+
* (`worktree.root` is `../{repo}-wt`), so walking up from one never reaches the
|
|
96
|
+
* primary's `node_modules`. A `--docs` worktree has none of its own, so the
|
|
97
|
+
* primary checkout is asked for second — found through git, never guessed from
|
|
98
|
+
* the folder layout.
|
|
99
|
+
*/
|
|
100
|
+
function locateEngine(projectDir, platform = process.platform) {
|
|
101
|
+
if (process.env.SKITTERSPEC_BIN) return { engine: process.env.SKITTERSPEC_BIN, tried: [] }
|
|
102
|
+
const tried = [projectDir]
|
|
103
|
+
const local = walkUp(projectDir, platform)
|
|
104
|
+
if (local) return { engine: local, tried }
|
|
105
|
+
const primary = primaryCheckoutDir(projectDir)
|
|
106
|
+
if (primary) {
|
|
107
|
+
tried.push(primary)
|
|
108
|
+
const found = walkUp(primary, platform)
|
|
109
|
+
if (found) return { engine: found, tried }
|
|
110
|
+
}
|
|
111
|
+
return { engine: 'skitterspec', tried }
|
|
112
|
+
}
|
|
113
|
+
|
|
114
|
+
/**
|
|
115
|
+
* Where `projectDir` sits in the checkout its worktree was added from, or null
|
|
116
|
+
* when it is not in a linked worktree.
|
|
117
|
+
*
|
|
118
|
+
* WHAT WOULD FOOL THIS: a git directory kept somewhere else
|
|
119
|
+
* (`--separate-git-dir`, a submodule's `.git/modules/<name>`). Its parent then
|
|
120
|
+
* holds no `node_modules`, so the lookup finds nothing and falls through to
|
|
121
|
+
* PATH exactly as it did before — a wasted look, never a wrong engine.
|
|
122
|
+
*/
|
|
123
|
+
function primaryCheckoutDir(projectDir) {
|
|
124
|
+
const r = spawnSync('git', ['rev-parse', '--show-toplevel', '--git-common-dir'], {
|
|
125
|
+
cwd: projectDir,
|
|
126
|
+
encoding: 'utf8',
|
|
127
|
+
timeout: 2000,
|
|
128
|
+
})
|
|
129
|
+
if (r.error || r.status !== 0) return null
|
|
130
|
+
const [top, common] = (r.stdout || '').split(/\r?\n/)
|
|
131
|
+
if (!top || !common) return null
|
|
132
|
+
const primary = path.dirname(path.resolve(projectDir, common))
|
|
133
|
+
if (path.resolve(primary) === path.resolve(top)) return null
|
|
134
|
+
// A project in a subfolder of its repo has the same subfolder in the primary.
|
|
135
|
+
// A path that will not map (a symlinked spelling of the same tree) is asked
|
|
136
|
+
// about at the primary's root instead.
|
|
137
|
+
const rel = path.relative(top, projectDir)
|
|
138
|
+
return rel && !rel.startsWith('..') && !path.isAbsolute(rel) ? path.join(primary, rel) : primary
|
|
139
|
+
}
|
|
140
|
+
|
|
141
|
+
function walkUp(start, platform) {
|
|
142
|
+
let at = start
|
|
89
143
|
for (let i = 0; i < 6 && at; i++) {
|
|
90
144
|
for (const name of ENGINES) {
|
|
91
145
|
// ON WINDOWS, THE PACKAGE'S OWN JS ENTRY, never `.bin/<name>`. That is a
|
|
@@ -103,14 +157,26 @@ function findEngine(projectDir, platform = process.platform) {
|
|
|
103
157
|
if (up === at) break
|
|
104
158
|
at = up
|
|
105
159
|
}
|
|
106
|
-
return
|
|
160
|
+
return null
|
|
107
161
|
}
|
|
108
162
|
|
|
109
163
|
// How to run what `findEngine` found: a `.js` engine through this node, since
|
|
110
164
|
// Windows cannot execute one directly — anything else as itself, as before.
|
|
111
165
|
function engineCommand(projectDir, platform = process.platform) {
|
|
112
|
-
const engine =
|
|
113
|
-
|
|
166
|
+
const { engine, tried } = locateEngine(projectDir, platform)
|
|
167
|
+
const command = /\.[cm]?js$/i.test(engine) ? { file: process.execPath, args: [engine] } : { file: engine, args: [] }
|
|
168
|
+
return Object.defineProperty(command, 'tried', { value: tried })
|
|
169
|
+
}
|
|
170
|
+
|
|
171
|
+
// Still open, but not silently: an engine nobody can reach turns this guard off
|
|
172
|
+
// for as long as it stays unreachable, and the operator is owed one line saying
|
|
173
|
+
// so. Stderr with exit 0 is information, never a decision.
|
|
174
|
+
function unreachable(hook, engine, result) {
|
|
175
|
+
if (!result.error || result.error.code !== 'ENOENT') return
|
|
176
|
+
const dirs = engine.tried.length ? engine.tried.join(', ') : '(SKITTERSPEC_BIN)'
|
|
177
|
+
process.stderr.write(
|
|
178
|
+
`${hook}: no skitterspec engine found from ${dirs} or on PATH — this guard is off here; set SKITTERSPEC_BIN to fix\n`,
|
|
179
|
+
)
|
|
114
180
|
}
|
|
115
181
|
|
|
116
182
|
// The tools that write a file. A matcher is configured too, but a hook that is
|
|
@@ -169,6 +235,7 @@ function main() {
|
|
|
169
235
|
|
|
170
236
|
// No engine, a crash, a timeout — all cannot-tell. `status` is null when the
|
|
171
237
|
// process never ran or was killed, and neither is a refusal.
|
|
238
|
+
unreachable('main-guard', engine, result)
|
|
172
239
|
if (result.error || result.status === null) allow()
|
|
173
240
|
if (result.status !== 1) allow()
|
|
174
241
|
|
|
@@ -193,4 +260,4 @@ if (require.main === module) {
|
|
|
193
260
|
}
|
|
194
261
|
}
|
|
195
262
|
|
|
196
|
-
module.exports = { findEngine, engineCommand, WRITE_TOOLS, writeTarget, isRefusal }
|
|
263
|
+
module.exports = { findEngine, locateEngine, engineCommand, WRITE_TOOLS, writeTarget, isRefusal }
|
|
@@ -63,10 +63,69 @@ function readPayload() {
|
|
|
63
63
|
const ENGINES = ['skitterspec', 'skitterspec-linear', 'skitterspec-jira', 'skitterspec-github', 'skitterspec-azure-boards']
|
|
64
64
|
|
|
65
65
|
function findEngine(projectDir, platform = process.platform) {
|
|
66
|
-
|
|
67
|
-
|
|
66
|
+
return locateEngine(projectDir, platform).engine
|
|
67
|
+
}
|
|
68
|
+
|
|
69
|
+
/**
|
|
70
|
+
* `findEngine`, plus the directories it walked up from — which is what a hook
|
|
71
|
+
* names when nothing answered.
|
|
72
|
+
*
|
|
73
|
+
* A GIT WORKTREE IS A SIBLING OF ITS PRIMARY CHECKOUT, not a child of it
|
|
74
|
+
* (`worktree.root` is `../{repo}-wt`), so walking up from one never reaches the
|
|
75
|
+
* primary's `node_modules`. A `--docs` worktree has none of its own, so the
|
|
76
|
+
* primary checkout is asked for second — found through git, never guessed from
|
|
77
|
+
* the folder layout.
|
|
78
|
+
*/
|
|
79
|
+
function locateEngine(projectDir, platform = process.platform) {
|
|
80
|
+
if (process.env.SKITTERSPEC_BIN) return { engine: process.env.SKITTERSPEC_BIN, tried: [] }
|
|
81
|
+
const tried = [projectDir]
|
|
82
|
+
const local = walkUp(projectDir, platform)
|
|
83
|
+
if (local) return { engine: local, tried }
|
|
84
|
+
const primary = primaryCheckoutDir(projectDir)
|
|
85
|
+
if (primary) {
|
|
86
|
+
tried.push(primary)
|
|
87
|
+
const found = walkUp(primary, platform)
|
|
88
|
+
if (found) return { engine: found, tried }
|
|
89
|
+
}
|
|
90
|
+
return { engine: 'skitterspec', tried }
|
|
91
|
+
}
|
|
92
|
+
|
|
93
|
+
/**
|
|
94
|
+
* Where `projectDir` sits in the checkout its worktree was added from, or null
|
|
95
|
+
* when it is not in a linked worktree.
|
|
96
|
+
*
|
|
97
|
+
* WHAT WOULD FOOL THIS: a git directory kept somewhere else
|
|
98
|
+
* (`--separate-git-dir`, a submodule's `.git/modules/<name>`). Its parent then
|
|
99
|
+
* holds no `node_modules`, so the lookup finds nothing and falls through to
|
|
100
|
+
* PATH exactly as it did before — a wasted look, never a wrong engine.
|
|
101
|
+
*/
|
|
102
|
+
function primaryCheckoutDir(projectDir) {
|
|
103
|
+
const r = spawnSync('git', ['rev-parse', '--show-toplevel', '--git-common-dir'], {
|
|
104
|
+
cwd: projectDir,
|
|
105
|
+
encoding: 'utf8',
|
|
106
|
+
timeout: 2000,
|
|
107
|
+
})
|
|
108
|
+
if (r.error || r.status !== 0) return null
|
|
109
|
+
const [top, common] = (r.stdout || '').split(/\r?\n/)
|
|
110
|
+
if (!top || !common) return null
|
|
111
|
+
const primary = path.dirname(path.resolve(projectDir, common))
|
|
112
|
+
if (path.resolve(primary) === path.resolve(top)) return null
|
|
113
|
+
// A project in a subfolder of its repo has the same subfolder in the primary.
|
|
114
|
+
// A path that will not map (a symlinked spelling of the same tree) is asked
|
|
115
|
+
// about at the primary's root instead.
|
|
116
|
+
const rel = path.relative(top, projectDir)
|
|
117
|
+
return rel && !rel.startsWith('..') && !path.isAbsolute(rel) ? path.join(primary, rel) : primary
|
|
118
|
+
}
|
|
119
|
+
|
|
120
|
+
function walkUp(start, platform) {
|
|
121
|
+
let at = start
|
|
68
122
|
for (let i = 0; i < 6 && at; i++) {
|
|
69
123
|
for (const name of ENGINES) {
|
|
124
|
+
// ON WINDOWS, THE PACKAGE'S OWN JS ENTRY, never `.bin/<name>`. That is a
|
|
125
|
+
// shell shim nothing here can execute (spawn refuses it: EFTYPE), and the
|
|
126
|
+
// `.cmd` beside it needs a shell — which a hook handing a tool's command
|
|
127
|
+
// line over as an argument must never use. Unreachable, the hook failed
|
|
128
|
+
// open, and every guard was silently off on Windows (chore-windows-ci).
|
|
70
129
|
const candidate =
|
|
71
130
|
platform === 'win32'
|
|
72
131
|
? path.join(at, 'node_modules', '@skitterbyte', name, 'bin', `${name}.js`)
|
|
@@ -77,12 +136,26 @@ function findEngine(projectDir, platform = process.platform) {
|
|
|
77
136
|
if (up === at) break
|
|
78
137
|
at = up
|
|
79
138
|
}
|
|
80
|
-
return
|
|
139
|
+
return null
|
|
81
140
|
}
|
|
82
141
|
|
|
142
|
+
// How to run what `findEngine` found: a `.js` engine through this node, since
|
|
143
|
+
// Windows cannot execute one directly — anything else as itself, as before.
|
|
83
144
|
function engineCommand(projectDir, platform = process.platform) {
|
|
84
|
-
const engine =
|
|
85
|
-
|
|
145
|
+
const { engine, tried } = locateEngine(projectDir, platform)
|
|
146
|
+
const command = /\.[cm]?js$/i.test(engine) ? { file: process.execPath, args: [engine] } : { file: engine, args: [] }
|
|
147
|
+
return Object.defineProperty(command, 'tried', { value: tried })
|
|
148
|
+
}
|
|
149
|
+
|
|
150
|
+
// Still open, but not silently: an engine nobody can reach turns this guard off
|
|
151
|
+
// for as long as it stays unreachable, and the operator is owed one line saying
|
|
152
|
+
// so. Stderr with exit 0 is information, never a decision.
|
|
153
|
+
function unreachable(hook, engine, result) {
|
|
154
|
+
if (!result.error || result.error.code !== 'ENOENT') return
|
|
155
|
+
const dirs = engine.tried.length ? engine.tried.join(', ') : '(SKITTERSPEC_BIN)'
|
|
156
|
+
process.stderr.write(
|
|
157
|
+
`${hook}: no skitterspec engine found from ${dirs} or on PATH — this guard is off here; set SKITTERSPEC_BIN to fix\n`,
|
|
158
|
+
)
|
|
86
159
|
}
|
|
87
160
|
|
|
88
161
|
const WRITE_TOOLS = new Set(['Edit', 'Write', 'NotebookEdit', 'MultiEdit'])
|
|
@@ -143,6 +216,7 @@ function main() {
|
|
|
143
216
|
|
|
144
217
|
const engine = engineCommand(home)
|
|
145
218
|
const result = spawnSync(engine.file, [...engine.args, ...argv], { cwd: home, encoding: 'utf8', timeout: 8000 })
|
|
219
|
+
unreachable('project-guard', engine, result)
|
|
146
220
|
if (result.error || result.status !== 1) allow()
|
|
147
221
|
// Exit 1 alone is a crash as often as a refusal; the printed line decides.
|
|
148
222
|
const said = (result.stdout || '').trim()
|
|
@@ -158,4 +232,4 @@ if (require.main === module) {
|
|
|
158
232
|
}
|
|
159
233
|
}
|
|
160
234
|
|
|
161
|
-
module.exports = { findEngine, engineCommand, WRITE_TOOLS, writeTarget, mayConcern, insideHome, isRefusal }
|
|
235
|
+
module.exports = { findEngine, locateEngine, engineCommand, WRITE_TOOLS, writeTarget, mayConcern, insideHome, isRefusal }
|
|
@@ -81,8 +81,62 @@ function readPayload() {
|
|
|
81
81
|
const ENGINES = ['skitterspec', 'skitterspec-linear', 'skitterspec-jira', 'skitterspec-github', 'skitterspec-azure-boards']
|
|
82
82
|
|
|
83
83
|
function findEngine(projectDir, platform = process.platform) {
|
|
84
|
-
|
|
85
|
-
|
|
84
|
+
return locateEngine(projectDir, platform).engine
|
|
85
|
+
}
|
|
86
|
+
|
|
87
|
+
/**
|
|
88
|
+
* `findEngine`, plus the directories it walked up from — which is what a hook
|
|
89
|
+
* names when nothing answered.
|
|
90
|
+
*
|
|
91
|
+
* A GIT WORKTREE IS A SIBLING OF ITS PRIMARY CHECKOUT, not a child of it
|
|
92
|
+
* (`worktree.root` is `../{repo}-wt`), so walking up from one never reaches the
|
|
93
|
+
* primary's `node_modules`. A `--docs` worktree has none of its own, so the
|
|
94
|
+
* primary checkout is asked for second — found through git, never guessed from
|
|
95
|
+
* the folder layout.
|
|
96
|
+
*/
|
|
97
|
+
function locateEngine(projectDir, platform = process.platform) {
|
|
98
|
+
if (process.env.SKITTERSPEC_BIN) return { engine: process.env.SKITTERSPEC_BIN, tried: [] }
|
|
99
|
+
const tried = [projectDir]
|
|
100
|
+
const local = walkUp(projectDir, platform)
|
|
101
|
+
if (local) return { engine: local, tried }
|
|
102
|
+
const primary = primaryCheckoutDir(projectDir)
|
|
103
|
+
if (primary) {
|
|
104
|
+
tried.push(primary)
|
|
105
|
+
const found = walkUp(primary, platform)
|
|
106
|
+
if (found) return { engine: found, tried }
|
|
107
|
+
}
|
|
108
|
+
return { engine: 'skitterspec', tried }
|
|
109
|
+
}
|
|
110
|
+
|
|
111
|
+
/**
|
|
112
|
+
* Where `projectDir` sits in the checkout its worktree was added from, or null
|
|
113
|
+
* when it is not in a linked worktree.
|
|
114
|
+
*
|
|
115
|
+
* WHAT WOULD FOOL THIS: a git directory kept somewhere else
|
|
116
|
+
* (`--separate-git-dir`, a submodule's `.git/modules/<name>`). Its parent then
|
|
117
|
+
* holds no `node_modules`, so the lookup finds nothing and falls through to
|
|
118
|
+
* PATH exactly as it did before — a wasted look, never a wrong engine.
|
|
119
|
+
*/
|
|
120
|
+
function primaryCheckoutDir(projectDir) {
|
|
121
|
+
const r = spawnSync('git', ['rev-parse', '--show-toplevel', '--git-common-dir'], {
|
|
122
|
+
cwd: projectDir,
|
|
123
|
+
encoding: 'utf8',
|
|
124
|
+
timeout: 2000,
|
|
125
|
+
})
|
|
126
|
+
if (r.error || r.status !== 0) return null
|
|
127
|
+
const [top, common] = (r.stdout || '').split(/\r?\n/)
|
|
128
|
+
if (!top || !common) return null
|
|
129
|
+
const primary = path.dirname(path.resolve(projectDir, common))
|
|
130
|
+
if (path.resolve(primary) === path.resolve(top)) return null
|
|
131
|
+
// A project in a subfolder of its repo has the same subfolder in the primary.
|
|
132
|
+
// A path that will not map (a symlinked spelling of the same tree) is asked
|
|
133
|
+
// about at the primary's root instead.
|
|
134
|
+
const rel = path.relative(top, projectDir)
|
|
135
|
+
return rel && !rel.startsWith('..') && !path.isAbsolute(rel) ? path.join(primary, rel) : primary
|
|
136
|
+
}
|
|
137
|
+
|
|
138
|
+
function walkUp(start, platform) {
|
|
139
|
+
let at = start
|
|
86
140
|
for (let i = 0; i < 6 && at; i++) {
|
|
87
141
|
for (const name of ENGINES) {
|
|
88
142
|
// ON WINDOWS, THE PACKAGE'S OWN JS ENTRY, never `.bin/<name>`. That is a
|
|
@@ -100,14 +154,26 @@ function findEngine(projectDir, platform = process.platform) {
|
|
|
100
154
|
if (up === at) break
|
|
101
155
|
at = up
|
|
102
156
|
}
|
|
103
|
-
return
|
|
157
|
+
return null
|
|
104
158
|
}
|
|
105
159
|
|
|
106
160
|
// How to run what `findEngine` found: a `.js` engine through this node, since
|
|
107
161
|
// Windows cannot execute one directly — anything else as itself, as before.
|
|
108
162
|
function engineCommand(projectDir, platform = process.platform) {
|
|
109
|
-
const engine =
|
|
110
|
-
|
|
163
|
+
const { engine, tried } = locateEngine(projectDir, platform)
|
|
164
|
+
const command = /\.[cm]?js$/i.test(engine) ? { file: process.execPath, args: [engine] } : { file: engine, args: [] }
|
|
165
|
+
return Object.defineProperty(command, 'tried', { value: tried })
|
|
166
|
+
}
|
|
167
|
+
|
|
168
|
+
// Still open, but not silently: an engine nobody can reach turns this guard off
|
|
169
|
+
// for as long as it stays unreachable, and the operator is owed one line saying
|
|
170
|
+
// so. Stderr with exit 0 is information, never a decision.
|
|
171
|
+
function unreachable(hook, engine, result) {
|
|
172
|
+
if (!result.error || result.error.code !== 'ENOENT') return
|
|
173
|
+
const dirs = engine.tried.length ? engine.tried.join(', ') : '(SKITTERSPEC_BIN)'
|
|
174
|
+
process.stderr.write(
|
|
175
|
+
`${hook}: no skitterspec engine found from ${dirs} or on PATH — this guard is off here; set SKITTERSPEC_BIN to fix\n`,
|
|
176
|
+
)
|
|
111
177
|
}
|
|
112
178
|
|
|
113
179
|
// The engine's own refusal line, from `spec-env review gate --check`. Pure.
|
|
@@ -143,6 +209,7 @@ function main() {
|
|
|
143
209
|
|
|
144
210
|
// No engine, a crash, a timeout — all cannot-tell. `status` is null when the
|
|
145
211
|
// process never ran or was killed, and neither is a refusal.
|
|
212
|
+
unreachable('review-gate', engine, result)
|
|
146
213
|
if (result.error || result.status === null) allow()
|
|
147
214
|
if (result.status !== 1) allow()
|
|
148
215
|
|
|
@@ -178,4 +245,4 @@ if (require.main === module) {
|
|
|
178
245
|
}
|
|
179
246
|
}
|
|
180
247
|
|
|
181
|
-
module.exports = { findEngine, engineCommand, isRefusal }
|
|
248
|
+
module.exports = { findEngine, locateEngine, engineCommand, isRefusal }
|