@codewizard-dt/bootstrap 2.14.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.
Files changed (40) hide show
  1. package/lib/hooks/README.md +639 -142
  2. package/lib/hooks/absolute-path-guard.js +142 -0
  3. package/lib/hooks/claude-settings-guard.js +200 -0
  4. package/lib/hooks/env-content-read-guard.js +367 -0
  5. package/lib/hooks/git-protected-ops-block.js +12 -7
  6. package/lib/hooks/interpreter-indirection-guard.js +576 -0
  7. package/lib/hooks/lib/command-parse.js +63 -0
  8. package/lib/hooks/package-install-consent.js +151 -0
  9. package/lib/hooks/protected-write-guard.js +237 -0
  10. package/lib/scripts/README.md +73 -8
  11. package/lib/scripts/build-mcp-guide.sh +9 -1
  12. package/lib/scripts/install-global.sh +62 -11
  13. package/lib/scripts/install-mcps.sh +140 -36
  14. package/lib/scripts/lib.sh +24 -15
  15. package/lib/scripts/merge-gitignore.sh +221 -33
  16. package/lib/scripts/merge-settings-deny.js +112 -39
  17. package/lib/scripts/merge-settings-hooks.js +374 -0
  18. package/lib/scripts/templates/file-suggestion.sh +142 -0
  19. package/lib/scripts/templates/gitignore +8 -0
  20. package/lib/scripts/templates/guides/stubs/playwright.md +2 -0
  21. package/lib/scripts/templates/settings-deny.json +81 -1
  22. package/lib/scripts/templates/settings-hooks.json +151 -0
  23. package/lib/skills/debug-logs/SKILL.md +1 -1
  24. package/lib/skills/git-commit/SKILL.md +8 -0
  25. package/package.json +5 -2
  26. package/raw/research/brave-mcp-single-docker-container/index.md +0 -94
  27. package/raw/research/brave-mcp-single-docker-container/sources.md +0 -70
  28. package/raw/research/dark-mode-theme/index.md +0 -85
  29. package/raw/research/dark-mode-theme/sources.md +0 -49
  30. package/raw/research/mcp-add-scope-writes/index.md +0 -46
  31. package/raw/research/mcp-add-scope-writes/sources.md +0 -38
  32. package/raw/research/mcp-one-process-per-user/index.md +0 -75
  33. package/raw/research/mcp-one-process-per-user/sources.md +0 -66
  34. package/raw/research/mcp-scope-conflict-handling/index.md +0 -61
  35. package/raw/research/mcp-scope-conflict-handling/sources.md +0 -32
  36. package/raw/research/serena-mcp-disconnect/index.md +0 -81
  37. package/raw/research/serena-mcp-disconnect/sources.md +0 -87
  38. package/raw/research/wiki-tooling-improvements/index.md +0 -126
  39. package/raw/research/wiki-tooling-improvements/sources.md +0 -73
  40. package/raw/software-factory-case-study.pdf +0 -0
@@ -0,0 +1,142 @@
1
+ #!/usr/bin/env node
2
+ 'use strict';
3
+
4
+ // absolute-path-guard.js — PreToolUse hook (matcher: Bash)
5
+ //
6
+ // Blocks EVASIVE SPELLINGS of a small set of destructive commands: the path
7
+ // form (`/bin/rm`, `/usr/bin/sudo`, `./rm`), the backslash-escaped form
8
+ // (`\rm`), and the wrapper-prefixed form (`env rm`, `FOO=1 rm`).
9
+ //
10
+ // Why a hook and not more deny entries: a deny rule matches the literal
11
+ // spelling of a command, anchored at the start of the string. `Bash(rm -rf ~*)`
12
+ // blocks `rm -rf ~` and nothing else — `/bin/rm -rf ~`, `\rm -rf ~`, and
13
+ // `env rm -rf ~` all run the identical program and none of them match. Adding
14
+ // deny entries per path prefix is unbounded (`/bin`, `/usr/bin`, `/usr/sbin`,
15
+ // `/opt/homebrew/bin`, any relative path), so the class has to be closed by
16
+ // parsing the invocation instead of enumerating its spellings.
17
+
18
+ // ---------------------------------------------------------------------------
19
+ // THE LINE THIS HOOK DRAWS: it fires on the SPELLING, never on the command.
20
+ //
21
+ // The deny entries for these commands are deliberately narrow. `rm` is denied
22
+ // only for catastrophic targets (`rm -rf ~*`, `rm -rf /Users*`); plain
23
+ // `rm build/output.js` is intentionally allowed. Same for `chmod` (only `777`,
24
+ // `a+rwx`, `+s` forms are denied — `chmod +x script.sh` is allowed), `chown`
25
+ // (only `-R`/`--recursive`), `diskutil` (only the erase/partition
26
+ // subcommands), and `launchctl` (only `load`/`bootstrap`/`submit`).
27
+ //
28
+ // So this hook must NOT block a guarded name on sight. If it did, it would
29
+ // break routine `rm build/out.js`, `chmod +x script.sh`, and `chown me file` —
30
+ // a regression far worse than the gap being closed.
31
+ //
32
+ // Instead it fires only when the invocation is written in a form that evades
33
+ // literal matching. A plainly-spelled `rm build/out.js` passes straight
34
+ // through this hook to the permission engine, which then allows or denies it
35
+ // on its own merits.
36
+ //
37
+ // This is safe precisely BECAUSE the hook grants nothing. It only forces a
38
+ // command back into the form the deny list can inspect. The remedy for a false
39
+ // positive is to retype the command without the path prefix or wrapper — which
40
+ // re-exposes it to the deny rules rather than bypassing them. So the worst
41
+ // cost of over-firing is one retype, and the argument-blind rule buys
42
+ // immunity from argument-level obfuscation.
43
+ //
44
+ // Accepted consequence, stated plainly: `/bin/rm file.txt` is blocked even
45
+ // though `rm file.txt` is allowed. That is intended. There is no legitimate
46
+ // reason to reach for the absolute path here, and the path prefix is itself
47
+ // the signal — inspecting the arguments to decide would put us back to
48
+ // matching literal spellings, which is the failure this tier exists to escape.
49
+ // ---------------------------------------------------------------------------
50
+
51
+ const { readHookInput, splitSegments, tokenize, deny } = require('./lib/command-parse');
52
+
53
+ // INTENTIONALLY PARTIAL — the destructive core only, not a mirror of the ~116
54
+ // entries in lib/scripts/templates/settings-deny.json. Every name here has at
55
+ // least one deny entry that the evasive spellings above would slip past. The
56
+ // list stays short and explicit on purpose: each addition costs a class of
57
+ // false positives (see the note above), so names are added only when the
58
+ // consequence of an ungated run is destructive and irreversible. Widening it
59
+ // to cover every denied command would be a much bigger behavioral change than
60
+ // it looks, and is not the job of this hook.
61
+ const GUARDED = new Set([
62
+ 'rm', // Bash(rm -rf ~*), Bash(rm -rf /Users*), …
63
+ 'dd', // Bash(dd *)
64
+ 'mkfs', // Bash(mkfs *)
65
+ 'sudo', // Bash(sudo *)
66
+ 'diskutil', // Bash(diskutil eraseDisk *), …
67
+ 'chmod', // Bash(chmod 777 *), Bash(chmod +s *), …
68
+ 'chown', // Bash(chown -R *), Bash(chown --recursive *)
69
+ 'shutdown', // Bash(shutdown *)
70
+ 'launchctl', // Bash(launchctl load *), …
71
+ 'crontab', // Bash(crontab *)
72
+ 'osascript', // Bash(osascript *)
73
+ ]);
74
+
75
+ // Prefixes that push the real command off the start of the segment, which is
76
+ // where an anchored deny pattern expects to find it. `env` and the leading
77
+ // `VAR=value` form are the ones the task named; `command`, `exec`, and `nohup`
78
+ // are the same class and cost nothing to cover. `sudo` is deliberately NOT
79
+ // here — it is a guarded name in its own right, so it must be judged as a
80
+ // first token (plainly-spelled `sudo` falls through to `Bash(sudo *)`, which
81
+ // already blocks all of it; `/usr/bin/sudo` is caught below).
82
+ const WRAPPERS = new Set(['env', 'command', 'exec', 'nohup']);
83
+
84
+ const ENV_ASSIGNMENT = /^[A-Za-z_][A-Za-z0-9_]*=/;
85
+
86
+ function basename(token) {
87
+ return token.slice(token.lastIndexOf('/') + 1);
88
+ }
89
+
90
+ // Walk past wrapper and env-assignment tokens to the command actually being
91
+ // run, reporting whether anything had to be skipped to reach it.
92
+ function resolveCommandToken(tokens) {
93
+ let i = 0;
94
+ while (i < tokens.length) {
95
+ const t = tokens[i];
96
+ if (ENV_ASSIGNMENT.test(t) || WRAPPERS.has(basename(t.replace(/^\\+/, '')))) i++;
97
+ else break;
98
+ }
99
+ return { token: tokens[i] ?? null, wrapped: i > 0 };
100
+ }
101
+
102
+ // Returns a description of HOW this invocation evades literal matching, or
103
+ // null when it is spelled plainly and should be left to the deny list.
104
+ function evasionKind(token, wrapped) {
105
+ if (token.startsWith('\\')) return 'a backslash-escaped name (`\\rm`), which also skips alias and shell-function lookup';
106
+ if (token.includes('/')) return 'a path (`/bin/rm`, `./rm`) rather than the bare command name';
107
+ if (wrapped) return 'a wrapper or environment-assignment prefix (`env rm`, `FOO=1 rm`)';
108
+ return null;
109
+ }
110
+
111
+ readHookInput(data => {
112
+ if (data.tool_name !== 'Bash') return;
113
+
114
+ const fullCmd = String(data.tool_input?.command ?? '').trim();
115
+ if (!fullCmd) return;
116
+
117
+ for (const segment of splitSegments(fullCmd)) {
118
+ // Only the first token of a segment is examined, not every token. That is
119
+ // what keeps `echo "use /bin/rm"` and `grep -r chmod .` from firing: those
120
+ // mention a guarded name, they do not invoke one. splitSegments already
121
+ // broke the chain on `;`, `&&`, `||`, and `|`, so a command hidden after a
122
+ // separator still gets its own turn as a first token.
123
+ const { token, wrapped } = resolveCommandToken(tokenize(segment));
124
+ if (!token) continue;
125
+
126
+ const name = basename(token.replace(/^\\+/, ''));
127
+ if (!GUARDED.has(name)) continue;
128
+
129
+ const kind = evasionKind(token, wrapped);
130
+ if (!kind) continue; // plainly spelled — the deny list decides this one
131
+
132
+ deny(
133
+ `Blocked: \`${segment}\` invokes \`${name}\` using ${kind}. ` +
134
+ `The permission deny list matches the literal spelling of a command, so it sees ` +
135
+ `\`${name} …\` but not this form — the rules that would normally govern \`${name}\` ` +
136
+ `never get consulted, which is why this is blocked at the hook layer instead. ` +
137
+ `If the command is legitimate, run it with the plain name (\`${name} …\`). ` +
138
+ `That is not a workaround: it puts the command back in front of the deny rules, ` +
139
+ `which will permit it if it is safe and block it if it is not.`
140
+ );
141
+ }
142
+ });
@@ -0,0 +1,200 @@
1
+ #!/usr/bin/env node
2
+ 'use strict';
3
+
4
+ // claude-settings-guard.js — PreToolUse hook (matcher: Edit|Write|NotebookEdit|MultiEdit)
5
+ //
6
+ // Guards the two files that define what an agent is allowed to do
7
+ // (~/.claude/settings.json, ~/.claude/settings.local.json) and the directory
8
+ // whose contents run on every subsequent tool call (~/.claude/hooks/).
9
+ //
10
+ // Unlike the other hooks in this directory this one matches FILE TOOLS, not
11
+ // Bash — env-file-guard.js is the structural precedent. The Bash-side of the
12
+ // same protected paths (`echo … >> ~/.claude/settings.json`) is covered
13
+ // separately by protected-write-guard.js.
14
+ //
15
+ // Why a hook and not deny entries:
16
+ //
17
+ // TASK-026 originally shipped `Edit(~/.claude/settings.json)` and
18
+ // `Edit(~/.claude/settings.local.json)` as deny entries. They were removed on
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
+ //
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.
34
+ //
35
+ // Why ~/.claude/hooks/** is ALSO checked here, and is not redundant:
36
+ //
37
+ // TASK-026's `Edit(~/.claude/hooks/**)` and `Edit(**/.claude/hooks/**)` deny
38
+ // entries remain in place and are the primary control — this hook does not
39
+ // replace them. But file permission checks consult only `Edit(path)` and
40
+ // `Read(path)`; `Write(...)` rules are accepted by the settings parser and
41
+ // then never consulted (raw/research/bypass-mode-enforcement/index.md:108,
42
+ // sourced to code.claude.com/docs/en/permissions). The Write *tool* still
43
+ // works. So `Write(~/.claude/hooks/evil.js)` has no deny coverage whatsoever,
44
+ // and neither does the MultiEdit/NotebookEdit surface. That is the deny list
45
+ // proving insufficient, not this hook duplicating it.
46
+ //
47
+ // The hooks/** block is ABSOLUTE — no bootstrap-claude exception. Even in
48
+ // this repo the canonical flow is: edit lib/hooks/, then run
49
+ // install-global.sh, which rsyncs into ~/.claude/hooks/. Editing the
50
+ // installed copy directly is always wrong; the next install silently
51
+ // overwrites it.
52
+ //
53
+ // RESIDUAL RISK, stated plainly:
54
+ //
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.
66
+ //
67
+ // Known gaps, deliberate:
68
+ // - Project-level `.claude/settings.json` files are not guarded here; this
69
+ // hook is scoped to the user-global ~/.claude/ tree per its checkbox.
70
+ // - A write is judged by its resolved target only. An agent that first
71
+ // replaces some unguarded path with a symlink and then writes through it is
72
+ // caught (the target resolves into ~/.claude/), but an agent that writes a
73
+ // script elsewhere and executes it is a Bash concern, not this hook's.
74
+
75
+ const fs = require('fs');
76
+ const os = require('os');
77
+ const path = require('path');
78
+ const { readHookInput, deny } = require('./lib/command-parse');
79
+
80
+ // Upper bound on any parent walk. path.dirname() is purely lexical and reaches
81
+ // a fixed point at the filesystem root, so this is belt-and-braces against a
82
+ // pathological input rather than a real loop risk — but a hook must never hang.
83
+ const MAX_WALK = 64;
84
+
85
+ /**
86
+ * Resolve a path all the way to its real location, tolerating targets that do
87
+ * not exist yet.
88
+ *
89
+ * realpathSync() throws on a path that has not been created, which is the
90
+ * normal case for a Write. So walk up to the nearest ancestor that DOES exist,
91
+ * resolve that, and re-attach the components below it. A symlinked parent
92
+ * directory pointing into ~/.claude/ is therefore still caught even when the
93
+ * file itself is brand new.
94
+ */
95
+ function realpathBestEffort(input) {
96
+ const absolute = path.resolve(input);
97
+ const tail = [];
98
+ let current = absolute;
99
+
100
+ for (let i = 0; i < MAX_WALK; i++) {
101
+ try {
102
+ const real = fs.realpathSync(current);
103
+ return tail.length ? path.join(real, ...[...tail].reverse()) : real;
104
+ } catch {
105
+ // Does not exist yet (or is unreadable) — try its parent.
106
+ }
107
+ const parent = path.dirname(current);
108
+ if (parent === current) break; // hit the filesystem root
109
+ tail.push(path.basename(current));
110
+ current = parent;
111
+ }
112
+
113
+ // Nothing along the chain resolved; the lexical path is the best answer.
114
+ return absolute;
115
+ }
116
+
117
+ // `~` is not expanded by the shell when it arrives inside a JSON tool_input, so
118
+ // a literal "~/.claude/settings.json" reaches this hook unexpanded.
119
+ function expandHome(input, home) {
120
+ const s = String(input);
121
+ if (s === '~') return home;
122
+ if (s.startsWith('~/')) return path.join(home, s.slice(2));
123
+ return s;
124
+ }
125
+
126
+ const HOME = realpathBestEffort(os.homedir());
127
+
128
+ const SETTINGS_FILES = [
129
+ path.join(HOME, '.claude', 'settings.json'),
130
+ path.join(HOME, '.claude', 'settings.local.json'),
131
+ ];
132
+ const HOOKS_DIR = path.join(HOME, '.claude', 'hooks');
133
+
134
+ /** Returns 'settings' | 'hooks' | null. */
135
+ function classify(resolved) {
136
+ if (SETTINGS_FILES.includes(resolved)) return 'settings';
137
+ if (resolved === HOOKS_DIR || resolved.startsWith(HOOKS_DIR + path.sep)) return 'hooks';
138
+ return null;
139
+ }
140
+
141
+ function reasonForSettings(resolved) {
142
+ return (
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.`
152
+ );
153
+ }
154
+
155
+ function reasonForHooks(resolved) {
156
+ return (
157
+ `Blocked: editing \`${resolved}\`. \`~/.claude/hooks/\` holds the installed COPY of ` +
158
+ `the hook scripts, which run on every subsequent tool call. There is no exception to ` +
159
+ `this one, including inside bootstrap-claude itself: the canonical flow is to edit ` +
160
+ `\`lib/hooks/\` in the bootstrap-claude repo and run \`install-global.sh\`, which rsyncs ` +
161
+ `the result here. Editing the installed copy directly means the change is untracked and ` +
162
+ `the next install silently overwrites it.`
163
+ );
164
+ }
165
+
166
+ // MultiEdit carries an array of edits; NotebookEdit names its target
167
+ // `notebook_path` rather than `file_path`. Collect every path a single tool
168
+ // call would touch, so a protected target cannot ride along in a batch.
169
+ function targetsOf(toolName, toolInput) {
170
+ if (!toolInput) return [];
171
+ if (toolName === 'MultiEdit') {
172
+ const edits = Array.isArray(toolInput.edits) ? toolInput.edits : [];
173
+ return edits.map(e => e && e.file_path).filter(Boolean);
174
+ }
175
+ const single = toolInput.file_path || toolInput.notebook_path;
176
+ return single ? [single] : [];
177
+ }
178
+
179
+ const GUARDED_TOOLS = ['Edit', 'Write', 'NotebookEdit', 'MultiEdit'];
180
+
181
+ readHookInput(data => {
182
+ if (!GUARDED_TOOLS.includes(data.tool_name)) return;
183
+
184
+ const targets = targetsOf(data.tool_name, data.tool_input);
185
+ if (!targets.length) return;
186
+
187
+ // Relative paths resolve against the session's directory, not this process's.
188
+ const baseDir = typeof data.cwd === 'string' && data.cwd ? data.cwd : process.cwd();
189
+
190
+ for (const target of targets) {
191
+ const resolved = realpathBestEffort(path.resolve(baseDir, expandHome(target, HOME)));
192
+ const kind = classify(resolved);
193
+ if (!kind) continue;
194
+
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));
199
+ }
200
+ });