@codewizard-dt/bootstrap 2.13.0 → 2.15.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 (38) hide show
  1. package/lib/hooks/README.md +592 -12
  2. package/lib/hooks/absolute-path-guard.js +142 -0
  3. package/lib/hooks/claude-settings-guard.js +235 -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 +62 -5
  11. package/lib/scripts/build-mcp-guide.sh +9 -1
  12. package/lib/scripts/install-global.sh +25 -2
  13. package/lib/scripts/install-mcps.sh +140 -36
  14. package/lib/scripts/lib.sh +11 -7
  15. package/lib/scripts/merge-gitignore.sh +242 -33
  16. package/lib/scripts/merge-settings-deny.js +112 -39
  17. package/lib/scripts/templates/file-suggestion.sh +142 -0
  18. package/lib/scripts/templates/gitignore +8 -0
  19. package/lib/scripts/templates/guides/stubs/playwright.md +2 -0
  20. package/lib/scripts/templates/settings-deny.json +81 -1
  21. package/lib/skills/debug-logs/SKILL.md +1 -1
  22. package/lib/skills/git-commit/SKILL.md +8 -0
  23. package/package.json +5 -2
  24. package/raw/research/brave-mcp-single-docker-container/index.md +0 -94
  25. package/raw/research/brave-mcp-single-docker-container/sources.md +0 -70
  26. package/raw/research/dark-mode-theme/index.md +0 -85
  27. package/raw/research/dark-mode-theme/sources.md +0 -49
  28. package/raw/research/mcp-add-scope-writes/index.md +0 -46
  29. package/raw/research/mcp-add-scope-writes/sources.md +0 -38
  30. package/raw/research/mcp-one-process-per-user/index.md +0 -75
  31. package/raw/research/mcp-one-process-per-user/sources.md +0 -66
  32. package/raw/research/mcp-scope-conflict-handling/index.md +0 -61
  33. package/raw/research/mcp-scope-conflict-handling/sources.md +0 -32
  34. package/raw/research/serena-mcp-disconnect/index.md +0 -81
  35. package/raw/research/serena-mcp-disconnect/sources.md +0 -87
  36. package/raw/research/wiki-tooling-improvements/index.md +0 -126
  37. package/raw/research/wiki-tooling-improvements/sources.md +0 -73
  38. 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,235 @@
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 by user decision, because THIS repo legitimately manages those
20
+ // files — that is exactly what install-global.sh and merge-settings-deny.js
21
+ // do — and a blanket deny made the repo unable to work on itself.
22
+ //
23
+ // The removal was forced, not preferred. Deny beats allow at every scope, and
24
+ // a hook returning `allow` cannot loosen a deny rule either, so there is no
25
+ // way to express "blocked everywhere except here" while the deny entry
26
+ // exists. The entry had to come out for the exception to be sayable at all.
27
+ // A hook is the only layer that can carry a conditional.
28
+ //
29
+ // Why ~/.claude/hooks/** is ALSO checked here, and is not redundant:
30
+ //
31
+ // TASK-026's `Edit(~/.claude/hooks/**)` and `Edit(**/.claude/hooks/**)` deny
32
+ // entries remain in place and are the primary control — this hook does not
33
+ // replace them. But file permission checks consult only `Edit(path)` and
34
+ // `Read(path)`; `Write(...)` rules are accepted by the settings parser and
35
+ // then never consulted (raw/research/bypass-mode-enforcement/index.md:108,
36
+ // sourced to code.claude.com/docs/en/permissions). The Write *tool* still
37
+ // works. So `Write(~/.claude/hooks/evil.js)` has no deny coverage whatsoever,
38
+ // and neither does the MultiEdit/NotebookEdit surface. That is the deny list
39
+ // proving insufficient, not this hook duplicating it.
40
+ //
41
+ // The hooks/** block is ABSOLUTE — no bootstrap-claude exception. Even in
42
+ // this repo the canonical flow is: edit lib/hooks/, then run
43
+ // install-global.sh, which rsyncs into ~/.claude/hooks/. Editing the
44
+ // installed copy directly is always wrong; the next install silently
45
+ // overwrites it.
46
+ //
47
+ // RESIDUAL RISK, stated plainly:
48
+ //
49
+ // An agent working inside a genuine bootstrap-claude checkout can still
50
+ // self-grant permissions by writing ~/.claude/settings.json. This hook does
51
+ // not prevent that and is not trying to. It is an accepted, deliberate
52
+ // trade-off: managing those settings is this repo's entire purpose, so the
53
+ // exception is the feature. The containment for a compromised agent inside
54
+ // this repo is Tier 3 (/sandbox — OS-level confinement), not this hook.
55
+ // Do not "harden" this by removing the exception; that breaks the repo and
56
+ // still would not contain a Bash-capable agent.
57
+ //
58
+ // Known gaps, deliberate:
59
+ // - Project-level `.claude/settings.json` files are not guarded here; this
60
+ // hook is scoped to the user-global ~/.claude/ tree per its checkbox.
61
+ // - A write is judged by its resolved target only. An agent that first
62
+ // replaces some unguarded path with a symlink and then writes through it is
63
+ // caught (the target resolves into ~/.claude/), but an agent that writes a
64
+ // script elsewhere and executes it is a Bash concern, not this hook's.
65
+
66
+ const fs = require('fs');
67
+ const os = require('os');
68
+ const path = require('path');
69
+ const { readHookInput, deny } = require('./lib/command-parse');
70
+
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
+ // Upper bound on any parent walk. path.dirname() is purely lexical and reaches
78
+ // a fixed point at the filesystem root, so this is belt-and-braces against a
79
+ // pathological input rather than a real loop risk — but a hook must never hang.
80
+ const MAX_WALK = 64;
81
+
82
+ /**
83
+ * Resolve a path all the way to its real location, tolerating targets that do
84
+ * not exist yet.
85
+ *
86
+ * realpathSync() throws on a path that has not been created, which is the
87
+ * normal case for a Write. So walk up to the nearest ancestor that DOES exist,
88
+ * resolve that, and re-attach the components below it. A symlinked parent
89
+ * directory pointing into ~/.claude/ is therefore still caught even when the
90
+ * file itself is brand new.
91
+ */
92
+ function realpathBestEffort(input) {
93
+ const absolute = path.resolve(input);
94
+ const tail = [];
95
+ let current = absolute;
96
+
97
+ for (let i = 0; i < MAX_WALK; i++) {
98
+ try {
99
+ const real = fs.realpathSync(current);
100
+ return tail.length ? path.join(real, ...[...tail].reverse()) : real;
101
+ } catch {
102
+ // Does not exist yet (or is unreadable) — try its parent.
103
+ }
104
+ const parent = path.dirname(current);
105
+ if (parent === current) break; // hit the filesystem root
106
+ tail.push(path.basename(current));
107
+ current = parent;
108
+ }
109
+
110
+ // Nothing along the chain resolved; the lexical path is the best answer.
111
+ return absolute;
112
+ }
113
+
114
+ // `~` is not expanded by the shell when it arrives inside a JSON tool_input, so
115
+ // a literal "~/.claude/settings.json" reaches this hook unexpanded.
116
+ function expandHome(input, home) {
117
+ const s = String(input);
118
+ if (s === '~') return home;
119
+ if (s.startsWith('~/')) return path.join(home, s.slice(2));
120
+ return s;
121
+ }
122
+
123
+ const HOME = realpathBestEffort(os.homedir());
124
+
125
+ const SETTINGS_FILES = [
126
+ path.join(HOME, '.claude', 'settings.json'),
127
+ path.join(HOME, '.claude', 'settings.local.json'),
128
+ ];
129
+ const HOOKS_DIR = path.join(HOME, '.claude', 'hooks');
130
+
131
+ /** Returns 'settings' | 'hooks' | null. */
132
+ function classify(resolved) {
133
+ if (SETTINGS_FILES.includes(resolved)) return 'settings';
134
+ if (resolved === HOOKS_DIR || resolved.startsWith(HOOKS_DIR + path.sep)) return 'hooks';
135
+ return null;
136
+ }
137
+
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
+ function reasonForSettings(resolved) {
171
+ return (
172
+ `Blocked: editing \`${resolved}\` outside a bootstrap-claude checkout. ` +
173
+ `This file decides what every agent session is permitted to do, so a write to it ` +
174
+ `is a change to your own permission boundary rather than a change to a project. ` +
175
+ `The one exception is the repo that exists to manage it: inside a genuine ` +
176
+ `bootstrap-claude checkout (identified by \`${MARKER_FILE}\` plus a package.json ` +
177
+ `named \`${MARKER_PACKAGE_NAME}\`, not by directory name) this edit is allowed. ` +
178
+ `To change the permission rules, edit \`lib/scripts/templates/settings-deny.json\` ` +
179
+ `in the bootstrap-claude repo and re-run \`install-global.sh\`, which merges it in — ` +
180
+ `that way the change is reviewable in git instead of being a local mutation nobody sees.`
181
+ );
182
+ }
183
+
184
+ function reasonForHooks(resolved) {
185
+ return (
186
+ `Blocked: editing \`${resolved}\`. \`~/.claude/hooks/\` holds the installed COPY of ` +
187
+ `the hook scripts, which run on every subsequent tool call. There is no exception to ` +
188
+ `this one, including inside bootstrap-claude itself: the canonical flow is to edit ` +
189
+ `\`lib/hooks/\` in the bootstrap-claude repo and run \`install-global.sh\`, which rsyncs ` +
190
+ `the result here. Editing the installed copy directly means the change is untracked and ` +
191
+ `the next install silently overwrites it.`
192
+ );
193
+ }
194
+
195
+ // MultiEdit carries an array of edits; NotebookEdit names its target
196
+ // `notebook_path` rather than `file_path`. Collect every path a single tool
197
+ // call would touch, so a protected target cannot ride along in a batch.
198
+ function targetsOf(toolName, toolInput) {
199
+ if (!toolInput) return [];
200
+ if (toolName === 'MultiEdit') {
201
+ const edits = Array.isArray(toolInput.edits) ? toolInput.edits : [];
202
+ return edits.map(e => e && e.file_path).filter(Boolean);
203
+ }
204
+ const single = toolInput.file_path || toolInput.notebook_path;
205
+ return single ? [single] : [];
206
+ }
207
+
208
+ const GUARDED_TOOLS = ['Edit', 'Write', 'NotebookEdit', 'MultiEdit'];
209
+
210
+ readHookInput(data => {
211
+ if (!GUARDED_TOOLS.includes(data.tool_name)) return;
212
+
213
+ const targets = targetsOf(data.tool_name, data.tool_input);
214
+ if (!targets.length) return;
215
+
216
+ // Relative paths resolve against the session's directory, not this process's.
217
+ const baseDir = typeof data.cwd === 'string' && data.cwd ? data.cwd : process.cwd();
218
+
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
+ for (const target of targets) {
224
+ const resolved = realpathBestEffort(path.resolve(baseDir, expandHome(target, HOME)));
225
+ const kind = classify(resolved);
226
+ if (!kind) continue;
227
+
228
+ if (kind === 'hooks') deny(reasonForHooks(resolved));
229
+
230
+ if (bootstrapRoot === undefined) bootstrapRoot = findBootstrapRoot(baseDir);
231
+ if (bootstrapRoot) continue; // the deliberate carve-out — see RESIDUAL RISK above
232
+
233
+ deny(reasonForSettings(resolved));
234
+ }
235
+ });