@codewizard-dt/bootstrap 2.14.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.
- package/lib/hooks/README.md +592 -12
- package/lib/hooks/absolute-path-guard.js +142 -0
- package/lib/hooks/claude-settings-guard.js +235 -0
- package/lib/hooks/env-content-read-guard.js +367 -0
- package/lib/hooks/git-protected-ops-block.js +12 -7
- package/lib/hooks/interpreter-indirection-guard.js +576 -0
- package/lib/hooks/lib/command-parse.js +63 -0
- package/lib/hooks/package-install-consent.js +151 -0
- package/lib/hooks/protected-write-guard.js +237 -0
- package/lib/scripts/README.md +62 -5
- package/lib/scripts/build-mcp-guide.sh +9 -1
- package/lib/scripts/install-global.sh +25 -2
- package/lib/scripts/install-mcps.sh +140 -36
- package/lib/scripts/lib.sh +10 -6
- package/lib/scripts/merge-gitignore.sh +163 -27
- package/lib/scripts/merge-settings-deny.js +112 -39
- package/lib/scripts/templates/file-suggestion.sh +142 -0
- package/lib/scripts/templates/gitignore +8 -0
- package/lib/scripts/templates/guides/stubs/playwright.md +2 -0
- package/lib/scripts/templates/settings-deny.json +81 -1
- package/lib/skills/debug-logs/SKILL.md +1 -1
- package/lib/skills/git-commit/SKILL.md +8 -0
- package/package.json +5 -2
- package/raw/research/brave-mcp-single-docker-container/index.md +0 -94
- package/raw/research/brave-mcp-single-docker-container/sources.md +0 -70
- package/raw/research/dark-mode-theme/index.md +0 -85
- package/raw/research/dark-mode-theme/sources.md +0 -49
- package/raw/research/mcp-add-scope-writes/index.md +0 -46
- package/raw/research/mcp-add-scope-writes/sources.md +0 -38
- package/raw/research/mcp-one-process-per-user/index.md +0 -75
- package/raw/research/mcp-one-process-per-user/sources.md +0 -66
- package/raw/research/mcp-scope-conflict-handling/index.md +0 -61
- package/raw/research/mcp-scope-conflict-handling/sources.md +0 -32
- package/raw/research/serena-mcp-disconnect/index.md +0 -81
- package/raw/research/serena-mcp-disconnect/sources.md +0 -87
- package/raw/research/wiki-tooling-improvements/index.md +0 -126
- package/raw/research/wiki-tooling-improvements/sources.md +0 -73
- 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
|
+
});
|
package/lib/scripts/README.md
CHANGED
|
@@ -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
|
|
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` |
|
|
29
|
-
| `merge-settings-deny.js` | `install-global.sh` | Zero-dependency Node script that merges the canonical
|
|
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/
|
|
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
|
|
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
|
|
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
|
-
|
|
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)."
|