@skitterbyte/skitterspec-linear 19.15.0 → 19.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/README.md +2 -1
- package/assets/claude-md-section.md +18 -9
- package/assets/commands/allow-main.md +1 -2
- 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-status/SKILL.md +1 -1
- package/assets/skills/spec-sync/SKILL.md +12 -12
- 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/linear/cli-sync.js +3 -3
- package/src/vendor/provider-kit/src/specs.js +46 -1
- package/src/vendor/sync-core/src/summary.js +10 -1
- package/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
|
package/README.md
CHANGED
|
@@ -85,6 +85,8 @@ them. Your `specs/` content and live `.core` config are never touched.
|
|
|
85
85
|
| `/spec-diff` | Read what a phase changed, on a page you can mark up |
|
|
86
86
|
| `/spec-reviewed` | Pick up a verdict pressed when nothing was waiting for it |
|
|
87
87
|
| `/spec-epic-next` | Name the epic member that can start now, to start in a new tab |
|
|
88
|
+
| `/spec-resume` | Go back into a spec in flight, by name or ticket, and act on a message |
|
|
89
|
+
| `/spec-park` | Record what a spec in flight is waiting on: a deploy, a release, a soak |
|
|
88
90
|
| `/spec-to-main` | Land the branch mid-spec, without finishing it |
|
|
89
91
|
| `/spec-complete` | Verify, land, tear down |
|
|
90
92
|
| `/spec-cancel` | Record why, stamp the header, tear down |
|
|
@@ -94,7 +96,6 @@ them. Your `specs/` content and live `.core` config are never touched.
|
|
|
94
96
|
| `/spec-init` | Bootstrap or repair the workflow in a project |
|
|
95
97
|
| `/spec-connect` | Point your canonical `localhost` ports at one spec's stack |
|
|
96
98
|
| `/spec-live` | Check one spec out in the primary checkout, so your running server reloads it |
|
|
97
|
-
| `/spec-remote-review` | Permit (or forbid) reviewing from off your network |
|
|
98
99
|
| `/allow-main` | Allow writes on the base branch for this session — yours to run, never Claude's |
|
|
99
100
|
| `/allow-project` | Let this session work on another skitterspec project — yours to run, never Claude's |
|
|
100
101
|
| `/spec-skip` | Move on from a phase without a verdict, reason recorded — yours to run, never Claude's |
|
|
@@ -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.
|
|
@@ -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 }
|