@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,367 @@
1
+ #!/usr/bin/env node
2
+ 'use strict';
3
+
4
+ // env-content-read-guard.js — PreToolUse hook
5
+ // (matcher: Bash|mcp__serena__.*|mcp__plugin_[^_]+_serena__.*)
6
+ //
7
+ // Stops the CONTENTS of a .env file from reaching the transcript, on the two
8
+ // surfaces that can emit them: a Bash command, and a Serena tool call.
9
+ //
10
+ // This closes a hole that was live in the repo, not a hypothetical one:
11
+ // `cat .env` printed secrets into the conversation. Three controls each
12
+ // assumed one of the others covered it —
13
+ //
14
+ // - `Read(**/.env)` in settings-deny.json is a FILE-TOOL rule. A Bash
15
+ // command never reaches the Read matcher, so it never applies.
16
+ // - env-file-guard.js matches only Read/Write/Edit/MultiEdit — never Bash,
17
+ // never an MCP tool.
18
+ // - serena-bash-grep-block.js intercepts cat/head/tail/less/more/bat, but
19
+ // only when the target is `.md` (:258) or a code extension (:264).
20
+ // `.env` is neither, so the interception never fires. Its grep phase goes
21
+ // further and explicitly ALLOWS `.env` targets (:126, :160, :189) as a
22
+ // "non-code extension" — correct for Serena-first navigation, wrong for
23
+ // secrets.
24
+ //
25
+ // Why a hook and not a deny entry: a deny rule matches the literal spelling of
26
+ // a command. `Bash(cat .env)` would block exactly that string and none of
27
+ // `head -n 5 .env`, `strings .env`, `grep KEY .env`, `xxd .env`, `cat < .env`,
28
+ // or `cp .env /tmp/x`. The class is only closable by parsing the command.
29
+ //
30
+ // ---------------------------------------------------------------------------
31
+ // `source .env` AND `. .env` REMAIN PERMITTED. THIS IS DELIBERATE.
32
+ //
33
+ // Do not "close this gap" later — it is not a gap. CLAUDE.md grants it
34
+ // ("You are, however, allowed to source an .env file to use the variables in
35
+ // the command line") and env-file-guard.js:39 says so in its own deny message.
36
+ //
37
+ // The reasoning, so it does not have to be rediscovered: sourcing loads values
38
+ // into the shell's environment and prints NOTHING. Nothing enters the
39
+ // transcript. The leak is sourcing PLUS emission (`source .env && echo $KEY`) —
40
+ // and the emission half can be written without `source` at all. So blocking
41
+ // `source` would block the safe case while missing the unsafe one. This hook
42
+ // therefore governs DISPLAY and DUPLICATION, not USE.
43
+ //
44
+ // That distinction is what every deny message here has to communicate: the
45
+ // values may be used, they may not be shown.
46
+ // ---------------------------------------------------------------------------
47
+ //
48
+ // Placement: both surfaces live in this one file rather than the Serena half
49
+ // being folded into serena-bash-grep-block.js. Two reasons, in order of weight:
50
+ //
51
+ // 1. serena-bash-grep-block.js does not, in fact, inspect Serena tool calls —
52
+ // it exits on `tool_name !== 'Bash'` (:28) and is wired under the `Bash`
53
+ // matcher. It SUGGESTS Serena calls; it never receives one. Putting the
54
+ // Serena rule there would mean broadening its matcher and giving a
55
+ // Serena-first NAVIGATION hook a second, orthogonal concern (secrets).
56
+ // 2. Keeping both surfaces here means `isBlockedEnvFile` and the
57
+ // `.env.example` exception exist ONCE for this concern, so the Bash side
58
+ // and the Serena side cannot drift apart. Two `.env` controls that
59
+ // disagree about what `.env` means is a bug waiting to happen.
60
+ //
61
+ // Known gaps, deliberate — each would cost more than it closes:
62
+ // - A Serena `search_for_pattern` with no `relative_path` scans the project
63
+ // and could match .env lines. Denying every unscoped search would make the
64
+ // tool unusable, and Serena's project scan honours gitignore, where `.env`
65
+ // and `.env.*` (with `!.env.example`) always sit — both in this repo and in
66
+ // the gitignore this repo ships (lib/scripts/templates/gitignore:23-25).
67
+ // Same for a `relative_path` naming a DIRECTORY that contains a .env.
68
+ // - `find . -name .env -exec cat {} +` and `xargs cat .env` put the reader
69
+ // somewhere other than the front of a segment; the verb check looks at the
70
+ // first token only (see below).
71
+ // - `git show HEAD:.env` and `docker exec … cat .env` reach the contents
72
+ // through a tool this hook does not model.
73
+ // - A segment that merely QUOTES a blocked form (`grep -rn "cat .env" docs/`)
74
+ // fires. Accepted for the same reason as protected-write-guard.js:50 —
75
+ // narrowing it means inspecting quoting well enough to reimplement the
76
+ // shell, and the cost of over-firing is one rephrase.
77
+
78
+ const path = require('path');
79
+ const { readHookInput, splitSegments, tokenize, deny } = require('./lib/command-parse');
80
+
81
+ // KEPT BYTE-IDENTICAL WITH env-file-guard.js:6-13. If the allow-list changes,
82
+ // change it in both places or in neither — two .env controls that disagree
83
+ // about which files are secret is worse than one control. It also matches the
84
+ // gitignore this repo ships (`.env`, `.env.*`, `!.env.example`), so "secret" is
85
+ // defined the same way by the guard and by the thing that keeps it out of git.
86
+ function isBlockedEnvFile(filePath) {
87
+ if (!filePath) return false;
88
+ const basename = path.basename(String(filePath));
89
+ // Block .env exactly, and .env.* variants (e.g. .env.local, .env.production)
90
+ // Allow .env.example — the one permitted exception
91
+ return basename === '.env' ||
92
+ (basename.startsWith('.env.') && basename !== '.env.example');
93
+ }
94
+
95
+ // Commands whose ordinary purpose is to put file contents on stdout. The list
96
+ // is wider than the "cat/head/tail" trio the task named, because the narrow
97
+ // list would have been theatre: `strings .env`, `xxd .env`, `cut -d= -f2 .env`
98
+ // and `grep KEY .env` all print the same secrets with the same ease.
99
+ //
100
+ // grep-family is included even though serena-bash-grep-block.js allows `.env`
101
+ // targets. That allowance is right for its purpose (Serena-first navigation
102
+ // does not care about non-code files) and wrong for this one — a grep against
103
+ // .env prints the matching lines, which for a credentials file IS the payload.
104
+ const READERS = new Set([
105
+ // whole-file dumpers
106
+ 'cat', 'tac', 'nl', 'head', 'tail', 'less', 'more', 'most', 'bat',
107
+ 'od', 'xxd', 'hexdump', 'strings', 'rev',
108
+ // searchers — they print the matched lines
109
+ 'grep', 'egrep', 'fgrep', 'rg', 'ag', 'ack',
110
+ // stream processors used as readers
111
+ 'sed', 'awk', 'gawk', 'cut', 'sort', 'uniq', 'paste', 'column',
112
+ ]);
113
+
114
+ // Duplicating a .env moves live credentials to a path none of the .env rules
115
+ // watch, so the copy is readable by everything afterwards. Beyond the `cp` the
116
+ // task named, the same one-line operation spelled with a different tool.
117
+ const COPIERS = new Set(['cp', 'scp', 'rsync', 'ditto', 'install']);
118
+
119
+ // Prefixes that push the real command off the front of a segment. `sudo` IS
120
+ // treated as a wrapper here, unlike in absolute-path-guard.js — there it is a
121
+ // guarded name in its own right, here it is just noise in front of `cat`.
122
+ const WRAPPERS = new Set(['env', 'command', 'exec', 'nohup', 'time', 'sudo']);
123
+
124
+ const ENV_ASSIGNMENT = /^[A-Za-z_][A-Za-z0-9_]*=/;
125
+
126
+ // An output redirect with an optional fd prefix. `(?![&>])` keeps `2>&1` from
127
+ // being read as a redirect to a file named `&1`.
128
+ const OUT_REDIRECT = /^(?:&|\d+)?>>?(?![&>])/;
129
+
130
+ function stripQuotes(token) {
131
+ return String(token).replace(/^["']+/, '').replace(/["']+$/, '');
132
+ }
133
+
134
+ function basename(token) {
135
+ const cleaned = String(token).replace(/^\\+/, '');
136
+ return cleaned.slice(cleaned.lastIndexOf('/') + 1);
137
+ }
138
+
139
+ /**
140
+ * The tokens of a segment that act as INPUT paths: flags dropped, and — the
141
+ * part that matters — output-redirect DESTINATIONS dropped while input-redirect
142
+ * SOURCES are kept.
143
+ *
144
+ * Direction is the whole point. `cat .env.example > .env` writes a scaffold
145
+ * file and is legitimate; `cat .env > /tmp/x` exfiltrates one. The only thing
146
+ * separating them is which side of the operator the non-example path sits on.
147
+ */
148
+ function inputPaths(tokens) {
149
+ const found = [];
150
+ for (let i = 0; i < tokens.length; i++) {
151
+ let t = stripQuotes(tokens[i]);
152
+ if (!t) continue;
153
+
154
+ const out = OUT_REDIRECT.exec(t);
155
+ if (out) {
156
+ // `> file` puts the destination in the next token; `>file` carries it
157
+ // inline. Either way it is a destination, not something being read.
158
+ if (t.length === out[0].length) i++;
159
+ continue;
160
+ }
161
+
162
+ let viaRedirect = false;
163
+ if (t.startsWith('<')) {
164
+ viaRedirect = true;
165
+ t = t.slice(1) || stripQuotes(tokens[++i] ?? '');
166
+ }
167
+
168
+ if (!t || t.startsWith('-')) continue;
169
+ found.push({ path: t, viaRedirect, index: i });
170
+ }
171
+ return found;
172
+ }
173
+
174
+ /** Walk past wrapper and env-assignment tokens to the command actually run. */
175
+ function resolveCommandToken(tokens) {
176
+ let i = 0;
177
+ while (i < tokens.length) {
178
+ const t = tokens[i];
179
+ if (ENV_ASSIGNMENT.test(t) || WRAPPERS.has(basename(t))) i++;
180
+ else break;
181
+ }
182
+ return { token: tokens[i] ?? null, index: i };
183
+ }
184
+
185
+ // Every deny message ends with this, because a block that does not say what to
186
+ // do instead just gets worked around.
187
+ const ALTERNATIVE =
188
+ 'You can USE these values without seeing them: `source .env` in the same Bash command ' +
189
+ '(`source .env && ./script.sh`) loads them into the environment and prints nothing. ' +
190
+ 'Sourcing a .env file is explicitly permitted; displaying its contents is not. ' +
191
+ 'If you only need to know which keys exist, read `.env.example` — that one is allowed.';
192
+
193
+ const WHY_SECRET =
194
+ 'A .env file holds live credentials. Once they are printed they are in the conversation ' +
195
+ 'history, in anything that logs it, and in every context window that follows — there is ' +
196
+ 'no way to un-print them.';
197
+
198
+ /**
199
+ * One pass of the verb rules over a command scope (a segment, or the whole
200
+ * command — see the call site for why both).
201
+ */
202
+ function checkScope(scope, displayCmd) {
203
+ const tokens = tokenize(scope);
204
+ if (tokens.length === 0) return;
205
+
206
+ const inputs = inputPaths(tokens);
207
+ const blocked = inputs.filter(p => isBlockedEnvFile(p.path));
208
+ if (blocked.length === 0) return; // no .env is being read here — nothing to judge
209
+
210
+ // Rule 1: an input redirect. The verb is irrelevant — `< .env` hands the
211
+ // file's contents to whatever runs, and the two commands that would normally
212
+ // want that (`source`, `.`) do not use a redirect to get it.
213
+ const redirected = blocked.find(p => p.viaRedirect);
214
+ if (redirected) {
215
+ deny(
216
+ `Blocked: \`${displayCmd}\` feeds \`${redirected.path}\` into a command on stdin. ` +
217
+ `${WHY_SECRET} ` +
218
+ `An input redirect is not a recognised file-read, so neither the \`Read(**/.env)\` deny ` +
219
+ `entry nor env-file-guard.js sees it. ` +
220
+ `${ALTERNATIVE}`
221
+ );
222
+ }
223
+
224
+ const { token: verbToken, index: verbIndex } = resolveCommandToken(tokens);
225
+ if (!verbToken) return;
226
+ const verb = basename(verbToken);
227
+
228
+ // Rule 2: a content-emitting reader pointed at a .env.
229
+ if (READERS.has(verb)) {
230
+ deny(
231
+ `Blocked: \`${displayCmd}\` would print the contents of \`${blocked[0].path}\` into the ` +
232
+ `transcript. ${WHY_SECRET} ` +
233
+ `Nothing else stops this: \`Read(**/.env)\` is a file-tool permission rule that a Bash ` +
234
+ `command never reaches, and env-file-guard.js matches only Read/Write/Edit/MultiEdit. ` +
235
+ `${ALTERNATIVE}`
236
+ );
237
+ }
238
+
239
+ // Rule 3: a copy whose SOURCE is a .env. The last operand is the
240
+ // destination, so `cp .env.example .env` — ordinary scaffolding — falls
241
+ // through untouched, while `cp .env /tmp/x` does not.
242
+ if (COPIERS.has(verb)) {
243
+ const operands = inputs.filter(p => p.index > verbIndex);
244
+ const sources = operands.slice(0, -1);
245
+ const leaked = sources.find(p => isBlockedEnvFile(p.path));
246
+ if (leaked) {
247
+ deny(
248
+ `Blocked: \`${displayCmd}\` copies \`${leaked.path}\` somewhere else. That is a leak by ` +
249
+ `duplication rather than by display: the copy lands at a path none of the .env rules ` +
250
+ `watch, and everything downstream can read it freely. ${WHY_SECRET} ` +
251
+ `Copying .env.example INTO place (\`cp .env.example .env\`) is unaffected — only a .env ` +
252
+ `used as the SOURCE is blocked. ` +
253
+ `${ALTERNATIVE}`
254
+ );
255
+ }
256
+ }
257
+ }
258
+
259
+ function checkBash(data) {
260
+ const fullCmd = String(data.tool_input?.command ?? '').trim();
261
+ if (!fullCmd) return;
262
+
263
+ // Each `;`/`&&`/`||`/`|` segment gets its own turn, so a reader hidden after
264
+ // a separator is still judged as a first token — the same reasoning as
265
+ // absolute-path-guard.js:118.
266
+ for (const segment of splitSegments(fullCmd)) checkScope(segment, segment);
267
+
268
+ // …and then, in one narrow case, the whole command as a single scope.
269
+ // splitSegments splits on `|` without regard for quoting, so
270
+ // `grep "KEY|TOKEN" .env` is torn into `grep "KEY` and `TOKEN" .env` — and the
271
+ // second piece's first token is not a reader, so the per-segment pass misses
272
+ // it entirely. Re-running over the full string puts `grep` back in front of
273
+ // `.env`.
274
+ //
275
+ // Gated on the command containing BOTH a quote and a pipe, which is exactly
276
+ // the condition under which a segment can have been torn mid-token. Without
277
+ // the gate this pass would fire on `cat a.txt | grep x && echo .env`, where
278
+ // the `.env` belongs to a segment that never reads it.
279
+ if (/["']/.test(fullCmd) && fullCmd.includes('|')) checkScope(fullCmd, fullCmd);
280
+ }
281
+
282
+ // ── Serena surface ─────────────────────────────────────────────────────────
283
+ //
284
+ // Closing only Bash would move the leak rather than seal it. serena-bash-grep-
285
+ // block.js actively redirects Bash greps toward Serena, and Serena's
286
+ // search_for_pattern returns the matched lines — so the blocked `grep KEY .env`
287
+ // has an approved-looking replacement that prints exactly the same secrets.
288
+
289
+ /** Strip the mcp__serena__ / mcp__plugin_<x>_serena__ prefix from a tool name. */
290
+ function bareSerenaTool(toolName) {
291
+ const m = /^mcp__(?:plugin_[^_]+_)?serena__(.+)$/.exec(String(toolName));
292
+ return m ? m[1] : '';
293
+ }
294
+
295
+ // Serena tools that return FILE CONTENTS. `find_file` and `list_dir` return
296
+ // paths and names only — knowing that a .env exists is not a leak, so they are
297
+ // deliberately absent.
298
+ const SERENA_READERS = new Set([
299
+ 'read_file',
300
+ 'search_for_pattern',
301
+ 'find_symbol', // include_body=true returns bodies
302
+ 'find_referencing_symbols', // returns the code around each reference
303
+ 'get_symbols_overview',
304
+ ]);
305
+
306
+ // Serena tools that MUTATE a file. Not a leak, but env-file-guard.js's own
307
+ // message says a .env "cannot be read or written", and these tools reach the
308
+ // file without passing any control that enforces the second half. Included for
309
+ // parity: the .env write ban should not depend on which tool is holding the pen.
310
+ const SERENA_WRITERS = new Set([
311
+ 'create_text_file',
312
+ 'replace_content',
313
+ 'replace_in_files',
314
+ 'replace_lines',
315
+ 'delete_lines',
316
+ 'insert_at_line',
317
+ ]);
318
+
319
+ // Serena addresses files by `relative_path` throughout; the others are accepted
320
+ // defensively so a renamed or plugin-wrapped parameter cannot slip past.
321
+ // `paths_include_glob` is checked because scoping a search with `**/.env` is
322
+ // just another way of naming the target.
323
+ const SERENA_PATH_KEYS = ['relative_path', 'file_path', 'path', 'paths_include_glob'];
324
+
325
+ function checkSerena(tool, input) {
326
+ const reading = SERENA_READERS.has(tool);
327
+ const writing = SERENA_WRITERS.has(tool);
328
+ if (!reading && !writing) return;
329
+
330
+ const target = SERENA_PATH_KEYS
331
+ .map(key => input?.[key])
332
+ .find(value => typeof value === 'string' && isBlockedEnvFile(value));
333
+ if (!target) return;
334
+
335
+ if (reading) {
336
+ deny(
337
+ `Blocked: this Serena call targets \`${target}\`, and \`${tool}\` returns file contents. ` +
338
+ `${WHY_SECRET} ` +
339
+ `Blocking \`cat .env\` on the Bash side while leaving this open would only move the leak: ` +
340
+ `serena-bash-grep-block.js redirects Bash greps to Serena, so search_for_pattern is the ` +
341
+ `first thing reached for after a Bash block. ` +
342
+ `${ALTERNATIVE}`
343
+ );
344
+ }
345
+
346
+ deny(
347
+ `Blocked: this Serena call would modify \`${target}\`. A .env file can be neither read nor ` +
348
+ `written by an agent — env-file-guard.js enforces that for Read/Write/Edit/MultiEdit, and ` +
349
+ `Serena's editing tools reach the same file without passing through it. ` +
350
+ `Edit the file yourself if its contents need to change. ` +
351
+ `${ALTERNATIVE}`
352
+ );
353
+ }
354
+
355
+ readHookInput(data => {
356
+ // A hook that throws exits non-zero and reads as a hook failure, so an
357
+ // unexpected payload shape must degrade to "allow", never to a crash.
358
+ try {
359
+ const tool = String(data?.tool_name ?? '');
360
+ if (tool === 'Bash') return checkBash(data);
361
+
362
+ const serenaTool = bareSerenaTool(tool);
363
+ if (serenaTool) return checkSerena(serenaTool, data?.tool_input);
364
+ } catch {
365
+ /* malformed input — fall through to allow */
366
+ }
367
+ });
@@ -6,11 +6,15 @@
6
6
  // Hard-blocks `git stash`, `git restore`, and `git checkout` (and their
7
7
  // subcommands, e.g. `git stash pop`) in ANY segment of a Bash command.
8
8
  //
9
- // Why a hook and not a deny rule: the permissions allow/deny engine is
10
- // short-circuited under bypassPermissions mode (power-mode teammates,
11
- // --dangerously-skip-permissions). PreToolUse hooks fire regardless of
12
- // permission mode and for subagent tool calls, so this is the only
13
- // enforcement point that reliably stops these commands everywhere.
9
+ // Why a hook and not a deny rule: deny rules ARE enforced in every permission
10
+ // mode — bypassPermissions included (power-mode teammates,
11
+ // --dangerously-skip-permissions) — and for subagent tool calls as well as
12
+ // main-session ones. What they cannot do is see past a literal spelling:
13
+ // `Bash(git stash:*)` matches `git stash` and misses `git -C /repo stash`,
14
+ // `npm test && git stash`, and `git log | git stash`. This hook receives the
15
+ // raw, undecomposed command string and parses inside it, so every one of those
16
+ // forms is caught — and it can return an explanatory message, which a deny rule
17
+ // cannot.
14
18
  //
15
19
  // Matching is done in JS (not via the hook `if:` filter) so it never depends
16
20
  // on the same matcher path that lets compound/piped commands slip through.
@@ -65,8 +69,9 @@ process.stdin.on('end', () => {
65
69
  permissionDecision: 'deny',
66
70
  permissionDecisionReason:
67
71
  `Blocked: \`git ${subcommand}\` is disabled in this environment because it can ` +
68
- `silently discard or hide uncommitted work. This block is enforced even under ` +
69
- `bypassed permissions. If you need to set work aside, ask the user.`,
72
+ `silently discard or hide uncommitted work. Rewriting the command will not get ` +
73
+ `around it — the chained, piped, and \`git -C <path>\` forms are all matched here. ` +
74
+ `If you need to set work aside, ask the user.`,
70
75
  },
71
76
  }));
72
77
  process.exit(0);