@skitterbyte/skitterspec-jira 2.17.0 → 2.18.1
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 +51 -0
- package/assets/core/env.config.md +5 -2
- package/assets/rules/spec-planning.md +12 -0
- package/assets/rules/spec-reports.md +60 -2
- package/assets/skills/spec-next/SKILL.md +11 -1
- package/package.json +1 -1
- package/src/cli.js +59 -2
- package/src/env/hooks.js +6 -3
- package/src/init.js +496 -14
package/MIGRATION.md
CHANGED
|
@@ -1,5 +1,56 @@
|
|
|
1
1
|
# Migration guide
|
|
2
2
|
|
|
3
|
+
## A PR-mode finish runs the `afterLand` entries its land matched (nothing to edit)
|
|
4
|
+
|
|
5
|
+
After the host merged a PR, `spec-env integrate` used to print `nothing to
|
|
6
|
+
run` and list every conditional `afterLand` entry under `skipped (nothing in
|
|
7
|
+
the land matched)`, whatever its `when` said. The range it read was the
|
|
8
|
+
branch's own (`origin/main...branch`), and a merged branch is already inside
|
|
9
|
+
`origin/main`, so that range was always empty.
|
|
10
|
+
|
|
11
|
+
The finish now reads what the primary checkout's base gains by catching up
|
|
12
|
+
(`main...origin/main`), so an entry whose glob matches a file in the land
|
|
13
|
+
runs, with `# <path> changed`. Where base was already caught up by hand,
|
|
14
|
+
nothing lies between the two refs. That range is treated as unknown, and the
|
|
15
|
+
conditional entries run with `# range unknown`.
|
|
16
|
+
|
|
17
|
+
Your globs were right: a leading `**/` already matched a top-level path. If
|
|
18
|
+
a PR-mode land skipped an install or a generate, run it by hand in the
|
|
19
|
+
primary checkout once. Later lands run it for you.
|
|
20
|
+
|
|
21
|
+
## A local install stays local in a worktree (check for stray team files)
|
|
22
|
+
|
|
23
|
+
`update` run inside a worktree of a local install (`init --local`) used to run
|
|
24
|
+
as a **team** install. The manifest that records `"scope": "local"` is kept out
|
|
25
|
+
of git, and `spec-env bootstrap` did not seed it, so the worktree had none.
|
|
26
|
+
That run then:
|
|
27
|
+
|
|
28
|
+
- appended the `<!-- skitterspec:start -->` block to the **tracked**
|
|
29
|
+
`CLAUDE.md`,
|
|
30
|
+
- created an untracked `.claude/settings.json` holding skitterspec's hooks,
|
|
31
|
+
- listed unedited managed files as `customized (kept)`,
|
|
32
|
+
- and wrote the worktree a manifest with no `scope`.
|
|
33
|
+
|
|
34
|
+
Bootstrap now seeds the manifest with the other local-install files. `update`
|
|
35
|
+
also reads a local scope from the `.git/info/exclude` block when a worktree
|
|
36
|
+
has no manifest of its own, so a worktree bootstrapped before this release is
|
|
37
|
+
covered without re-bootstrapping. It reports
|
|
38
|
+
`local install (recorded in .git/info/exclude) — kept local`.
|
|
39
|
+
|
|
40
|
+
**If an earlier `update` already ran in such a worktree, revert it by hand.**
|
|
41
|
+
Nothing removes it for you, because a `CLAUDE.md` edit or a
|
|
42
|
+
`.claude/settings.json` might be yours:
|
|
43
|
+
|
|
44
|
+
```
|
|
45
|
+
git checkout -- CLAUDE.md # drop the appended block
|
|
46
|
+
rm .claude/settings.json # only if skitterspec created it
|
|
47
|
+
rm specs/.core/.skitterspec-manifest.json # the scopeless one it wrote
|
|
48
|
+
skitterspec spec-env bootstrap <spec> # re-seeds the primary's manifest
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
Run these in the worktree. A worktree that never ran `update` needs nothing.
|
|
52
|
+
|
|
53
|
+
|
|
3
54
|
## The tailnet is `remote`; publishing the review is retired (nothing to edit)
|
|
4
55
|
|
|
5
56
|
The review stack's `remote:` line used to be a claude.ai page the review was
|
|
@@ -202,10 +202,13 @@ through to a documented conservative default; see the field notes below.
|
|
|
202
202
|
// The changed files are what the land brings into the base branch:
|
|
203
203
|
// `base...branch` for `integrate` (read before the rebase, so it is the
|
|
204
204
|
// branch's own changes), and the carried fix commits — minus the release's
|
|
205
|
-
// version commit — for `hotfix land`.
|
|
205
|
+
// version commit — for `hotfix land`. A PR-mode finish (the host has
|
|
206
|
+
// merged) reads `base...<remote>/<base>`: what the primary checkout's base
|
|
207
|
+
// gains by catching up, since the landed branch's own range is empty.
|
|
206
208
|
// When that cannot be known, the conditional entries RUN. That is the
|
|
207
209
|
// "already landed" plan (the land happened elsewhere, so its range is not
|
|
208
|
-
// here)
|
|
210
|
+
// here), a PR-mode finish whose base was already caught up by hand, and
|
|
211
|
+
// any diff git would not answer. A redundant generate costs
|
|
209
212
|
// seconds; a skipped one leaves the base red with nothing pointing at why.
|
|
210
213
|
// A land that changed no files is known, not unknown, and skips them.
|
|
211
214
|
// The plan says why for every entry: a matched one ends in
|
|
@@ -36,6 +36,18 @@ finding one. They are marked `disable-model-invocation`, meaning
|
|
|
36
36
|
**only you can run them** — a skill that wants one will tell you to type it
|
|
37
37
|
rather than invoking it.
|
|
38
38
|
|
|
39
|
+
**A command finds the project itself, wherever the session stands.** Its line
|
|
40
|
+
runs in the session's current directory, which after a `cd` may be the git root
|
|
41
|
+
or a worktree's root rather than the project folder — and in a repo whose
|
|
42
|
+
project is a subfolder, a runner started there found no install and printed
|
|
43
|
+
npm's registry 404. So with a local install the line is a small `node -e`
|
|
44
|
+
launcher, written that way because both `/bin/sh` and cmd.exe can start it. It
|
|
45
|
+
runs in the current directory when the install is there, which is the usual case and unchanged. Otherwise
|
|
46
|
+
it runs in this checkout's project folder, using the subfolder recorded when
|
|
47
|
+
the command was installed and the primary checkout's install when a worktree
|
|
48
|
+
has none. Failing both, it refuses in one line naming the folder it expected.
|
|
49
|
+
`skitterspec update` rewrites the command files to this form.
|
|
50
|
+
|
|
39
51
|
**The `spec-remote-review` command was retired** with the published review tier
|
|
40
52
|
(feat-tailnet-remote-tier). It toggled whether a spec might publish its review
|
|
41
53
|
as a claude.ai page — a second store no wait could watch, and a page this
|
|
@@ -460,6 +460,47 @@ work on. A row that cannot be run spends the trust the position was designed to
|
|
|
460
460
|
earn — and the two skills that got it wrong got it wrong independently, which is
|
|
461
461
|
what makes it a missing constraint rather than two slips.
|
|
462
462
|
|
|
463
|
+
### Open manual steps are rows
|
|
464
|
+
|
|
465
|
+
When the next action includes steps only a person can do — a manual test pass,
|
|
466
|
+
a check in the running app — and any are still open, `Next`
|
|
467
|
+
**lists every one of them, one per row**. The label sits on the first row
|
|
468
|
+
only, each step gets a row of its own with the label cell blank, and a closing
|
|
469
|
+
row names what comes after:
|
|
470
|
+
|
|
471
|
+
| | |
|
|
472
|
+
|---|---|
|
|
473
|
+
| **Follow-ups** | none |
|
|
474
|
+
| **Next** | `/spec-live`, then: |
|
|
475
|
+
| | 1. Open Settings → Business Unit Setup |
|
|
476
|
+
| | 2. Pick a business unit with gaps; each process shows ✗ with its gaps |
|
|
477
|
+
| | 3. Set one process up, press **Check again**; its card turns ✓ |
|
|
478
|
+
| | then `/spec-next` to finish phase 5 |
|
|
479
|
+
|
|
480
|
+
**A count is not a list.** `run the seven manual steps` names steps the reader
|
|
481
|
+
cannot see: the list it means is several messages up, or gone after a `/clear`.
|
|
482
|
+
Neither is the phase file's path — that sends the reader out of the terminal to
|
|
483
|
+
find out what to do, which is the failure `/spec-next`'s *Manual steps* exists
|
|
484
|
+
to fix.
|
|
485
|
+
|
|
486
|
+
**Copy them from the phase file, never from an earlier message.** The open
|
|
487
|
+
manual tasks there — and the numbered sub-tasks `/spec-next` writes under a
|
|
488
|
+
vague one — are the record. A run that did not list them (`/commit`,
|
|
489
|
+
`/spec-resume`) reads them there; one that did copies the same text. A
|
|
490
|
+
conversation is not durable, and steps re-made from memory drift from the ones
|
|
491
|
+
the reader was shown.
|
|
492
|
+
|
|
493
|
+
**It applies to every skill's block**, not only `/spec-next`'s. The report this
|
|
494
|
+
was written from came from `/commit`, after `/spec-next` had listed the steps
|
|
495
|
+
and been answered **Not yet**.
|
|
496
|
+
|
|
497
|
+
**It is an amendment, and it is argued from this section's own rule.** It adds
|
|
498
|
+
no row type and nothing after the block — `Next` stays last, and is the same
|
|
499
|
+
single next action, written out. A `Next` that counts steps out of sight is not
|
|
500
|
+
runnable from the state the run leaves behind; one row per step is what makes it
|
|
501
|
+
so, and seven steps in one cell are a paragraph nobody follows. A report with no
|
|
502
|
+
open manual steps keeps its one-row `Next`.
|
|
503
|
+
|
|
463
504
|
## Field vocabulary, in this order
|
|
464
505
|
|
|
465
506
|
A skill emits only the fields it declares, in this order, skipping the rest.
|
|
@@ -484,7 +525,7 @@ behind it — say nothing rather than reporting that there was nothing to report
|
|
|
484
525
|
| `Untouched` | Uncommitted work the run deliberately left alone — whose, and how much. |
|
|
485
526
|
| `Review` | The rendered diff page: files, `+`/`−`, and the stack — the same tiers the banner lists, labelled, run together with `·` because a row is one cell, with any alternates inline after their tier's URL (`also <url>`), plus `live` where the engine reported one. **No question** — a row cannot be waited on, so a question in one is unanswerable by construction (see *asking implies waiting*). **Omitted entirely when the run is waiting on a verdict**: the banner after the block carries it instead, and a row saying the same thing beside it splits the reader's attention across two places. |
|
|
486
527
|
| `Follow-ups` | **Always.** `none`, or one line each. |
|
|
487
|
-
| `Next` | **Last.** The single next action for this work — runnable from the state the run leaves behind. |
|
|
528
|
+
| `Next` | **Last.** The single next action for this work — runnable from the state the run leaves behind. Open manual steps take a row each (*Open manual steps are rows*). |
|
|
488
529
|
|
|
489
530
|
The order runs identity → context → what happened → where it went → what to do.
|
|
490
531
|
**`Tracker` is first** because the id is what addresses this work outside the
|
|
@@ -533,7 +574,8 @@ silence.
|
|
|
533
574
|
|
|
534
575
|
## Where the block may grow
|
|
535
576
|
|
|
536
|
-
|
|
577
|
+
Two places. `Next` takes a row per open manual step (*Open manual steps are
|
|
578
|
+
rows*, above). And a non-`✅` verdict adds a `Why` row, and quotes the output that
|
|
537
579
|
justifies it — the failing assertion, the conflict, the engine's refusal — in a
|
|
538
580
|
fenced block **above** the table, where a fence means what a fence should mean:
|
|
539
581
|
|
|
@@ -601,6 +643,22 @@ the reasoning.
|
|
|
601
643
|
| **Follow-ups** | Session expiry is read from two places; phase 4 leans on one |
|
|
602
644
|
| **Next** | `/spec-next` → phase 4 (Docs) |
|
|
603
645
|
|
|
646
|
+
**`⚠️` — stopped at manual steps answered Not yet.**
|
|
647
|
+
|
|
648
|
+
⚠️ **Phase 2 code built; manual check open** — `feat-orders`, 2 of 4
|
|
649
|
+
|
|
650
|
+
| | |
|
|
651
|
+
|---|---|
|
|
652
|
+
| **Branch** | `spec/feat-orders` · 3 commits, dirty |
|
|
653
|
+
| **Built** | Order form, POST /orders handler |
|
|
654
|
+
| **Tests** | 131 passed · npm test |
|
|
655
|
+
| **Notes** | Manual check answered **Not yet** — the phase stays `🔄` |
|
|
656
|
+
| **Follow-ups** | none |
|
|
657
|
+
| **Next** | `/commit`, then `/spec-live`, then: |
|
|
658
|
+
| | 1. Place an order with two lines; the confirmation lists both |
|
|
659
|
+
| | 2. Place one with a negative quantity; the form refuses it |
|
|
660
|
+
| | then `/spec-next` to finish phase 2 |
|
|
661
|
+
|
|
604
662
|
**`⏸` — refused, nothing changed.**
|
|
605
663
|
|
|
606
664
|
⏸ **`/spec-next` refused — no spec in flight**
|
|
@@ -347,6 +347,13 @@ plain markdown list in the conversation — never fenced, and
|
|
|
347
347
|
out of the terminal to find out what to do, which is the failure this exists to
|
|
348
348
|
fix; the steps themselves are what they act on.
|
|
349
349
|
|
|
350
|
+
**Steps you had to write are saved first.** When the phase file holds only a
|
|
351
|
+
vague manual task — "check it on the running host" — and you wrote the steps
|
|
352
|
+
yourself, add them under that task as numbered sub-checkboxes **before** you
|
|
353
|
+
ask. The conversation does not survive a `/clear`, and a later run that makes
|
|
354
|
+
up its own set lists different steps from the ones the reader was shown. A
|
|
355
|
+
phase whose manual steps are already tasks is left as it is.
|
|
356
|
+
|
|
350
357
|
Then ask one question, with three answers:
|
|
351
358
|
|
|
352
359
|
- **All done** — tick those steps and carry on to the end of the phase.
|
|
@@ -365,6 +372,8 @@ needs no new shape in the report.
|
|
|
365
372
|
tasks after an unconfirmed step are not built past it, and the phase did not
|
|
366
373
|
end: **skip §4's done-marking and §5 entirely** — no page, no arm, no wait.
|
|
367
374
|
End `⚠️` and name `/spec-next` in `Next`; it re-lists the same unticked steps.
|
|
375
|
+
Its `Next` lists the open steps a row each, copied from the phase file —
|
|
376
|
+
`.claude/rules/spec-reports.md`, *Open manual steps are rows*.
|
|
368
377
|
|
|
369
378
|
## 4. Record progress
|
|
370
379
|
|
|
@@ -706,7 +715,8 @@ the shape; this section carries only what is specific here.
|
|
|
706
715
|
- `⚠️` — built and green, with something worth knowing (a mirror that did not
|
|
707
716
|
refresh, a deviation from the plan) — or stopped at manual steps answered
|
|
708
717
|
**Some failed** or **Not yet**: the phase stays `🔄`, `Notes` says which steps
|
|
709
|
-
are open, and `Next` is `/commit
|
|
718
|
+
are open, and `Next` is `/commit`, then a row per open step, then
|
|
719
|
+
`/spec-next` to pick them up.
|
|
710
720
|
- `❌` — the phase's tests are red, or it stopped part-way. Quote the failure.
|
|
711
721
|
- `⏸` — no spec in flight, several in flight with this session in none of
|
|
712
722
|
them, or the name given does not match the one that is.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@skitterbyte/skitterspec-jira",
|
|
3
|
-
"version": "2.
|
|
3
|
+
"version": "2.18.1",
|
|
4
4
|
"description": "Spec-driven development for Claude Code, with one-way Jira Cloud sync — a superset of @skitterbyte/skitterspec: the base filesystem workflow plus /spec-status · /spec-push and the spec-sync CLI. The repo is canonical; Jira is a generated mirror. Install this OR the base OR the Linear superset — exactly one.",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"claude",
|
package/src/cli.js
CHANGED
|
@@ -5,7 +5,7 @@ const path = require('path')
|
|
|
5
5
|
const os = require('os')
|
|
6
6
|
const { pathToFileURL } = require('url')
|
|
7
7
|
const { execFileSync } = require('child_process')
|
|
8
|
-
const { init, resync, reset, checkSync, isExistingSetup, localSeedFiles } = require('./init.js')
|
|
8
|
+
const { init, resync, reset, uninstall, disable, enable, checkSync, isExistingSetup, localSeedFiles } = require('./init.js')
|
|
9
9
|
const {
|
|
10
10
|
detectReleaseTooling,
|
|
11
11
|
removeReleaseTooling,
|
|
@@ -287,6 +287,16 @@ Usage:
|
|
|
287
287
|
edits (--force to overwrite). Leaves specs/ + live
|
|
288
288
|
.core config alone. --check reports what it would
|
|
289
289
|
change and writes nothing.
|
|
290
|
+
skitterspec uninstall [dir] Take a local install (init --local) back off this
|
|
291
|
+
machine: managed files, hooks, the CLAUDE.local.md
|
|
292
|
+
block, the git excludes. Prints the plan; --yes
|
|
293
|
+
acts. Edited files are kept; specs/ is untouched.
|
|
294
|
+
Refuses a team install, or while a spec is in flight.
|
|
295
|
+
skitterspec disable [dir] Switch a local install off for this machine's
|
|
296
|
+
Claude — skills, commands, rules, hooks, the
|
|
297
|
+
CLAUDE.local.md block — leaving the files on disk.
|
|
298
|
+
skitterspec enable [dir] Switch it back on; installs it (init --local) when
|
|
299
|
+
there is nothing here to switch on.
|
|
290
300
|
skitterspec spec-env <cmd> Per-spec isolation engine (opt-in; needs
|
|
291
301
|
specs/.core/env.config.json). Subcommands:
|
|
292
302
|
up <spec> print the plan to provision a worktree +
|
|
@@ -3472,7 +3482,9 @@ function specEnvIntegratePr(dir, config, spec, base, flags, retarget = null) {
|
|
|
3472
3482
|
// branch's own range — remote image first, local base as the fallback
|
|
3473
3483
|
// when the remote ref is not here.
|
|
3474
3484
|
primaryPath: dir,
|
|
3475
|
-
changedFiles:
|
|
3485
|
+
changedFiles: aheadOfRemoteBase === false
|
|
3486
|
+
? catchUpRange(git, base, `${remote}/${base}`)
|
|
3487
|
+
: landRange(git, `${remote}/${base}`, spec.branch) || landRange(git, base, spec.branch),
|
|
3476
3488
|
worktreeState: { dirty },
|
|
3477
3489
|
base,
|
|
3478
3490
|
remote,
|
|
@@ -3723,6 +3735,21 @@ function landRange(git, base, branch) {
|
|
|
3723
3735
|
return out.split('\n').map((l) => l.trim()).filter(Boolean)
|
|
3724
3736
|
}
|
|
3725
3737
|
|
|
3738
|
+
// The range of a PR-mode finish: what local base gains by catching up with the
|
|
3739
|
+
// remote image the host merged into. The branch's own range cannot answer once
|
|
3740
|
+
// it has landed — it is inside `<remote>/<base>`, so `<remote>/<base>...branch`
|
|
3741
|
+
// is empty, and an empty known range skipped every conditional entry
|
|
3742
|
+
// (bug-pr-afterland-range).
|
|
3743
|
+
//
|
|
3744
|
+
// WHAT WOULD FOOL IT: a base already caught up by hand (`git pull`), which
|
|
3745
|
+
// leaves nothing between the two refs while the afterLand those files wanted
|
|
3746
|
+
// never ran. Empty therefore reads as unknown, which runs the conditional
|
|
3747
|
+
// entries (`.claude/rules/negative-checks.md` rule 4).
|
|
3748
|
+
function catchUpRange(git, base, remoteBase) {
|
|
3749
|
+
const range = landRange(git, base, remoteBase)
|
|
3750
|
+
return range && range.length ? range : null
|
|
3751
|
+
}
|
|
3752
|
+
|
|
3726
3753
|
// The `afterLand` commands, as a section printed after a land plan — or after
|
|
3727
3754
|
// integrate's already-landed line. Empty string when none apply, so a project
|
|
3728
3755
|
// without the key sees exactly the output it always has, and one of plain
|
|
@@ -8530,6 +8557,36 @@ async function run(argv) {
|
|
|
8530
8557
|
resync(dir, { claudeMd: opts.claudeMd, force: opts.force, diff: opts.diff, local: opts.local })
|
|
8531
8558
|
await cleanupReleaseTooling(dir, opts)
|
|
8532
8559
|
break
|
|
8560
|
+
case 'uninstall': {
|
|
8561
|
+
// What is in flight is read here, where the spec machinery lives, and
|
|
8562
|
+
// handed to the engine: every provisioned worktree (specless ones too)
|
|
8563
|
+
// and a live overlay holding the primary checkout. A read that throws is
|
|
8564
|
+
// cannot-tell, and the engine refuses on it rather than deleting.
|
|
8565
|
+
const inFlight = []
|
|
8566
|
+
let cannotTell = null
|
|
8567
|
+
try {
|
|
8568
|
+
// Anchored as spec-env anchors, so a project in a subfolder of its
|
|
8569
|
+
// repo, or a run from inside a worktree, reads the same registry.
|
|
8570
|
+
const anchor = primaryAnchor(dir, gitReader(dir))
|
|
8571
|
+
const { config } = loadEnvConfig(anchor.dir)
|
|
8572
|
+
attachProject(config, anchor)
|
|
8573
|
+
for (const w of provisionedSpecChoice(anchor.dir, config, anchor.dir, { lastLive: false }).worktrees) {
|
|
8574
|
+
inFlight.push({ spec: w.spec, where: `(worktree ${w.worktree})` })
|
|
8575
|
+
}
|
|
8576
|
+
const receipt = readReceipt(anchor.dir, config)
|
|
8577
|
+
if (receipt && receipt.spec) inFlight.push({ spec: String(receipt.spec), where: '(live in the primary checkout)' })
|
|
8578
|
+
} catch (error) {
|
|
8579
|
+
cannotTell = error.message
|
|
8580
|
+
}
|
|
8581
|
+
process.exitCode = uninstall(dir, { yes: opts.yes, inFlight, cannotTell })
|
|
8582
|
+
break
|
|
8583
|
+
}
|
|
8584
|
+
case 'disable':
|
|
8585
|
+
process.exitCode = disable(dir)
|
|
8586
|
+
break
|
|
8587
|
+
case 'enable':
|
|
8588
|
+
process.exitCode = await enable(dir)
|
|
8589
|
+
break
|
|
8533
8590
|
default:
|
|
8534
8591
|
throw new Error(unknownCommand(cmd))
|
|
8535
8592
|
}
|
package/src/env/hooks.js
CHANGED
|
@@ -225,12 +225,15 @@ function ensureHooks(dir, { local = false } = {}) {
|
|
|
225
225
|
* group left with no hooks is dropped, then an empty `PreToolUse`, then an empty
|
|
226
226
|
* `hooks`. Every other key — and every other event — is untouched.
|
|
227
227
|
*
|
|
228
|
+
* `local` reads `settings.local.json` instead, for `uninstall` taking a local
|
|
229
|
+
* install back off; `dryRun` counts what would go and writes nothing.
|
|
230
|
+
*
|
|
228
231
|
* Returns `{ removed, emptied, reason }`. `emptied` is true when nothing is left
|
|
229
232
|
* but `{}`: the caller deletes the file then, since a committed `{}` is noise.
|
|
230
233
|
* A missing file is `absent`; an unparseable one is `malformed` and untouched.
|
|
231
234
|
*/
|
|
232
|
-
function removeHooks(dir) {
|
|
233
|
-
const file = settingsPath(dir)
|
|
235
|
+
function removeHooks(dir, { local = false, dryRun = false } = {}) {
|
|
236
|
+
const file = settingsPath(dir, { local })
|
|
234
237
|
let parsed
|
|
235
238
|
try {
|
|
236
239
|
parsed = JSON.parse(fs.readFileSync(file, 'utf-8'))
|
|
@@ -259,7 +262,7 @@ function removeHooks(dir) {
|
|
|
259
262
|
else delete parsed.hooks.PreToolUse
|
|
260
263
|
if (!Object.keys(parsed.hooks).length) delete parsed.hooks
|
|
261
264
|
const emptied = !Object.keys(parsed).length
|
|
262
|
-
if (!emptied) writeSettings(file, parsed)
|
|
265
|
+
if (!emptied && !dryRun) writeSettings(file, parsed)
|
|
263
266
|
return { removed, emptied, reason: 'removed' }
|
|
264
267
|
}
|
|
265
268
|
|
package/src/init.js
CHANGED
|
@@ -245,8 +245,88 @@ function renderExec(content, dir, env = process.env) {
|
|
|
245
245
|
})
|
|
246
246
|
}
|
|
247
247
|
|
|
248
|
-
//
|
|
249
|
-
|
|
248
|
+
// --- the command launcher (bug-commands-outside-project) -------------------
|
|
249
|
+
//
|
|
250
|
+
// A command file lives in the project folder's `.claude/commands/`, but its `!`
|
|
251
|
+
// line runs in whatever directory the SESSION is standing in. A runner resolves
|
|
252
|
+
// the install from there, so in a repo whose project is a subfolder a session
|
|
253
|
+
// that had cd'd to the git root — or to a worktree's root — got npm's registry
|
|
254
|
+
// 404 instead of the engine. So on the local rung a command's `{{exec}}` renders
|
|
255
|
+
// as a launcher that picks the folder first:
|
|
256
|
+
//
|
|
257
|
+
// 1. the cwd, walking up, when the install is there — the healthy path, run
|
|
258
|
+
// in the cwd exactly as before;
|
|
259
|
+
// 2. else this checkout's project folder (git toplevel + the prefix recorded
|
|
260
|
+
// here at render time), then the primary checkout's — a `--docs` worktree
|
|
261
|
+
// has no install of its own — run in THIS checkout's project folder, so a
|
|
262
|
+
// bare command still means the spec you are standing on;
|
|
263
|
+
// 3. else one line naming the folder it expected, exit 1.
|
|
264
|
+
//
|
|
265
|
+
// It is `node -e`, inline, rather than a script file beside the commands,
|
|
266
|
+
// because finding a file from an unknown cwd is the very problem being solved,
|
|
267
|
+
// and a local-scope install keeps `.claude/` out of git, so a worktree may not
|
|
268
|
+
// have one. Node runs the engine's JS entry directly (no `.bin` shim, no
|
|
269
|
+
// shell), which is the one form both `/bin/sh` and cmd.exe can start — vm-bridge
|
|
270
|
+
// runs these lines through cmd.
|
|
271
|
+
//
|
|
272
|
+
// WHAT WOULD BREAK IT: the line passes through two shells' quoting. It is one
|
|
273
|
+
// double-quoted word, so the script must hold no `"`, `$`, `` ` ``, `\`, `%` or
|
|
274
|
+
// `!` — and neither may anything substituted into it. A prefix holding one of
|
|
275
|
+
// those is cannot-tell and renders as `''` (rule 4): rungs 1 and 3 still hold.
|
|
276
|
+
const LAUNCHER = [
|
|
277
|
+
"const f=require('fs'),p=require('path'),c=require('child_process'),K='{{pkg}}',B='{{bin}}',P='{{prefix}}'",
|
|
278
|
+
"const g=a=>{try{return c.execFileSync('git',a,{encoding:'utf8',stdio:['ignore','pipe','ignore']}).trim()}catch(e){}}",
|
|
279
|
+
'const w=d=>{for(let i=0;i<6;i++){const m=p.join(d,' +
|
|
280
|
+
"'node_modules',K,'package.json');if(f.existsSync(m)){const b=JSON.parse(f.readFileSync(m,'utf8')).bin;" +
|
|
281
|
+
"return p.join(p.dirname(m),typeof b=='string'?b:b[B])}const u=p.dirname(d);if(u==d)return;d=u}}",
|
|
282
|
+
'let d=process.cwd(),e=w(d)',
|
|
283
|
+
"if(e==null){const t=g(['rev-parse','--show-toplevel']),m=g(['rev-parse','--git-common-dir']);" +
|
|
284
|
+
'if(t){d=p.join(t,P);e=w(d)||m&&w(p.join(p.dirname(p.resolve(m)),P))}}',
|
|
285
|
+
"if(e==null){console.error(B+': not installed for '+d+' (no node_modules/'+K+' there or above) - install it there, or run from the project folder');process.exit(1)}",
|
|
286
|
+
"const r=c.spawnSync(process.execPath,[e,...process.argv.slice(1)],{cwd:d,stdio:'inherit'});process.exit(r.status==null?1:r.status)",
|
|
287
|
+
].join(';')
|
|
288
|
+
|
|
289
|
+
const UNSAFE_IN_LAUNCHER = /["'$`\\%!]/
|
|
290
|
+
|
|
291
|
+
// The project's folder within its git repo, as a repo path — '' at the root,
|
|
292
|
+
// outside a repo, or when it cannot be carried safely in the launcher.
|
|
293
|
+
function launcherPrefix(dir) {
|
|
294
|
+
let top
|
|
295
|
+
try {
|
|
296
|
+
top = execFileSync('git', ['-C', dir, 'rev-parse', '--show-toplevel'], {
|
|
297
|
+
encoding: 'utf8',
|
|
298
|
+
stdio: ['ignore', 'pipe', 'ignore'],
|
|
299
|
+
}).trim()
|
|
300
|
+
} catch {
|
|
301
|
+
return ''
|
|
302
|
+
}
|
|
303
|
+
const real = (p) => {
|
|
304
|
+
try {
|
|
305
|
+
return fs.realpathSync.native(p)
|
|
306
|
+
} catch {
|
|
307
|
+
return path.resolve(p)
|
|
308
|
+
}
|
|
309
|
+
}
|
|
310
|
+
const rel = path.relative(real(top), real(dir))
|
|
311
|
+
if (!rel || rel.startsWith('..') || path.isAbsolute(rel)) return ''
|
|
312
|
+
const prefix = rel.split(path.sep).join('/')
|
|
313
|
+
return UNSAFE_IN_LAUNCHER.test(prefix) ? '' : prefix
|
|
314
|
+
}
|
|
315
|
+
|
|
316
|
+
function launcherFor(bin, dir) {
|
|
317
|
+
const script = LAUNCHER.replace('{{pkg}}', distributionPackage())
|
|
318
|
+
.replace('{{bin}}', bin)
|
|
319
|
+
.replace('{{prefix}}', launcherPrefix(dir))
|
|
320
|
+
return `node -e "${script}" --`
|
|
321
|
+
}
|
|
322
|
+
|
|
323
|
+
// What a command file's `!` line runs. Only the local rung changes: a global
|
|
324
|
+
// install and the `npx -p` fallback resolve the same from any directory.
|
|
325
|
+
function renderCommand(content, dir, env = process.env) {
|
|
326
|
+
if (!content.includes('{{exec}}')) return content
|
|
327
|
+
if (detectRunner(dir, env).rung !== 'local') return renderExec(content, dir, env)
|
|
328
|
+
return content.replace(EXEC_RE, (_m, _sp, bin) => (bin ? launcherFor(bin, dir) : 'node'))
|
|
329
|
+
}
|
|
250
330
|
|
|
251
331
|
// Which managed files carry the token: markdown only. Hooks and JSON templates
|
|
252
332
|
// are copied byte for byte.
|
|
@@ -318,6 +398,7 @@ const report = { created: [], updated: [], skipped: [], refused: [], removed: []
|
|
|
318
398
|
|
|
319
399
|
function resetReport() {
|
|
320
400
|
scope = 'team'
|
|
401
|
+
enabledOnFlush = null
|
|
321
402
|
for (const k of Object.keys(report)) report[k].length = 0
|
|
322
403
|
for (const k of Object.keys(writtenHashes)) delete writtenHashes[k]
|
|
323
404
|
}
|
|
@@ -386,7 +467,7 @@ function managedTargets(dir) {
|
|
|
386
467
|
})
|
|
387
468
|
for (const name of SKILLS) add(path.join('skills', name, 'SKILL.md'), path.join(dir, '.claude', 'skills', name, 'SKILL.md'))
|
|
388
469
|
for (const name of COMMANDS)
|
|
389
|
-
add(path.join('commands', name), path.join(dir, '.claude', 'commands', name))
|
|
470
|
+
add(path.join('commands', name), path.join(dir, '.claude', 'commands', name), renderCommand)
|
|
390
471
|
for (const name of RULES) add(path.join('rules', name), path.join(dir, '.claude', 'rules', name))
|
|
391
472
|
for (const name of HOOKS) add(path.join('hooks', name), path.join(dir, '.claude', 'hooks', name))
|
|
392
473
|
for (const asset of CORE_FILES) add(asset, path.join(dir, 'specs', '.core', path.basename(asset)))
|
|
@@ -424,20 +505,25 @@ function readManifest(dir) {
|
|
|
424
505
|
// Absent means team: every manifest written before `--local` existed
|
|
425
506
|
// reads exactly as it did.
|
|
426
507
|
scope: parsed.scope === 'local' ? 'local' : 'team',
|
|
508
|
+
// Absent means enabled: only `disable` writes the field.
|
|
509
|
+
enabled: parsed.enabled !== false,
|
|
427
510
|
}
|
|
428
511
|
}
|
|
429
512
|
} catch {
|
|
430
513
|
/* missing or malformed → empty baseline */
|
|
431
514
|
}
|
|
432
|
-
return { version: MANIFEST_VERSION, files: {}, baselined: false, scope: 'team' }
|
|
515
|
+
return { version: MANIFEST_VERSION, files: {}, baselined: false, scope: 'team', enabled: true }
|
|
433
516
|
}
|
|
434
517
|
|
|
435
|
-
function writeManifest(dir, files, { local = false } = {}) {
|
|
518
|
+
function writeManifest(dir, files, { local = false, enabled = true } = {}) {
|
|
436
519
|
const target = path.join(dir, MANIFEST_FILE)
|
|
437
520
|
ensureDir(path.dirname(target))
|
|
438
521
|
const sorted = {}
|
|
439
522
|
for (const k of Object.keys(files).sort()) sorted[k] = files[k]
|
|
440
523
|
const body = local ? { version: MANIFEST_VERSION, scope: 'local', files: sorted } : { version: MANIFEST_VERSION, files: sorted }
|
|
524
|
+
// Written only when false, so an enabled install's manifest reads exactly as
|
|
525
|
+
// every manifest written before `disable` existed.
|
|
526
|
+
if (!enabled) body.enabled = false
|
|
441
527
|
fs.writeFileSync(target, JSON.stringify(body, null, 2) + '\n')
|
|
442
528
|
}
|
|
443
529
|
|
|
@@ -499,7 +585,8 @@ function flushManifest(dir) {
|
|
|
499
585
|
// env.config.json that installIsolation happens to write through writeFile).
|
|
500
586
|
const managed = managedTargets(dir)
|
|
501
587
|
const managedRel = new Set(managed.map((t) => t.relPath))
|
|
502
|
-
const
|
|
588
|
+
const prior = readManifest(dir)
|
|
589
|
+
const merged = { ...prior.files, ...writtenHashes }
|
|
503
590
|
const next = {}
|
|
504
591
|
for (const [relPath, hash] of Object.entries(merged)) {
|
|
505
592
|
if (managedRel.has(relPath)) next[relPath] = hash
|
|
@@ -510,9 +597,13 @@ function flushManifest(dir) {
|
|
|
510
597
|
for (const relPath of Object.keys(next)) {
|
|
511
598
|
if (!fs.existsSync(path.join(dir, relPath))) delete next[relPath] // prune gone
|
|
512
599
|
}
|
|
513
|
-
writeManifest(dir, next, { local: scope === 'local' })
|
|
600
|
+
writeManifest(dir, next, { local: scope === 'local', enabled: enabledOnFlush === null ? prior.enabled : enabledOnFlush })
|
|
514
601
|
}
|
|
515
602
|
|
|
603
|
+
// Set by a run that decides the install's switch: `init` turns it on, and
|
|
604
|
+
// `null` keeps whatever the manifest says (`update` on a disabled install).
|
|
605
|
+
let enabledOnFlush = null
|
|
606
|
+
|
|
516
607
|
function writeFile(dir, target, content, { force }) {
|
|
517
608
|
// A dangling symlink (its target no longer exists) is invisible to existsSync,
|
|
518
609
|
// which follows the link — but the link itself is still on disk, so a plain
|
|
@@ -571,7 +662,8 @@ function writeFile(dir, target, content, { force }) {
|
|
|
571
662
|
|
|
572
663
|
function copyAsset(dir, assetRelPath, targetAbs, opts) {
|
|
573
664
|
const raw = fs.readFileSync(path.join(ASSETS, assetRelPath), 'utf8')
|
|
574
|
-
const
|
|
665
|
+
const render = assetRelPath.startsWith(`commands${path.sep}`) ? renderCommand : renderExec
|
|
666
|
+
const content = renderable(assetRelPath) ? render(raw, dir) : raw
|
|
575
667
|
writeFile(dir, targetAbs, content, opts)
|
|
576
668
|
}
|
|
577
669
|
|
|
@@ -1004,8 +1096,14 @@ function resync(dir, { force = false, claudeMd = true, diff = false, local = fal
|
|
|
1004
1096
|
// `update` copied `.claude/hooks/` and registered nothing, for every upgrading
|
|
1005
1097
|
// project, while reporting a file created. `init-review-gate-hook.test.js`
|
|
1006
1098
|
// asserts over the entry points rather than over this call.
|
|
1007
|
-
|
|
1008
|
-
|
|
1099
|
+
// A disabled install stays disabled through an update: the files refresh,
|
|
1100
|
+
// and the two things Claude reads from outside them are not written back.
|
|
1101
|
+
const disabled = scope === 'local' && !manifest.enabled
|
|
1102
|
+
if (disabled) report.skipped.push('hooks and CLAUDE.local.md block (disabled — skitterspec enable turns them on)')
|
|
1103
|
+
else {
|
|
1104
|
+
registerReviewGateHook(dir)
|
|
1105
|
+
if (claudeMd) installClaudeMd(dir, { mode: 'update' })
|
|
1106
|
+
}
|
|
1009
1107
|
suggestReleaseWith(dir)
|
|
1010
1108
|
flushManifest(dir)
|
|
1011
1109
|
if (scope === 'local') writeLocalExcludes(dir)
|
|
@@ -1205,8 +1303,10 @@ function suggestReleaseWith(dir) {
|
|
|
1205
1303
|
// Switching a local install back to team is out of scope and says so.
|
|
1206
1304
|
function resolveScope(dir, local) {
|
|
1207
1305
|
const recorded = readManifest(dir).scope
|
|
1208
|
-
|
|
1306
|
+
const excluded = !local && recorded !== 'local' && excludeNamesManifest(dir)
|
|
1307
|
+
scope = local || recorded === 'local' || excluded ? 'local' : 'team'
|
|
1209
1308
|
if (!local && recorded === 'local') report.skipped.push('local install (recorded in the manifest) — kept local')
|
|
1309
|
+
if (excluded) report.skipped.push('local install (recorded in .git/info/exclude) — kept local')
|
|
1210
1310
|
if (local && recorded !== 'local') {
|
|
1211
1311
|
report.warnings.push(
|
|
1212
1312
|
'--local keeps skitterspec on this machine: teammates get none of its skills, rules ' +
|
|
@@ -1243,11 +1343,16 @@ function localExcludes(dir) {
|
|
|
1243
1343
|
}
|
|
1244
1344
|
|
|
1245
1345
|
// What `spec-env bootstrap` seeds into a local install's worktrees: the managed
|
|
1246
|
-
// paths
|
|
1247
|
-
// git carries none of it there. Empty for a team install, which
|
|
1346
|
+
// paths, the two per-machine files and the manifest. A worktree is a fresh
|
|
1347
|
+
// checkout, and git carries none of it there. Empty for a team install, which
|
|
1348
|
+
// git carries.
|
|
1349
|
+
//
|
|
1350
|
+
// THE MANIFEST IS SEEDED because it is what records the scope: without it a
|
|
1351
|
+
// worktree's `update` read team and wrote the block into the tracked CLAUDE.md
|
|
1352
|
+
// and the hooks into a new .claude/settings.json (bug-local-scope-worktree).
|
|
1248
1353
|
function localSeedFiles(dir) {
|
|
1249
1354
|
if (readManifest(dir).scope !== 'local') return []
|
|
1250
|
-
return [...localManagedPaths(dir), '.claude/settings.local.json', 'CLAUDE.local.md']
|
|
1355
|
+
return [...localManagedPaths(dir), '.claude/settings.local.json', 'CLAUDE.local.md', MANIFEST_FILE.replace(/\\/g, '/')]
|
|
1251
1356
|
}
|
|
1252
1357
|
|
|
1253
1358
|
const EXCLUDE_START = '# >>> skitterspec (local install)'
|
|
@@ -1288,6 +1393,31 @@ function writeLocalExcludes(dir) {
|
|
|
1288
1393
|
report.updated.push('.git/info/exclude (skitterspec block)')
|
|
1289
1394
|
}
|
|
1290
1395
|
|
|
1396
|
+
// Whether the shared `.git/info/exclude` block names THIS project's manifest —
|
|
1397
|
+
// the positive signal that a worktree with no manifest of its own belongs to a
|
|
1398
|
+
// local install. The exclude lives in the common dir, so every worktree sees
|
|
1399
|
+
// the block the primary checkout's install wrote; matching the prefixed
|
|
1400
|
+
// manifest path, not the bare block, keeps a second project in the same repo
|
|
1401
|
+
// from being read as local by a neighbour's install.
|
|
1402
|
+
//
|
|
1403
|
+
// WHAT WOULD FOOL IT: a block hand-edited to drop the manifest line, or git
|
|
1404
|
+
// unreachable. Both answer false — the scope the manifest recorded, as before.
|
|
1405
|
+
function excludeNamesManifest(dir) {
|
|
1406
|
+
try {
|
|
1407
|
+
const git = (...args) => execFileSync('git', ['-C', dir, ...args], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim()
|
|
1408
|
+
const commonDir = path.resolve(dir, git('rev-parse', '--git-common-dir'))
|
|
1409
|
+
const prefix = git('rev-parse', '--show-prefix')
|
|
1410
|
+
const text = fs.readFileSync(path.join(commonDir, 'info', 'exclude'), 'utf8')
|
|
1411
|
+
const start = text.indexOf(EXCLUDE_START)
|
|
1412
|
+
const end = text.indexOf(EXCLUDE_END, start)
|
|
1413
|
+
if (start === -1 || end === -1) return false
|
|
1414
|
+
const entry = `/${prefix}${MANIFEST_FILE.replace(/\\/g, '/')}`
|
|
1415
|
+
return text.slice(start, end).split(/\r?\n/).some((l) => l.trim() === entry)
|
|
1416
|
+
} catch {
|
|
1417
|
+
return false
|
|
1418
|
+
}
|
|
1419
|
+
}
|
|
1420
|
+
|
|
1291
1421
|
// Convert a COMMITTED (team) install into a local one, in place. Every step
|
|
1292
1422
|
// leaves the files on disk and stages or edits only; it never commits — the
|
|
1293
1423
|
// operator commits the removal, and teammates who pull it lose the install.
|
|
@@ -1469,11 +1599,360 @@ function hooksAt(read, ref) {
|
|
|
1469
1599
|
.filter((h) => h && typeof h.command === 'string' && GATE_HOOKS.some((k) => k.re.test(h.command))).length
|
|
1470
1600
|
}
|
|
1471
1601
|
|
|
1602
|
+
// DISABLE / ENABLE — switch whether this machine's Claude uses a local install,
|
|
1603
|
+
// without touching its files (feat-uninstall-local). Claude Code has no single
|
|
1604
|
+
// switch covering skills, commands, rules and hooks, so the install is switched
|
|
1605
|
+
// through three settings in `.claude/settings.local.json`:
|
|
1606
|
+
// - `skillOverrides: { <name>: "off" }` — every managed skill and command
|
|
1607
|
+
// (command files are skills to Claude Code). Exact names: no wildcard.
|
|
1608
|
+
// - `claudeMdExcludes: ["**/.claude/rules/<file>"]` — every managed rule, as
|
|
1609
|
+
// a glob so the one entry matches in every worktree.
|
|
1610
|
+
// - our hooks and the CLAUDE.local.md block are taken out, and written back
|
|
1611
|
+
// from the shipped assets by `enable`, so nothing has to be saved.
|
|
1612
|
+
// Only entries naming OUR paths are written or removed: an override or exclude
|
|
1613
|
+
// the developer wrote is never taken.
|
|
1614
|
+
function switchNames() {
|
|
1615
|
+
return [...SKILLS, ...COMMANDS.map((c) => c.replace(/\.md$/, ''))]
|
|
1616
|
+
}
|
|
1617
|
+
|
|
1618
|
+
function ruleExcludes() {
|
|
1619
|
+
return RULES.map((r) => `**/.claude/rules/${r}`)
|
|
1620
|
+
}
|
|
1621
|
+
|
|
1622
|
+
// The local settings, parsed — `{}` when absent, null when not valid JSON.
|
|
1623
|
+
function readLocalSettings(dir) {
|
|
1624
|
+
try {
|
|
1625
|
+
const parsed = JSON.parse(fs.readFileSync(path.join(dir, '.claude', 'settings.local.json'), 'utf8'))
|
|
1626
|
+
return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : null
|
|
1627
|
+
} catch (error) {
|
|
1628
|
+
return error.code === 'ENOENT' ? {} : null
|
|
1629
|
+
}
|
|
1630
|
+
}
|
|
1631
|
+
|
|
1632
|
+
function writeLocalSettings(dir, settings) {
|
|
1633
|
+
const file = path.join(dir, '.claude', 'settings.local.json')
|
|
1634
|
+
if (!Object.keys(settings).length) {
|
|
1635
|
+
if (fs.existsSync(file)) fs.unlinkSync(file)
|
|
1636
|
+
return
|
|
1637
|
+
}
|
|
1638
|
+
ensureDir(path.dirname(file))
|
|
1639
|
+
fs.writeFileSync(file, JSON.stringify(settings, null, 2) + '\n')
|
|
1640
|
+
}
|
|
1641
|
+
|
|
1642
|
+
// Take our override and exclude entries out of the local settings. Returns
|
|
1643
|
+
// false when the file is not valid JSON (left untouched).
|
|
1644
|
+
function clearSwitches(dir) {
|
|
1645
|
+
const settings = readLocalSettings(dir)
|
|
1646
|
+
if (settings === null) return false
|
|
1647
|
+
const names = new Set(switchNames())
|
|
1648
|
+
const globs = new Set(ruleExcludes())
|
|
1649
|
+
if (settings.skillOverrides && typeof settings.skillOverrides === 'object') {
|
|
1650
|
+
for (const name of Object.keys(settings.skillOverrides)) {
|
|
1651
|
+
if (names.has(name) && settings.skillOverrides[name] === 'off') delete settings.skillOverrides[name]
|
|
1652
|
+
}
|
|
1653
|
+
if (!Object.keys(settings.skillOverrides).length) delete settings.skillOverrides
|
|
1654
|
+
}
|
|
1655
|
+
if (Array.isArray(settings.claudeMdExcludes)) {
|
|
1656
|
+
settings.claudeMdExcludes = settings.claudeMdExcludes.filter((g) => !globs.has(g))
|
|
1657
|
+
if (!settings.claudeMdExcludes.length) delete settings.claudeMdExcludes
|
|
1658
|
+
}
|
|
1659
|
+
writeLocalSettings(dir, settings)
|
|
1660
|
+
return true
|
|
1661
|
+
}
|
|
1662
|
+
|
|
1663
|
+
function stripLocalClaudeBlock(dir) {
|
|
1664
|
+
const file = path.join(dir, 'CLAUDE.local.md')
|
|
1665
|
+
if (!fs.existsSync(file)) return false
|
|
1666
|
+
const text = fs.readFileSync(file, 'utf8')
|
|
1667
|
+
const re = new RegExp(`\\n*${SPEC_MARKER_START}[\\s\\S]*?${SPEC_MARKER_END}\\n?`)
|
|
1668
|
+
if (!re.test(text)) return false
|
|
1669
|
+
const next = text.replace(re, '\n')
|
|
1670
|
+
if (next.trim()) fs.writeFileSync(file, next.replace(/^\n+/, ''))
|
|
1671
|
+
else fs.unlinkSync(file)
|
|
1672
|
+
return true
|
|
1673
|
+
}
|
|
1674
|
+
|
|
1675
|
+
function rewriteManifestEnabled(dir, enabled) {
|
|
1676
|
+
const manifest = readManifest(dir)
|
|
1677
|
+
writeManifest(dir, manifest.files, { local: manifest.scope === 'local', enabled })
|
|
1678
|
+
}
|
|
1679
|
+
|
|
1680
|
+
// Turn a local install off for this machine's Claude. Deletes nothing, so it
|
|
1681
|
+
// refuses nothing about work in flight; returns the exit code.
|
|
1682
|
+
function disable(dir, { log = (s) => process.stdout.write(s) } = {}) {
|
|
1683
|
+
if (!fs.existsSync(path.join(dir, MANIFEST_FILE))) {
|
|
1684
|
+
log('disable: no skitterspec install here (no manifest) — nothing to disable.\n')
|
|
1685
|
+
return 0
|
|
1686
|
+
}
|
|
1687
|
+
const manifest = readManifest(dir)
|
|
1688
|
+
if (manifest.scope !== 'local') {
|
|
1689
|
+
log(
|
|
1690
|
+
'disable: refused — this is a team install. Its hooks are in the committed settings,\n' +
|
|
1691
|
+
' so they cannot be switched off for one person. disable works on a local install (init --local).\n',
|
|
1692
|
+
)
|
|
1693
|
+
return 1
|
|
1694
|
+
}
|
|
1695
|
+
const settings = readLocalSettings(dir)
|
|
1696
|
+
if (settings === null) {
|
|
1697
|
+
log('disable: refused — .claude/settings.local.json is not valid JSON, and the switch is written there. Nothing changed.\n')
|
|
1698
|
+
return 1
|
|
1699
|
+
}
|
|
1700
|
+
const overrides = settings.skillOverrides && typeof settings.skillOverrides === 'object' ? settings.skillOverrides : {}
|
|
1701
|
+
for (const name of switchNames()) overrides[name] = 'off'
|
|
1702
|
+
settings.skillOverrides = overrides
|
|
1703
|
+
const excludes = Array.isArray(settings.claudeMdExcludes) ? settings.claudeMdExcludes : []
|
|
1704
|
+
for (const glob of ruleExcludes()) if (!excludes.includes(glob)) excludes.push(glob)
|
|
1705
|
+
settings.claudeMdExcludes = excludes
|
|
1706
|
+
writeLocalSettings(dir, settings)
|
|
1707
|
+
const hooks = removeHooks(dir, { local: true })
|
|
1708
|
+
if (hooks.emptied) writeLocalSettings(dir, {})
|
|
1709
|
+
const block = stripLocalClaudeBlock(dir)
|
|
1710
|
+
rewriteManifestEnabled(dir, false)
|
|
1711
|
+
log(
|
|
1712
|
+
`disable: skitterspec is off for Claude on this machine (${dir})\n` +
|
|
1713
|
+
` ${switchNames().length} skills and commands switched off · ${RULES.length} rules excluded\n` +
|
|
1714
|
+
` ${hooks.removed} hook(s) removed${block ? ' · CLAUDE.local.md block removed' : ''}\n` +
|
|
1715
|
+
' the files stay on disk — skitterspec enable turns it back on. Restart Claude Code to pick it up.\n',
|
|
1716
|
+
)
|
|
1717
|
+
return 0
|
|
1718
|
+
}
|
|
1719
|
+
|
|
1720
|
+
// Turn a local install back on — and install it when there is nothing here to
|
|
1721
|
+
// turn on, since asking to use it has one meaning then.
|
|
1722
|
+
async function enable(dir, { log = (s) => process.stdout.write(s) } = {}) {
|
|
1723
|
+
const manifest = readManifest(dir)
|
|
1724
|
+
const present = fs.existsSync(path.join(dir, MANIFEST_FILE))
|
|
1725
|
+
const filesHere = managedTargets(dir).some((t) => !t.relPath.startsWith('specs') && fs.existsSync(t.abs))
|
|
1726
|
+
if (!present || (manifest.scope === 'local' && !filesHere)) {
|
|
1727
|
+
log('enable: no local install here — installing it (init --local).\n')
|
|
1728
|
+
// `update` mode installs the files and switches them on, and leaves the
|
|
1729
|
+
// project's committed config (isolation, gating) exactly as it is.
|
|
1730
|
+
await init({ dir, force: false, claudeMd: true, mode: 'update', local: true })
|
|
1731
|
+
return 0
|
|
1732
|
+
}
|
|
1733
|
+
if (manifest.scope !== 'local') {
|
|
1734
|
+
log('enable: refused — this is a team install, which is always on. enable works on a local install (init --local).\n')
|
|
1735
|
+
return 1
|
|
1736
|
+
}
|
|
1737
|
+
if (!clearSwitches(dir)) {
|
|
1738
|
+
log('enable: refused — .claude/settings.local.json is not valid JSON, and the switch is written there. Nothing changed.\n')
|
|
1739
|
+
return 1
|
|
1740
|
+
}
|
|
1741
|
+
resetReport()
|
|
1742
|
+
scope = 'local'
|
|
1743
|
+
registerReviewGateHook(dir)
|
|
1744
|
+
installClaudeMd(dir, { mode: 'init' })
|
|
1745
|
+
rewriteManifestEnabled(dir, true)
|
|
1746
|
+
log(
|
|
1747
|
+
`enable: skitterspec is on for Claude on this machine (${dir})\n` +
|
|
1748
|
+
' skills, commands and rules switched back on · hooks registered · CLAUDE.local.md block written\n' +
|
|
1749
|
+
' Restart Claude Code to pick it up.\n',
|
|
1750
|
+
)
|
|
1751
|
+
return 0
|
|
1752
|
+
}
|
|
1753
|
+
|
|
1754
|
+
// UNINSTALL — take a local install (`init --local`) back off this machine,
|
|
1755
|
+
// exactly: the managed files, our hooks in settings.local.json, the block in
|
|
1756
|
+
// CLAUDE.local.md, the exclude block, `.spec-env/` and the manifest. Nothing
|
|
1757
|
+
// under `specs/` is touched — it is committed and shared. Plans by default and
|
|
1758
|
+
// acts only with `yes`; returns the exit code.
|
|
1759
|
+
//
|
|
1760
|
+
// A file is deleted only when it is PRISTINE. An unrecognised hash is either
|
|
1761
|
+
// the developer's edit or a lost record, and only one of those is safe to
|
|
1762
|
+
// delete, so it is kept (`.claude/rules/negative-checks.md` rule 4) — but kept
|
|
1763
|
+
// under `.claude/` it would still be loaded, so it is PARKED in
|
|
1764
|
+
// `<git-common-dir>/skitterspec-kept/`: outside the tree, so git status is
|
|
1765
|
+
// unchanged, and never over an earlier parked copy.
|
|
1766
|
+
//
|
|
1767
|
+
// `inFlight` is the caller's list of provisioned specs and a held live overlay;
|
|
1768
|
+
// any entry refuses, because each worktree carries a seeded copy of the install
|
|
1769
|
+
// and a torn-down primary leaves nothing to finish them with. `cannotTell` is
|
|
1770
|
+
// the caller failing to read that list, which also refuses: deleting is the
|
|
1771
|
+
// destructive branch, so the unknown case does not get it.
|
|
1772
|
+
function uninstall(dir, { yes = false, inFlight = [], cannotTell = null, log = (s) => process.stdout.write(s) } = {}) {
|
|
1773
|
+
const manifestAbs = path.join(dir, MANIFEST_FILE)
|
|
1774
|
+
if (!fs.existsSync(manifestAbs)) {
|
|
1775
|
+
log('uninstall: no skitterspec install here (no manifest) — nothing to do.\n')
|
|
1776
|
+
return 0
|
|
1777
|
+
}
|
|
1778
|
+
const manifest = readManifest(dir)
|
|
1779
|
+
if (manifest.scope !== 'local') {
|
|
1780
|
+
log(
|
|
1781
|
+
'uninstall: refused — this is a team install, committed for everyone.\n' +
|
|
1782
|
+
' Removing it is a commit for the team to make, not one machine\'s command.\n' +
|
|
1783
|
+
' uninstall only takes a local install (init --local) back off.\n',
|
|
1784
|
+
)
|
|
1785
|
+
return 1
|
|
1786
|
+
}
|
|
1787
|
+
if (cannotTell) {
|
|
1788
|
+
log(`uninstall: refused — cannot tell whether a spec is in flight (${cannotTell}).\n Nothing changed.\n`)
|
|
1789
|
+
return 1
|
|
1790
|
+
}
|
|
1791
|
+
if (inFlight.length) {
|
|
1792
|
+
log(
|
|
1793
|
+
'uninstall: refused — work is still in flight here, and its worktrees carry a copy of the install:\n' +
|
|
1794
|
+
inFlight.map((f) => ` ${f.spec} ${f.where}\n`).join('') +
|
|
1795
|
+
' Finish each with /spec-complete, drop it with /spec-cancel (or spec-env down <name>),\n' +
|
|
1796
|
+
' and hand a live spec back with /spec-live main. Nothing changed.\n',
|
|
1797
|
+
)
|
|
1798
|
+
return 1
|
|
1799
|
+
}
|
|
1800
|
+
|
|
1801
|
+
// The files: every managed target outside specs/, plus any manifest entry
|
|
1802
|
+
// the package no longer ships (a retired skill is still a skill on disk).
|
|
1803
|
+
const targets = new Map()
|
|
1804
|
+
for (const t of managedTargets(dir)) targets.set(t.relPath.split(path.sep).join('/'), t.bundled)
|
|
1805
|
+
for (const k of Object.keys(manifest.files)) if (!targets.has(k)) targets.set(k, undefined)
|
|
1806
|
+
const remove = []
|
|
1807
|
+
const keep = []
|
|
1808
|
+
const exclude = localExcludeFile(dir)
|
|
1809
|
+
const parkRoot = exclude && path.join(path.dirname(path.dirname(exclude.file)), 'skitterspec-kept')
|
|
1810
|
+
const parkFor = (relPath) => {
|
|
1811
|
+
let target = path.join(parkRoot, relPath)
|
|
1812
|
+
for (let n = 2; fs.existsSync(target); n++) target = path.join(parkRoot, `${relPath}.${n}`)
|
|
1813
|
+
return target
|
|
1814
|
+
}
|
|
1815
|
+
for (const [relPath, bundled] of [...targets].sort(([a], [b]) => a.localeCompare(b))) {
|
|
1816
|
+
if (relPath.startsWith('specs/')) continue
|
|
1817
|
+
const state = managedState(dir, relPath, manifest, bundled)
|
|
1818
|
+
if (state === 'pristine') remove.push(relPath)
|
|
1819
|
+
else if (state !== 'missing') keep.push({ relPath, parked: parkRoot ? parkFor(relPath) : null })
|
|
1820
|
+
}
|
|
1821
|
+
|
|
1822
|
+
const hooks = removeHooks(dir, { local: true, dryRun: true })
|
|
1823
|
+
const switches = readLocalSettings(dir)
|
|
1824
|
+
const hasSwitches =
|
|
1825
|
+
switches !== null &&
|
|
1826
|
+
(Object.keys(switches.skillOverrides || {}).some((n) => switchNames().includes(n)) ||
|
|
1827
|
+
(Array.isArray(switches.claudeMdExcludes) && switches.claudeMdExcludes.some((g) => ruleExcludes().includes(g))))
|
|
1828
|
+
const claudeLocal = path.join(dir, 'CLAUDE.local.md')
|
|
1829
|
+
const blockRe = new RegExp(`\\n*${SPEC_MARKER_START}[\\s\\S]*?${SPEC_MARKER_END}\\n?`)
|
|
1830
|
+
const claudeText = fs.existsSync(claudeLocal) ? fs.readFileSync(claudeLocal, 'utf8') : null
|
|
1831
|
+
const hasBlock = claudeText !== null && blockRe.test(claudeText)
|
|
1832
|
+
const hasExclude = exclude !== null && exclude.text.includes(EXCLUDE_START)
|
|
1833
|
+
const specEnv = path.join(dir, '.spec-env')
|
|
1834
|
+
|
|
1835
|
+
const lines = []
|
|
1836
|
+
const say = (label, items) => {
|
|
1837
|
+
if (!items.length) return
|
|
1838
|
+
lines.push(`\n${label}:\n`)
|
|
1839
|
+
for (const it of items) lines.push(` ${it}\n`)
|
|
1840
|
+
}
|
|
1841
|
+
say(yes ? 'removed' : 'would remove', [
|
|
1842
|
+
...remove,
|
|
1843
|
+
...(hooks.reason === 'removed' ? [`.claude/settings.local.json (${hooks.removed} skitterspec hook(s)${hooks.emptied ? ', then the emptied file' : ''})`] : []),
|
|
1844
|
+
...(hasSwitches ? ['.claude/settings.local.json (skitterspec disable switches)'] : []),
|
|
1845
|
+
...(hasBlock ? ['CLAUDE.local.md (spec workflow block)'] : []),
|
|
1846
|
+
...(hasExclude ? [`${path.relative(dir, exclude.file).split(path.sep).join('/')} (skitterspec block)`] : []),
|
|
1847
|
+
...(fs.existsSync(specEnv) ? ['.spec-env/'] : []),
|
|
1848
|
+
MANIFEST_FILE.split(path.sep).join('/'),
|
|
1849
|
+
])
|
|
1850
|
+
say(
|
|
1851
|
+
yes ? 'parked — edited since install, moved out of Claude\'s reach' : 'would park — edited since install',
|
|
1852
|
+
keep.map((k) => (k.parked ? `${k.relPath} → ${k.parked}` : `${k.relPath} (kept in place — no git dir to park it in)`)),
|
|
1853
|
+
)
|
|
1854
|
+
const warnings = []
|
|
1855
|
+
if (hooks.reason === 'malformed') warnings.push('.claude/settings.local.json is not valid JSON — skitterspec hooks left in it; remove them by hand')
|
|
1856
|
+
if (exclude === null) warnings.push('not a git repository — no exclude block to remove')
|
|
1857
|
+
say('warnings', warnings)
|
|
1858
|
+
|
|
1859
|
+
if (!yes) {
|
|
1860
|
+
log(`uninstall: plan — nothing changed (${dir})\n${lines.join('')}\n re-run with --yes to remove the local install.\n`)
|
|
1861
|
+
return 0
|
|
1862
|
+
}
|
|
1863
|
+
|
|
1864
|
+
const managedSet = new Set(targets.keys())
|
|
1865
|
+
const parents = new Set()
|
|
1866
|
+
for (const relPath of remove) {
|
|
1867
|
+
assertSafeToDelete(relPath, managedSet)
|
|
1868
|
+
fs.unlinkSync(path.join(dir, relPath))
|
|
1869
|
+
parents.add(path.dirname(path.join(dir, relPath)))
|
|
1870
|
+
}
|
|
1871
|
+
for (const k of keep) {
|
|
1872
|
+
if (!k.parked) continue
|
|
1873
|
+
fs.mkdirSync(path.dirname(k.parked), { recursive: true })
|
|
1874
|
+
try {
|
|
1875
|
+
fs.renameSync(path.join(dir, k.relPath), k.parked)
|
|
1876
|
+
} catch (error) {
|
|
1877
|
+
if (error.code !== 'EXDEV') throw error
|
|
1878
|
+
fs.copyFileSync(path.join(dir, k.relPath), k.parked)
|
|
1879
|
+
fs.unlinkSync(path.join(dir, k.relPath))
|
|
1880
|
+
}
|
|
1881
|
+
parents.add(path.dirname(path.join(dir, k.relPath)))
|
|
1882
|
+
}
|
|
1883
|
+
// Folders our files left empty — a skill's own, then .claude/<kind>/ — and
|
|
1884
|
+
// never one that still holds something of the developer's.
|
|
1885
|
+
const stop = path.join(dir, '.claude')
|
|
1886
|
+
for (const start of parents) {
|
|
1887
|
+
for (let at = start; at.startsWith(stop + path.sep); at = path.dirname(at)) {
|
|
1888
|
+
try {
|
|
1889
|
+
if (fs.readdirSync(at).length) break
|
|
1890
|
+
fs.rmdirSync(at)
|
|
1891
|
+
} catch {
|
|
1892
|
+
break
|
|
1893
|
+
}
|
|
1894
|
+
}
|
|
1895
|
+
}
|
|
1896
|
+
// A disabled install's switches go too, or they would outlive what they name.
|
|
1897
|
+
clearSwitches(dir)
|
|
1898
|
+
if (hooks.reason === 'removed') {
|
|
1899
|
+
const done = removeHooks(dir, { local: true })
|
|
1900
|
+
if (done.emptied) fs.unlinkSync(path.join(dir, '.claude', 'settings.local.json'))
|
|
1901
|
+
}
|
|
1902
|
+
if (hasBlock) {
|
|
1903
|
+
const next = claudeText.replace(blockRe, '\n')
|
|
1904
|
+
if (next.trim()) fs.writeFileSync(claudeLocal, next.replace(/^\n+/, ''))
|
|
1905
|
+
else fs.unlinkSync(claudeLocal)
|
|
1906
|
+
}
|
|
1907
|
+
if (hasExclude) {
|
|
1908
|
+
const start = exclude.text.indexOf(EXCLUDE_START)
|
|
1909
|
+
const end = exclude.text.indexOf(EXCLUDE_END, start)
|
|
1910
|
+
if (end !== -1) {
|
|
1911
|
+
fs.writeFileSync(exclude.file, exclude.text.slice(0, start) + exclude.text.slice(end + EXCLUDE_END.length).replace(/^\n/, ''))
|
|
1912
|
+
}
|
|
1913
|
+
}
|
|
1914
|
+
fs.rmSync(specEnv, { recursive: true, force: true })
|
|
1915
|
+
fs.unlinkSync(manifestAbs)
|
|
1916
|
+
|
|
1917
|
+
log(
|
|
1918
|
+
`uninstall: done (${dir})\n${lines.join('')}\n` +
|
|
1919
|
+
` the CLI itself is still installed — npm uninstall -g ${distributionPackage()} removes it.\n`,
|
|
1920
|
+
)
|
|
1921
|
+
return 0
|
|
1922
|
+
}
|
|
1923
|
+
|
|
1924
|
+
// The git common dir's info/exclude, read — null when this is not a git repo.
|
|
1925
|
+
function localExcludeFile(dir) {
|
|
1926
|
+
let commonDir
|
|
1927
|
+
try {
|
|
1928
|
+
commonDir = path.resolve(
|
|
1929
|
+
dir,
|
|
1930
|
+
execFileSync('git', ['-C', dir, 'rev-parse', '--git-common-dir'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim(),
|
|
1931
|
+
)
|
|
1932
|
+
} catch {
|
|
1933
|
+
return null
|
|
1934
|
+
}
|
|
1935
|
+
const file = path.join(commonDir, 'info', 'exclude')
|
|
1936
|
+
let text = ''
|
|
1937
|
+
try {
|
|
1938
|
+
text = fs.readFileSync(file, 'utf8')
|
|
1939
|
+
} catch {
|
|
1940
|
+
/* no exclude file */
|
|
1941
|
+
}
|
|
1942
|
+
return { file, text }
|
|
1943
|
+
}
|
|
1944
|
+
|
|
1472
1945
|
async function init({ dir, force, claudeMd, mode, isolation, workspaceMode, gating, project, local = false }) {
|
|
1473
1946
|
if (!fs.existsSync(dir)) throw new Error(`target dir does not exist: ${dir}`)
|
|
1474
1947
|
resetReport()
|
|
1475
1948
|
resolveScope(dir, local)
|
|
1476
1949
|
if (scope === 'local') convertCommitted(dir)
|
|
1950
|
+
// Installing is enabling: a disabled install comes back on.
|
|
1951
|
+
if (scope === 'local' && !readManifest(dir).enabled) {
|
|
1952
|
+
clearSwitches(dir)
|
|
1953
|
+
report.updated.push('.claude/settings.local.json (skitterspec enabled)')
|
|
1954
|
+
}
|
|
1955
|
+
enabledOnFlush = true
|
|
1477
1956
|
|
|
1478
1957
|
installSkills(dir, { force })
|
|
1479
1958
|
installCommands(dir, { force })
|
|
@@ -1517,6 +1996,9 @@ module.exports = {
|
|
|
1517
1996
|
isExistingSetup,
|
|
1518
1997
|
resync,
|
|
1519
1998
|
reset,
|
|
1999
|
+
uninstall,
|
|
2000
|
+
disable,
|
|
2001
|
+
enable,
|
|
1520
2002
|
assertSafeToDelete,
|
|
1521
2003
|
assertComposedAssets,
|
|
1522
2004
|
detectPackageManager,
|