@codewizard-dt/bootstrap 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/lib/hooks/README.md +98 -181
- package/lib/hooks/claude-settings-guard.js +38 -73
- package/lib/scripts/README.md +25 -17
- package/lib/scripts/install-global.sh +39 -11
- package/lib/scripts/lib.sh +14 -9
- package/lib/scripts/merge-gitignore.sh +64 -12
- package/lib/scripts/merge-settings-hooks.js +374 -0
- package/lib/scripts/templates/settings-hooks.json +151 -0
- package/package.json +1 -1
package/lib/hooks/README.md
CHANGED
|
@@ -4,10 +4,14 @@ PreToolUse / PostToolUse / SessionStart hook scripts managed by this template.
|
|
|
4
4
|
`./lib/scripts/install-global.sh` (also `npx @codewizard-dt/bootstrap install`)
|
|
5
5
|
rsyncs this directory — including `lib/` — to `~/.claude/hooks/`.
|
|
6
6
|
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
7
|
+
The same run also *registers* them: after the deny-list merge,
|
|
8
|
+
`lib/scripts/merge-settings-hooks.js` merges the canonical wiring template
|
|
9
|
+
([`lib/scripts/templates/settings-hooks.json`](../scripts/templates/settings-hooks.json))
|
|
10
|
+
into the `hooks` key of `~/.claude/settings.json`. Manual pasting is no longer
|
|
11
|
+
required — copying the scripts and wiring them are one step, repeated
|
|
12
|
+
idempotently on every `install` / `setup` / `update` run. See
|
|
13
|
+
[the wiring section below](#required-claudesettingsjson-wiring) for the merge
|
|
14
|
+
semantics.
|
|
11
15
|
|
|
12
16
|
## Why hooks (vs. allow/deny permission rules)
|
|
13
17
|
|
|
@@ -54,7 +58,7 @@ environment assignment, or on the far side of an MCP tool boundary.
|
|
|
54
58
|
| `package-install-consent.js` | `Bash` | Every package-manager install, with one allowlisted source (Serena) |
|
|
55
59
|
| `absolute-path-guard.js` | `Bash` | Evasive *spellings* of destructive commands (`/bin/rm`, `\rm`, `env rm`) |
|
|
56
60
|
| `protected-write-guard.js` | `Bash` | `>`/`>>` into shell/git/Claude config, `DYLD_*`/`LD_*` injection, `git -c` RCE config keys |
|
|
57
|
-
| `claude-settings-guard.js` | `Edit\|Write\|NotebookEdit\|MultiEdit` | File-tool writes to `~/.claude/settings*.json`
|
|
61
|
+
| `claude-settings-guard.js` | `Edit\|Write\|NotebookEdit\|MultiEdit` | File-tool writes to `~/.claude/settings*.json` and `~/.claude/hooks/**` — unconditional, no exceptions |
|
|
58
62
|
| `env-content-read-guard.js` | `Bash\|mcp__serena__.*\|mcp__plugin_[^_]+_serena__.*` | `.env` *contents* reaching the transcript, on both the Bash and Serena surfaces |
|
|
59
63
|
|
|
60
64
|
They share `lib/command-parse.js` (stdin read, segment split, tokenize, deny
|
|
@@ -352,10 +356,28 @@ protected paths (`echo … >> ~/.claude/settings.json`) is
|
|
|
352
356
|
`protected-write-guard.js` rule 1.
|
|
353
357
|
|
|
354
358
|
**Blocks** `Edit`/`Write`/`NotebookEdit`/`MultiEdit` targeting
|
|
355
|
-
`~/.claude/settings.json
|
|
356
|
-
|
|
357
|
-
|
|
358
|
-
|
|
359
|
+
`~/.claude/settings.json`, `~/.claude/settings.local.json`, and anything under
|
|
360
|
+
`~/.claude/hooks/`. **Unconditional — the verdict does not depend on cwd.**
|
|
361
|
+
|
|
362
|
+
> **A bootstrap-claude carve-out existed here and was removed on 2026-07-30.**
|
|
363
|
+
> It allowed the settings write when the session's cwd sat inside a genuine
|
|
364
|
+
> checkout, identified by marker file (`lib/scripts/templates/settings-deny.json`
|
|
365
|
+
> plus a `package.json` named `@codewizard-dt/bootstrap`) rather than by directory
|
|
366
|
+
> name. The rationale was that this repo manages those files.
|
|
367
|
+
>
|
|
368
|
+
> **That rationale was wrong.** The repo writes them through
|
|
369
|
+
> `node merge-settings-deny.js` (and now `merge-settings-hooks.js`) *inside*
|
|
370
|
+
> `install-global.sh` — Bash subprocesses that no `PreToolUse` hook and no
|
|
371
|
+
> permission rule ever observes. Nothing here
|
|
372
|
+
> ever needed the Edit *tool* on those paths. The exception was not load-bearing,
|
|
373
|
+
> and it did let any agent running in this repo rewrite its own permission
|
|
374
|
+
> boundary — which was demonstrated live before it was closed.
|
|
375
|
+
>
|
|
376
|
+
> The former marker shapes are still exercised in
|
|
377
|
+
> `test/command-class-hooks.test.js`, now asserting **deny**, because they are the
|
|
378
|
+
> most sensitive canaries for the carve-out creeping back.
|
|
379
|
+
|
|
380
|
+
<!-- superseded, retained for provenance:
|
|
359
381
|
**A checkout is identified by marker file, not by path substring.**
|
|
360
382
|
`cwd.includes('bootstrap-claude')` is spoofed by `mkdir bootstrap-claude`, so
|
|
361
383
|
both of these must hold at a candidate root: `lib/scripts/templates/settings-deny.json`
|
|
@@ -375,6 +397,18 @@ deny made the repo unable to work on itself. A hook is the only layer that can
|
|
|
375
397
|
carry a conditional. The shipped deny list carries zero `.claude/settings`
|
|
376
398
|
entries today and `test/settings-deny.test.js` locks that in, so the carve-out is
|
|
377
399
|
live rather than dead on arrival.
|
|
400
|
+
-->
|
|
401
|
+
|
|
402
|
+
**The deny entries stay out, and that is now a free choice rather than a forced one.**
|
|
403
|
+
`Edit(~/.claude/settings.json)` and `Edit(~/.claude/settings.local.json)` were
|
|
404
|
+
removed from `settings-deny.json` to make the carve-out expressible — deny beats
|
|
405
|
+
allow at every scope, and a hook cannot loosen a deny rule, so the exception was
|
|
406
|
+
unsayable while they existed. With the carve-out gone they could be restored as
|
|
407
|
+
defence in depth. They have not been, deliberately: the deny merge is
|
|
408
|
+
additive-only with **no removal path**, so re-adding them is permanent for every
|
|
409
|
+
installed user, and the hook already blocks the same surface *plus* the `Write`
|
|
410
|
+
and `NotebookEdit` tools that `Edit(...)` rules never reach. Restore them only if
|
|
411
|
+
the hook proves unreliable.
|
|
378
412
|
|
|
379
413
|
**Why the `~/.claude/hooks/` tree is also checked here, and is not duplication.** The
|
|
380
414
|
`Edit(~/.claude/hooks/**)` and `Edit(**/.claude/hooks/**)` deny entries remain in
|
|
@@ -395,13 +429,18 @@ same function so both sides of the comparison are real paths, and a literal `~`
|
|
|
395
429
|
`NotebookEdit` names its target `notebook_path`; `MultiEdit` is checked per
|
|
396
430
|
`edits[].file_path`, so a protected target cannot ride along in a batch.
|
|
397
431
|
|
|
398
|
-
**Residual risk,
|
|
399
|
-
|
|
400
|
-
|
|
401
|
-
|
|
402
|
-
|
|
403
|
-
|
|
404
|
-
|
|
432
|
+
**Residual risk, stated plainly.** This hook guards the file *tools*. An agent
|
|
433
|
+
with Bash can still reach these files another way — `node write-settings.js`
|
|
434
|
+
gets there, and nothing here parses inside a script file.
|
|
435
|
+
`protected-write-guard.js` catches shell redirects
|
|
436
|
+
(`echo … >> ~/.claude/settings.json`) and `interpreter-indirection-guard.js`
|
|
437
|
+
catches `node -e`, but a script written to disk and then executed is uncovered by
|
|
438
|
+
design.
|
|
439
|
+
|
|
440
|
+
So this is a guardrail, not a boundary: it closes the casual and accidental paths
|
|
441
|
+
— which is most of them — and raises the cost of the deliberate one. The only
|
|
442
|
+
real containment for a compromised agent is OS-level sandboxing (`/sandbox`).
|
|
443
|
+
Do not read "unconditional" as "guaranteed".
|
|
405
444
|
|
|
406
445
|
**Not covered, deliberately:** project-level `.claude/settings.json` files (this
|
|
407
446
|
hook is scoped to the user-global `~/.claude/` tree); and writing a script
|
|
@@ -683,164 +722,38 @@ acquirer rather than blocking on it.
|
|
|
683
722
|
|
|
684
723
|
## Required `~/.claude/settings.json` wiring
|
|
685
724
|
|
|
686
|
-
|
|
687
|
-
|
|
688
|
-
|
|
689
|
-
|
|
690
|
-
|
|
691
|
-
|
|
692
|
-
|
|
693
|
-
|
|
694
|
-
|
|
695
|
-
|
|
696
|
-
|
|
697
|
-
|
|
698
|
-
|
|
699
|
-
|
|
700
|
-
|
|
701
|
-
|
|
702
|
-
|
|
703
|
-
|
|
704
|
-
|
|
705
|
-
|
|
706
|
-
|
|
707
|
-
|
|
708
|
-
|
|
709
|
-
|
|
710
|
-
|
|
711
|
-
|
|
712
|
-
|
|
713
|
-
|
|
714
|
-
|
|
715
|
-
|
|
716
|
-
|
|
717
|
-
|
|
718
|
-
}
|
|
719
|
-
]
|
|
720
|
-
},
|
|
721
|
-
{
|
|
722
|
-
"matcher": "Bash|mcp__serena__.*|mcp__plugin_[^_]+_serena__.*",
|
|
723
|
-
"hooks": [
|
|
724
|
-
{
|
|
725
|
-
"type": "command",
|
|
726
|
-
"command": "node ~/.claude/hooks/env-content-read-guard.js"
|
|
727
|
-
}
|
|
728
|
-
]
|
|
729
|
-
},
|
|
730
|
-
{
|
|
731
|
-
"matcher": "Read",
|
|
732
|
-
"hooks": [
|
|
733
|
-
{
|
|
734
|
-
"type": "command",
|
|
735
|
-
"command": "node ~/.claude/hooks/serena-first-read-guard.js"
|
|
736
|
-
}
|
|
737
|
-
]
|
|
738
|
-
},
|
|
739
|
-
{
|
|
740
|
-
"matcher": "Edit|MultiEdit",
|
|
741
|
-
"hooks": [
|
|
742
|
-
{
|
|
743
|
-
"type": "command",
|
|
744
|
-
"command": "node ~/.claude/hooks/serena-edit-guard.js"
|
|
745
|
-
}
|
|
746
|
-
]
|
|
747
|
-
},
|
|
748
|
-
{
|
|
749
|
-
"matcher": "Write",
|
|
750
|
-
"hooks": [
|
|
751
|
-
{
|
|
752
|
-
"type": "command",
|
|
753
|
-
"command": "node ~/.claude/hooks/serena-write-guard.js"
|
|
754
|
-
}
|
|
755
|
-
]
|
|
756
|
-
},
|
|
757
|
-
{
|
|
758
|
-
"matcher": "Grep",
|
|
759
|
-
"hooks": [
|
|
760
|
-
{
|
|
761
|
-
"type": "command",
|
|
762
|
-
"command": "node ~/.claude/hooks/serena-first-guard.js"
|
|
763
|
-
}
|
|
764
|
-
]
|
|
765
|
-
},
|
|
766
|
-
{
|
|
767
|
-
"matcher": "Glob",
|
|
768
|
-
"hooks": [
|
|
769
|
-
{
|
|
770
|
-
"type": "command",
|
|
771
|
-
"command": "node ~/.claude/hooks/serena-first-glob-guard.js"
|
|
772
|
-
}
|
|
773
|
-
]
|
|
774
|
-
},
|
|
775
|
-
{
|
|
776
|
-
"matcher": "Agent",
|
|
777
|
-
"hooks": [
|
|
778
|
-
{
|
|
779
|
-
"type": "command",
|
|
780
|
-
"command": "node ~/.claude/hooks/serena-pre-delegation.js"
|
|
781
|
-
}
|
|
782
|
-
]
|
|
783
|
-
},
|
|
784
|
-
{
|
|
785
|
-
"matcher": "Bash",
|
|
786
|
-
"hooks": [
|
|
787
|
-
{
|
|
788
|
-
"type": "command",
|
|
789
|
-
"command": "node ~/.claude/hooks/serena-bash-grep-block.js"
|
|
790
|
-
},
|
|
791
|
-
{
|
|
792
|
-
"type": "command",
|
|
793
|
-
"command": "node ~/.claude/hooks/mv-absolute-path-block.js",
|
|
794
|
-
"if": "Bash(mv *)"
|
|
795
|
-
},
|
|
796
|
-
{
|
|
797
|
-
"type": "command",
|
|
798
|
-
"command": "node ~/.claude/hooks/git-protected-ops-block.js"
|
|
799
|
-
},
|
|
800
|
-
{
|
|
801
|
-
"type": "command",
|
|
802
|
-
"command": "node ~/.claude/hooks/interpreter-indirection-guard.js"
|
|
803
|
-
},
|
|
804
|
-
{
|
|
805
|
-
"type": "command",
|
|
806
|
-
"command": "node ~/.claude/hooks/package-install-consent.js"
|
|
807
|
-
},
|
|
808
|
-
{
|
|
809
|
-
"type": "command",
|
|
810
|
-
"command": "node ~/.claude/hooks/absolute-path-guard.js"
|
|
811
|
-
},
|
|
812
|
-
{
|
|
813
|
-
"type": "command",
|
|
814
|
-
"command": "node ~/.claude/hooks/protected-write-guard.js"
|
|
815
|
-
}
|
|
816
|
-
]
|
|
817
|
-
}
|
|
818
|
-
],
|
|
819
|
-
"PostToolUse": [
|
|
820
|
-
{
|
|
821
|
-
"matcher": "mcp__serena__.*|mcp__plugin_[^_]+_serena__.*",
|
|
822
|
-
"hooks": [
|
|
823
|
-
{
|
|
824
|
-
"type": "command",
|
|
825
|
-
"command": "node ~/.claude/hooks/serena-usage-tracker.js"
|
|
826
|
-
}
|
|
827
|
-
]
|
|
828
|
-
}
|
|
829
|
-
],
|
|
830
|
-
"PostToolUseFailure": [
|
|
831
|
-
{
|
|
832
|
-
"matcher": "mcp__serena__.*|mcp__plugin_[^_]+_serena__.*",
|
|
833
|
-
"hooks": [
|
|
834
|
-
{
|
|
835
|
-
"type": "command",
|
|
836
|
-
"command": "node ~/.claude/hooks/serena-usage-tracker.js"
|
|
837
|
-
}
|
|
838
|
-
]
|
|
839
|
-
}
|
|
840
|
-
]
|
|
841
|
-
}
|
|
842
|
-
}
|
|
843
|
-
```
|
|
725
|
+
The canonical wiring — which script runs on which event, under which matcher —
|
|
726
|
+
lives in exactly one place:
|
|
727
|
+
[`lib/scripts/templates/settings-hooks.json`](../scripts/templates/settings-hooks.json).
|
|
728
|
+
It is a bare hooks-value object (four events: `SessionStart`, `PreToolUse`,
|
|
729
|
+
`PostToolUse`, `PostToolUseFailure`) whose entries map 1:1 onto the scripts in
|
|
730
|
+
this directory. This README deliberately does not inline a copy: the template
|
|
731
|
+
file is what `merge-settings-hooks.js` reads and merges into the `hooks` key of
|
|
732
|
+
`~/.claude/settings.json` on every `install` / `setup` / `update` run, so a
|
|
733
|
+
second copy here could only drift from what actually ships.
|
|
734
|
+
|
|
735
|
+
Merge semantics — "the template owns its blocks":
|
|
736
|
+
|
|
737
|
+
- **Foreign (user-added) blocks and hook entries are never modified, reordered,
|
|
738
|
+
or removed.** The same goes for entire hooks events the template does not ship
|
|
739
|
+
(e.g. `UserPromptSubmit`): the merge never visits them. A repo hook found
|
|
740
|
+
relocated into a user-modified block is left where it is (with a warning), not
|
|
741
|
+
duplicated back into the template's block, and the merge never writes an empty
|
|
742
|
+
placeholder block. It always exits 0 — a wiring merge must never abort an
|
|
743
|
+
install.
|
|
744
|
+
- **Direct edits to an *owned* entry are overwritten on the next run.** An entry
|
|
745
|
+
is owned when its `command` points at `~/.claude/hooks/<name>.js` (or an
|
|
746
|
+
absolute-path expansion of it) and `<name>` matches a hook the template ships.
|
|
747
|
+
Because the template owns its blocks, any local tweak to such an entry — and
|
|
748
|
+
any matcher drift on a block made up entirely of owned entries — is reverted
|
|
749
|
+
to the template's version the next time `install` / `setup` / `update` runs.
|
|
750
|
+
To opt an entry out of the overwrite, point its `command` at a different path
|
|
751
|
+
(e.g. a copy of the script outside `~/.claude/hooks/`) so it no longer
|
|
752
|
+
classifies as owned; the merge will then treat it as foreign and leave it
|
|
753
|
+
alone. Note the limit of that opt-out: because the re-pointed entry no longer
|
|
754
|
+
carries the template basename, the next merge run re-appends the stock
|
|
755
|
+
template entry alongside it — your variant is preserved, but the shipped hook
|
|
756
|
+
is not disabled.
|
|
844
757
|
|
|
845
758
|
Three notes on the command-class guard matchers, each of which makes a hook
|
|
846
759
|
silently inert if it is wrong:
|
|
@@ -863,13 +776,16 @@ silently inert if it is wrong:
|
|
|
863
776
|
permission-matcher path that lets compound and piped commands slip past a `deny`
|
|
864
777
|
rule.
|
|
865
778
|
|
|
866
|
-
Reminder: `install-global.sh` rsyncs these scripts to `~/.claude/hooks/` on
|
|
867
|
-
run
|
|
868
|
-
|
|
869
|
-
|
|
779
|
+
Reminder: `install-global.sh` rsyncs these scripts to `~/.claude/hooks/` on
|
|
780
|
+
every run **and** registers them, by running `merge-settings-hooks.js` right
|
|
781
|
+
after the deny-list merge. There is no one-time manual step: the wiring is
|
|
782
|
+
re-merged automatically on every `install` / `setup` / `update` run, and when
|
|
783
|
+
that merge creates the wiring fresh or applies changes, the install prints a
|
|
784
|
+
note to restart your Claude Code sessions (hooks load at session start, so a
|
|
785
|
+
running session does not pick up new wiring).
|
|
870
786
|
|
|
871
|
-
The `PostToolUse` matcher is broadened from the six navigation tools
|
|
872
|
-
Serena tools so every call feeds health tracking; the tracker gates the read-guard
|
|
787
|
+
The template's `PostToolUse` matcher is broadened from the six navigation tools
|
|
788
|
+
to **all** Serena tools so every call feeds health tracking; the tracker gates the read-guard
|
|
873
789
|
nav counters internally (only the six nav/exploration tools advance the gate, as
|
|
874
790
|
before). The `PostToolUseFailure` block points at the same script — see
|
|
875
791
|
[Health tracking & fail-open enforcement](#health-tracking--fail-open-enforcement)
|
|
@@ -894,4 +810,5 @@ Two documented caveats on those deny rules:
|
|
|
894
810
|
matching call even when a narrower `allow` rule also matches. So
|
|
895
811
|
`Bash(git stash:*)` also blocks read-only `git stash list`.
|
|
896
812
|
|
|
897
|
-
Hooks load at session start, so restart any running session after
|
|
813
|
+
Hooks load at session start, so restart any running session after an install
|
|
814
|
+
run that created or changed the wiring.
|
|
@@ -16,15 +16,21 @@
|
|
|
16
16
|
//
|
|
17
17
|
// TASK-026 originally shipped `Edit(~/.claude/settings.json)` and
|
|
18
18
|
// `Edit(~/.claude/settings.local.json)` as deny entries. They were removed on
|
|
19
|
-
// 2026-07-29
|
|
20
|
-
//
|
|
21
|
-
//
|
|
19
|
+
// 2026-07-29 to make room for a bootstrap-claude carve-out, on the belief that
|
|
20
|
+
// THIS repo needs to edit those files because install-global.sh and
|
|
21
|
+
// merge-settings-deny.js manage them.
|
|
22
22
|
//
|
|
23
|
-
//
|
|
24
|
-
//
|
|
25
|
-
//
|
|
26
|
-
//
|
|
27
|
-
//
|
|
23
|
+
// THAT BELIEF WAS WRONG, and the carve-out was removed on 2026-07-30. The
|
|
24
|
+
// repo's settings writes go through `node merge-settings-deny.js` *inside*
|
|
25
|
+
// install-global.sh — Bash subprocesses, which no PreToolUse hook and no
|
|
26
|
+
// permission rule ever sees. Nothing in this repo's workflow needs the Edit
|
|
27
|
+
// TOOL on those files. The exception cost real safety and bought nothing:
|
|
28
|
+
// it let any agent running here rewrite its own permission boundary, which
|
|
29
|
+
// was demonstrated live before it was closed.
|
|
30
|
+
//
|
|
31
|
+
// The block is now unconditional. To change the permission rules, edit
|
|
32
|
+
// lib/scripts/templates/settings-deny.json and re-run install-global.sh —
|
|
33
|
+
// the same flow this hook's message tells everyone else to use.
|
|
28
34
|
//
|
|
29
35
|
// Why ~/.claude/hooks/** is ALSO checked here, and is not redundant:
|
|
30
36
|
//
|
|
@@ -46,14 +52,17 @@
|
|
|
46
52
|
//
|
|
47
53
|
// RESIDUAL RISK, stated plainly:
|
|
48
54
|
//
|
|
49
|
-
//
|
|
50
|
-
//
|
|
51
|
-
//
|
|
52
|
-
//
|
|
53
|
-
//
|
|
54
|
-
//
|
|
55
|
-
//
|
|
56
|
-
//
|
|
55
|
+
// This hook guards the file TOOLS. An agent with Bash can still write these
|
|
56
|
+
// files another way — `node write-settings.js` reaches them, and no hook here
|
|
57
|
+
// parses inside a script file. protected-write-guard.js catches shell
|
|
58
|
+
// redirects (`echo … >> ~/.claude/settings.json`) and
|
|
59
|
+
// interpreter-indirection-guard.js catches `node -e`, but a script written to
|
|
60
|
+
// disk and then executed is not covered by design.
|
|
61
|
+
//
|
|
62
|
+
// So this is a guardrail, not a boundary: it closes the casual and accidental
|
|
63
|
+
// paths, which is most of them, and raises the cost of the deliberate one. The
|
|
64
|
+
// only real containment for a compromised agent is Tier 3 (/sandbox —
|
|
65
|
+
// OS-level confinement). Do not read the unconditional block as a guarantee.
|
|
57
66
|
//
|
|
58
67
|
// Known gaps, deliberate:
|
|
59
68
|
// - Project-level `.claude/settings.json` files are not guarded here; this
|
|
@@ -68,12 +77,6 @@ const os = require('os');
|
|
|
68
77
|
const path = require('path');
|
|
69
78
|
const { readHookInput, deny } = require('./lib/command-parse');
|
|
70
79
|
|
|
71
|
-
// Both marker conditions must hold for a directory to count as a real
|
|
72
|
-
// bootstrap-claude checkout. A path-substring test like
|
|
73
|
-
// `cwd.includes('bootstrap-claude')` is spoofed by `mkdir bootstrap-claude`.
|
|
74
|
-
const MARKER_FILE = path.join('lib', 'scripts', 'templates', 'settings-deny.json');
|
|
75
|
-
const MARKER_PACKAGE_NAME = '@codewizard-dt/bootstrap';
|
|
76
|
-
|
|
77
80
|
// Upper bound on any parent walk. path.dirname() is purely lexical and reaches
|
|
78
81
|
// a fixed point at the filesystem root, so this is belt-and-braces against a
|
|
79
82
|
// pathological input rather than a real loop risk — but a hook must never hang.
|
|
@@ -135,49 +138,17 @@ function classify(resolved) {
|
|
|
135
138
|
return null;
|
|
136
139
|
}
|
|
137
140
|
|
|
138
|
-
/**
|
|
139
|
-
* A directory is a bootstrap-claude root only if it carries the template the
|
|
140
|
-
* deny list is authored in AND its package.json claims the package name.
|
|
141
|
-
* A missing, unreadable, or unparseable package.json means "not a checkout" —
|
|
142
|
-
* never a crash.
|
|
143
|
-
*/
|
|
144
|
-
function isBootstrapRoot(dir) {
|
|
145
|
-
try {
|
|
146
|
-
if (!fs.statSync(path.join(dir, MARKER_FILE)).isFile()) return false;
|
|
147
|
-
const pkg = JSON.parse(fs.readFileSync(path.join(dir, 'package.json'), 'utf8'));
|
|
148
|
-
return pkg && pkg.name === MARKER_PACKAGE_NAME;
|
|
149
|
-
} catch {
|
|
150
|
-
return false;
|
|
151
|
-
}
|
|
152
|
-
}
|
|
153
|
-
|
|
154
|
-
/**
|
|
155
|
-
* Walk up from the session's directory looking for a marker root. The walk is
|
|
156
|
-
* lexical (path.dirname), so it cannot follow a symlink into a cycle, and it
|
|
157
|
-
* terminates at the filesystem root. No marker root found means no exception.
|
|
158
|
-
*/
|
|
159
|
-
function findBootstrapRoot(startDir) {
|
|
160
|
-
let dir = realpathBestEffort(startDir);
|
|
161
|
-
for (let i = 0; i < MAX_WALK; i++) {
|
|
162
|
-
if (isBootstrapRoot(dir)) return dir;
|
|
163
|
-
const parent = path.dirname(dir);
|
|
164
|
-
if (parent === dir) return null;
|
|
165
|
-
dir = parent;
|
|
166
|
-
}
|
|
167
|
-
return null;
|
|
168
|
-
}
|
|
169
|
-
|
|
170
141
|
function reasonForSettings(resolved) {
|
|
171
142
|
return (
|
|
172
|
-
`Blocked: editing \`${resolved}
|
|
173
|
-
`
|
|
174
|
-
`
|
|
175
|
-
`
|
|
176
|
-
|
|
177
|
-
`
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
`
|
|
143
|
+
`Blocked: editing \`${resolved}\`. This file decides what every agent session is ` +
|
|
144
|
+
`permitted to do, so a write to it is a change to your own permission boundary ` +
|
|
145
|
+
`rather than a change to a project. There is no exception — not even inside the ` +
|
|
146
|
+
`bootstrap-claude repo, which manages these settings through ` +
|
|
147
|
+
`\`install-global.sh\` (a shell subprocess this hook never sees) rather than through ` +
|
|
148
|
+
`the Edit tool. To change the permission rules, edit ` +
|
|
149
|
+
`\`lib/scripts/templates/settings-deny.json\` in the bootstrap-claude repo and re-run ` +
|
|
150
|
+
`\`install-global.sh\`, which merges it in — that way the change is reviewable in git ` +
|
|
151
|
+
`instead of being a local mutation nobody sees.`
|
|
181
152
|
);
|
|
182
153
|
}
|
|
183
154
|
|
|
@@ -216,20 +187,14 @@ readHookInput(data => {
|
|
|
216
187
|
// Relative paths resolve against the session's directory, not this process's.
|
|
217
188
|
const baseDir = typeof data.cwd === 'string' && data.cwd ? data.cwd : process.cwd();
|
|
218
189
|
|
|
219
|
-
// Resolved once and reused: the walk touches the filesystem, and it is the
|
|
220
|
-
// same answer for every target in a MultiEdit batch.
|
|
221
|
-
let bootstrapRoot;
|
|
222
|
-
|
|
223
190
|
for (const target of targets) {
|
|
224
191
|
const resolved = realpathBestEffort(path.resolve(baseDir, expandHome(target, HOME)));
|
|
225
192
|
const kind = classify(resolved);
|
|
226
193
|
if (!kind) continue;
|
|
227
194
|
|
|
228
|
-
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
deny(reasonForSettings(resolved));
|
|
195
|
+
// Both kinds block unconditionally. There is no cwd-dependent branch here
|
|
196
|
+
// any more — see the header for why the bootstrap-claude carve-out was
|
|
197
|
+
// removed rather than narrowed.
|
|
198
|
+
deny(kind === 'hooks' ? reasonForHooks(resolved) : reasonForSettings(resolved));
|
|
234
199
|
}
|
|
235
200
|
});
|
package/lib/scripts/README.md
CHANGED
|
@@ -8,9 +8,9 @@ All scripts use `set -euo pipefail`. Every script that touches a target project
|
|
|
8
8
|
|
|
9
9
|
| Script | `bootstrap` command | What it does |
|
|
10
10
|
|--------|---------------------|---------------|
|
|
11
|
-
| `setup-project.sh` | `setup` | Preflight-checks `claude` and `uv` are installed, then runs the full new-project sequence:
|
|
12
|
-
| `update-project.sh` | `update` | Re-
|
|
13
|
-
| `install-global.sh` | `install` | Installs/updates
|
|
11
|
+
| `setup-project.sh` | `setup` | Preflight-checks `claude` and `uv` are installed, then runs the full new-project sequence: global hooks/skills/settings install first (offline-safe, via `install-global.sh --skip-mcps` — includes the deny-list and hooks-wiring merges), then the interactive MCP install (guarded — a failure warns and continues), wiki scaffold + tiered guides sync (optional guides prompted), `.gitignore` merge, and Serena `project.yml` bootstrap. Does **not** scaffold deployment — that's explicit via `deploy`. |
|
|
12
|
+
| `update-project.sh` | `update` | Re-runs the same shared sequence as `setup` (global hooks/skills/settings via `install-global.sh --skip-mcps`, then the guarded interactive MCP install) and re-syncs the wiki scaffold + tiered `wiki/guides/` into an existing project. Detects legacy `.docs/`-layout families (`tasks`, `uat`, `adr`, `prd`, `bugs`, `roadmaps`) and warns without touching them — migration is a separate, explicit step (`migrate`). Never touches `.github/`. |
|
|
13
|
+
| `install-global.sh` | `install` | Installs/updates hooks, skills, settings, and MCPs globally with **no project path** — the shared step both `setup` and `update` delegate to. Local/offline-safe steps run first: hooks rsync to `~/.claude/hooks/` (stderr warning if `lib/hooks` is missing), skills install (pruning stale skill folders from the wiki rename — `adr-*` → `decision-*`, `prd-*` → `req-*`), the canonical permission deny-list merge into `~/.claude/settings.json` via `merge-settings-deny.js`, then the hooks-wiring merge via `merge-settings-hooks.js` — registering the copied hook scripts in the settings `hooks` key, with a restart-your-session reminder when the wiring was created or changed. Then copies `templates/file-suggestion.sh` → `~/.claude/file-suggestion.sh` and registers it as the `fileSuggestion` `@`-autocomplete picker (`merge-settings-deny.js --set-key` mode) — printing a restart note on fresh registration, or leaving a pre-existing different `fileSuggestion` untouched. MCPs install **last** — the only network-dependent step, guarded so a failure warns instead of aborting the local installs — and `--skip-mcps` skips them when the caller already handled MCP install interactively. |
|
|
14
14
|
| `setup-deployment.sh` | `deploy` / `deployment` | Reads `raw/guides/deployment-strategy.md` as a prompt template, copies it into the target's `wiki/guides/` (deploy-only guide tier — the wiki sync never ships it), and runs `claude` to scaffold `.github/workflows/`, `Makefile` Docker targets, and `.gitleaks.toml` into the target project. Deliberately **not** called by `setup`/`update` — CI files get hand-customized per project (Dockerfile paths, runner labels, deploy steps) and must never be created or clobbered implicitly. `security.yml` is always overwritten (generic); `build.yml`/`.gitleaks.toml` are copy-once; `Makefile` targets are merged. |
|
|
15
15
|
| `migrate-project.sh` | `migrate` | Claude-driven migration of a legacy `.docs/`-layout project to the LLM Wiki structure (`wiki/knowledge/` + `wiki/work/`). Preflight requires a clean git tree; runs on a fresh `wiki-migration` branch so the whole migration is one reviewable diff. Scaffolds first via `sync-wiki-scaffold.sh --interactive`, assembles `wiki/guides/mcp-tools.md` via `build-mcp-guide.sh`, then drives the semantic conversion (frontmatter synthesis, ID renames, link rewrites, family indexes) with the prompt at `lib/prompts/migrate-wiki.md`. `git mv` before edit, so history is preserved. `--dry-run` prints the file inventory only and does not touch anything. |
|
|
16
16
|
| `setup-strict-typechecks.sh` | `typechecks` | Loads `lib/prompts/setup-strict-typechecks.md`, appends an optional language list (space- or comma-separated), and runs `claude` to detect languages, research current strict-mode conventions, install toolchains, and wire `make typecheck`. |
|
|
@@ -20,13 +20,14 @@ All scripts use `set -euo pipefail`. Every script that touches a target project
|
|
|
20
20
|
|
|
21
21
|
| Script | Used by | Purpose |
|
|
22
22
|
|--------|---------|---------|
|
|
23
|
-
| `lib.sh` | Every script above | Shared bash library: `resolve_project_dir` (path resolution + validation), `mcp_installed`/`serena_installed`/`detect_installed_mcps` (MCP state checks), `run_project_sync` (the common setup/update sequence:
|
|
23
|
+
| `lib.sh` | Every script above | Shared bash library: `resolve_project_dir` (path resolution + validation), `mcp_installed`/`serena_installed`/`detect_installed_mcps` (MCP state checks), `run_project_sync` (the common setup/update sequence: `install-global.sh --skip-mcps` first — hooks/skills/deny-list/hooks-wiring/fileSuggestion, offline-safe — then the guarded interactive MCP install, wiki scaffold, gitignore, MCP-tools guide, Serena bootstrap), and `prompt_yn`/`prompt_scope` (interactive prompt helpers). |
|
|
24
24
|
| `install-mcps.sh` | `install-global.sh`, `setup-project.sh`, `update-project.sh` | Installs Brave Search, Context7, Playwright, and (when a project dir is given) Serena. Two modes: non-interactive (`install-global.sh`'s default — installs everything missing at user scope) and `--interactive --project-dir <dir>` (prompts per-MCP and asks for scope, used by `setup`/`update`). Playwright has a dedicated conflict flow: registered as `playwright` (user scope) by default; when a project ships its own `playwright`, a git-tracked `.mcp.json` is never modified (interactive options: register ours as `playwright-shared` + disable the project entry machine-locally via `disabledMcpjsonServers` in `.claude/settings.local.json` / register alongside / skip), while a machine-local registration can be replaced or kept (ours then uses the alternate name). Non-interactive conflicts are left untouched with a hint. |
|
|
25
25
|
| `sync-wiki-scaffold.sh` | `setup-project.sh`, `update-project.sh`, `migrate-project.sh` | Scaffolds an **empty** wiki into the target project from `templates/wiki/`: creates `raw/` + all `wiki/` family directories, lifecycle docs, per-family `index.md`, and stub `index.md`/`log.md`. Copy-once for project-owned files; always-refreshes `conventions.md` and `lifecycle.md`. Delivers guides from `raw/guides/` tier-wise into `wiki/guides/`: `command-anti-patterns.md` required (always refreshed); `evals-framework.md` + `type-checking-templates/` optional (`--interactive` prompts on first delivery, sticky refresh once present — legacy `.docs/guides/` presence counts, opt out by deleting); migrates legacy `.docs/guides/` (template-owned files removed or relocated, deprecated `task-spec.md` deleted, empty dirs pruned). Also delivers the `## LLM Wiki` section and `.env` safety policy (copy-once, sentinel-guarded, from `templates/CLAUDE-wiki.md` / `templates/CLAUDE-env-safety.md`) into the target's `CLAUDE.md` — when a `CLAUDE.md` already exists without the schema, prompts whether to modify it or write `CLAUDE.local.md` instead (non-interactive default: `CLAUDE.local.md`). |
|
|
26
26
|
| `build-mcp-guide.sh` | `setup-project.sh`, `update-project.sh`, `migrate-project.sh` | Assembles `wiki/guides/mcp-tools.md` in the target project from the per-server stub files in `templates/guides/stubs/`, including only the sections for MCPs actually installed. |
|
|
27
27
|
| `bootstrap-serena.sh` | `setup-project.sh`, `update-project.sh` | Headlessly triggers `.serena/project.yml` creation via `claude --print` and enables the optional Serena tools needed by this template's workflow. Preflights `claude` and `python3`. |
|
|
28
28
|
| `merge-gitignore.sh` | `setup-project.sh`, `update-project.sh` | Fully interactive `.gitignore` merge — **nothing is ever added without asking**. The packaged template's titled sections are offered one by one (`Add/update .gitignore section '<title>' (N new line(s))? [y/N]`); sections with nothing new are skipped silently. Non-interactive runs (or no tty) change nothing at all. Never touches existing project content. Also offers (git repos only) to keep `.serena/`/`raw/`/`wiki/` out of git via **`.git/info/exclude`** — never `.gitignore`, which would blind Serena on the wiki (see `wiki/knowledge/concepts/git-ignore-tool-visibility.md`); per-machine and idempotent. `info/exclude` *is* honored by ripgrep-class walkers and the `@` file picker, so the excluded paths are written under a `# bootstrap wiki & agent state (machine-local)` sentinel that the `fileSuggestion` picker installed by `install-global.sh` reads back to restore `@`-autocomplete. |
|
|
29
29
|
| `merge-settings-deny.js` | `install-global.sh` | Zero-dependency Node script that merges the canonical permission deny list (`templates/settings-deny.json` — `Bash(...)` command patterns plus `Edit(...)`/`Read(...)` file-tool patterns) into `~/.claude/settings.json` `permissions.deny`. Entries are opaque strings, so any rule form the permission system accepts merges unchanged. Additive union only: missing entries are appended, user entries are never removed or reordered, all other settings keys pass through untouched. Atomic write, preserves existing indentation, and always exits 0 (warns + skips on unparseable or unexpected file shapes so an install never aborts over a settings merge). `--target`/`--source` flags exist as test seams. A second mode, `--set-key <name> --set-value <json>`, merges a single top-level settings key instead of the deny list (used to register `fileSuggestion`): absent → set; already deep-equal → no-op; present but different → one-line warning and skip, never a clobber. Supplying `--set-key` skips the deny merge entirely; a malformed `--set-value` exits 1, since that is a call-site bug rather than a user's file. |
|
|
30
|
+
| `merge-settings-hooks.js` | `install-global.sh` | Zero-dependency Node sibling of `merge-settings-deny.js` (deliberately not a new mode of it — different, block-and-entry-aware semantics) that merges the canonical hook wiring (`templates/settings-hooks.json`) into the `hooks` key of `~/.claude/settings.json` with a "template owns its blocks" model: repo-owned entries (a `command` under `~/.claude/hooks/` whose basename appears in the template) are created or updated in place; matcher drift on a pure-owned block is adopted (a matcher rename ships without duplicating the block); user/foreign blocks and entries are never modified, reordered, or removed; a repo hook found relocated into a mixed block is warned about but not duplicated; no empty placeholder blocks are ever written. Always exits 0 (warns + skips on unparseable or unexpected file shapes so an install never aborts over a settings merge). `--target`/`--source` flags exist as test seams. |
|
|
30
31
|
|
|
31
32
|
## Standalone infra scripts (not wired to the CLI)
|
|
32
33
|
|
|
@@ -50,6 +51,7 @@ Static and semi-static assets copied or read by the scripts above — never exec
|
|
|
50
51
|
| `templates/gitignore` | `merge-gitignore.sh` | Packed copy of this repo's own `.gitignore` (dotfiles aren't included in npm packages, so it's shipped under a non-dot name and renamed on copy). |
|
|
51
52
|
| `templates/file-suggestion.sh` | `install-global.sh` | The `fileSuggestion` `@`-autocomplete picker, copied to `~/.claude/file-suggestion.sh`. Reads the picker's stdin JSON `query` with `sed` (no `jq`), lists the project from `rg --files` (falling back to `git ls-files`, then `find`), and re-includes the paths under the `# bootstrap wiki & agent state (machine-local)` sentinel in `.git/info/exclude` — so bootstrap's hidden dirs are suggestible again while a user's other `info/exclude` entries stay hidden. Always exits 0. |
|
|
52
53
|
| `templates/settings-deny.json` | `merge-settings-deny.js` | The canonical `permissions.deny` list (bare JSON array of rule strings). Covers **both** `Bash(...)` command patterns (destructive disk/system commands, `sudo`, permission footguns, git working-tree/history protections, macOS persistence, credential exfiltration, fetch-and-execute) **and** file-tool path patterns — `Edit(...)` / `Read(...)` — protecting Claude Code's own settings and hooks, shell profiles, git config, and credential stores. Audited against the Claude Code permission-rule docs; merged additively into `~/.claude/settings.json` on every `install`/`setup`/`update`. See [Deny-list notes](#deny-list-notes) for the enforcement model and known costs. |
|
|
54
|
+
| `templates/settings-hooks.json` | `merge-settings-hooks.js` | The canonical hook wiring — a bare hooks-value object (the value of the settings `hooks` key, not a full settings file) covering 4 events (`SessionStart`, `PreToolUse`, `PostToolUse`, `PostToolUseFailure`) whose entries map 1:1 onto the 18 hook scripts in `lib/hooks/*.js`. The single source of truth for the wiring merged into `~/.claude/settings.json` on every `install`/`setup`/`update`; each block's matcher is load-bearing (see `lib/hooks/README.md`), which is why the wiring ships as a template instead of being hand-pasted. |
|
|
53
55
|
|
|
54
56
|
## Deny-list notes
|
|
55
57
|
|
|
@@ -84,19 +86,25 @@ tool call, and Claude Code hot-reloads both files so such a write takes effect
|
|
|
84
86
|
immediately. It matters *most* under `bypassPermissions`, where Claude Code's
|
|
85
87
|
built-in protection for `.claude` paths is **not** applied.
|
|
86
88
|
|
|
87
|
-
That protection
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
`
|
|
89
|
+
That protection lives in a `PreToolUse` hook (`claude-settings-guard.js`) rather
|
|
90
|
+
than in this deny list. `claude-settings-guard.js` blocks `Edit`/`Write`/
|
|
91
|
+
`NotebookEdit`/`MultiEdit` on `~/.claude/settings.json` and `settings.local.json`
|
|
92
|
+
**unconditionally** — the verdict does not depend on cwd.
|
|
93
|
+
|
|
94
|
+
*History worth knowing, because the code changed under it:* the deny entries were
|
|
95
|
+
originally removed to make room for a bootstrap-claude carve-out, on the belief
|
|
96
|
+
that this repo needs to edit those files. **It does not.** The repo writes them
|
|
97
|
+
through `node merge-settings-deny.js` *inside* `install-global.sh` — a Bash
|
|
98
|
+
subprocess that no hook and no permission rule ever observes. The exception was
|
|
99
|
+
never load-bearing and was removed on 2026-07-30, after it was demonstrated that
|
|
100
|
+
any agent running in this repo could rewrite its own permission boundary with a
|
|
101
|
+
plain `Edit` call.
|
|
102
|
+
|
|
103
|
+
The deny entries stay out, but now by choice rather than necessity: the merge is
|
|
104
|
+
additive-only with **no removal path**, so restoring them is permanent for every
|
|
105
|
+
installed user, and the hook already covers the same paths *plus* the `Write` and
|
|
106
|
+
`NotebookEdit` surfaces that `Edit(...)` rules never reach. Restore them only if
|
|
107
|
+
the hook proves unreliable.
|
|
100
108
|
|
|
101
109
|
**`~/.claude/hooks/**` stays in the deny list with no exception**, including
|
|
102
110
|
inside this repo. The canonical flow there is to edit `lib/hooks/` and re-run
|