@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
|
@@ -1,6 +1,7 @@
|
|
|
1
1
|
#!/usr/bin/env node
|
|
2
|
-
// Merge the canonical
|
|
3
|
-
// user's ~/.claude/settings.json permissions.deny array.
|
|
2
|
+
// Merge the canonical permission deny list (templates/settings-deny.json) into
|
|
3
|
+
// the user's ~/.claude/settings.json permissions.deny array. Entries cover both
|
|
4
|
+
// Bash command patterns and file-tool path patterns (Edit(...) / Read(...)).
|
|
4
5
|
//
|
|
5
6
|
// Additive union only: canonical entries missing from the user's list are
|
|
6
7
|
// appended; user entries are never removed, reordered, or deduplicated, and
|
|
@@ -12,7 +13,14 @@
|
|
|
12
13
|
// leaving the target file untouched.
|
|
13
14
|
//
|
|
14
15
|
// Usage: merge-settings-deny.js [--target <path>] [--source <path>]
|
|
16
|
+
// merge-settings-deny.js --set-key <name> --set-value <json> [--target <path>]
|
|
15
17
|
// --target/--source exist as test seams; the install flow passes no args.
|
|
18
|
+
//
|
|
19
|
+
// --set-key/--set-value is a separate operation: it sets one top-level settings
|
|
20
|
+
// key when that key is absent, no-ops when it is already deep-equal, and warns
|
|
21
|
+
// and leaves the file alone when it holds a different value. The deny merge does
|
|
22
|
+
// not run in this mode. A malformed --set-value is a usage error and exits
|
|
23
|
+
// non-zero; a malformed target still fails safe with exit 0.
|
|
16
24
|
|
|
17
25
|
'use strict';
|
|
18
26
|
|
|
@@ -24,16 +32,20 @@ function parseArgs(argv) {
|
|
|
24
32
|
const opts = {
|
|
25
33
|
target: path.join(os.homedir(), '.claude', 'settings.json'),
|
|
26
34
|
source: path.join(__dirname, 'templates', 'settings-deny.json'),
|
|
35
|
+
setKey: null,
|
|
36
|
+
setValue: null,
|
|
27
37
|
};
|
|
28
38
|
for (let i = 0; i < argv.length; i++) {
|
|
29
39
|
if (argv[i] === '--target' && argv[i + 1]) opts.target = argv[++i];
|
|
30
40
|
else if (argv[i] === '--source' && argv[i + 1]) opts.source = argv[++i];
|
|
41
|
+
else if (argv[i] === '--set-key' && argv[i + 1]) opts.setKey = argv[++i];
|
|
42
|
+
else if (argv[i] === '--set-value' && argv[i + 1]) opts.setValue = argv[++i];
|
|
31
43
|
}
|
|
32
44
|
return opts;
|
|
33
45
|
}
|
|
34
46
|
|
|
35
47
|
function warnSkip(message) {
|
|
36
|
-
console.error(`Warning: ${message} — skipping
|
|
48
|
+
console.error(`Warning: ${message} — skipping ${operation}`);
|
|
37
49
|
process.exit(0);
|
|
38
50
|
}
|
|
39
51
|
|
|
@@ -41,39 +53,117 @@ function isPlainObject(value) {
|
|
|
41
53
|
return typeof value === 'object' && value !== null && !Array.isArray(value);
|
|
42
54
|
}
|
|
43
55
|
|
|
44
|
-
|
|
56
|
+
// Structural comparison, not JSON.stringify equality: differing key order in an
|
|
57
|
+
// equivalent object must still count as a no-op, not a clobber warning.
|
|
58
|
+
function deepEqual(a, b) {
|
|
59
|
+
if (a === b) return true;
|
|
60
|
+
if (a === null || b === null || typeof a !== 'object' || typeof b !== 'object') return false;
|
|
61
|
+
if (Array.isArray(a) !== Array.isArray(b)) return false;
|
|
62
|
+
if (Array.isArray(a)) {
|
|
63
|
+
return a.length === b.length && a.every((v, i) => deepEqual(v, b[i]));
|
|
64
|
+
}
|
|
65
|
+
const keys = Object.keys(a);
|
|
66
|
+
if (keys.length !== Object.keys(b).length) return false;
|
|
67
|
+
return keys.every((k) => Object.prototype.hasOwnProperty.call(b, k) && deepEqual(a[k], b[k]));
|
|
68
|
+
}
|
|
45
69
|
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
70
|
+
function readTarget(file) {
|
|
71
|
+
if (!fs.existsSync(file)) return null;
|
|
72
|
+
try {
|
|
73
|
+
return fs.readFileSync(file, 'utf8');
|
|
74
|
+
} catch (err) {
|
|
75
|
+
warnSkip(`could not read ${file}`);
|
|
76
|
+
}
|
|
51
77
|
}
|
|
52
|
-
|
|
53
|
-
|
|
78
|
+
|
|
79
|
+
function parseSettings(text, file) {
|
|
80
|
+
if (text === null) return {};
|
|
81
|
+
let parsed;
|
|
82
|
+
try {
|
|
83
|
+
parsed = JSON.parse(text);
|
|
84
|
+
} catch (err) {
|
|
85
|
+
warnSkip(`could not parse ${file} (file untouched)`);
|
|
86
|
+
}
|
|
87
|
+
if (!isPlainObject(parsed)) {
|
|
88
|
+
warnSkip(`${file} is not a JSON object (file untouched)`);
|
|
89
|
+
}
|
|
90
|
+
return parsed;
|
|
54
91
|
}
|
|
55
92
|
|
|
56
|
-
|
|
57
|
-
|
|
93
|
+
// Reuse the file's existing indentation (tabs or N spaces); default 2 spaces.
|
|
94
|
+
function detectIndent(text) {
|
|
95
|
+
if (text === null) return ' ';
|
|
96
|
+
if (text.match(/\n(\t+)"/)) return '\t';
|
|
97
|
+
const spaceMatch = text.match(/\n( +)"/);
|
|
98
|
+
return spaceMatch ? spaceMatch[1] : ' ';
|
|
99
|
+
}
|
|
100
|
+
|
|
101
|
+
function writeSettings(file, value, indent) {
|
|
102
|
+
const tmp = `${file}.tmp-${process.pid}`;
|
|
58
103
|
try {
|
|
59
|
-
|
|
104
|
+
fs.mkdirSync(path.dirname(file), { recursive: true });
|
|
105
|
+
fs.writeFileSync(tmp, JSON.stringify(value, null, indent) + '\n');
|
|
106
|
+
fs.renameSync(tmp, file);
|
|
60
107
|
} catch (err) {
|
|
61
|
-
|
|
108
|
+
try { fs.unlinkSync(tmp); } catch (_) {}
|
|
109
|
+
warnSkip(`could not write ${file} (${err.message})`);
|
|
62
110
|
}
|
|
63
111
|
}
|
|
64
112
|
|
|
65
|
-
|
|
66
|
-
|
|
113
|
+
const { target, source, setKey, setValue } = parseArgs(process.argv.slice(2));
|
|
114
|
+
const operation = setKey === null ? 'deny-list merge' : `"${setKey}" update`;
|
|
115
|
+
|
|
116
|
+
if (setKey !== null || setValue !== null) {
|
|
117
|
+
if (setKey === null) {
|
|
118
|
+
console.error('Error: --set-value requires --set-key <name>');
|
|
119
|
+
process.exit(1);
|
|
120
|
+
}
|
|
121
|
+
if (setValue === null) {
|
|
122
|
+
console.error(`Error: --set-key ${setKey} requires --set-value <json>`);
|
|
123
|
+
process.exit(1);
|
|
124
|
+
}
|
|
125
|
+
|
|
126
|
+
let value;
|
|
67
127
|
try {
|
|
68
|
-
|
|
128
|
+
value = JSON.parse(setValue);
|
|
69
129
|
} catch (err) {
|
|
70
|
-
|
|
130
|
+
console.error(`Error: --set-value is not valid JSON (${err.message})`);
|
|
131
|
+
process.exit(1);
|
|
71
132
|
}
|
|
72
|
-
|
|
73
|
-
|
|
133
|
+
|
|
134
|
+
const rawTarget = readTarget(target);
|
|
135
|
+
const current = parseSettings(rawTarget, target);
|
|
136
|
+
|
|
137
|
+
if (Object.prototype.hasOwnProperty.call(current, setKey)) {
|
|
138
|
+
if (deepEqual(current[setKey], value)) {
|
|
139
|
+
console.log(`settings.json: "${setKey}" already set`);
|
|
140
|
+
} else {
|
|
141
|
+
console.error(
|
|
142
|
+
`Warning: settings.json already defines "${setKey}" — keeping it and skipping ${JSON.stringify(value)}`
|
|
143
|
+
);
|
|
144
|
+
}
|
|
145
|
+
process.exit(0);
|
|
74
146
|
}
|
|
147
|
+
|
|
148
|
+
current[setKey] = value;
|
|
149
|
+
writeSettings(target, current, detectIndent(rawTarget));
|
|
150
|
+
console.log(`settings.json: "${setKey}" set`);
|
|
151
|
+
process.exit(0);
|
|
75
152
|
}
|
|
76
153
|
|
|
154
|
+
let canonical;
|
|
155
|
+
try {
|
|
156
|
+
canonical = JSON.parse(fs.readFileSync(source, 'utf8'));
|
|
157
|
+
} catch (err) {
|
|
158
|
+
warnSkip(`settings-deny template missing or invalid (${source})`);
|
|
159
|
+
}
|
|
160
|
+
if (!Array.isArray(canonical) || !canonical.every((e) => typeof e === 'string')) {
|
|
161
|
+
warnSkip(`settings-deny template is not an array of strings (${source})`);
|
|
162
|
+
}
|
|
163
|
+
|
|
164
|
+
const raw = readTarget(target);
|
|
165
|
+
const settings = parseSettings(raw, target);
|
|
166
|
+
|
|
77
167
|
if ('permissions' in settings && !isPlainObject(settings.permissions)) {
|
|
78
168
|
warnSkip(`${target}: "permissions" is not an object (file untouched)`);
|
|
79
169
|
}
|
|
@@ -98,24 +188,7 @@ if (added === 0 && raw !== null) {
|
|
|
98
188
|
process.exit(0);
|
|
99
189
|
}
|
|
100
190
|
|
|
101
|
-
|
|
102
|
-
let indent = ' ';
|
|
103
|
-
if (raw !== null) {
|
|
104
|
-
const tabMatch = raw.match(/\n(\t+)"/);
|
|
105
|
-
const spaceMatch = raw.match(/\n( +)"/);
|
|
106
|
-
if (tabMatch) indent = '\t';
|
|
107
|
-
else if (spaceMatch) indent = spaceMatch[1];
|
|
108
|
-
}
|
|
109
|
-
|
|
110
|
-
const tmp = `${target}.tmp-${process.pid}`;
|
|
111
|
-
try {
|
|
112
|
-
fs.mkdirSync(path.dirname(target), { recursive: true });
|
|
113
|
-
fs.writeFileSync(tmp, JSON.stringify(settings, null, indent) + '\n');
|
|
114
|
-
fs.renameSync(tmp, target);
|
|
115
|
-
} catch (err) {
|
|
116
|
-
try { fs.unlinkSync(tmp); } catch (_) {}
|
|
117
|
-
warnSkip(`could not write ${target} (${err.message})`);
|
|
118
|
-
}
|
|
191
|
+
writeSettings(target, settings, detectIndent(raw));
|
|
119
192
|
|
|
120
193
|
if (raw === null) {
|
|
121
194
|
console.log(`settings.json: created with ${added} deny entries`);
|
|
@@ -0,0 +1,142 @@
|
|
|
1
|
+
#!/usr/bin/env bash
|
|
2
|
+
# Custom @-autocomplete provider for Claude Code.
|
|
3
|
+
#
|
|
4
|
+
# Installed to ~/.claude/file-suggestion.sh by install-global.sh and registered
|
|
5
|
+
# under the "fileSuggestion" settings key. A custom command replaces the
|
|
6
|
+
# built-in picker entirely, which is the point: the built-in picker honours
|
|
7
|
+
# .git/info/exclude (and recent versions suggest only git-tracked files), so the
|
|
8
|
+
# machine-local excludes written by merge-gitignore.sh blind @-autocomplete on
|
|
9
|
+
# .serena/, raw/, and wiki/. This script re-includes exactly the paths listed
|
|
10
|
+
# under the bootstrap sentinel in .git/info/exclude — a user's other deliberately
|
|
11
|
+
# hidden entries stay hidden, and a project with no sentinel block gets plain
|
|
12
|
+
# `rg --files` behaviour.
|
|
13
|
+
#
|
|
14
|
+
# Contract (community-verified; not fully spelled out in the settings docs):
|
|
15
|
+
# stdin JSON object with a "query" field
|
|
16
|
+
# env CLAUDE_PROJECT_DIR
|
|
17
|
+
# stdout newline-separated project-relative paths (~15 useful)
|
|
18
|
+
# exit ALWAYS 0 — a non-zero exit or stderr chatter degrades the picker
|
|
19
|
+
#
|
|
20
|
+
# No jq/fzf dependency. rg is preferred; git ls-files and find are fallbacks.
|
|
21
|
+
|
|
22
|
+
# Every diagnostic from every tool below is swallowed: the picker consumes
|
|
23
|
+
# stdout only, and stray stderr is visible noise on every keystroke.
|
|
24
|
+
exec 2>/dev/null
|
|
25
|
+
|
|
26
|
+
SENTINEL='# bootstrap wiki & agent state (machine-local)'
|
|
27
|
+
MAX_RESULTS=15
|
|
28
|
+
|
|
29
|
+
# --- query -------------------------------------------------------------------
|
|
30
|
+
# Missing/empty/unparseable stdin degrades to list mode (empty query).
|
|
31
|
+
QUERY=''
|
|
32
|
+
if [ ! -t 0 ]; then
|
|
33
|
+
STDIN_JSON=$(cat)
|
|
34
|
+
QUERY=$(printf '%s' "$STDIN_JSON" | tr '\n' ' ' \
|
|
35
|
+
| sed -n 's/.*"query"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p')
|
|
36
|
+
fi
|
|
37
|
+
|
|
38
|
+
cd "${CLAUDE_PROJECT_DIR:-.}" || exit 0
|
|
39
|
+
|
|
40
|
+
have_rg() { command -v rg >/dev/null 2>&1; }
|
|
41
|
+
|
|
42
|
+
# --- base listing ------------------------------------------------------------
|
|
43
|
+
# rg honours .gitignore and .git/info/exclude, so this is the built-in-equivalent
|
|
44
|
+
# view; the re-include pass below adds back the bootstrap-hidden dirs.
|
|
45
|
+
list_base() {
|
|
46
|
+
if have_rg; then
|
|
47
|
+
rg --files
|
|
48
|
+
return 0
|
|
49
|
+
fi
|
|
50
|
+
|
|
51
|
+
tracked=$(git ls-files --cached --others --exclude-standard) \
|
|
52
|
+
&& [ -n "$tracked" ] \
|
|
53
|
+
&& { printf '%s\n' "$tracked"; return 0; }
|
|
54
|
+
|
|
55
|
+
# Not a git repo (or git absent): walk the tree directly.
|
|
56
|
+
find . -type f -not -path './.git/*' | sed 's|^\./||'
|
|
57
|
+
}
|
|
58
|
+
|
|
59
|
+
# --- sentinel-scoped re-inclusion -------------------------------------------
|
|
60
|
+
# Emit the lines between the bootstrap sentinel comment and the next comment
|
|
61
|
+
# line (or EOF) in .git/info/exclude — expected values are .serena/, raw/, wiki/.
|
|
62
|
+
sentinel_entries() {
|
|
63
|
+
[ -f .git/info/exclude ] || return 0
|
|
64
|
+
awk -v sentinel="$SENTINEL" '
|
|
65
|
+
$0 == sentinel { in_block = 1; next }
|
|
66
|
+
in_block && /^[[:space:]]*#/ { in_block = 0 }
|
|
67
|
+
in_block { print }
|
|
68
|
+
' .git/info/exclude
|
|
69
|
+
}
|
|
70
|
+
|
|
71
|
+
list_reincluded() {
|
|
72
|
+
sentinel_entries | while IFS= read -r entry; do
|
|
73
|
+
dir=${entry%/}
|
|
74
|
+
# Only re-include relative in-tree directories that actually exist here;
|
|
75
|
+
# a sentinel path may name a dir this project does not have.
|
|
76
|
+
case "$dir" in
|
|
77
|
+
'' | /* | *..*) continue ;;
|
|
78
|
+
esac
|
|
79
|
+
[ -d "$dir" ] || continue
|
|
80
|
+
|
|
81
|
+
if have_rg; then
|
|
82
|
+
rg --files --no-ignore "$dir"
|
|
83
|
+
else
|
|
84
|
+
find "$dir" -type f | sed 's|^\./||'
|
|
85
|
+
fi
|
|
86
|
+
done
|
|
87
|
+
}
|
|
88
|
+
|
|
89
|
+
# --- matching ----------------------------------------------------------------
|
|
90
|
+
# Subsequence ("fuzzy") matching, because replacing the built-in picker replaces
|
|
91
|
+
# its matcher too, and a plain substring match is strictly worse than what it
|
|
92
|
+
# displaced: `@wikitasks` and `@wiki/tasks` both find nothing under -F, since
|
|
93
|
+
# neither appears contiguously in `wiki/work/tasks/...`. The query's characters
|
|
94
|
+
# must appear in order, not adjacently.
|
|
95
|
+
#
|
|
96
|
+
# Build an ERE with `.*` between each character. Escaping is per-character and
|
|
97
|
+
# happens *while* building, never as a separate pass — escaping first and then
|
|
98
|
+
# interleaving would split a backslash from the character it escapes.
|
|
99
|
+
fuzzy_pattern() {
|
|
100
|
+
local q=$1 out='' i c
|
|
101
|
+
for (( i = 0; i < ${#q}; i++ )); do
|
|
102
|
+
c=${q:i:1}
|
|
103
|
+
case $c in
|
|
104
|
+
# ERE metacharacters, plus backslash. Anything else is literal.
|
|
105
|
+
'.'|'['|']'|'('|')'|'{'|'}'|'*'|'+'|'?'|'|'|'^'|'$'|'\') out="$out\\$c" ;;
|
|
106
|
+
*) out="$out$c" ;;
|
|
107
|
+
esac
|
|
108
|
+
out="$out.*"
|
|
109
|
+
done
|
|
110
|
+
printf '%s' "$out"
|
|
111
|
+
}
|
|
112
|
+
|
|
113
|
+
# Contiguous matches rank above merely-subsequence ones: `@tasks` should surface
|
|
114
|
+
# `wiki/work/tasks/` before a path that happens to contain t…a…s…k…s scattered.
|
|
115
|
+
# Both passes read the same candidate list from a temp file rather than running
|
|
116
|
+
# the (expensive) listing twice.
|
|
117
|
+
rank() {
|
|
118
|
+
local candidates=$1 pattern
|
|
119
|
+
if [ -z "$QUERY" ]; then
|
|
120
|
+
cat -- "$candidates"
|
|
121
|
+
return 0
|
|
122
|
+
fi
|
|
123
|
+
pattern=$(fuzzy_pattern "$QUERY")
|
|
124
|
+
grep -iF -- "$QUERY" "$candidates"
|
|
125
|
+
# Subsequence hits that are not already contiguous hits.
|
|
126
|
+
grep -iE -- "$pattern" "$candidates" | grep -ivF -- "$QUERY"
|
|
127
|
+
}
|
|
128
|
+
|
|
129
|
+
# --- emit --------------------------------------------------------------------
|
|
130
|
+
# `head` truncating the pipe SIGPIPEs the upstream stages; the pipeline's status
|
|
131
|
+
# is head's (pipefail is deliberately not set) and their stderr is already gone.
|
|
132
|
+
CANDIDATES=$(mktemp -t file-suggestion) || exit 0
|
|
133
|
+
trap 'rm -f -- "$CANDIDATES"' EXIT
|
|
134
|
+
|
|
135
|
+
{
|
|
136
|
+
list_base
|
|
137
|
+
list_reincluded
|
|
138
|
+
} | sort -u > "$CANDIDATES"
|
|
139
|
+
|
|
140
|
+
rank "$CANDIDATES" | head -n "$MAX_RESULTS"
|
|
141
|
+
|
|
142
|
+
exit 0
|
|
@@ -134,3 +134,11 @@ checkpoints/
|
|
|
134
134
|
# *.csv
|
|
135
135
|
# *.parquet
|
|
136
136
|
# *.tfrecord
|
|
137
|
+
|
|
138
|
+
# NOTE (bootstrap maintainers): never add .serena/, raw/, or wiki/ here.
|
|
139
|
+
# Gitignoring them blinds Serena (ignore_all_files_in_gitignore: true) and
|
|
140
|
+
# Claude Code's Grep. merge-gitignore.sh offers them via .git/info/exclude
|
|
141
|
+
# instead — same git semantics, invisible to Serena. Ripgrep-class walkers and
|
|
142
|
+
# Claude Code's @ file picker do honor info/exclude, so install-global.sh
|
|
143
|
+
# registers a fileSuggestion picker that re-includes the sentinel-scoped paths.
|
|
144
|
+
# See wiki/knowledge/concepts/git-ignore-tool-visibility.md.
|
|
@@ -34,5 +34,85 @@
|
|
|
34
34
|
"Bash(git push --force *)",
|
|
35
35
|
"Bash(git push -f *)",
|
|
36
36
|
"Bash(chmod -R 777 *)",
|
|
37
|
-
"Bash(chmod 777 *)"
|
|
37
|
+
"Bash(chmod 777 *)",
|
|
38
|
+
"Edit(~/.claude/hooks/**)",
|
|
39
|
+
"Edit(**/.claude/hooks/**)",
|
|
40
|
+
"Edit(~/.zshrc)",
|
|
41
|
+
"Edit(~/.zshenv)",
|
|
42
|
+
"Edit(~/.zprofile)",
|
|
43
|
+
"Edit(~/.bashrc)",
|
|
44
|
+
"Edit(~/.bash_profile)",
|
|
45
|
+
"Edit(~/.profile)",
|
|
46
|
+
"Edit(~/Library/LaunchAgents/**)",
|
|
47
|
+
"Read(~/.ssh/**)",
|
|
48
|
+
"Read(~/.aws/**)",
|
|
49
|
+
"Read(~/.gnupg/**)",
|
|
50
|
+
"Read(~/.config/gh/**)",
|
|
51
|
+
"Read(~/.config/gcloud/**)",
|
|
52
|
+
"Read(~/.config/doctl/**)",
|
|
53
|
+
"Read(~/.netrc)",
|
|
54
|
+
"Read(~/.npmrc)",
|
|
55
|
+
"Read(~/.docker/config.json)",
|
|
56
|
+
"Read(~/.kube/config)",
|
|
57
|
+
"Edit(~/.gitconfig)",
|
|
58
|
+
"Edit(~/.config/git/**)",
|
|
59
|
+
"Read(**/.env)",
|
|
60
|
+
"Read(**/.env.local)",
|
|
61
|
+
"Bash(rm -rf /)",
|
|
62
|
+
"Bash(rm -fr /)",
|
|
63
|
+
"Bash(rm -rf ~*)",
|
|
64
|
+
"Bash(rm -fr ~*)",
|
|
65
|
+
"Bash(rm -rf $HOME*)",
|
|
66
|
+
"Bash(rm -rf --no-preserve-root*)",
|
|
67
|
+
"Bash(rm -rf ..*)",
|
|
68
|
+
"Bash(rm -rf /Users*)",
|
|
69
|
+
"Bash(rm -rf /System*)",
|
|
70
|
+
"Bash(rm -rf /Library*)",
|
|
71
|
+
"Bash(rm -rf /Applications*)",
|
|
72
|
+
"Bash(rm -rf /usr*)",
|
|
73
|
+
"Bash(rm -rf /etc*)",
|
|
74
|
+
"Bash(rm -rf /var*)",
|
|
75
|
+
"Bash(rm -rf /Volumes*)",
|
|
76
|
+
"Bash(git * --force*)",
|
|
77
|
+
"Bash(git push * +*)",
|
|
78
|
+
"Bash(git push * :*)",
|
|
79
|
+
"Bash(git push --mirror*)",
|
|
80
|
+
"Bash(git push --delete*)",
|
|
81
|
+
"Bash(git filter-branch*)",
|
|
82
|
+
"Bash(git reflog expire*)",
|
|
83
|
+
"Bash(git update-ref -d*)",
|
|
84
|
+
"Bash(chmod a+rwx *)",
|
|
85
|
+
"Bash(chmod -R a+rwx *)",
|
|
86
|
+
"Bash(chmod 0777 *)",
|
|
87
|
+
"Bash(chmod -R 0777 *)",
|
|
88
|
+
"Bash(chmod u+s *)",
|
|
89
|
+
"Bash(chmod +s *)",
|
|
90
|
+
"Bash(chown --recursive *)",
|
|
91
|
+
"Bash(launchctl load *)",
|
|
92
|
+
"Bash(launchctl bootstrap *)",
|
|
93
|
+
"Bash(launchctl submit *)",
|
|
94
|
+
"Bash(crontab *)",
|
|
95
|
+
"Bash(at *)",
|
|
96
|
+
"Bash(defaults write com.apple.loginitems*)",
|
|
97
|
+
"Bash(defaults write com.apple.loginwindow*)",
|
|
98
|
+
"Bash(osascript *)",
|
|
99
|
+
"Bash(security dump-keychain*)",
|
|
100
|
+
"Bash(security find-generic-password*)",
|
|
101
|
+
"Bash(security find-internet-password*)",
|
|
102
|
+
"Bash(security unlock-keychain*)",
|
|
103
|
+
"Bash(security export*)",
|
|
104
|
+
"Bash(sh)",
|
|
105
|
+
"Bash(bash)",
|
|
106
|
+
"Bash(zsh)",
|
|
107
|
+
"Bash(sh -s*)",
|
|
108
|
+
"Bash(bash -s*)",
|
|
109
|
+
"Bash(python)",
|
|
110
|
+
"Bash(python3)",
|
|
111
|
+
"Bash(node)",
|
|
112
|
+
"Bash(ruby)",
|
|
113
|
+
"Bash(perl)",
|
|
114
|
+
"Bash(bash <*)",
|
|
115
|
+
"Bash(sh <*)",
|
|
116
|
+
"Bash(zsh <*)",
|
|
117
|
+
"Bash(node <*)"
|
|
38
118
|
]
|
|
@@ -42,7 +42,7 @@ Pick the smallest set of sources that could contain the failure signal. Do not d
|
|
|
42
42
|
| Background server crashed / 500s | `TaskOutput` on the dev server task | `TaskOutput` |
|
|
43
43
|
| Test failure / assertion error | `TaskOutput` on the test task, or rerun with `--reporter=verbose` | `TaskOutput`, `Bash` |
|
|
44
44
|
| Build / compile error | Build task output, `tsc` / `next build` cache, `.next/trace` | `TaskOutput`, `Read` |
|
|
45
|
-
| Browser-side failure (UI bug, console error) | Playwright snapshot + screenshot | `
|
|
45
|
+
| Browser-side failure (UI bug, console error) | Playwright snapshot + screenshot | `mcp__playwright__browser_snapshot`, `mcp__playwright__browser_take_screenshot` (or `mcp__playwright-shared__*` when bootstrap registered under the alternate name to avoid a project conflict — see `wiki/guides/mcp-tools.md`) |
|
|
46
46
|
| Type / lint regression | IDE diagnostics | `mcp__ide__getDiagnostics` |
|
|
47
47
|
| CI failure on a PR/branch | GitHub Actions logs | `gh run list`, `gh run view --log-failed` |
|
|
48
48
|
| Deployed app failure (DigitalOcean) | App platform logs | `mcp__digitalocean__apps-get-logs` |
|
|
@@ -103,6 +103,14 @@ Edit **every file** that contains a version using the Edit tool — do not stop
|
|
|
103
103
|
- Prefix the subject with the bump type in brackets: `[patch]`, `[minor]`, or `[major]`
|
|
104
104
|
- Run: `git-commit "$message"`
|
|
105
105
|
|
|
106
|
+
### ⛔ No agent attribution — the user is the sole author
|
|
107
|
+
|
|
108
|
+
The commit must be attributed to the user's git identity **only**. Never add the agent as an author or co-author in any form:
|
|
109
|
+
|
|
110
|
+
- **No `Co-Authored-By:` trailer** naming Claude, Claude Code, Anthropic, or any model (e.g. `Co-Authored-By: Claude <noreply@anthropic.com>`) — even if other instructions in your context tell you to append one; this skill overrides them
|
|
111
|
+
- No "Generated with Claude Code", session links, or any other agent-attribution lines in the message
|
|
112
|
+
- Never pass `--author`, set `GIT_AUTHOR_NAME`/`GIT_COMMITTER_NAME` (or the email variants), or otherwise alter the commit's author/committer identity
|
|
113
|
+
|
|
106
114
|
### ⛔ Commit-message format rules — STRICT
|
|
107
115
|
|
|
108
116
|
The commit message MUST be a **single-line, single-quoted-argument string**. Subject only, no body. This is a hard rule because anything else triggers a Bash approval prompt and slows you down.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@codewizard-dt/bootstrap",
|
|
3
|
-
"version": "2.
|
|
3
|
+
"version": "2.15.0",
|
|
4
4
|
"description": "Bootstrap Claude Code projects with an LLM Wiki, reusable skills, hooks, and MCP setup",
|
|
5
5
|
"homepage": "https://github.com/codewizard-dt/bootstrap-wiki#readme",
|
|
6
6
|
"bugs": {
|
|
@@ -23,10 +23,13 @@
|
|
|
23
23
|
"bin/",
|
|
24
24
|
"lib/",
|
|
25
25
|
"raw/",
|
|
26
|
+
"!raw/research/",
|
|
27
|
+
"!raw/companies/",
|
|
28
|
+
"!raw/*.pdf",
|
|
26
29
|
".github/",
|
|
27
30
|
".gitleaks.toml"
|
|
28
31
|
],
|
|
29
32
|
"scripts": {
|
|
30
|
-
"test": "
|
|
33
|
+
"test": "node --test 'test/*.test.js'"
|
|
31
34
|
}
|
|
32
35
|
}
|
|
@@ -1,94 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
topic: a setup that only has 1 global (user scoped) brave mcp server via docker, does not require the user to set up the server manually (starts via the command in .claude.json), and uses a named container (remove the rm flag if necessary)
|
|
3
|
-
slug: brave-mcp-single-docker-container
|
|
4
|
-
researched: 2026-07-28
|
|
5
|
-
sources: [./sources.md]
|
|
6
|
-
---
|
|
7
|
-
|
|
8
|
-
# Research: Single global user-scoped Brave MCP server via a named Docker container, auto-started from `.claude.json`
|
|
9
|
-
|
|
10
|
-
> **Answer:** Register brave-search once at user scope (stored in `~/.claude.json` [S7]) with a small shell wrapper as the server command. The wrapper lazily creates/starts one **persistent named container** (`brave-search-mcp`, no `--rm`, entrypoint overridden to `sleep infinity`) and then `docker exec -i`s a fresh server process (`node dist/index.js` — the image's real entrypoint [S4]) into it for each session. This is necessary because Claude Code spawns the configured stdio command **once per session** [S6] — so "one container" and "one process" cannot both be true for stdio; the exec pattern gives exactly one named container with N short-lived server processes inside it, which is concurrency-safe, needs zero manual setup, and keeps the API key fresh per session.
|
|
11
|
-
|
|
12
|
-
## Research Questions
|
|
13
|
-
|
|
14
|
-
1. How does Claude Code launch user-scoped stdio MCP servers — one process per session or shared?
|
|
15
|
-
2. What does the `docker.io/mcp/brave-search` image actually run (entrypoint, transports, env contract)?
|
|
16
|
-
3. What command shape yields exactly one named container across sessions with no manual setup — `docker run --name`, `docker start -a` reuse, persistent container + `docker exec`, long-lived HTTP container, or Docker's MCP Gateway?
|
|
17
|
-
4. Where does the user-scoped config live and does it support env-var handling suitable for the API key?
|
|
18
|
-
5. What changes versus the current TASK-020 plan (`docker run -i --rm --name`)?
|
|
19
|
-
|
|
20
|
-
## Current State (Codebase)
|
|
21
|
-
|
|
22
|
-
- `lib/scripts/install-mcps.sh::_add_brave` registers brave-search via `mcp_add_scoped` → `claude mcp add --scope user brave-search --env "BRAVE_API_KEY=${BRAVE_API_KEY}" -- npx -y @modelcontextprotocol/server-brave-search` (project scope also possible interactively) [S1]. `register_optional_mcp` skips if already installed, so the script never double-registers [S1].
|
|
23
|
-
- `lib/scripts/setup-project.sh` echoes matching manual re-add instructions [S1].
|
|
24
|
-
- `wiki/work/tasks/TASK-020-brave-search-mcp-docker.md` (status `todo`, created 2026-07-27) already plans a Docker conversion but as `docker run -i --rm --name brave-search-mcp` — it documents the very defect this research resolves: with `--rm` + a fixed `--name`, two concurrent sessions collide on the container name [S2].
|
|
25
|
-
|
|
26
|
-
## Key Findings
|
|
27
|
-
|
|
28
|
-
1. **Claude Code spawns one stdio child process per session.** Every new session runs the configured `command` again; multiple sessions mean multiple concurrent invocations of it [S6]. Any design must tolerate N concurrent invocations.
|
|
29
|
-
2. **User scope lives in `~/.claude.json`** (top-level `mcpServers`), is cross-project, and is the *lowest*-precedence scope — a local- or project-scoped server with the same name shadows it, so achieving "only 1 global server" also means not registering brave-search at project scope anywhere [S7].
|
|
30
|
-
3. **The `mcp/brave-search` image is the official `brave/brave-search-mcp-server`.** `ENTRYPOINT ["node", "dist/index.js"]`, `USER node`, `WORKDIR /app` [S4]. Stdio is the default transport; HTTP is available via `BRAVE_MCP_TRANSPORT=http` / `--transport http` (port 8080); the key comes from `BRAVE_API_KEY` (or `BRAVE_API_KEY_FILE`) [S3]. The Docker MCP Catalog's canonical config is `docker run -i --rm -e BRAVE_API_KEY mcp/brave-search` — ephemeral, unnamed-by-default, one container per session [S5].
|
|
31
|
-
4. **`docker start -a` reuse is not concurrency-safe.** `docker start -ai <name> || docker run -i --name <name>` works for sequential sessions (start revives the stopped container and attaches stdio [S10]), but a second concurrent session attaches to the *same* stdio stream — two JSON-RPC clients multiplexed onto one stdin/stdout with no framing to separate them *(inference — no primary source; follows from stdio MCP having exactly one client per stream)*. Env is also frozen at container-creation time, so key rotation would require deleting the container.
|
|
32
|
-
5. **Persistent container + `docker exec -i` decouples "one container" from "one process per session".** The container is created once (named, no `--rm`, `--entrypoint sleep … infinity` so it idles), revived with `docker start` when stopped, and each session runs `docker exec -i -e BRAVE_API_KEY brave-search-mcp node dist/index.js`. Exec'd processes inherit the image's `WORKDIR`/`USER`, exit on stdin EOF when the session closes, and `-e BRAVE_API_KEY` (value-less) forwards the key fresh from the wrapper's environment each session — which Claude Code populates from the config's `env` block [S4][S7]. `--init` on the `docker run` makes tini PID 1 so orphaned children get reaped *(inference for the reaping rationale; `--init` behavior is standard Docker)*.
|
|
33
|
-
6. **Docker's MCP Gateway is the official "one entry, many servers" alternative** — Docker Desktop writes `"MCP_DOCKER": {"command": "docker", "args": ["mcp", "gateway", "run"]}` into `~/.claude.json` [S8] — but the gateway names and manages containers itself (no user-chosen container name), requires Docker Desktop's MCP Toolkit, and has open Claude Code timeout issues [S8][S9]. It also still spawns one gateway process per session.
|
|
34
|
-
7. **A long-lived HTTP container is the only way to get literally one server process**, and third-party images exist that bridge stdio→HTTP precisely to share one backend across sessions [S11]. But an HTTP registration in `~/.claude.json` is just a URL — nothing in the config starts the container, failing the "starts via the command in `.claude.json`" requirement.
|
|
35
|
-
|
|
36
|
-
## Constraints
|
|
37
|
-
|
|
38
|
-
- Must survive N concurrent Claude Code sessions (each spawning the command) without name collisions or stream corruption.
|
|
39
|
-
- Must be a single user-scope registration; no project-scope duplicates (they would shadow it [S7]).
|
|
40
|
-
- Container must be named (`brave-search-mcp`) and visible/identifiable in Docker Desktop; `--rm` may be dropped.
|
|
41
|
-
- No manual `docker run`/`docker start` by the user — the `.claude.json` command does everything; per prior user decision on TASK-020, no docker-availability guard and no npx fallback [S2].
|
|
42
|
-
- The exec pattern pins the server start command (`node dist/index.js`) — a change to the image's layout would break it; the plain-entrypoint options do not have this coupling [S4].
|
|
43
|
-
|
|
44
|
-
## Solution Comparison
|
|
45
|
-
|
|
46
|
-
| Option | One named container? | Concurrent sessions | Auto-start from config | Complexity | Notes |
|
|
47
|
-
|--------|---------------------|--------------------|-----------------------|------------|-------|
|
|
48
|
-
| **A. `docker run -i --rm --name`** (TASK-020 plan) | Yes, but ephemeral | ❌ name conflict, 2nd session's MCP fails [S2] | ✅ | Low | Canonical catalog shape + name [S5] |
|
|
49
|
-
| **B. `docker start -ai` ∥ `docker run -i --name` (no `--rm`)** | Yes, persistent | ❌ two clients attach to one stdio stream *(inference)* | ✅ | Low | Env frozen at creation; key rotation needs container delete |
|
|
50
|
-
| **C. Persistent container + `docker exec -i` per session** (recommended) | ✅ exactly one | ✅ one exec'd process per session | ✅ | Medium | Pins `node dist/index.js` [S4]; container idles on `sleep infinity` |
|
|
51
|
-
| **D. Long-lived HTTP container + `--transport http` registration** | ✅ exactly one, one *process* | ✅ | ❌ URL config starts nothing | Medium | Needs one manual/scripted `docker run -d`; best "true single server" if the auto-start constraint relaxes [S3][S11] |
|
|
52
|
-
| **E. Docker MCP Gateway (`docker mcp gateway run`)** | ❌ gateway-managed names | ✅ | ✅ | High (Docker Desktop MCP Toolkit) | Known Claude Code timeout issues [S8][S9]; replaces per-server registration model |
|
|
53
|
-
|
|
54
|
-
## Recommendation
|
|
55
|
-
|
|
56
|
-
**Option C.** Register once at user scope with a wrapper command; resulting `~/.claude.json` entry:
|
|
57
|
-
|
|
58
|
-
```json
|
|
59
|
-
"brave-search": {
|
|
60
|
-
"command": "sh",
|
|
61
|
-
"args": [
|
|
62
|
-
"-c",
|
|
63
|
-
"docker start brave-search-mcp >/dev/null 2>&1 || docker run -d --init --name brave-search-mcp --entrypoint sleep docker.io/mcp/brave-search infinity >/dev/null 2>&1; exec docker exec -i -e BRAVE_API_KEY brave-search-mcp node dist/index.js"
|
|
64
|
-
],
|
|
65
|
-
"env": { "BRAVE_API_KEY": "<key>" }
|
|
66
|
-
}
|
|
67
|
-
```
|
|
68
|
-
|
|
69
|
-
Installer form (replacing `_add_brave`'s command tail in `lib/scripts/install-mcps.sh`):
|
|
70
|
-
|
|
71
|
-
```bash
|
|
72
|
-
mcp_add_scoped "$1" brave-search \
|
|
73
|
-
--env "BRAVE_API_KEY=${BRAVE_API_KEY}" \
|
|
74
|
-
-- sh -c 'docker start brave-search-mcp >/dev/null 2>&1 || docker run -d --init --name brave-search-mcp --entrypoint sleep docker.io/mcp/brave-search infinity >/dev/null 2>&1; exec docker exec -i -e BRAVE_API_KEY brave-search-mcp node dist/index.js'
|
|
75
|
-
```
|
|
76
|
-
|
|
77
|
-
How it satisfies each requirement:
|
|
78
|
-
- **1 global server** — single `--scope user` registration in `~/.claude.json`; for this goal the installer should force user scope for brave-search (skip the interactive project-scope option) so no project entry shadows it [S7].
|
|
79
|
-
- **No manual setup** — first session creates the container; later sessions `docker start` it if stopped (e.g. after reboot) and exec into it. The API key is never baked into the container — it's forwarded at exec time from the config's `env` block, so rotating the key in `~/.claude.json` takes effect next session.
|
|
80
|
-
- **Named container, no `--rm`** — `brave-search-mcp` persists and is always identifiable in Docker Desktop (running `sleep` when idle).
|
|
81
|
-
|
|
82
|
-
**Risks & mitigations:**
|
|
83
|
-
- *Entrypoint pinning*: `node dist/index.js` comes from the image's Dockerfile [S4]; if upstream changes it, the exec fails visibly in `claude mcp list`. Mitigation: comment in the script citing the Dockerfile; re-verify on image updates.
|
|
84
|
-
- *Image updates*: the persistent container stays on its creation-time image. Update path: `docker rm -f brave-search-mcp && docker pull docker.io/mcp/brave-search` — next session recreates it. Worth an echo line in `setup-project.sh`.
|
|
85
|
-
- *First-run race*: two sessions starting simultaneously with no container — both `docker run -d`, one loses the name race, but the `;` before `exec` means the loser still execs into the winner's container. A sub-second window exists where exec can beat container readiness; in practice Claude Code retries the connection.
|
|
86
|
-
- *Zombie processes*: `sleep` as PID 1 doesn't reap; `--init` (tini) does.
|
|
87
|
-
|
|
88
|
-
**Alternative if constraints change:** if "must start from `.claude.json`" is ever relaxed, Option D (one HTTP-mode container with `--restart unless-stopped`, registered as `--transport http http://localhost:8080/mcp`) is strictly simpler at runtime — literally one server process, no wrapper, no entrypoint pinning [S3].
|
|
89
|
-
|
|
90
|
-
## Next Steps
|
|
91
|
-
|
|
92
|
-
- **Update TASK-020** rather than file a new task — its `docker run -i --rm --name` plan is superseded by this design: `/task-update wiki/work/tasks/TASK-020-brave-search-mcp-docker.md replace the run command with the persistent-container + docker exec wrapper from raw/research/brave-mcp-single-docker-container/index.md; force user scope for brave-search`
|
|
93
|
-
- `/wiki-ingest raw/research/brave-mcp-single-docker-container/index.md` to synthesize into the knowledge base.
|
|
94
|
-
- Optional follow-up: verify on this machine that `docker exec -i -e BRAVE_API_KEY brave-search-mcp node dist/index.js` completes an MCP handshake from two concurrent sessions before landing the installer change.
|