@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
@@ -1,6 +1,7 @@
1
1
  #!/usr/bin/env node
2
- // Merge the canonical Bash deny list (templates/settings-deny.json) into the
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 deny-list merge`);
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
- const { target, source } = parseArgs(process.argv.slice(2));
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
- let canonical;
47
- try {
48
- canonical = JSON.parse(fs.readFileSync(source, 'utf8'));
49
- } catch (err) {
50
- warnSkip(`settings-deny template missing or invalid (${source})`);
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
- if (!Array.isArray(canonical) || !canonical.every((e) => typeof e === 'string')) {
53
- warnSkip(`settings-deny template is not an array of strings (${source})`);
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
- let raw = null;
57
- if (fs.existsSync(target)) {
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
- raw = fs.readFileSync(target, 'utf8');
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
- warnSkip(`could not read ${target}`);
108
+ try { fs.unlinkSync(tmp); } catch (_) {}
109
+ warnSkip(`could not write ${file} (${err.message})`);
62
110
  }
63
111
  }
64
112
 
65
- let settings = {};
66
- if (raw !== null) {
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
- settings = JSON.parse(raw);
128
+ value = JSON.parse(setValue);
69
129
  } catch (err) {
70
- warnSkip(`could not parse ${target} (file untouched)`);
130
+ console.error(`Error: --set-value is not valid JSON (${err.message})`);
131
+ process.exit(1);
71
132
  }
72
- if (!isPlainObject(settings)) {
73
- warnSkip(`${target} is not a JSON object (file untouched)`);
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
- // Reuse the file's existing indentation (tabs or N spaces); default 2 spaces.
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.
@@ -1,6 +1,8 @@
1
1
 
2
2
  ## Playwright (Browser Automation)
3
3
 
4
+ Server name in this project: `__PW_SERVER_NAME__` — tools appear as `mcp____PW_SERVER_NAME____browser_*`.
5
+
4
6
  ### Tools
5
7
 
6
8
  | Tool | Purpose |
@@ -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 | `mcp__playwright-shared__browser_snapshot`, `mcp__playwright-shared__browser_take_screenshot` (or `mcp__playwright__*` when the project registers its own server) |
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.13.0",
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": "echo \"Error: no test specified\" && exit 1"
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.